pymovements.Gaze.split#
- Gaze.split(by: str | Sequence[str] | None = None, *, as_dict: Literal[False]) list[Gaze][source]#
- Gaze.split(by: Sequence[str] | None = None, *, as_dict: Literal[True]) dict[tuple[Any, ...], Gaze]
Split a single Gaze object into multiple Gaze objects based on specified column(s).
- Parameters:
by (str | Sequence[str] | None) – Column name(s) to split the DataFrame by. If a single string is provided, it will be used as a single column name. If a sequence is provided, the DataFrame will be split by unique combinations of values in all specified columns. If None, uses trial_columns. (default=None)
as_dict (bool) – Return a dictionary instead of a list. The dictionary keys are tuples of the distinct group values that identify each group split. (default: False)
- Returns:
A collection of new Gaze instances, each containing a partition of the original data with all metadata and configurations preserved.
- Return type:
Notes
The original gaze data and metadata are not modified; the method returns new Gaze objects.
Examples
First let’s create a simple samples dataframe:
>>> import numpy as np >>> import polars as pl >>> import pymovements as pm >>> samples = polars.from_dict( ... {'x': range(100), 'y': range(100), 'trial': np.repeat([1, 2, 3, 4, 5], 20)}, ... ) >>> samples shape: (100, 3) ┌─────┬─────┬───────┐ │ x ┆ y ┆ trial │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ ╞═════╪═════╪═══════╡ │ 0 ┆ 0 ┆ 1 │ │ 1 ┆ 1 ┆ 1 │ │ 2 ┆ 2 ┆ 1 │ │ 3 ┆ 3 ┆ 1 │ │ 4 ┆ 4 ┆ 1 │ │ … ┆ … ┆ … │ │ 95 ┆ 95 ┆ 5 │ │ 96 ┆ 96 ┆ 5 │ │ 97 ┆ 97 ┆ 5 │ │ 98 ┆ 98 ┆ 5 │ │ 99 ┆ 99 ┆ 5 │ └─────┴─────┴───────┘
Then let’s initialize our Gaze object:
>>> gaze = pm.Gaze(samples=samples, pixel_columns=['x', 'y'], trial_columns='trial') >>> gaze shape: (100, 2) ┌───────┬───────────┐ │ trial ┆ pixel │ │ --- ┆ --- │ │ i64 ┆ list[i64] │ ╞═══════╪═══════════╡ │ 1 ┆ [0, 0] │ │ 1 ┆ [1, 1] │ │ 1 ┆ [2, 2] │ │ 1 ┆ [3, 3] │ │ 1 ┆ [4, 4] │ │ … ┆ … │ │ 5 ┆ [95, 95] │ │ 5 ┆ [96, 96] │ │ 5 ┆ [97, 97] │ │ 5 ┆ [98, 98] │ │ 5 ┆ [99, 99] │ └───────┴───────────┘
Now we can split the gaze by the 5 unique trial column values into 5 separate objects:
>>> gazes = gaze.split(by='trial') >>> len(gazes) 5