segmentation2events#

pymovements.events.segmentation.segmentation2events(segmentation: Series | ndarray, name: str, time_column: Series | ndarray | None = None, trial_columns: DataFrame | None = None) → DataFrame[source]#

Convert a binary segmentation map to a list of events.

This function identifies continuous regions of 1’s in the segmentation array and converts them to event onset and offset pairs. The onset and offset are both inclusive, matching the convention used in events2segmentation().

Parameters:

  • segmentation (pl.Series | np.ndarray) – A 1D binary array or Series where 1 or True indicates an event and 0 or False indicates no event. Must contain only values 0, 1, True or False.

  • name (str) – The name of the event type to use for the ‘name’ column in the output DataFrame.

  • time_column (pl.Series | np.ndarray | None) – The values to use for the onset and offset columns. If provided, the values of the events will be mapped to the values in this column. If None, the indices themselves will be used. Default is None.

  • trial_columns (pl.DataFrame | None) – A DataFrame containing trial identifiers for each sample. If provided, events will be identified within each trial separately. Default is None.

Returns:

A DataFrame containing the onset and offset of each event. The onset and offset are both inclusive. Onsets and offsets correspond to the values in time_column if provided, otherwise they are indices of the input segmentation array.

Return type:

pl.DataFrame

Raises:

  • ValueError – If segmentation is not a 1D array. If segmentation contains values other than 0 and 1. If time_column length does not match segmentation length. If trial_columns length does not match segmentation length.

  • TypeError – If segmentation is not a polars.Series or numpy.ndarray.

Notes

The onset and offset are both inclusive. For example, a sequence of ones from index 2 to 4 results in an onset of 2 and an offset of 4.

The returned onset and offset values represent the values in the time_column (if provided) or the indices of the segmentation array where an event starts and ends.

Warning

The offset is considered inclusive. This means that the sample at the offset value is part of the event.

Examples

>>> import polars as pl
>>> from pymovements.events import segmentation2events
>>> segmentation = pl.Series([0, 0, 1, 1, 1, 0, 0, 1, 1, 0])
>>> segmentation2events(segmentation, name='blink')
shape: (2, 3)
┌───────┬───────┬────────┐
│ name  ┆ onset ┆ offset │
│ ---   ┆ ---   ┆ ---    │
│ str   ┆ i64   ┆ i64    │
╞═══════╪═══════╪════════╡
│ blink ┆ 2     ┆ 4      │
│ blink ┆ 7     ┆ 8      │
└───────┴───────┴────────┘
>>> # Using a time column:
>>> time = pl.Series([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0])
>>> segmentation2events(segmentation, name='blink', time_column=time)
shape: (2, 3)
┌───────┬───────┬────────┐
│ name  ┆ onset ┆ offset │
│ ---   ┆ ---   ┆ ---    │
│ str   ┆ f64   ┆ f64    │
╞═══════╪═══════╪════════╡
│ blink ┆ 0.3   ┆ 0.5    │
│ blink ┆ 0.8   ┆ 0.9    │
└───────┴───────┴────────┘