← markers package

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.1

Ports/Properties

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)

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)