pymovements.gaze.from_asc#

pymovements.gaze.from_asc(file: str | Path, *, patterns: str | list[dict[str, Any] | str] | None = None, metadata_patterns: list[dict[str, Any] | str] | None = None, schema: dict[str, Any] | None = None, experiment: Experiment | None = None, trial_columns: str | list[str] | None = None, add_columns: dict[str, str] | None = None, column_schema_overrides: dict[str, Any] | None = None, encoding: str | None = None, definition: pm.DatasetDefinition | None = None) → GazeDataFrame[source]#

Initialize a pymovements.gaze.GazeDataFrame.

Parameters:

  • file (str | Path) – Path of IPC/feather file.

  • patterns (str | list[dict[str, Any] | str] | None) – List of patterns to match for additional columns or a key identifier of eye tracker specific default patterns. Supported values are: ‘eyelink’. If None is passed, ‘eyelink’ is assumed. (default: None)

  • metadata_patterns (list[dict[str, Any] | str] | None) – List of patterns to match for extracting metadata from custom logged messages. (default: None)

  • schema (dict[str, Any] | None) – Dictionary to optionally specify types of columns parsed by patterns. (default: None)

  • experiment (Experiment | None) – The experiment definition. (default: None)

  • trial_columns (str | list[str] | None) – The names of the columns (extracted by patterns) to use as trial columns. If the list is empty or None, the asc file is assumed to contain only one trial. If the list is not empty, the asc file is assumed to contain multiple trials and the transformation methods will be applied to each trial separately. (default: None)

  • add_columns (dict[str, str] | None) – Dictionary containing columns to add to loaded data frame. (default: None)

  • column_schema_overrides (dict[str, Any] | None) – Dictionary containing types for columns. (default: None)

  • encoding (str | None) – Text encoding of the file. If None, the locale encoding is used. (default: None)

  • definition (pm.DatasetDefinition | None) – A dataset definition. Explicitly passed arguments take precedence over definition. (default: None)

Returns:

The gaze data frame read from the asc file.

Return type:

GazeDataFrame

Examples

Let’s assume we have an EyeLink asc file stored at tests/files/eyelink_monocular_example.asc. We can then load the data into a GazeDataFrame:

>>> from pymovements.gaze.io import from_asc
>>> gaze = from_asc(file='tests/files/eyelink_monocular_example.asc')
>>> gaze.frame
shape: (16, 3)
┌─────────┬───────┬────────────────┐
│ time    ┆ pupil ┆ pixel          │
│ ---     ┆ ---   ┆ ---            │
│ i64     ┆ f64   ┆ list[f64]      │
╞═════════╪═══════╪════════════════╡
│ 2154556 ┆ 778.0 ┆ [138.1, 132.8] │
│ 2154557 ┆ 778.0 ┆ [138.2, 132.7] │
│ 2154560 ┆ 777.0 ┆ [137.9, 131.6] │
│ 2154564 ┆ 778.0 ┆ [138.1, 131.0] │
│ 2154596 ┆ 784.0 ┆ [139.6, 132.1] │
│ …       ┆ …     ┆ …              │
│ 2339246 ┆ 622.0 ┆ [629.9, 531.9] │
│ 2339271 ┆ 617.0 ┆ [639.4, 531.9] │
│ 2339272 ┆ 617.0 ┆ [639.0, 531.9] │
│ 2339290 ┆ 618.0 ┆ [637.6, 531.4] │
│ 2339291 ┆ 618.0 ┆ [637.3, 531.2] │
└─────────┴───────┴────────────────┘
>>> gaze.experiment.eyetracker.sampling_rate
1000.0
On this page

This Page