← formatting package

Segmentation

Cut fixed-length segments out of a continuous time series.

This node requires input data that has both a multi-channel time-series stream (channels by samples), and a marker stream in it. The node will then cut out a segment around each marker of interest, and return a packet that is a multi-dimensional array of same-length segments, i.e., time x space x instance, where the instance axis represents the segments (trials or epochs). Important: Note that the markers of interest must first be flagged as "target markers", using the AssignTargetValues node (usually segments are extracted around a subset of marker types), which is typically placed before this node in the pipeline. The data that comes out of this node is no longer a continuous time series, but instead is now segmented. The resulting data array has a new "instance" axis that indexes the segments. This processing step is also called epoching in some other frameworks (e.g., EEGLAB), and the segments are typically called "epochs" or "trials" (we use the term "trials" throughout NeuroPype documentation). This node will work both on packets that contain an entire recording ("offline data"), which it extracts one segment for each target marker in the recording, as well as as on packets from streaming data. For offline data, markers that would result in segments that extend beyond data limits are ignored; see RemoveIntersectingMarkers node to remove these markers prior to Segmentation. For streaming data, the node consumes chunks and emits segments as soon as all the data that is overlapped by the segment has been received ( therefore, for a given nonempty input chunk, this node may output zero, one, or more segments). There is also an optional mode that extracts a single sliding segment on each update that lies at the end of the data received by the node (see online segmentation mode parameter). The new segments receive new time stamps that are relative to the marker around which they were originally extracted (i.e., the part of the segment that lies before the marker, if any, will have negative time stamps). The absolute time of the marker is stored as well, though (so no information is lost). The newly added instance axis data has a data field which holds an array of independent variables (IVs) for each trial. Default columns include Marker, TargetValue, TrialIndex, and optionally Subject and Session if the latter are defined in the Origin.subject_id and Origin.session_id of the stream properties (see SetStreamProperties). Trials can be selected by IV using the SelectInstances node downstream. The marker stream is dropped by default (unless keep_marker_chunk is set to True), as it is typically no longer needed. Version 1.0.5

Ports/Properties

data

Data to segment.

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

time_bounds

Time limits for extracted segments, relative to the position of the marker, in seconds. For each target marker, a segment will be extracted around it, and the beginning and end of the segment is given by these two values (e.g., [-1, 2] yields segments that begin one second before the marker and end two seconds after the marker). Segments may intersect the marker, or lie before it, or lie after it.

• verbose name: Segment Time Limits
• default value: [-1, 2]
• port type: ListPort
• value type: list (can be None)

select_markers

(Optional) Data will be segmented around these markers only. This is a list of marker strings. If this is not provided, but target values have been assigned to markers in a previous step (typically using the AssignTargets node), then segmentation will extract segments only around those markers that have target values set. Otherwise this node will fall back to all markers in the data, except for markers that are empty strings (e.g., scrubbed using some preceding marker rewriting node).

• verbose name: Select Markers
• default value: None
• port type: ListPort
• value type: list (can be None)

online_epoching

Online segment extraction mode. If this is set to marker-locked, then segments will be extracted the same way on streaming data ("online") as on non-streaming data such as imported recordings ("offline"). If this is set to sliding, then for online data, on each tick a single segment will be extracted that lies at the end of the data received by this node. This mode can be handy when the remainder of the pipeline is calibrated on data relative to markers, but during online processing the pipeline should produce outputs continuously, regardless of whether there is any marker or not.

• verbose name: Online Segmentation Mode
• default value: marker-locked
• port type: EnumPort
• value type: str (can be None)

sample_offset

Optional additional shift of the segment position, in samples. This setting allows to shift all segments 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.

• verbose name: Additional Sample Offset
• default value: 0
• port type: IntPort
• value type: int (can be None)

max_gap_length

Maximum length of time-stamp gaps that are allowed in segments. If a gap between successive samples is larger than this duration in seconds, then the affected segment is not extracted. 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. Set to 0 or empty (None) to disable.

• verbose name: Max Gap Length
• default value: 0.2
• port type: FloatPort
• value type: float (can be None)

keep_marker_chunk

Keep the markers within the segments/epochs in a stream named 'segmented-markers'. The original marker stream is dropped in all cases.

• verbose name: Keep Marker Stream
• default value: False
• port type: BoolPort
• value type: bool (can be None)

verbose

Verbose output. Can be used for debugging your pipeline.

• 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)