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, events: bool = False, messages: bool | list[str] = False, metadata: dict[str, Any] | None = None) → 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)

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

  • messages (bool | list[str]) – Flag indicating if any additional messages should be parsed from the asc file and stored in pymovements.gaze.experiment.Experiment. The message format is ‘MSG <timestamp> <content>’. If True, all available messages will be parsed from the asc, alternatively, a list of regular expressions can be passed, and only the messages that match any of the regular expressions will be kept. Regular expressions are only applied to the message content, implicitly parsing the MSG <timestamp> prefix. (default: False)

  • metadata (dict[str, Any] | None) – Dictionary containing additional metadata. (default: None)

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 from_asc().

Moreover, the following optional edf2asc parameters are safe to use and will also result in an ASC file that is compatible with from_asc():

  • -input: include the status of the Host PC parallel port (although the values will not be read by pymovements).

  • -ftime: format timestamps as floating point values.

  • -t: use only tabs as delimiters.

  • -utf8: force UTF-8 encoding.

  • -buttons: include button events (although the values will not be read by pymovements).

  • -vel and -fvel: include velocity values (although the values will not be read by pymovements).

  • -l or -nr: only include left eye data.

  • -r or -nl: only include right eye data.

  • -avg: include average values of the left and right eye data in case of a binocular file (although the values will not be read by pymovements).

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