pymovements.events.EventDataFrame

class pymovements.events.EventDataFrame(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)

A DataFrame 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.

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 = EventDataFrame(
...    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      │
└──────────┴─────────┴─────────┴──────────┘

__init__(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)

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.
copy()	Return a copy of the EventDataFrame.
map_to_aois(aoi_dataframe)	Map events to aois.
split(by)	Split the EventDataFrame 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.