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, events: bool = False) → Gaze[source]#

Initialize a Gaze.

Parameters:

  • file (str | Path) – Path of ASC 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)

  • events (bool) – Flag indicating if events should be parsed from the asc file. (default: False)

Returns:

The initialized gaze object read from the asc file.

Return type:

Gaze

Notes

ASC files are created from EyeLink EDF files using the edf2asc tool (can be downloaded from the SR Research Support website). ASC files contain gaze samples, events, and metadata about the experiment in a text (ASCII) format. For example, if you have an Eyelink EDF file stored at tests/files/eyelink_monocular_example.edf, you can convert it to an ASC file using the following command: edf2asc tests/files/eyelink_monocular_example.edf. This will create an ASC file named tests/files/eyelink_monocular_example.asc.

Running edf2asc with the default settings (no flags/parameters) will always produce an ASC file that can be read by this function, although currently only monocular recordings are supported. If a binocular ASC file is provided, only the left eye data will be read. If you want to use right eye data, you can use the -r or -nl edf2asc flags to get an ASC file with only right eye data. Additionally, the following optional edf2asc parameters/flags are safe to use and will also result in an ASC file that can be read by this function:

  • -input for writing the status of the Host PC parallel port to the ASC file (although these values will not be read).

  • -ftime for outputting time as a floating point value.

  • -t for using only tabs as delimiters.

  • -utf8 for forcing UTF-8 encoding of the ASC file.

  • -buttons for outputting button values in samples (although these values will not be read).

  • -vel and -fvel for outputting velocity values (although these values will not be read).

  • -l or -nr and -r or -nl for outputting left and right eye data only in case of a binocular file (this is currently the only way to access right eye data).

  • -avg for outputting average values of the left and right eye data in case of a binocular file (although these will not be read).

Using other edf2asc parameters may lead to errors or unexpected behavior. For example, using -e or -ns to output only events or -s or -ne to only output samples will not work with this function, as it expects both samples and events to be present in the ASC file.

Examples

We can load an asc file stored at tests/files/eyelink_monocular_example.asc into a Gaze:

>>> from pymovements.gaze.io import from_asc
>>> gaze = from_asc(file='tests/files/eyelink_monocular_example.asc')
>>> gaze.samples
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