eyeprocesspy

Reproducible Python infrastructure for eye-tracking, pupillometry, AOIs, process data, psychometrics, and multimodal behavioral measurement.

Documentation · PyPI · Release v0.2.2 · Zenodo DOI · 88 workflows

eyeprocesspy is the Python companion and deep-parity port of the R package eyeprocess, with frozen eyeprocess 0.11.1 as the scientific reference. It provides one governed analytical surface for vendor import, canonical data contracts, preprocessing, gaze and AOI analysis, pupillometry, process measurement, psychometrics/IRT, multimodal workflows, validation, provenance, plotting, and reproducible reporting.

Published release — 0.2.2. Version 0.2.2 adds the fully qualified measurement-validity and dynamic-gaze tranche plus the completed Bayesian-network robustness layer: spatial calibration error/correction, pupil-size artefact modelling, dynamic AOIs, smooth-pursuit and microsaccade analysis, event-detector benchmarking, naturalistic coordinates, scanpath metric sensitivity, gaze stress testing, CPT/structural/discretization/noise/sample-size robustness, and predictive calibration. The controlling qualification passed 1,892 tests, 36,556 / 36,556 statements, and 12,630 / 12,630 branches with exact 100% coverage, plus a green Ubuntu/macOS/Windows × Python 3.11–3.14 matrix, Ruff, mypy, wheel/sdist build/install, frozen-R oracle, and strict documentation gates.

Install

pip install eyeprocesspy

For the optional Bayesian-network analysis layer:

pip install "eyeprocesspy[bayesnet]"

The BN layer consumes already processed feature tables and provides theory-constrained static structure learning, parameter fitting, posterior evidence propagation, participant-level bootstrap stability, grouped validation, detector/AOI sensitivity, CPT/structural/discretization/noise/sample-size robustness, predictive calibration, plots, and reporting. It does not silently discretize continuous physiology or reinterpret learned directed edges as causal effects.

Open the Bayesian-network guide →

Pin the current release when exact reproducibility matters:

pip install eyeprocesspy==0.2.2

For source installation from the immutable release tag:

pip install "git+https://github.com/stefanosbalaskas/eyeprocesspy.git@v0.2.2"

Windows users can also use the hardened installer described in the manual-install guide. It has been exercised on a real Windows/Python 3.11.9 installation with the recommended extras and a clean pip check.

Release evidence

See RELEASE_VALIDATION.md, TEST_SUMMARY.md, and the parity & validation guide for the underlying evidence.

What it covers

30-second reproducible check

import eyeprocesspy as ep

study = ep.eyeprocess_benchmark_study()
audit = ep.validate_benchmark_study(study)
data = ep.import_benchmark_study(study)

print(audit["valid"])
print(data)

For a real export:

import eyeprocesspy as ep

eye = ep.read_eye_export("participant_001.csv", vendor="auto")
issues = ep.validate_eye_dataset(eye)

See the package in action

Gaze trace	Probabilistic AOI

Pupil time series	Process reliability

Open the complete visual gallery →

Choose your path

• New to the package: Getting started → Worked examples → Cookbook
• Standardized Data Quality: Overview · 9-point example · Plot gallery · Sensitivity · Focused API\n- Eye-tracking / AOI work: End-to-end eye-tracking · Measurement validity & dynamic gaze · Gazepoint import & QC
• Gaze latency / TTFF: Censored gaze-latency method · Disclosure example · Evidence-verification example · Troubleshooting · Reproducibility checklist
• Pupillometry / multimodal: Pupillometry guide · Quality & uncertainty
• Psychometrics / IRT: Psychometrics & IRT · IRT example
• Full workflows: Featured workflows · 88-article library
• Lookup: API reference · Plotting reference · FAQ

Scientific boundary

eyeprocesspy provides measurement and analysis infrastructure. A metric is not automatically a validated psychological construct, diagnosis, or causal explanation. Reliability does not establish construct validity; prediction does not establish causation; probabilistic AOI membership represents modeled coordinate uncertainty rather than probability of attention; and gaze, pupil, biometric, and process measures require an appropriate design, measurement model, and ethical interpretation.

Citation

For eyeprocesspy 0.2.2, use the metadata in CITATION.cff and report the exact package version plus the frozen R reference exposed as eyeprocesspy.__r_reference_version__. The GitHub/PyPI release is available immediately; if Zenodo mints a new archive DOI for v0.2.2, that immutable DOI should be preferred in formal citations.

The initial 0.1.0 archive remains available at DOI 10.5281/zenodo.22285167 for studies that specifically used that release.

Relationship to R eyeprocess

The Python package is developed against the frozen eyeprocess 0.11.1 reference. API, articles, data, plots, numerical evidence, backends, and unavoidable language-specific divergences are tracked explicitly. Python-native extensions are kept distinct from reference parity so they do not masquerade as R-equivalent behavior.

License

MIT. See LICENSE.

October 2026 research article and figure

Gaze event reconstruction and reference confidence documents experimental, source-only validation methods and reproducible synthetic examples. It is available in the website navigation, while independently qualified external empirical claims and stable PyPI APIs remain separate (scientific acceptance criteria).