Getting Started

While the calculations and outputs generated by SideEye can be customized, eye tracking experiment files can easily be processed with the sideeye script without additional configuration. To use this script you will need:

  • A region file (.cnt or .reg)
  • One or more .DA1 or .ASC files
  • A Configuration JSON file (optional)

Running the Script

After installing SideEye, open a Terminal or Command Prompt window and run the following command:

sideeye

A file selection window will prompt you for each of the necessary files. First is the configuration JSON file. If your DA1, ASC, or region files differ from the formats specified in the default configuration, use a custom configuration file. See The Configuration File for a full explanation. Otherwise, click “Cancel” and the default configuration will be used.

Next you will be prompted to select DA1 or ASC files. Select one or more files associated with the same experiment. See below for more detail on DA1 file formats.

The next file selection prompt is for a region file. Select the .reg or .cnt file associated with the experiment. See below for more detail on the types of region files.

Finally, enter an output file name. If SideEye is successful in processing your experiment, a CSV of all the measures calculated for each trial will be generated.

.DA1 File Formats

A .DA1 file describes the position and timing of fixations. Each line of the file represents a single trial in an experiment. The first fields in the line contain information identifying the trial. After these fields, fixations are represented by groups of four numbers - x-position, y-position, start time, and end time. Five fields are necessary for parsing a .DA1 file:

index: An integer identifying a single trial, usually the first number in the line.

condition: A value identifying the condition of the trial.

number: A value identifying the item of the trial.

time: The total time of a trial, sometimes either not included in DA1 files or at the end of every line. If this is true, this parameter should be -1.

fixation_start: The position in a line where fixation data starts.

The default configuration for .DA1 files is:

"da1_fields" : {
  "index": 0,
  "condition": 1,
  "number": 2,
  "time": -1,
  "fixation_start": 8
}

This default configuration matches a .DA1 file with the following format:

Position:   0   |   1   |   2   | 3 | 4 | 5 | 6 | 7 |   8   |   9   | ... |  -1  |
----------------------------------------------------------------------------------
Value:    index | cond. | num.  |   |   |   |   |   | fix.  | fix.  | ... | time |

If your .DA1 files do not match this format, copy default_config.json into a new file in the same directory, and edit the da1_fields section to match your .DA1 file format.

Numeric Region File Formats

Region files (typically .cnt or .reg) describe regions of interest in items of the experiment. Regions are defined by a character position of the beginning and ending of the region. Character positions can either be a single integer for single-line items, or a pair (line, character) of integers for multi-line items. A line in a region file contains the number and condition of an item, followed by the beginning and end positions of the regions. Four fields are necessary for parsing a region file.

number: Item identifier.

condition: Item condition.

boundaries_start: The position where region boundaries start in a line.

includes_y: True for multi-line items where regions are bounded by character and line position pairs, false for single-line items where regions are bounded by single integer character positions.

The default configuration for region files is:

"region_fields": {
  "number": 0,
  "condition": 1,
  "boundaries_start": 3,
  "includes_y": false
}

The default configuration matches a region file with the following format:

Position:   0   |   1   | 2 |   3   |   4   |   5   |   6   | ... |
-------------------------------------------------------------------
Value:    num.  | cond. |   |  r1   |  r1   |  r2   |  r2   | ... |

If your region file does not match this format, copy default_config.json into a new file in the same directory, and edit the region_fields section to match your region file format.

Text Region File Formats

Text region files are a new format for use with SideEye. This format can be used instead of a .cnt or .reg file, and allows for region length to be calculated automatically, and for region text to be included in the experiment output. There is only one format for this type of region file, so the region_fields configuration section is ignored. In this format, each line represents an item.

In this format, each line should have a number or string identifying the item number, followed by a tab or space, a number or string identifying the item condition, another tab or space, and then the text of the item. In the region text, regions are separated by the / character, and lines are separated by \n.

For example, the following line represents an item with number 1, condition 3, and four regions on two lines:

1    3    This is an item/ with two lines/\nand four/ regions.

The item displayed by the eye tracker would be:

This is an item with two lines
and four regions.