eyeprocess

Vendor-neutral infrastructure for reproducible eye-tracking and multimodal process-data research.

eyeprocess transforms heterogeneous eye-tracking, pupillometry, behavioural, and biometric exports into validated, analysis-ready process data. It combines vendor-neutral harmonization with first-class Gazepoint support, explicit quality and provenance controls, gaze/AOI/scanpath analysis, pupillometry and biometric workflows, interoperability, and psychometric/process modelling.

Release channels: CRAN 0.11.1 (published 2026-09-28) · GitHub stable 0.12.0 · development 0.12.0.9000

Website · CRAN · Reference · Articles · GitHub · Releases

What eyeprocess provides

Area	Capabilities
Import and harmonization	Vendor-aware readers, generic mappings, canonical schemas, explicit timebase and coordinate handling
Validation and provenance	Source inspection, schema coverage, quality audits, source fingerprints, validation corpora, provenance manifests
Gaze and AOI analysis	Trial construction, AOI registration and assignment, fixation summaries, scanpaths, transitions, visual diagnostics
Censored gaze latency	Survival-ready event/censor tables, Kaplan-Meier curves, clustered/frailty Cox, Weibull/log-normal AFT, diagnostics and sensitivity
Pupil and biometrics	Pupil preprocessing, binocular handling, physiological synchronization, quality-aware feature derivation
Process and psychometric modelling	IRT, response-time models, multimodal process measurement, validation and sensitivity infrastructure
Interoperability and storage	Eye-Tracking-BIDS, Arrow/Parquet workflows, conversion bridges, auditable storage contracts

Event-detector multiverse and inference robustness

The development surface includes a vendor-neutral detector-sensitivity workflow that carries event-detection uncertainty all the way to the scientific model:

raw gaze → detector → events → AOIs → derived features → identical model → robustness report

Key interfaces include define_event_detector_spec(), run_detector_multiverse(), match_detected_events(), propagate_detector_to_features(), run_detector_inference_multiverse(), and report_detector_multiverse().

The workflow supports I-VT, I-DT, a transparently labelled adaptive-velocity reference detector, a REMoDNaV command-line bridge, external detector callbacks, and vendor-supplied events. It retains zero-event trials, never converts all-missing gaze to zero dwell, errors on ambiguous AOI membership unless a rule is chosen explicitly, requires an explicit model engine, and keeps non-converged/failed branches visible.

See the Event-Detector Multiverse article and the detector-multiverse reference section.

AOI perturbation, uncertainty, and reporting

AOI boundaries are treated as an analytical specification rather than a fixed truth. The AOI robustness workflow can dilate, erode, translate, jitter, and anisotropically expand declared geometry in pixels or degrees of visual angle; remap samples/fixations with explicit ambiguity and missingness; recompute complete AOI feature cells; propagate the same analyst-specified model; retain failed/non-converged branches; and summarize assignment, coefficient, interval, convergence, and model-N stability.

The website now provides a complete route from planning to reviewer-ready evidence:

AOI Perturbation and Uncertainty Analysis — worked synthetic workflow, four plot families, interpretation, failure handling, and limitations.
AOI Sensitivity Analysis Plan and Reporting Template — prespecify geometry, perturbation envelope, units, denominator rules, model, and amendment policy.
AOI Robustness Reporting Bundle — package branch audits, assignment/model evidence, failures, provenance, report text, figures, and optional file manifests for manuscripts or reviewer responses.

Core functions include create_aoi_perturbation_grid(), run_aoi_sensitivity_analysis(), estimate_aoi_assignment_stability(), assess_aoi_inference_stability(), report_aoi_sensitivity(), and the four AOI plotting functions. Robustness frequencies are descriptive sensitivity summaries, not probabilities that an AOI definition or scientific conclusion is true.

September 2026 measurement-accountability additions

The current development branch adds three conservative diagnostics that make timing uncertainty and validation scope explicit without changing the package’s existing synchronization or modelling engines:

pupil_latency_sensitivity() compares sustained-threshold, maximum-slope-tangent, and piecewise-breakpoint pupil onsets and reports estimator spread, signal diagnostics, and latency resolvability instead of presenting one onset as hardware- or algorithm-independent.
event_marker_qc() audits whether independent channel offsets corroborate a nominal event and reports consensus offset and uncertainty. It is event-plausibility QC only: it does not synchronize clocks, correct drift, or modify timestamps.
validation_ladder() separates acquisition QC, analytical QC, construct checking, within-person evidence, and held-out-person generalization. A generalization claim cannot be marked supported without held-out-person validation.

The development branch also adds censored gaze-latency survival analysis, retaining valid never-inspected trials as right-censored observations and distinguishing clustered Cox from latent participant frailty. A companion evidence-verification worked example demonstrates time to first source/evidence AOI entry with explicit censoring, diagnostics, sensitivity models, and reporting. Before freezing an analysis, use the survival reproducibility checklist.

See the Measurement accountability article and the measurement-accountability reference section.

Standardized spatial data quality

The development branch adds a vendor-neutral data-quality subsystem for target-referenced accuracy, RMS sample-to-sample and spatial-SD precision, BCEA, realized sampling behavior, and data loss. The canonical report keeps these dimensions separate, records metric-specific units and provenance, and treats thresholds as review rules rather than automatic exclusions.

validation <- simulate_gaze_quality_calibration(samples_per_target = 8)

quality <- create_gaze_quality_report(
  validation,
  by = c("profile", "target_id"),
  valid = "valid",
  missing_reason = "missing_reason",
  nominal_sampling_hz = 60
)

report_gaze_quality(quality)

The synthetic validation profiles deliberately separate accuracy, precision, irregular sampling, and missingness. Timing diagnostics distinguish long observed intervals from the estimated number of nominal samples represented by those gaps. See the Standardized Data Quality guide and the Data Quality plot gallery and reporting clinic.

September 2026 trial-level mediation preparation

The current development branch also adds a vendor-neutral preparation contract for repeated-measures mediation with gaze or other trial-level process variables. prepare_multilevel_mediation_data() preserves every trial, separates within- and between-participant exposure and mediator components, distinguishes genuine zero gaze from unobserved or poor-quality trials, audits trial support and missingness, and carries preprocessing/event/AOI/quality provenance forward.

The preparation layer does not fit a mediation model. Bayesian inference belongs in gp3bayes; eyeprocess owns decomposition, observation semantics, quality flags, and model-ready trial structure. Serial mediators and moderators are prepared with add_multilevel_mediation_component() so statistical backends do not reimplement the scientific decomposition.

See the Trial-level multilevel mediation article and the mediation-preparation functions in the reference index.

Design commitments

Harmonize semantics, not merely column names.
Retain native timestamps and source files.
Record every timebase and coordinate transformation.
Keep vendor-produced and package-derived ocular events distinguishable.
Never resample, interpolate, clip, reconstruct, or exclude observations silently.
Treat gaze, pupil, and physiology as observations—not automatic psychological constructs.
Keep Gazepoint support deep while the canonical representation remains vendor-neutral.

Supported inputs

Ecosystem	Initial interface	Support level
Gazepoint Analysis	`read_gazepoint()`, `read_gazepoint_folder()`	First class
Gazepoint Biometrics	`read_gazepoint_biometrics()`	First class
Generic CSV/TSV	`read_eye_generic()`	Universal mapping
Tobii Pro Lab	`read_tobii()`	Dedicated
Pupil Labs Neon	`read_pupil_neon()`	Dedicated
Pupil Labs Core	`read_pupil_core()`	Dedicated
EyeLink ASC	`read_eyelink_asc()`	Dedicated
EyeLink Data Viewer	`read_eyelink_report()`	Explicit mapping
EyeLink EDF	`read_eyelink_edf()`	Local EDF2ASC bridge
SMI BeGaze ASCII	`read_smi()`	Legacy dedicated
Custom adapters	`register_eye_adapter()`	Extensible

Support level and empirical validation are deliberately kept separate. The existence of an adapter is not treated as proof of production compatibility with every exporter or software version.

Installation

CRAN

The current CRAN release is 0.11.1, published on 28 September 2026:

install.packages("eyeprocess")

The canonical CRAN record is https://CRAN.R-project.org/package=eyeprocess and the package DOI is https://doi.org/10.32614/CRAN.package.eyeprocess.

GitHub stable release

The GitHub release line is newer than CRAN. To install the exact v0.12.0 release:

install.packages("remotes")
remotes::install_github("stefanosbalaskas/eyeprocess", ref = "v0.12.0")

Development

For the current 0.12.0.9000 development branch:

remotes::install_github("stefanosbalaskas/eyeprocess")

Optional modelling backends are deliberately not mandatory dependencies. Install only the engines required for a specific analysis.

Quick start

library(eyeprocess)

x <- read_gazepoint_folder(
  "data/P001",
  include = c("gaze", "fixations", "events", "biometrics")
)

validate_eye_dataset(x)
audit_timebase(x)
audit_signal_quality(x)

x <- build_trials(x, start_events = "TRIAL_START", end_events = "TRIAL_END")

x <- register_aois(
  x,
  new_aoi("prompt",  x = 0,    y = 0, width = 0.50, height = 1),
  new_aoi("options", x = 0.50, y = 0, width = 0.50, height = 1)
)

x <- assign_aois(x)
x <- derive_all_features(x)

plot_scanpath(x, trial_id = x$intervals$trial_id[1])
plot_pupil_timeseries(x, trial_id = x$intervals$trial_id[1])

For generic exports, Tobii, Pupil Labs, EyeLink, SMI, real-export validation, preprocessing, storage, and complete Gazepoint workflows, see the articles.

Process measurement and psychometrics

eyeprocess connects behavioural responses with process evidence while keeping measurement assumptions explicit. The multimodal measurement ladder is:

M0 response → M1 + RT → M2 + gaze → M3 + pupil → M4 + trait-conditioned latent response-process state

Examples of public interfaces include fit_irt(), fit_explanatory_irt(), fit_accuracy_rt(), fit_process_irt(), multimodal_m3_spec(), fit_multimodal_m3(), multimodal_m4_spec(), and fit_multimodal_m4().

M4 remains REVIEW / evidence-gated. The availability of an estimator or model interface is not treated as evidence of unrestricted confirmatory validity. M4 states are model-based statistical response-process states; state labels do not by themselves establish cognitive strategy, attention, engagement, cognitive load, effort, emotion, guessing, misconduct, comprehension, or another psychological construct.

Validation and reproducibility

The 0.11.1 CRAN release preserves an auditable validation contract across data import, transformations, storage, modelling, and reporting. It was published on CRAN on 28 September 2026 after the CRAN remediation cycle, and is available from the canonical package page and package DOI above. The newer v0.12.0 GitHub release and 0.12.0.9000 development branch remain separate release channels and should not be reported as the CRAN version.

The package also provides infrastructure for real-export validation, grouped validation, parameter recovery, simulation-based calibration, leakage checks, sensitivity analysis, model-evidence audits, benchmark generation, and reproducible reporting.

Detailed implementation and validation records are maintained in:

Responsible interpretation

eyeprocess does not equate fixation with attention, dwell time with difficulty, pupil dilation with cognitive load, rapid response with guessing, physiological variation with a named mental state, or a data-derived process factor with a psychological construct.

Useful audit interfaces include:

interpretive_warnings()
analysis_readiness(x)
provenance_manifest(x)

Documentation

Citation

For the citation associated with the installed package, run:

citation("eyeprocess")
packageVersion("eyeprocess")

Studies should report the exact package version and, when relevant, the source commit and modelling backend used. The canonical CRAN package DOI is 10.32614/CRAN.package.eyeprocess.

Contributing and issues

License

MIT License.