SideEye is still in beta! New features are in development, but if you find any bugs or have suggestions, Open a GitHub issue or email [email protected].
SideEye is a Python package for processing eye tracking data that interfaces with EyeTrack and Experiment Builder.
It is meant to parse eye-tracking-while-reading data and calculate useful experimental measures. Currently, SideEye can only parse the .DA1 file format, but other formats will be added later. The goal is to parse all eye-tracking-while-reading data into a common format, and provide a consistent and accurate method for processing the data.
Documentation (currently incomplete, but more detail than provided here) can be found at sideeye.readthedocs.io.
Refer to examples/sample.py for an up-to-date sample script.
SideEye requires Python >= 3.5.
pip install sideeye
The configuration file is a JSON file specifying the changeable parameters used by SideEye's default parsing and output functions. An example is found in examples/sample_config.json. The config file should always have the same format. It has several sections:
da1_fields: The locations of values in each line of a DA1 file.
region_fields: The locations of values in each line of a region file.
cutoffs: Fixation duration cutoffs.
region_measures: Used in region measure calculation and output.
trial_measures: Used in trial measure calculation and output.
region_output: Reported columns for region measures in output file.
trial_output: Reported columns for trial measures in output file.
terminal_output: Amount of status/debugging info to output to terminal.
This section contains parameters needed for parsing DA1 files. Because there are several formats for DA1 files, the positions of each value in a line are needed. The parameters are all positions in a line, where 0 is the first value in the line.:
index: An integer identifying a single trial, usually the first number in a 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.
As an example, a line of a DA1 file could look like this:
Position: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | -1 | Value: index | cond. | num. | | | | | | fix. | fix. | ... | time |
And the da1_fields section of the config file would be:
"da1_fields" : {
"index": 0,
"condition": 1,
"number": 2,
"time": -1,
"fixation_start": 8
}
Similar to da1_fields, this section specifies the positions of values in each line of a region file. The parameters are:
number: Item identifier.
condition: Item condition.
boundaries_start: The position where region boundaries start in a line.
includes_y: Whether or not the region file includes line position in region boundaries. If true, a region is bounded by four numbers: (char_start, line_start), (char_end, line_end). If false, the region is bounded by two numbers: char_start, char_end.
This section contains cutoffs for fixations. If a fixation's duration is less than min or greater than max, it will be excluded from measure calculations.
min: Minimum cutoff time for fixation duration.
max: Maximum cutoff time for fixation duration.
include_fixation: When true, if a fixation is excluded by cutoffs, its duration is included in the duration of the saccade between the previous and next non-excluded fixations.
include_saccades: When true, if a fixation is excluded by cutoffs, the duration of the saccade into and out of the fixation is included in the saccade between the previous and next non-excluded fixations.
This section contains parameters for region measure calculation and output. It is a list of all calculated region measure, each with two parameters:
cutoff: A cutoff value for the measure. If the calculated measure is greater than this value, its value in the output report is CUTOFF. For some measures, where the value is not numerical, this parameter is ignored.
include: A boolean (true/false) value specifying whether the measure should be included in the output report. If false, the measure will be excluded.
The measures in this section of the config file are:
skip first_pass_regressions_out first_pass_regressions_in first_fixation_duration single_fixation_duration first_pass go_past total_time right_bounded_time reread_time second_pass spillover_time refixation_time landing_position launch_site first_pass_fixation_count
This section contains parameters for trial measure calculation and output. Each measure has the same parameters as region_measures. The measures included in this section are:
location_first_regression latency_first_regression fixation_count percent_regressions trial_total_time average_forward_saccade average_backward_saccade
This section specifies the columns that should be included in the output file for region measures. Each output column has two parameters:
include: Whether or not the column should be included in the output report. true/false
header: A title for the header of the column. Can be different from the name of the column parameter.
Columns included in this section are:
experiment_name: Name of experiment.
filename: Filename of DA1 file.
date: Date of DA1 file if specified, or date file was parsed if not.
trial_id: Trial identifier.
trial_total_time: Total time of trial.
item_id: Item identifier.
item_condition: Condition of item.
region_label: Label for region.
region_number: Region number (beginning with 0).
region_text: Text included in region, if specified.
region_start: Character location of beginning of region.
region_end: Character location of end of region.
measure: Name of measure.
value: Value of measure.
This section specifies the columns that should be included in the output file for trial measures. Each column has the same parameters as region_output. The columns are the same, but with columns beginning with region_ excluded.
A number specifying the level of detail in terminal output.
0: Errors only.
1: File-level information (which file is currently being parsed).
2: Item and trial-level parsing information.
3: Measure-level calculation information.
4: Trial-level calculation information.
5: All output information.