pymovements.gaze.GazeDataFrame#

class pymovements.gaze.GazeDataFrame(data: pl.DataFrame | None = None, experiment: Experiment | None = None, *, trial_columns: str | list[str] | None = None, time_column: str | None = None, pixel_columns: list[str] | None = None, position_columns: list[str] | None = None, velocity_columns: list[str] | None = None, acceleration_columns: list[str] | None = None)[source]#

A DataFrame for gaze time series data.

Each row is a sample at a specific timestep. Each column is a channel in the gaze time series.

__init__(data: pl.DataFrame | None = None, experiment: Experiment | None = None, *, trial_columns: str | list[str] | None = None, time_column: str | None = None, pixel_columns: list[str] | None = None, position_columns: list[str] | None = None, velocity_columns: list[str] | None = None, acceleration_columns: list[str] | None = None)[source]

Initialize a pymovements.gaze.gaze_dataframe.GazeDataFrame.

Parameters:

  • data (pl.DataFrame) – A dataframe to be transformed to a polars dataframe.

  • experiment (Experiment) – The experiment definition.

  • time_column – The name if the timestamp column in the input data frame.

  • pixel_columns – The name of the pixel position columns in the input data frame.

  • position_columns – The name of the dva position columns in the input data frame.

  • velocity_columns – The name of the dva velocity columns in the input data frame.

  • acceleration_columns – The name of the dva acceleration columns in the input data frame.

Notes

About using the arguments pixel_columns, position_columns, velocity_columns, and acceleration_columns:

By passing a list of columns as any of these arguments, these columns will be merged into a single column with the corresponding name , e.g. using pixel_columns will merge the respective columns into the column pixel.

The supported number of component columns with the expected order are:

  • two columns: monocular data; expected order: x-component, y-component

  • four columns: binocular data; expected order: x-component left eye, y-component left eye, x-component right eye, y-component right eye,

  • six columns: binocular data with additional cyclopian data; expected order: x-component left eye, y-component left eye, x-component right eye, y-component right eye, x-component cyclopian eye, y-component cyclopian eye,

Examples

First let’s create an example DataFrame with three columns: the timestamp t and x and y for the pixel position.

>>> df = pl.from_dict(
...     data={'t': [1000, 1001, 1002], 'x': [0.1, 0.2, 0.3], 'y': [0.1, 0.2, 0.3]},
... )
>>> df
shape: (3, 3)
┌──────┬─────┬─────┐
│ t    ┆ x   ┆ y   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ f64 │
╞══════╪═════╪═════╡
│ 1000 ┆ 0.1 ┆ 0.1 │
│ 1001 ┆ 0.2 ┆ 0.2 │
│ 1002 ┆ 0.3 ┆ 0.3 │
└──────┴─────┴─────┘

We can now initialize our GazeDataFrame by specyfing the names of the pixel position columns.

>>> gaze = GazeDataFrame(data=df, pixel_columns=['x', 'y'])
>>> gaze.frame
shape: (3, 2)
┌──────┬────────────┐
│ t    ┆ pixel      │
│ ---  ┆ ---        │
│ i64  ┆ list[f64]  │
╞══════╪════════════╡
│ 1000 ┆ [0.1, 0.1] │
│ 1001 ┆ [0.2, 0.2] │
│ 1002 ┆ [0.3, 0.3] │
└──────┴────────────┘

Methods

__init__([data, experiment, trial_columns, ...])

Initialize a pymovements.gaze.gaze_dataframe.GazeDataFrame.

nest(input_columns, output_column)

Nest component columns into a single tuple column.

pix2deg()

Compute gaze positions in degrees of visual angle from pixel position coordinates.

pos2acc(*[, degree, window_length, padding])

Compute gaze acceleration in dva/s^2 from dva position coordinates.

pos2vel([method])

Compute gaze velocity in dva/s from dva position coordinates.

transform(transform_method, **kwargs)

Apply transformation method.

unnest(column, output_columns)

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

Attributes

columns

List of column names.

schema

Schema of event dataframe.

valid_acceleration_columns

valid_pixel_position_columns

valid_position_columns

valid_velocity_columns