Events#

class pymovements.Events(data: pl.DataFrame | None = None, name: str | list[str] | None = None, onsets: list[int | float] | np.ndarray | None = None, offsets: list[int | float] | np.ndarray | None = None, trials: list[int | float | str] | np.ndarray | None = None, trial_columns: list[str] | str | None = None)[source]#

A data structure for event data.

Each row has at least an event name with its onset and offset specified.

Parameters:

  • data (pl.DataFrame | None) – A dataframe to be transformed to a polars dataframe. This argument is mutually exclusive with all the other arguments. (default: None)

  • name (str | list[str] | None) – Name of events. (default: None)

  • onsets (list[int | float] | np.ndarray | None) – List of onsets. (default: None)

  • offsets (list[int | float] | np.ndarray | None) – List of offsets. (default: None)

  • trials (list[int | float | str] | np.ndarray | None) – List of trial identifiers. (default: None)

  • trial_columns (list[str] | str | None) – List of trial columns in passed dataframe.

frame#

A dataframe of events.

Type:

pl.DataFrame

trial_columns#

The name of the trial columns in the data frame. If not None, processing methods will be applied to each trial separately.

Type:

list[str] | None

Raises:

ValueError – If list of onsets is passed but not a list of offsets, or vice versa, or if length of onsets does not match length of offsets.

Examples

We define an event dataframe with given names of events and lists of onsets and offsets. Durations are computed automatically.

>>> event = Events(
...    name=['fixation', 'fixation', 'fixation', 'fixation', ],
...    onsets=[1988147, 1988351, 1988592, 1988788],
...    offsets=[1988322, 1988546, 1988736, 1989013]
... )
>>> event
shape: (4, 4)
┌──────────┬─────────┬─────────┬──────────┐
│ name     ┆ onset   ┆ offset  ┆ duration │
│ ---      ┆ ---     ┆ ---     ┆ ---      │
│ str      ┆ i64     ┆ i64     ┆ i64      │
╞══════════╪═════════╪═════════╪══════════╡
│ fixation ┆ 1988147 ┆ 1988322 ┆ 175      │
│ fixation ┆ 1988351 ┆ 1988546 ┆ 195      │
│ fixation ┆ 1988592 ┆ 1988736 ┆ 144      │
│ fixation ┆ 1988788 ┆ 1989013 ┆ 225      │
└──────────┴─────────┴─────────┴──────────┘

Methods

__init__([data, name, onsets, offsets, ...])

add_event_properties(event_properties, join_on)

Add new event properties into dataframe.

add_trial_column(column, data)

Add new trial columns with constant values.

clone()

Return a copy of an Events object.

copy()

Return a copy of an Events object.

map_to_aois(aoi_dataframe)

Map events to aois.

split([by])

Split the Events into multiple frames based on specified column(s).

unnest()

Explode a column of type pl.List into one column for each list component.

Attributes

columns

List of column names.

event_property_columns

Event property columns for this dataframe.

schema

Schema of event dataframe.

frame

trial_columns