Changes

Page history
Update Eyetracker Scripts HowTo authored by Jonathan Jones's avatar Jonathan Jones
Show whitespace changes
Inline Side-by-side
Eyetracker-Scripts-HowTo.md
View page @ ee1d26ef
The blocks software includes some scripts that process gaze sequences exported from TOBII. Their main purpose is to align TOBII gaze sequences with the videos collected from our top-down camera setup, allowing us to examine gaze behavior during each of the actions in the video instead of overall behavior during the entire video.
# Overview and workflow
1. Impute AOI hits in the Tobii export file.
This program takes an exported data file from the Tobii Pro Lab software and returns a processed version of the file. This data file contains the 'hit values' for the areas of interest for a particular task, eye movement type, and timestamp for each data point. Wherever there is a 'missing' hit value, this script will change the '0' into a '1'. The missing hit values classified as anywhere a string of '1's is disrupted by 0s, but there are no other fixations during that time window.
**INPUT:**
**OUTPUT:**
**EXAMPLE:**
``` console
$ cd ~/repo/blocks/blocks/eyetracking/scripts
$ python impute_aoi_hits.py \
--export_file ~/Downloads/eyetracking/ADULTS_EYE-TRACKING_DATA_EXPORT_PARTICIPANTS_1-26_9-20-19.csv \
--out_dir ~/Downloads/eyetracking/imputed_aoi
```
2. Segment the Tobii export file into smaller files (each one corresponds to an overhead video).
This program takes an exported data file from the Tobii Pro Lab software which represents a batch of several copy attempts, and chunks it into several smaller files. Each of the output files corresponds to a single copy attempt---ie one participant's attempt to copy one model.
**INPUT:**
**OUTPUT:**
**EXAMPLE:**
``` console
$ python segment_tobii_export.py \
--tobii_export_fn ~/Downloads/eyetracking/imputed_aoi/imputed-aois_ADULTS_EYE-TRACKING_DATA_EXPORT_PARTICIPANTS_1-26_9-20-19.csv \
--video_metadata_fn ~/blocks/data/input/blocks_file_index.xlsx \
--out_dir ~/Downloads/eyetracking/imputed_and_segmented
```
3. Convert overhead video labels to match eyetracker timestamp indices.
``` console
$ python make_eyetracker_labels.py
```
4. Move segmented Tobii export files and eyetracker label files to the remove server.
``` console
$ cp ~/Downloads/eyetracker_labels /Volumes/lcsr-cogsci$/ProcessedData/eyetracker-labels
$ cp ~/Downloads/imputed_and_segmented /Volumes/lcsr-cogsci$/ProcessedData/segmented-tobii-export
5. Parse annotations and compute action times.
``` console
$ cd ../../analysis
$ python compute_stats.py
```
6. Count AOI visits.
``` console
$ cd -
$ python count_aoi_visits.py
```
This program takes the annotated labels file that comes from the data annotation platform then changes the timestamps to match the indices of the closest timestamp in the data export.
# Processing the Tobii Pro Lab Data Export
**INPUT:**
This program takes the exported data file from the Tobii Pro Lab software for a particular video and returns a processed version of the file. This data file contains the 'hit values' for the areas of interest for a particular task, eye movement type, and timestamp for each data point. Wherever there is a 'missing' hit value, this script will change the '0' into a '1'. The missing hit values classified as anywhere a string of '1's is disrupted by 0s, but there are no other fixations during that time window. This script will work for one task at a time
**OUTPUT:**
To use the script:
**EXAMPLE:**
``` console
$ python make_eyetracker_labels.py
```
* Go to the 'src' file within the 'Blocks' folder. Open the script 'eyetracker_data_imputation.py' with a text editor. In file_list, write the names (and paths if need be) to the data export files to be processed. These files should be for the same task. Next to 'set_name', write the name of the task completed in the videos as it is defined in the Tobii Pro Lab software. Save the file.
4. Move segmented Tobii export files and eyetracker label files to the remove server.
* Open the terminal. Navigate to the blocks source directory and run the script:
``` bash
user@host:~$ cd repo/blocks/src
user@host:~/repo/blocks/src$ python eyetracker_data_imputation.py
```
**INPUT:**
New files will be saved that included the imputed 1s without changing the original data export file.
**OUTPUT:**
# Aligning the Timestamps in the Annotated Labels Files with the Timestamps from the Tobii Pro Lab Software
**EXAMPLE:**
``` console
$ cp ~/Downloads/eyetracker_labels /Volumes/lcsr-cogsci$/ProcessedData/eyetracker-labels
$ cp ~/Downloads/imputed_and_segmented /Volumes/lcsr-cogsci$/ProcessedData/segmented-tobii-export
```
This program takes the annotated labels file that comes from the data annotation platform then changes the timestamps to match the indices of the closest timestamp in the data export.
5. Parse annotations and compute action times.
To use the script:
* Open 'convert_annotated_label_frames_to_eyetracker_data_indices.py' from the 'src' file in the Blocks folder with a text editor. Write the name of your preferred annotator, the name of the study, the path to the eye-tracking exported metrics file, and the name of the blocks_file_index file. Save the file.
**INPUT:**
* Open the 'config' folder in Blocks folder with a text editor. Write the video numbers you would like to align in the file 'align_data.txt'.
**OUTPUT:**
* Open the terminal. Navigate to the blocks source directory and run the script:
``` bash
user@host:~$ cd repo/blocks/src
user@host:~/repo/blocks/src$ python convert_annotated_label_frames_to_eyetracker_data_indices.py
**EXAMPLE:**
``` console
$ cd ../../analysis
$ python compute_stats.py
```
* New files identical to the annotated labels files but with indices that reference the eye-tracking data rather than the overhead camera frames will be saved. The original file will be untouched.
# Calculating the Visits to Each Area of Interest from the Tobii Pro Lab Data Export
6. Count AOI visits.
This program will take the Microsoft Excel file that contains the processed data export and return the visits to each area of interest for the time intervals (end time to end time of each state) defined by the state data calculated from the compute-stats program.
To use the script:
**INPUT:**
* Open the file 'eyetracker_calculate_visit_counts.py' from the src file in the Blocks folder with a text editor. Fill in the name of the data export file you would like to calculate the visits from, the name of the file that contains the state data, and the name of the task that the data corresponds as defined in Tobii Pro Lab. Save the file.
**OUTPUT:**
* Open the terminal. Navigate to the blocks source directory and run the script:
``` bash
user@host:~$ cd repo/blocks/src
user@host:~/repo/blocks/src$ python eyetracker_calculate_visit_counts.py
**EXAMPLE:**
``` console
$ cd -
$ python count_aoi_visits.py
```
\ No newline at end of file
This program will output a new data file that is identical to the state data file with added columns that include the visit counts for each area of interest. The original files will not be changed.
\ No newline at end of file