CHAP: Open Source Software for Processing and Analyzing Pupillometry Data

Ronen Hershman, Avishai Henik and Noga Cohen

Follow us by adding yourself to our mailing list by clicking here

Download CHAP now!

About

Pupil dilation is an effective indicator of cognitive and affective processes. While there are several eye-tracker systems in the market that provide effective solutions for pupil dilation measurement, there is a lack of tools for processing and analyzing the data provided by these systems. For this reason, we developed CHAP - open-source software written in MATLAB. This software provides a user-friendly interface (graphical user interface) for processing and analyzing pupillometry data. Our software creates uniform conventions for the pre-processing and analysis of pupillometry data, and provides a quick and easy-to-implement tool for researchers interested in pupillometry.

CHAP’s Input

CHAP receives input of a standard data file from various eye-trackers. It receives input from EyeLink, Eye Tribe, Tobii, ASL and Pupil-labs eye-trackers. It also supports data files from other eye-tracker devices, as long as they have a specific format.

How Does It Work?

After installing CHAP, the user will be asked to choose a data file. After CHAP loads the data file and converts it to a mat file, it keeps relevant measures and removes irrelevant information saved by the eye-tracking system. After this cleaning, CHAP processes the data.
First, CHAP will detect both trial onsets and offsets. In addition, CHAP will also detect user-defined variables and events (up to 64 of each).
After CHAP reads the data, pupil data (pupil size in pixels or any other units) is pre-processed. Pre-processing includes:

  1. Exclusion of outlier samples
  2. Blink correction
  3. Exclusion of outlier trials
  4. Exclusion of participants

After selecting the parameters for excluding trials and participants, and including the desired variables and events, the user should select the desired conditions (up to 7).
Next, CHAP presents data for each selected condition and indicates the selected events on a dedicated graph.

In addition to basic pre-processing of the data, CHAP supports several advanced analysis features. These features can be selected by the user and are outlined below:
  • Bins: Down-sampling (reducing the sampling rate) is performed by averaging adjacent samples of overall X (user-defined) milliseconds.
  • Time-window: By using this feature, the data is aligned to the onset of the first selected event.
  • Relative change: Instead of using the units recorded by the eye-tracker device, the user can convert the data to a relative change score. The relative change indicates the difference from baseline (i.e., subtractive baseline correction or the percent change from baseline — divisive baseline correction). The baseline is defined by the user as an average of X milliseconds prior to the onset of the first event.
  • Conversion to Z-scores / millimeters
  • Scattering: The user can add scattering around the mean for each curve. The scattering is either the standard error or the confidence interval of 95%.

Output

CHAP supports three kinds of outputs:
  1. CSV / MATLAB file that contains all the data about the relevant variables and events for each participant.
  2. MATLAB figure with the graphs of average data for each participant.
  3. PNG image of the graph of the average data for each participant.

Group Analysis & Statistical Analysis

Group Analysis

Once users process one data file, they can run the same configuration for multiple data files (e.g., different participants). The user should select the folder that contains the data files and choose a name for the analysis. Then, output files will be created for each data file and for the mean of all participants.

Statistical Analysis

CHAP provides two approaches for statistical analysis. CHAP has the option to run a repeated measures analysis of variance (ANOVA). In addition to this parametric approach, CHAP also supports a Bayesian approach. Specifically, CHAP can run a Bayesian paired-sample t-test.
CHAP also supports temporal analysis of the data. By using temporal analysis, the user can investigate the temporal differences between conditions across the whole time course or a selected time-window.

Installation

The installation of CHAP includes 3 main steps:

  1. Downloading CHAP from here.
  2. Extracting the ZIP file.
  3. Running CHAP_installation.m file (that adds CHAP to the MATLAB path list).

For a list of the CHAP versions available (including information about the updates) visit here.

Please note:

  • When working with EyeLink data files:
    • Users who use Windows 32-bit version should go to CHAP's folder and copy manually the edf2mat/edfapi.dll file to C:\Windows\System32
    • Users who use Windows 64-bit version should go to CHAP 's folder and copy manually the edf2mat/edfapi64.dll file to C:\Windows\System32
    • Users who use Mac should go to CHAP 's folder and unzip manually the edf2mat/edfapi.framework.zip file and copy edfapi.framework to /Library/Frameworks.
    More information about converting EyeLink data files into MATLAB can be found here: https://github.com/uzh/edf-converter.
  • When working with Eye Tribe data files (txt files given by the default Eye Tribe interface), python should be installed.
For further information or if you have any questions please do not hesitate to contact us.

Publications

Hershman, R.*, Milshtein, D.*, & Henik, A. (in press). The Contribution of Temporal Analysis of Pupillometry Measurements to Cognitive Research. Psychological Research. https://dx.doi.org/10.1007/s00426-022-01656-0. Read online

Hershman, R., Henik, A., & Cohen, N. (2019). CHAP: Open-source software for processing and analyzing pupillometry data. Behavior Research Methods, 51, 1059-1074. https://doi.org/10.3758/s13428-018-01190-1. Preprint. Read online

Hershman, R., Henik, A., & Cohen, N. (2018). A novel blink detection method based on pupillometry noise. Behavior Research Methods, 50(1), 107-114. https://doi.org/10.3758/s13428-017-1008-1. Read online