Module: markers

Nodes related to event marker handling and formatting.

The nodes in this category are used to add or manipulate event or other data markers. Upon import, are stored in the instance.data axis of a 'markers' data chunk. Markers are typically used to identify events, for which the data can be segmented using the Segmentation node for event-related processing.

AddEventMarker

Find trials matching a particular set of event markers, and add a new marker with a time stamp that matches one of those events.

Such new markers can then be used for purposes such as segmentation to events where the surrounding trial satisfies certain desired conditions etc. The node uses regular expressions, a very powerful language for string matching to identify which markers comprise a trial of interest. See the below link for more details. To add markers matching different criteria (e.g., 'left', and 'right'), use multiple copies of this node in succession.

More Info...

Version 1.2.3

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • stream
    Name of stream containing markers to use for trial selection. Wildcards are supported, i.e. mystream* will select the first stream whose name starts with mystream. If unspecified, the first stream will be used.

    • verbose name: Stream
    • default value: None
    • port type: StringPort
    • value type: str (can be None)
  • trial_criteria
    List of marker patterns that constitute a matching trial. When a trial is found, the event markers in the trial will be matched against this list in order. If all conditions are true, a new event marker will be added to the trial. These conditions are assumed to be regular expressions.

    • verbose name: Required Trial Markers
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • trial_start
    The event marker that indicates the start of a trial. Can be a regular expression.

    • verbose name: Trial Start
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • trial_end
    The event marker that indicates the end of a trial, used to move to the next trial. Can be a regular expression.

    • verbose name: Trial End
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • event_to_match
    The event within a matching trial that the new event marker should be time-locked to. This should be one of the items in the 'Trial Criteria' parameter. When a matching trial is found a new event marker will be written with the same time stamp as this event marker.

    • verbose name: Event To Match
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • match_first_event_only
    If there are multiple event markers matching the event_to_match parameter, a new event marker will only be created for the first one.

    • verbose name: Match First Event Only
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • new_event_marker
    The name of the new event marker to be added to matching trials.

    • verbose name: New Event Marker
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • full_criteria
    A dictionary containing a set of criteria for adding markers, where the keys are the names of properties of this node (i.e ., trial_criteria, trial_start, etc.) and the values are the values for those properties (the same values you would pass if you were setting those properties directly. This provides a convenient way to programmatically pass in a collection of settings at once, to this single property, rather than having to set each property. If set, this will take precedence over all the other properties.

    • verbose name: Full Criteria
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • verbose
    Verbose debugging output.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

CalculateMarkerTimeDifference

Calculate difference between all markers and provided timestamps.

timestamps packet can be the output of ExtractMarkerTimestamps node (deprecated). Time difference will be stored as a new field/column in the instance axis data.

Version 0.3.1

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • timestamps
    Packet containing timestamps, usually from the output of ExtractMarkerTimestamps. If not provided then timestamps will be drawn from the data packet target_event.

    • verbose name: Timestamps
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: IN
  • look_for
    Direction to search for timestamp relative to each marker. Using 'next' will find reaction time from marker to timestamp.

    • verbose name: Look For
    • default value: next
    • port type: EnumPort
    • value type: str (can be None)
  • target_event
    Only calculate time differences to this or these events. Pass as string or list of strings. If not provided then all events are considered potential targets.

    • verbose name: Target Event
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: INOUT
  • target_field

    • verbose name: Target Field
    • default value: Marker
    • port type: StringPort
    • value type: str (can be None)
  • source_event
    Only find time differences from this event in the data packet. If not provided them timestamps will be calculated from all events.

    • verbose name: Source Event
    • default value: None
    • port type: StringPort
    • value type: str (can be None)
  • source_field

    • verbose name: Source Field
    • default value: Marker
    • port type: StringPort
    • value type: str (can be None)
  • new_field_name
    Name of field/column added to data instance table.

    • verbose name: New Field Name
    • default value: ReactionTime
    • port type: StringPort
    • value type: str (can be None)
  • transform
    Time differences, or reaction times, are typically skewed and may have outliers. Transforming reaction time can help mitigate these problems, which is helpful before doing statistical analyses. https://opensiuc.lib.siu.edu/cgi/viewcontent.cgi?referer=&httpsredir=1&article=1077&context=tpr

    • verbose name: Transform
    • default value: none
    • port type: EnumPort
    • value type: str (can be None)
  • grouping_fields
    When the timestamps input is not provided, thus both the source and target are taken from the same instance table, you can further constrain the search so target and source events will only be matched if they have equal values in all indicated grouping fields. Typical values for this parameter are one or more fields that key a unique trial id.

    • verbose name: Grouping Fields
    • default value: None
    • port type: ListPort
    • value type: list (can be None)
  • time_bounds_criteria
    Optional list of [minimum, maximum] (absolute value seconds) allowed between the source and target time difference in order to be logged as valid. For example, in the case of response (reaction) times from stimulus, if a trial had a missing response (e.g. no target response marker found) this node will by default calculate the time difference from stimulus to the next trial's response marker and therefore log a reaction time that is not valid for the current trial. Setting this time bound criteria can ignore these cases and not mis-identify invalid reaction times. Example: [0, 2.5] only allows valid time differences >0 and <2.5 seconds (non-inclusive) to be logged.

    • verbose name: Time Bounds Criteria
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • add_to_existing
    Add time differences to the existing field (defined in new_field_name) if it already exists in the data. (That allows this node to be run multiple times over the same data.)

    • verbose name: Add To Existing
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • pattern_syntax
    Optionally the syntax to use for the input marker patterns. If set to none, the input strings are not used as patterns but used to match a specific marker string verbatim. If set to wildcards, then the special character * can be used to match any number of characters (or none), while the character ? can be used to match any single character.

    • verbose name: Pattern Syntax
    • default value: none
    • port type: EnumPort
    • value type: str (can be None)
  • absolute_time
    Always record time differences in absolute values.

    • verbose name: Absolute Time
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

ExportMarkers

Write all markers and matching timestamps to a 2-column CSV file.

Useful for exporting behavioral data for further processing. The CSV file is written to the same folder as the file being processed. If multiple streams are found, a CSV file is written for each one. (Not for streaming data.)

Version 1.1.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: IN
  • stream
    Name of stream containing markers. Leave empty to write a CSV file for each marker stream found. Wildcards are supported, i.e. mystream* will select the first stream whose name starts with mystream.

    • verbose name: Stream
    • default value: None
    • port type: StringPort
    • value type: str (can be None)
  • filename
    File name to record to (csv). If empty, the source_url of the data will be used, if specified in the stream props, with the name of the marker stream (usually "markers", "markers-1" etc.) with a .csv extension.

    • verbose name: Filename
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • output_root
    Path for the output root folder.

    • verbose name: Output Root
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • cloud_host
    Cloud storage host to use (if any). You can override this option to select from what kind of cloud storage service data should be downloaded. On some environments (e.g., on NeuroScale), the value Default will be map to the default storage provider on that environment.

    • verbose name: Cloud Host
    • default value: Default
    • port type: EnumPort
    • value type: str (can be None)
  • cloud_account
    Cloud account name on storage provider (use default if omitted). You can override this to choose a non-default account name for some storage provider (e.g., Azure or S3.). On some environments (e.g., on NeuroScale), this value will be default-initialized to your account.

    • verbose name: Cloud Account
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • cloud_bucket
    Cloud bucket to read from (use default if omitted). This is the bucket or container on the cloud storage provider that the file would be written to. On some environments (e.g., on NeuroScale), this value will be default-initialized to a bucket that has been created for you.

    • verbose name: Cloud Bucket
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • cloud_credentials
    Secure credential to access cloud data (use default if omitted). These are the security credentials (e.g., password or access token) for the the cloud storage provider. On some environments (e.g., on NeuroScale), this value will be default-initialized to the right credentials for you.

    • verbose name: Cloud Credentials
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

ExtractMarkerTimestamps

Extract timestamps for specified markers.

Version 1.0.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • events
    List of events. If left empty, all events are used.

    • verbose name: Events
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

FuseMarkerStreams

Fuse the given marker streams into a single interleaved stream.

This node will take all marker streams it finds in a packet and create a new marker stream, named markers-fused containing all the event markers from those streams, sorted in chronological order. The original marker streams are dropped by default but can be retained by setting the keep_original_streams property to True. In most cases you would want to use the Merge Streams node upstream of this node to bundle multiple marker streams from different sources (i.e., different LSL streams) into a single packet.

Version 1.0.1

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • keep_original_streams
    If true, both the original marker streams and the new markers-fused marker stream will be kept. If false, the original marker streams will be dropped.

    • verbose name: Keep Original Streams
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

InsertMarkers

Insert markers into time-series data.

This node is not applicable to streaming data, that is, you can only apply it to whole recordings like those imported by one of the import nodes. A single application of this node will insert zero or more occurrences of a given marker string (or other payload) into the recording, according to the selected criteria. If you need to insert multiple different marker types, you need to apply this node multiple times in succession. The criteria supported by this node are quite sophisticated, and it is for instance possible to insert markers in time ranges relative to other markers, or between pairs of other markers, and to insert multiple markers randomly or regularly spaced in such time ranges. Some of the common use cases of this node are: inserting calibration-begin and calibration-end markers for use with the accumulate calibration data node, inserting multiple markers into longer data ranges for subsequent extraction of segments/trials from these ranges, or creating jittered placements of markers relative to other markers to simulate timing uncertainty. This node will operate on the first non-empty marker stream that it finds in the data, or fall back to the first empty marker stream, or append one if no marker stream is present.

Version 1.4.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • payload
    New marker to insert. This is the data payload (usually a string) to be used for every newly inserted marker. If this is None, the node will pass through the data unchanged. If given as a dictionary of names and values, then the respective instance fields will be set.

    • verbose name: Marker To Insert
    • default value: mynewevent
    • port type: Port
    • value type: object (can be None)
  • mode
    Type of insertion interval. Events can be inserted either in a fixed absolute time window (absolute), or relative to the beginning/end of the data (relative), or in time windows relative to reference events of a certain type (marker-locked), or in time window spanned by two subsequent events of certain types A and B, optionally with ignored events in between (marker-spanned).

    • verbose name: Insertion Mode
    • default value: relative
    • port type: EnumPort
    • value type: str (can be None)
  • time_limits
    Lower and upper time limit for the insertion range(s) (in seconds). In absolute mode, this is the beginning and end of the time range, regardless of where the signal (if any) begins or ends (unless you know the begin/end time of the signal, using this rarely makes sense); in relative mode, this range is instead relative to the range covered by the signal, where positive numbers count from the beginning of the data, and negative numbers count from the end (e.g., [10, -5] inserts 10 seconds after the beginning up to 5 seconds prior to the end). An empty interval (i.e., []) in this mode is interpreted as the whole data range. In marker-locked mode, this is the beginning and end of the range extracted relative to each marker (i.e., [-1, 2] would begin 1 second before each marker and end 2 seconds after). In marker-spanned mode, for every matching pair of successive markers of types A and B, the range begins x seconds relative to A and ends y seconds relative to B if the time limits are [x, y]. Marker A is called the anchor marker, and marker B is called the second anchor marker in the subsequent settings.

    • verbose name: Time Limits
    • default value: [0, 1]
    • port type: ListPort
    • value type: list (can be None)
  • anchor_marker
    Marker/event type relative to which insertion ranges shall be generated. Applies to marker-locked and marker-spanned mode. If mode is marker-spanned, this is the first marker in a pair of successive markers (referred to as A in other places of the node documentation), while the second marker is given by the second anchor marker.

    • verbose name: Anchor Marker
    • default value: myeventA
    • port type: Port
    • value type: object (can be None)
  • anchor_marker_B
    Second anchor marker (B) if insertion mode is marker-spanned. This marker indicates the end of a spanned range.

    • verbose name: Second Anchor Marker (Spanned Mode)
    • default value: myeventB
    • port type: Port
    • value type: object (can be None)
  • intermittent_markers
    If in spanned mode, this determines how to handle intermittent markers that occur between successive markers A and B by default. If set to allow, any marker type may occur between marker A and the next marker B, and a spanned range will still be generated. If set to forbid, no other marker may occur in between, or else the spanned range will not be generated. Exceptions can be listed in the below parameter for exceptions to this setting.

    • verbose name: Handling Of Intermittent Markers (Spanned Mode)
    • default value: allow
    • port type: EnumPort
    • value type: str (can be None)
  • except_markers
    List of markers types for which to make an exception from the default chosen in intermittent markers. For instance, if the default is allow, then the marker types in this list will be forbidden, and if the default is forbid, then the marker types in this list will be allowed.

    • verbose name: Exceptions To Intermittent Markers (Spanned Mode)
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • instance_fields_from
    Source item for unspecified instance field values. Item from which to take any instance field values that are not part of the provided payload. The first and last values refer to the first and last markers instances in the data. anchor refers to the anchor marker in marker-locked or marker-spanned ranges (only valid in those two insertion modes). And anchorB refers to the second anchor marker, only valid in marker-spanned insertion mode.

    • verbose name: Instance Fields From
    • default value: first
    • port type: EnumPort
    • value type: str (can be None)
  • marker_format
    Format of event markers. This affects how any markers are interpreted, i.e., both the anchor markers and the excepted marker strings: in the verbatim mode, the marker names in the data must match the given strings exactly. In the conditions mode, what is instead given is a Python-like expression string that may refer to event instance fields (e.g., "Marker == 'response' and Duration > 5)".

    • verbose name: Marker Format
    • default value: verbatim
    • port type: EnumPort
    • value type: str (can be None)
  • enforce_intermittent_in
    Segment within which intermittent markers shall be rejected. In marker-span mode, the span between the two anchor markers must be free of excluded intermittent markers (or the span from the marker to the end of the insertion range, if there is only one anchor marker). In insertion-span mode, the span into which markers are to be inserted (accounting for time offsets) must be free of excluded intermittent markers.

    • verbose name: Enforce Intermittent In
    • default value: marker-span
    • port type: EnumPort
    • value type: str (can be None)
  • count
    Number of markers to insert. This is either per interval or per second, depending on the count unit parameter. If using per second you can specify a decimal value in which each marker would be inserted at 1/value seconds apart. For example, if this value is set to 0.5, inserted markers would be spaced 1/0.5 = 2 seconds apart.

    • verbose name: Markers To Insert
    • default value: 1
    • port type: FloatPort
    • value type: float (can be None)
  • counting
    Counting measure. The desired number of markers can be inserted either per interval or per second.

    • verbose name: Count Unit
    • default value: perinterval
    • port type: EnumPort
    • value type: str (can be None)
  • placement
    Marker placement/alignment scheme. Markers can be inserted into ranges either at equal (regular) distance from each other or at random positions. Where the markers get inserted relative to the time bounds can be set similarly to text alignment. Left-align inserts markers starting from initial time bound and continues at precise spacing specified using the number of 'markers to insert' and 'count unit' parameters above. For example, if 'markers to insert'=0.5 and 'count unit'=persecond (meaning 1 marker every 2 seconds) in 'time limit'=[0, 7] seconds window, inserted markers would be placed every 2 seconds at t=0, 2, 4, and 6 seconds. Right-align would insert markers starting at the end time bound and continue backwards in 2 second intervals at t=1, 3, 5, and 7 seconds. Center-align would insert markers from the center of the time bounds outwards at t=1.5, 3.5, and 5.5 seconds. Justified would insert makers at evenly spaced intervals (at least 2 seconds apart) starting and ending precisely at both time bound endpoints at t=0, 2.33, 4.67, and 7 seconds.

    • verbose name: Spacing And Alignment Between Inserted Markers
    • default value: justified
    • port type: EnumPort
    • value type: str (can be None)
  • random_seed
    Random seed (for random placement).

    • verbose name: Random Seed
    • default value: 12345
    • port type: IntPort
    • value type: int (can be None)
  • extra_limits
    Extra time limits. These are additional absolute time limits outside of which markers will never be generated (in seconds). Can be used to drop markers outside a particular segment in a recording. Ignored if unspecified.

    • verbose name: Extra Limits
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • min_length
    Minimum insertion range length. Ranges shorter than this will be dropped (mostly relevant for marker-spanned mode). Ignored if unspecified

    • verbose name: Min Range Length
    • default value: None
    • port type: FloatPort
    • value type: float (can be None)
  • max_length
    Maximum insertion range length. Ranges longer than this will be dropped (mostly relevant for marker-spanned mode). Ignored if unspecified.

    • verbose name: Max Range Length
    • default value: None
    • port type: FloatPort
    • value type: float (can be None)
  • marker_locked_indices
    Indices of markers to use as targets in marker-locked mode. Use negative numbers to count backwards from the end. i.e., [0, -1] will insert markers using the first and last instances of the target anchor-marker only.

    • verbose name: Marker Locked Indices
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • payload_old
    Legacy name for the marker to insert port. Do not use

    • verbose name: Marker Type/payload To Insert
    • default value: None
    • port type: AliasPort
    • value type: object (can be None)
  • verbose
    Enable verbose output.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

RemoveIntersectingMarkerSpans

Remove spans of markers that intersect signal boundaries.

This node identifies spans of markers that are delimited by a start marker and a subsequent end marker (e.g., trial_start and trial_end). The node will then check if the signal between those markers has any gaps (e.g., due to packet loss, or artifacts having been removed, for example using the RemoveBadTimeWindows node), and if it finds them, it will remove the start and end markers, and optionally remove some or all in-between markers; see remove_markers property). This can be used to remove all markers for a trial containing a gap ("bad trial"). You can also specify a time offset for the start and/or end markers, where the search for gaps will begin and end. For example, specifying these as -0.5 and 0.2, respectively, will search for gaps within a span that starts 0.5 seconds before the start marker and ends 0.2 seconds after the end marker. A common use case for this is to remove trials with a stimulus and response marker, where the trial length is not fixed but relative to the response marker (i.e., next trial begins immediately after the response marker). One of the main uses of this node is in combination with the Segmentation node: in a case where one segments around multiple places in a trial (e.g., stimulus and response), this will involve two uses of the Segmentation node. However, if the trial contains a gap on only one of the segments (e.g., near the stimulus but not near the response), then only one of the segments gets dropped by the Segmentation node, and one ends up with different numbers of trials in the two pathways. By preceding instead removing the entire trial if it contains any gap anywhere, it can be ensured that the Segmentation nodes will yield the same number of retained trials. This node acts on continuous data, not epoched data, and does not remove any signal data. It simply removes markers which would otherwise be used to segment the data into trials (epochs) using the Segmentation node (usually in combination with AssignTargetValues to identify the markers to segment on).

Version 0.6.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • start_marker
    Marker that indicates the beginning of a span.

    • verbose name: Start Marker
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • end_marker
    Marker that indicates the end of a span.

    • verbose name: End Marker
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • remove_markers
    List of markers to remove from the span. Use the special symbols $start and $end to refer to those defined above. Use * to refer to any marker. So $start, *, $end will remove all markers in the span including the start and end markers, whereas * will remove all markers in the span but not the start and end markers. $start, $end will only remove the start and end markers and leave the others in the span untouched. You can also list specific markers to remove by marker string (i.e., $start, left, right will remove all markers named left or right in the span to be checked, plus the start_marker.

    • verbose name: Remove Markers
    • default value: ['$start', '*', '$end']
    • port type: ListPort
    • value type: list (can be None)
  • start_marker_offset
    Offset in seconds to add to the start marker, when determining the span to search. This can be a negative number.

    • verbose name: Start Marker Offset
    • default value: 0.0
    • port type: FloatPort
    • value type: float (can be None)
  • end_marker_offset
    Offset in seconds to add to the end marker, when determining the span to search. This can be a negative number.

    • verbose name: End Marker Offset
    • default value: 0.0
    • port type: FloatPort
    • value type: float (can be None)
  • max_gap_length
    Maximum length of time-stamp gaps that are allowed not considered a gap. If a gap between successive samples is larger than this duration in seconds, then any marker whose bounds intersect the gap will be dropped. Optional. Note that if your time stamps are jittered, this will generate a lot of false positives unless you use a very generous cutoff. You can use the DejitterTimestamps node early in the pipeline to remedy that.

    • verbose name: Max Gap Length
    • default value: 0.2
    • port type: FloatPort
    • value type: float (can be None)
  • cumulative_gap_length
    Cumulative gap length that is allowed. If the sum of all gaps between successive samples is larger than this duration in seconds, then any marker whose bounds intersect the gap will be dropped. Set at zero or empty to ignore. Note that this will subtract the expected time difference between samples based on the sampling rate, when calculating the total gap. Note that max_gap_length and cumulative_gap_length are not mutually exclusive.

    • verbose name: Cumulative Gap Length
    • default value: 0.0
    • port type: FloatPort
    • value type: float (can be None)
  • remove_other_markers
    Remove any other markers that lie within the affected segments.

    • verbose name: Remove Other Markers
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • handle_missing
    How to handle missing markers, that is, if the start_marker or end_marker is not found in the data. Ignore will silently pass the data through unchanged. Warn will pass the data through unchanged with a warning. Raise will raise an exception.

    • verbose name: Handle Missing
    • default value: raise
    • port type: EnumPort
    • value type: str (can be None)
  • verbose
    Print information about the markers removed.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

RemoveIntersectingMarkers

Remove markers whose neighborhoods intersect gaps in the data and/or specified other markers.

This node can be useful when segments are extracted relative to event markers, and some of these segments may intersect these gaps. The Segmentation node will then drop any segments that cross gaps (since all segments emitted by it must have the same length, i.e., number of samples), and therefore the number of segments retained will be lower than the number of event markers to begin with. For a single Segmentation run this works fine, but if one uses multiple Segmentation operations in parallel with different segment lengths, then one may end up with different numbers of trials in the resulting data. This can be a problem if you then wish to concatenate the segments. This node can be used to prevent that case, since it removes any markers where the surrounding time bounds interset gaps in the data (i.e., as a result of cleaning the data using BadTimeWindowRemoval or because there were breaks in the original signal. Then Segmentation runs are guaranteed to produce the same number of segments. Typically you would want to use AssignTargetValues before this node, and then only those markers that have been assigned a target value will be considered for removal, since Segmentation will only act on those markers (all other event markers will be ignored). Otherwise, all markers will be checked for removal using the specified time bounds. In some cases you also want to remove all markers that fall within the time segment of a marker having a TargetValue that is removed. This is useful if you will be segmenting separately on different markers and want to ensure that markers belonging to the same trial or epoch (i.e., a stim and response marker) are both removed if one is removed. In such a case, you would assign target values to the stim markers, set the time bounds in this node to the full length of the trial/epoch, and set the remove_non_targets flag to True. This will ensure that if a stim marker is removed its corresponding response marker, if any, or any other markers in the trial, will also be removed. You can then assign target values to the (remaining) response markers and segment on the stim and response markers separately and they will be guaranteed to match up.

Version 1.1.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • time_bounds
    Time limits around the markers that are checked for intersection with gaps, in seconds. The first number is the start time of the range relative to each marker, and the second number is the end time of the range. If any of these numbers is negative, it means that the time point lies this many seconds before the marker, while positive numbers mean that the point lies after the marker. So a range of [-2,2] means that any markers that are within 2 seconds of a marker will be dropped from the data, along with the marker itself, if there are gaps in the signal data within that time range. Important: if you use AssignTargets before this node, then only markers with an assigned target will be considered. To drop all markers that fall within this scope relative to markers with an assigned target value, set remove_non_targets to True.

    • verbose name: Marker Safety Bounds
    • default value: [-1, 2]
    • port type: ListPort
    • value type: list (can be None)
  • max_gap_length
    Maximum length of time-stamp gaps that are allowed not considered a gap. If a gap between successive samples is larger than this duration in seconds, then any marker whose bounds intersect the gap will be dropped. Optional. Note that if your time stamps are jittered, this will generate a lot of false positives unless you use a very generous cutoff. You can use the DejitterTimestamps node early during your processing to fix that.

    • verbose name: Max Gap Length
    • default value: 0.2
    • port type: FloatPort
    • value type: float (can be None)
  • remove_non_targets
    If False, only markers that have been assigned a TargetValue will be considered for removal. If True, all markers which fall within the specified time bounds of a marker having a TargetValue, will be removed if the TargetValue marker is removed (i.e., in the event the latter intersects with a time gap).

    • verbose name: Remove Non Targets
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • sample_offset
    Optional additional shift of the bounds position, in samples. This setting allows to shift all bounds by this many samples relative to the marker, which can be used to match the behavior of other systems (e.g., BCILAB or EEGLAB) in a sample-exact fashion. Same as in the Segmentation node.

    • verbose name: Additional Sample Offset
    • default value: 0
    • port type: IntPort
    • value type: int (can be None)
  • avoid_markers
    List of markers to avoid. Markers are removed whose neighborhoods cross any of these markers to avoid. Wildcards may be used.

    • verbose name: Avoid Markers
    • default value: None
    • port type: ListPort
    • value type: list (can be None)
  • verbose
    If True, print out additional information about the markers that are removed.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

RewriteMarkers

Rewrite, and optionally select, event markers according to one or more mapping rules.

This node allows one to rewrite one or more event markers to new markers. The node also optionally allows to use pattern-matching syntax, including wildcard syntax and regular expression syntax, which allows to match a large set of markers and then to remap those to a simpler, canonical marker name. An empty dictionary {} in the rewriting rules field will skip this node. You can also choose to drop all markers not matching the rewrite rules, effectively selecting only matching markers.

Version 0.9.3

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • rules
    Event marker rewriting rules. This is given as one or more mappings of some input marker string(s) or pattern(s) to some specific output marker string. This is given as in {some_input_markers1: 'mynewmarker1', some_input_marker2: 'mynewmarker2'}, where some_input_markers can be either a plain string, if just one marker shall be rewritten to a given new output marker, or a string pattern with * and/or ? wildcard characters (wildcard pattern syntax), or a regular expression (regex pattern syntax). It is also possible to use a list of input markers in round braces, as in {('myoldmarkerA', 'myoldmarkerB'): 'mynewmarker', ...}, or a list of string patterns. Pro Tip: if the input and output are identical no rewriting will take place. Use this combined with the 'remove all others' option to drop all markers except those matching the rewrite rule, without doing any actual rewriting. (Use regex as the pattern syntax to retain all markers that match a particular regex pattern.)

    • verbose name: Rewriting Rule
    • default value: {}
    • port type: Port
    • value type: object (can be None)
  • pattern_syntax
    Optionally the syntax to use for the input marker patterns. If set to none, the input strings are not used as patterns but used to match a specific marker string verbatim. If set to wildcards, then the special character * can be used to match any number of characters (or none), while the character ? can be used to match any single character.

    • verbose name: Pattern Syntax
    • default value: wildcards
    • port type: EnumPort
    • value type: str (can be None)
  • regex_sub
    Check this box if you want to use regex substitution with groups. Remember to escape any groups like this: \2 instead of `````.

    • verbose name: Regex Sub
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • remove_all_others
    Remove all other markers. If enabled, all markers other than those matched by the rules will be removed from the data.

    • verbose name: Remove All Others
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • iv_column
    If the marker stream instance axis data is a recarray then here we choose which field of the recarray to use for mapping. If the marker stream instance axis data is an array of strings then this field does nothing.

    • verbose name: Iv Column
    • default value: Marker
    • port type: StringPort
    • value type: str (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

SelectMarkerSpans

Keep or discard spans of data (along time) relative to markers.

This node is not applicable to streaming data, that is, you can only apply it to whole recordings like those imported by one of the import nodes. The criteria supported by this node are quite sophisticated, and it is for instance possible to select spans relative to other markers, or between pairs of other markers.

Version 0.9.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • operation
    Operation to perform for the respective spans. Keep retains only the data in the spans, and discard retains only the data outside the spans.

    • verbose name: Operation
    • default value: keep
    • port type: EnumPort
    • value type: str (can be None)
  • mode
    Type of interval. Intervals can be relative to reference events of a certain type (marker-locked), or in time window spanned by two subsequent events of certain types A and B, optionally with ignored events in between (marker-spanned).

    • verbose name: Span Mode
    • default value: marker-locked
    • port type: EnumPort
    • value type: str (can be None)
  • time_limits
    Lower and upper time limit for the span(s) (in seconds). In absolute mode, this is the beginning and end of the time range, regardless of where the signal (if any) begins or ends (unless you know the begin/end time of the signal, using this rarely makes sense); in relative mode, this range is instead relative to the range covered by the signal, where positive numbers count from the beginning of the data, and negative numbers count from the end (e.g., [10, -5] inserts 10 seconds after the beginning up to 5 seconds prior to the end). An empty interval (i.e., []) in this mode is interpreted as the whole data range. In marker-locked mode, this is the beginning and end of the span generated relative to each marker (i.e., [-1, 2] would begin 1 second before each marker and end 2 seconds after). In marker-spanned mode, for every matching pair of successive markers of types A and B, the range begins x seconds relative to A and ends y seconds relative to B if the time limits are [x, y]. Marker A is called the anchor marker, and marker B is called the second anchor marker in the subsequent settings.

    • verbose name: Time Limits
    • default value: [0, 1]
    • port type: ListPort
    • value type: list (can be None)
  • anchor_markers
    Marker/event type relative to which spans shall be generated. Applies to marker-locked and marker-spanned mode. If mode is marker-spanned, this is the first marker in a pair of successive markers (referred to as A in other places of the node documentation), while the second marker is given by the second anchor marker. If multiple are given, each marker generates a separate span, and in marker-spanned mode, there must be the same count of anchor_markers_B entries.

    • verbose name: Anchor Marker(S)
    • default value: ['myeventA']
    • port type: ListPort
    • value type: list (can be None)
  • anchor_marker_B
    Second anchor marker (B) if span mode is marker-spanned. This marker indicates the end of a spanned range. If spans relative to multiple pairs of marker types shall be generated, this must have the same number of entries as anchor_markers.

    • verbose name: Second Anchor Marker(S) (Spanned Mode)
    • default value: ['myeventB']
    • port type: ListPort
    • value type: list (can be None)
  • intermittent_markers
    If in spanned mode, this determines how to handle intermittent markers that occur between successive markers A and B by default. If set to allow, any marker type may occur between marker A and the next marker B, and a spanned range will still be generated. If set to forbid, no other marker may occur in between, or else the spanned range will not be generated. Exceptions can be listed in the below parameter for exceptions to this setting.

    • verbose name: Handling Of Intermittent Markers (Spanned Mode)
    • default value: allow
    • port type: EnumPort
    • value type: str (can be None)
  • except_markers
    List of markers types for which to make an exception from the default chosen in intermittent markers. For instance, if the default is allow, then the marker types in this list will be forbidden, and if the default is forbid, then the marker types in this list will be allowed.

    • verbose name: Exceptions To Intermittent Markers (Spanned Mode)
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • min_length
    Minimum span length. Ranges shorter than this will be dropped (mostly relevant for marker-spanned mode).

    • verbose name: Min Range Length
    • default value: 0
    • port type: FloatPort
    • value type: float (can be None)
  • max_length
    Maximum span length. Ranges longer than this will be dropped (mostly relevant for marker-spanned mode).

    • verbose name: Max Range Length
    • default value: inf
    • port type: FloatPort
    • value type: float (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

StripLongMarkers

Removes (replaces) event markers that exceed a maximum length.

Version 0.5.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • removed
    Stripped markers.

    • verbose name: Removed
    • default value: None
    • port type: DataPort
    • value type: list (can be None)
    • data direction: OUT
  • max_length
    Maximum marker length.

    • verbose name: Max Length
    • default value: 512
    • port type: IntPort
    • value type: int (can be None)
  • replace_with
    Replace removed markers with this string.

    • verbose name: Replace With
    • default value: (removed-marker-too-long)
    • port type: StringPort
    • value type: str (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

TrimMarkerSegment

Trim data before and after specified begin/end markers.

The incoming data must have a time axis and a marker stream with an instance axis. Data is trimmed along the time axis based on the timestamps of the given markers.

Version 1.6.1

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • stream
    Name of event stream containing the markers to trim by. Wildcards are supported.

    • verbose name: Stream
    • default value: markers
    • port type: StringPort
    • value type: str (can be None)
  • stream_name

    • verbose name: Stream Name
    • default value: None
    • port type: AliasPort
    • value type: str (can be None)
  • event_start
    Name of starting event marker. If empty, data will be retained from the start of the data until the event_end marker. Special case: use '*' to indicate any marker.

    • verbose name: Event Start
    • default value: start
    • port type: StringPort
    • value type: str (can be None)
  • start_occurrence
    In case of multiple 'event_start' markers, index of desired marker occurrence (0 is first ooccurrence, -1 is last ooccurrence, -2 is second to last, etc.) .

    • verbose name: Start Occurrence
    • default value: 0
    • port type: IntPort
    • value type: int (can be None)
  • before_start_time
    Time in seconds before the starting event marker at which to trim. A value of

    • verbose name: Before Start Time
    • default value: 0
    • port type: FloatPort
    • value type: float (can be None)
  • event_end
    Name of ending event marker. If empty, data will be retained " from the event_start marker to the end of the data. Special case: use '*' to indicate any marker.

    • verbose name: Event End
    • default value: end
    • port type: StringPort
    • value type: str (can be None)
  • end_occurrence
    In case of multiple 'event_end' markers, index of desired marker occurrence (0 is first ooccurrence, -1 is last ooccurrence, -2 is second to last, etc.) .

    • verbose name: End Occurrence
    • default value: -1
    • port type: IntPort
    • value type: int (can be None)
  • after_end_time
    Time in seconds to after the named event marker when at which to trim. A value of 0 will trim at the event marker.

    • verbose name: After End Time
    • default value: 0
    • port type: FloatPort
    • value type: float (can be None)
  • trim_marker_streams
    Also trim all marker streams to the same time range.

    • verbose name: Trim Marker Streams
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • drop_markers_in_trimmed_span
    Deprecated (does nothing); use trim_marker_streams instead.

    • verbose name: Drop Markers In Trimmed Span
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • on_missing_events
    Determines how to handle cases whether either the start or the end marker, or both, cannot be found. If 'raise-error', an Exception is raised and the pipeline stops. If 'return-none', the node passes on None as its data output. If 'one-sided' a one-sided trim is allowed, meaning that if the start marker is missing, data will be selected from the start of the data, and if the end marker is missing, data will be selected to the end of the data, without raising an error. Lastly, 'return-all' will return all the data if both markers are missing. The latter replaces the previous functionality of the ignore_errors param, which is deprecated. A log message warning of the missing marker(s) will be printed in any case.

    • verbose name: On Missing Events
    • default value: raise-error
    • port type: EnumPort
    • value type: str (can be None)
  • ignore_errors
    Continue operation if no data is found between the given markers. If True, a warning message will be printed. If False, an exception will be raised.

    • verbose name: Ignore Errors
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • verbose
    Show informational messages.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)