eyeris: A flexible, extensible, and reproducible pupillometry preprocessing framework in R

The paper introduces **eyeris**, an open-source, modular, and FAIR-compliant R framework designed to standardize pupillometry preprocessing by offering an intuitive, reproducible pipeline with best-practice signal processing and interactive quality control reports to address the current lack of robust tools in the field.

The Gist

Imagine you are trying to listen to a faint, beautiful melody played by a violinist in a noisy room. The room has wind blowing (wind noise), people walking by (footsteps), and the violinist occasionally sneezes (blinks). If you want to study the melody itself, you first have to clean up the recording. You need to remove the wind, the footsteps, and the sneezes, and then smooth out the static so the music is clear.

In the world of psychology and neuroscience, scientists use pupillometry to listen to the "music" of the brain. They measure how much a person's pupil (the black center of the eye) dilates or shrinks. This tiny change is a window into the mind, revealing things like how much attention someone is paying, how stressed they are, or how hard they are thinking.

However, just like that noisy room, the raw data from eye-tracking cameras is messy. It's full of "sneezes" (blinks), "footsteps" (head movements), and "static" (glitches). Until now, every scientist had to clean their own data using their own unique, often messy, method. This is like asking 100 different people to clean the same violin recording, but everyone uses a different vacuum cleaner, a different sponge, and a different amount of soap. The result? You can't compare their findings because the "clean" data looks different for everyone.

Enter eyeris: The "Gold Standard" Cleaning Robot.

The authors of this paper, led by Shawn Schwartz, have built a new tool called eyeris (pronounced like "iris," the colored part of your eye). Think of eyeris as a highly sophisticated, automated, and transparent cleaning robot designed specifically for pupil data.

Here is how it works, using some simple analogies:

1. The "Glass Box" (No Magic Tricks)

Many software tools are "black boxes." You put data in, press a button, and magic happens. You don't know what the machine did inside.
eyeris is a "Glass Box." Imagine a robot with a clear glass body. You can see every single step it takes.

• Step 1: It spots the "sneezes" (blinks) and carefully cuts them out, filling the gap with a smooth guess so the music doesn't stop.
• Step 2: It removes the "footsteps" (sudden spikes caused by head movement).
• Step 3: It smooths out the "static" using a filter, like a high-end audio equalizer, to make the signal clearer.
• Step 4: It organizes the data into neat little chapters (called "epochs") based on when the experiment started and stopped.

Because you can see inside the box, you know exactly how the data was cleaned. This stops scientists from accidentally (or intentionally) tweaking the cleaning process to get the results they want.

2. The "Recipe Book" (Standardization)

Before eyeris, if you asked two chefs to make a cake, one might use salt instead of sugar, and the other might bake it for 10 minutes instead of 30. You'd get two very different cakes.
eyeris provides a standardized recipe. It tells scientists: "First, do this. Then, do that. Use these specific settings."
This ensures that if a scientist in New York and a scientist in Tokyo both use eyeris on the same data, they get the exact same "clean" cake. This makes it possible to compare studies and trust the results.

3. The "Auto-Reporter" (Quality Control)

Cleaning a dataset is hard work. Usually, scientists have to manually look at thousands of graphs to check if the cleaning went well. It's like a librarian checking every single book in a library by hand.
eyeris is like a super-librarian that automatically generates a beautiful, interactive report for every single participant.

• It shows you a "Before" picture (the messy data).
• It shows you an "After" picture (the clean data).
• It highlights any weird spots that need attention.
• It does this for thousands of trials in seconds, saving researchers hours of boring work.

4. The "Digital Filing Cabinet" (Organization)

Finally, eyeris doesn't just clean the data; it organizes it. It puts everything into a neat, labeled filing cabinet (using a system called BIDS).

• It separates the "raw" messy files from the "clean" files.
• It creates a database so researchers can easily search through data from hundreds of people without getting lost in a pile of thousands of paper files.

Why Does This Matter?

Science is currently facing a "reproducibility crisis." This means that when scientists try to repeat each other's experiments, they often get different results. A big reason for this is that everyone was cleaning their data differently.

By introducing eyeris, the authors are giving the field of pupillometry the same kind of reliable, standardized tools that other fields (like MRI brain scanning) already have. It makes the science fairer, clearer, and more trustworthy.

In short: eyeris is the new, open-source, transparent, and easy-to-use tool that helps scientists clean up the "noise" in eye-tracking data so they can finally hear the true "music" of the human mind.

Technical Summary

1. Problem Statement

Pupillometry serves as a critical non-invasive window into cognitive processes (e.g., attention, arousal, memory) and autonomic function. However, the field suffers from a lack of standardized, robust preprocessing frameworks comparable to those in fMRI (e.g., fMRIPrep) or EEG (e.g., EEGLAB, MNE-Python).

• Reproducibility Crisis: Current workflows are often rigid, fragmented, or lack transparency, leading to a "garden of forking paths" where small, arbitrary preprocessing decisions significantly alter results and increase Type I error rates.
• FAIR Principles: Existing tools often fail to adhere to FAIR (Findability, Accessibility, Interoperability, and Reusability) principles, making data sharing and replication difficult.
• Technical Gaps: Researchers lack integrated tools for handling artifacts (blinks, spikes), managing large-scale datasets, generating interactive quality control (QC) reports, and extracting trial-level epochs with metadata parsing.

2. Methodology: The eyeris Framework

The authors developed eyeris, an open-source R package designed as a "glass-box" (transparent) preprocessing pipeline. Unlike "black-box" solutions, eyeris allows users to inspect, modify, and understand every step of the processing chain.

Core Architecture

• Entry Point: The primary function is glassbox(), which executes a prescribed, sequential pipeline. It supports both interactive mode (step-by-step parameter optimization with visual feedback) and headless mode (automated batch processing for large-scale/cloud deployments).
• Modularity: While glassbox() provides a recommended workflow, every step is a modular function, allowing advanced users to build custom pipelines or extend the framework.
• Data Structure: The package utilizes an S3 class system to track the history of operations, parameters, and data transformations, ensuring full provenance.

Prescribed Preprocessing Pipeline

The glassbox() function executes the following steps in a specific order to prevent data corruption:

1. Loading (load_asc): Parses SR Research EyeLink .asc files, handling metadata, events, and binocular data (averaging or independent processing).
2. Blink Removal (deblink): Identifies blink periods (NaN/0 values) and extends the missing data window (default ±50ms) to mask partial-occlusion artifacts before interpolation.
3. Transient Artifact Removal (detransient): Detects non-physiological spikes (e.g., from head movement) using a speed-based threshold derived from the Median Absolute Deviation (MAD) of pupil velocity.
4. Interpolation (interpolate): Fills missing data (from blinks/artifacts) using linear interpolation, suitable for the slow dynamics of pupil size.
5. Low-Pass Filtering (lpfilt): Applies a Butterworth low-pass filter (default passband 4 Hz, stopband 8 Hz) to remove high-frequency noise while preserving signal dynamics.
6. Downsampling (downsample): Reduces sampling rate with anti-aliasing filtering to preserve temporal dynamics without spectral aliasing.
7. Binning (bin): An alternative to downsampling that aggregates data into time bins (mean or median).
8. Detrending (detrend): Optional. Removes linear drifts (e.g., time-on-task effects). Disabled by default to preserve tonic arousal signals and avoid introducing biases.
9. Z-scoring (zscore): Enabled by default. Normalizes data per block to mean 0 and SD 1, facilitating cross-subject and cross-session comparisons by focusing on relative dynamics rather than absolute size.

Advanced Features

• Epoching (epoch): Extracts trial-level data based on event messages. It supports complex pattern matching (e.g., PROBE_{trial}_{stimulus}) to automatically parse and inject metadata into the resulting data frames.
• Export & Storage:
  • BIDS-like Structure: Exports data into a standardized directory structure separating raw and derived data.
  • Database Backend: Integrates DuckDB for scalable storage. Large datasets are stored in a single .eyerisdb file, allowing efficient SQL-based querying without loading entire datasets into memory.
  • Chunked Export: Supports exporting large databases to Parquet or CSV in chunks for sharing.
• Visualization: Generates interactive HTML diagnostic reports containing time-series plots, histograms, and filter frequency responses for every preprocessing step and trial.

3. Key Contributions

1. Standardization: Provides the first comprehensive, prescriptive preprocessing pipeline for pupillometry that enforces best practices in signal processing order and parameter selection.
2. Transparency ("Glass-Box"): Unlike previous tools, eyeris explicitly logs every transformation, parameter, and decision, generating interactive reports that serve as a record of data provenance.
3. Scalability: The integration of DuckDB and chunked export tools allows the framework to handle studies with hundreds or thousands of participants, overcoming the I/O bottlenecks of traditional CSV-based workflows.
4. Extensibility: The pipeline_handler() system allows developers to write custom preprocessing functions that seamlessly integrate into the main pipeline, adhering to a strict protocol for compatibility.
5. FAIR Compliance: By enforcing a BIDS-like structure and automated metadata handling, eyeris significantly improves the findability and reusability of pupillometry data.

4. Results & Validation

• Workflow Efficiency: The authors demonstrate that a complete preprocessing pipeline (from raw .asc to epoched, normalized data) can be executed in approximately three lines of code using glassbox().
• Quality Control: The interactive reports allow researchers to visually inspect thousands of trials for anomalies, enabling the removal of poor-quality data at the trial level rather than discarding entire participants.
• Reproducibility: The package automatically captures the "state" of the data at every step, ensuring that any derived dataset can be perfectly reproduced by re-running the pipeline with the logged parameters.
• Adoption of Best Practices: The framework resolves common debates (e.g., Z-scoring vs. raw data) by providing sensible defaults (Z-scoring enabled) while allowing users to override them based on specific research questions.

5. Significance

eyeris addresses a critical gap in cognitive neuroscience by bringing pupillometry research to the same level of methodological rigor and reproducibility as fMRI and EEG.

• For Researchers: It lowers the barrier to entry for novices (via glassbox()) while offering power and flexibility for experts (via modular extensions and database tools).
• For the Field: By standardizing preprocessing, it reduces the "garden of forking paths," thereby increasing the reliability of findings related to attention, arousal, and cognitive aging.
• Open Science: The tool promotes open science by making data sharing, QC, and replication significantly easier through automated reporting and standardized file structures.

In summary, eyeris is not just a preprocessing tool but a comprehensive ecosystem designed to modernize pupillometry research, ensuring high-fidelity data analysis and robust scientific inference.