eyekit.io API documentation
Description: Functions for reading and writing data.

# Module `eyekit.io`

Functions for reading and writing data.

View code on GitHub

## Functions

`def load(file_path)`

  Read in a JSON file. `FixationSequence` and `TextBlock` objects are automatically decoded and instantiated.

  View code on GitHub
`def save(data, file_path, *, compress: bool = False)`

  Write arbitrary data to a JSON file. If `compress` is `True`, the file is written in the most compact way; if `False`, the file will be more human readable. `FixationSequence` and `TextBlock` objects are automatically encoded.

  View code on GitHub
`def import_asc(file_path, *, variables: list = [], placement_of_variables: str = 'after_end', import_samples: bool = False, encoding: str = 'utf-8') ‑> list`

  Import data from an ASC file produced from an SR Research EyeLink device (you will first need to use SR Research's Edf2asc tool to convert your original EDF files to ASC). The importer will extract all trials from the ASC file, where a trial is defined as a sequence of fixations (EFIX lines) that occur inside a START–END block. Optionally, the importer can extract user-defined variables and ms-by-ms samples. For example, if your ASC file contains messages like this:

      MSG 4244101 trial_type practice
      MSG 4244101 passage_id 1
      MSG 4244592 stim_onset

  then you could extract the variables `"trial_type"` and `"passage_id"`. A variable is some string that is followed by a space; anything that follows this space is the variable's value. If the variable is not followed by a value (e.g., `"stim_onset"` above), then the time of the message is recorded as its value; this can be useful for recording the precise timing of an event. By default, the importer looks for variables that follow the END tag. However, if your variables are placed before the START tag, then set the `placement_of_variables` argument to `"before_start"`. If unsure, you should first inspect your ASC file to see what messages you wrote to the data stream and where they are placed. The importer will return a list of dictionaries, where each dictionary represents a single trial and contains the fixations along with any other extracted variables. For example:

      [
          {
              "trial_type": "practice",
              "passage_id": "1",
              "stim_onset": 4244592,
              "fixations": FixationSequence[...]
          },
          {
              "trial_type": "test",
              "passage_id": "2",
              "stim_onset": 4256311,
              "fixations": FixationSequence[...]
          }
      ]

  View code on GitHub
`def import_csv(file_path, *, x_header: str = 'x', y_header: str = 'y', start_header: str = 'start', end_header: str = 'end', trial_header: str = None, encoding: str = 'utf-8') ‑> list`

  Import data from a CSV file. By default, the importer expects the CSV file to contain the column headers, `x`, `y`, `start`, and `end`, but this can be customized by setting the relevant arguments to whatever column headers your CSV file contains. Each row of the CSV file is expected to represent a single fixation. If your CSV file contains data from multiple trials, you should also specify the column header of a trial identifier, so that the data can be segmented into trials. The importer will return a list of dictionaries, where each dictionary represents a single trial and contains the fixations along with the trial identifier (if specified). For example:

      [
          {
              "trial_id" : 1,
              "fixations" : FixationSequence[...]
          },
          {
              "trial_id" : 2,
              "fixations" : FixationSequence[...]
          }
      ]

  View code on GitHub
`def read(file_path)`

  Deprecated in 0.4 and removed in 0.6. Use `load()`.

  View code on GitHub
`def write(data, file_path, compress=False)`

  Deprecated in 0.4 and removed in 0.6. Use `save()`.

  View code on GitHub