Metadata-Version: 2.4
Name: eyeprocesspy
Version: 0.2.2
Summary: Vendor-neutral Python infrastructure for eye-tracking, pupillometry, biometrics, psychometrics, and multimodal process data, ported from eyeprocess 0.11.1.
Author: Stefanos Balaskas
License-Expression: MIT
Project-URL: Homepage, https://github.com/stefanosbalaskas/eyeprocesspy
Project-URL: Documentation, https://stefanosbalaskas.github.io/eyeprocesspy/
Project-URL: PyPI, https://pypi.org/project/eyeprocesspy/
Project-URL: Release, https://github.com/stefanosbalaskas/eyeprocesspy/releases/tag/v0.2.2
Project-URL: Source, https://github.com/stefanosbalaskas/eyeprocesspy
Project-URL: Issues, https://github.com/stefanosbalaskas/eyeprocesspy/issues
Project-URL: Changelog, https://github.com/stefanosbalaskas/eyeprocesspy/blob/main/CHANGELOG.md
Keywords: eye-tracking,pupillometry,biometrics,psychometrics,item-response-theory,multimodal,behavioral-data,gazepoint,reproducibility
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: scipy>=1.13
Provides-Extra: narrow
Requires-Dist: pyarrow>=20; extra == "narrow"
Provides-Extra: stan
Requires-Dist: cmdstanpy>=1.3; extra == "stan"
Provides-Extra: bayes
Requires-Dist: pymc; extra == "bayes"
Requires-Dist: arviz; extra == "bayes"
Provides-Extra: bayesnet
Requires-Dist: pgmpy>=1.0; extra == "bayesnet"
Provides-Extra: physio
Requires-Dist: neurokit2; extra == "physio"
Requires-Dist: biosppy; extra == "physio"
Provides-Extra: streaming
Requires-Dist: pylsl; extra == "streaming"
Requires-Dist: pyxdf; extra == "streaming"
Provides-Extra: gaze
Requires-Dist: pymovements; extra == "gaze"
Requires-Dist: remodnav; extra == "gaze"
Requires-Dist: multimatch-gaze; extra == "gaze"
Provides-Extra: survival
Requires-Dist: patsy>=1.0; extra == "survival"
Requires-Dist: statsmodels>=0.14; extra == "survival"
Requires-Dist: lifelines<0.31,>=0.30.3; extra == "survival"
Requires-Dist: matplotlib>=3.9; extra == "survival"
Provides-Extra: psychometrics
Requires-Dist: girth; extra == "psychometrics"
Requires-Dist: catsim; extra == "psychometrics"
Requires-Dist: patsy>=1.0; extra == "psychometrics"
Requires-Dist: statsmodels>=0.14; extra == "psychometrics"
Provides-Extra: plots
Requires-Dist: matplotlib>=3.9; extra == "plots"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.5; extra == "ml"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.6; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.30; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=6; extra == "dev"
Requires-Dist: coverage[toml]>=7.10; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Requires-Dist: mypy>=1.15; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: matplotlib>=3.9; extra == "dev"
Requires-Dist: patsy>=1.0; extra == "dev"
Requires-Dist: statsmodels>=0.14; extra == "dev"
Requires-Dist: lifelines<0.31,>=0.30.3; extra == "dev"
Requires-Dist: scikit-learn>=1.5; extra == "dev"
Requires-Dist: pyarrow>=20; extra == "dev"
Requires-Dist: pgmpy>=1.0; extra == "dev"
Requires-Dist: mkdocs>=1.6; extra == "dev"
Requires-Dist: mkdocs-material>=9.6; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.30; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/stefanosbalaskas/gpbiometricspy/main/docs/assets/python-suite-logo.png" width="270" alt="Python Suite research packages logo">
</p>

<h1 align="center">eyeprocesspy</h1>

<p align="center">
  <strong>Reproducible Python infrastructure for eye-tracking, pupillometry, AOIs, process data, psychometrics, and multimodal behavioral measurement.</strong>
</p>

<p align="center">
  <a href="https://stefanosbalaskas.github.io/eyeprocesspy/">Documentation</a> ·
  <a href="https://pypi.org/project/eyeprocesspy/">PyPI</a> ·
  <a href="https://github.com/stefanosbalaskas/eyeprocesspy/releases/tag/v0.2.2">Release v0.2.2</a> ·
  <a href="https://doi.org/10.5281/zenodo.22285167">Zenodo DOI</a> ·
  <a href="https://stefanosbalaskas.github.io/eyeprocesspy/articles/">88 workflows</a>
</p>

<p align="center">
  <a href="https://github.com/stefanosbalaskas/eyeprocesspy/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/stefanosbalaskas/eyeprocesspy/actions/workflows/ci.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/stefanosbalaskas/eyeprocesspy/actions/workflows/docs.yml"><img alt="Documentation" src="https://github.com/stefanosbalaskas/eyeprocesspy/actions/workflows/docs.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/stefanosbalaskas/eyeprocesspy/actions/workflows/deep-parity-audit.yml"><img alt="Deep parity" src="https://github.com/stefanosbalaskas/eyeprocesspy/actions/workflows/deep-parity-audit.yml/badge.svg?branch=main"></a>
  <a href="https://pypi.org/project/eyeprocesspy/"><img alt="PyPI" src="https://img.shields.io/pypi/v/eyeprocesspy.svg"></a>
  <a href="https://doi.org/10.5281/zenodo.22285167"><img alt="DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.22285167.svg"></a>
  <img alt="Python 3.11–3.14" src="https://img.shields.io/badge/Python-3.11%E2%80%933.14-blue">
  <img alt="Frozen API 1182/1182" src="https://img.shields.io/badge/frozen%20API-1182%20%2F%201182-success">
  <img alt="Coverage 100%" src="https://img.shields.io/badge/statements%20%2B%20branches-100%25-success">
</p>

`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

```bash
pip install eyeprocesspy
```

For the optional Bayesian-network analysis layer:

```bash
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 →](https://stefanosbalaskas.github.io/eyeprocesspy/guides/bayesian-networks/)

Pin the current release when exact reproducibility matters:

```bash
pip install eyeprocesspy==0.2.2
```

For source installation from the immutable release tag:

```bash
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](https://stefanosbalaskas.github.io/eyeprocesspy/manual-install/). It has been exercised on a real Windows/Python 3.11.9 installation with the recommended extras and a clean `pip check`.

## Release evidence

| Dimension | Verified state |
| --- | ---: |
| Frozen R public APIs resolved | **1,182 / 1,182** |
| Frozen R reference | **0.11.1** |
| Workflow articles linked | **88 / 88** |
| Release-gate tests | **1,892 passed** |
| Statement coverage | **36,556 / 36,556 (100%)** |
| Branch coverage | **12,630 / 12,630 (100%)** |
| Numerical `not_started` debt | **0** |
| Plot `not_started` debt | **0** |
| CI matrix | **Ubuntu / macOS / Windows × Python 3.11–3.14** |
| PyPI | **eyeprocesspy 0.2.2** |
| Zenodo | **10.5281/zenodo.22285167** |

See [`RELEASE_VALIDATION.md`](RELEASE_VALIDATION.md), [`TEST_SUMMARY.md`](TEST_SUMMARY.md), and the [parity & validation guide](https://stefanosbalaskas.github.io/eyeprocesspy/parity-and-validation/) for the underlying evidence.

## What it covers

| Research layer | Representative capabilities |
| --- | --- |
| **Import & canonicalization** | Vendor/generic readers, Gazepoint workflows, schema validation, coordinates, events, timebase, file pairing |
| **Gaze & AOIs** | Fixations, saccades, dwell, scanpaths, transitions, entropy, recurrence, hard/probabilistic/compositional AOIs |
| **Censored latency** | survival-ready event/censor tables, Kaplan–Meier, repeated-trial Cox, Weibull/log-normal AFT, PH diagnostics, sensitivity |
| **Pupil & multimodal** | Baselines, pupil features, missingness, functional pupil, synchronized streams, staged multimodal models |
| **Psychometrics & IRT** | Information, fit, DIF/DTF, process-informed and dynamic IRT, reliability, linking, norms, diagnostics |
| **Measurement intelligence** | Calibration uncertainty, spatial error fields, pupil-size artefact checks, reliability, process guardrails, fairness, item-bank optimization |
| **Dynamic & naturalistic gaze** | Dynamic AOIs, pursuit/microsaccade analysis, detector benchmarks, head/world coordinates, scanpath metric sensitivity |
| **Bayesian networks** | Static BN data contracts, temporal/edge constraints, pgmpy-backed learning/fitting/inference, participant bootstrap/CV, detector/AOI and robustness sensitivity, predictive calibration |
| **Validation** | Recovery, SBC-style evidence, stress tests, negative controls, grouped/leakage-aware validation, evidence atlases |
| **Reproducibility** | Benchmarks, manifests, provenance, frozen-R oracle, release audits, software-paper evidence |
| **Plots & reporting** | Publication-oriented gaze, AOI, pupil, quality, IRT, process and validation graphics |

## 30-second reproducible check

```python
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:

```python
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 |
| --- | --- |
| ![Gaze trace](docs/assets/gallery/gaze-trace.svg) | ![Probabilistic AOI](docs/assets/gallery/probabilistic-aoi.svg) |

| Pupil time series | Process reliability |
| --- | --- |
| ![Pupil time series](docs/assets/gallery/pupil-timeseries.svg) | ![Process reliability](docs/assets/gallery/process-reliability.svg) |

[Open the complete visual gallery →](https://stefanosbalaskas.github.io/eyeprocesspy/gallery/)

## Choose your path

- **New to the package:** [Getting started](https://stefanosbalaskas.github.io/eyeprocesspy/getting-started/) → [Worked examples](https://stefanosbalaskas.github.io/eyeprocesspy/examples/) → [Cookbook](https://stefanosbalaskas.github.io/eyeprocesspy/cookbook/)
- **Standardized Data Quality:** [Overview](https://stefanosbalaskas.github.io/eyeprocesspy/guides/data-quality/) · [9-point example](https://stefanosbalaskas.github.io/eyeprocesspy/examples/data-quality-validation/) · [Plot gallery](https://stefanosbalaskas.github.io/eyeprocesspy/examples/data-quality-plot-gallery/) · [Sensitivity](https://stefanosbalaskas.github.io/eyeprocesspy/examples/data-quality-sensitivity/) · [Focused API](https://stefanosbalaskas.github.io/eyeprocesspy/reference/data-quality/)\n- **Eye-tracking / AOI work:** [End-to-end eye-tracking](https://stefanosbalaskas.github.io/eyeprocesspy/guides/end-to-end-eye-tracking/) · [Measurement validity & dynamic gaze](https://stefanosbalaskas.github.io/eyeprocesspy/guides/measurement-validity-dynamic-gaze/) · [Gazepoint import & QC](https://stefanosbalaskas.github.io/eyeprocesspy/guides/gazepoint-import-qc/)
- **Gaze latency / TTFF:** [Censored gaze-latency method](https://stefanosbalaskas.github.io/eyeprocesspy/methods/gaze-survival/) · [Disclosure example](https://stefanosbalaskas.github.io/eyeprocesspy/examples/gaze-survival-analysis/) · [Evidence-verification example](https://stefanosbalaskas.github.io/eyeprocesspy/examples/gaze-verification-survival/) · [Troubleshooting](https://stefanosbalaskas.github.io/eyeprocesspy/methods/gaze-survival/troubleshooting/) · [Reproducibility checklist](https://stefanosbalaskas.github.io/eyeprocesspy/methods/gaze-survival/reproducibility-checklist/)
- **Pupillometry / multimodal:** [Pupillometry guide](https://stefanosbalaskas.github.io/eyeprocesspy/guides/pupillometry/) · [Quality & uncertainty](https://stefanosbalaskas.github.io/eyeprocesspy/guides/process-quality-uncertainty/)
- **Psychometrics / IRT:** [Psychometrics & IRT](https://stefanosbalaskas.github.io/eyeprocesspy/guides/psychometrics-irt/) · [IRT example](https://stefanosbalaskas.github.io/eyeprocesspy/examples/irt-diagnostics/)
- **Full workflows:** [Featured workflows](https://stefanosbalaskas.github.io/eyeprocesspy/articles/featured-workflows/) · [88-article library](https://stefanosbalaskas.github.io/eyeprocesspy/articles/)
- **Lookup:** [API reference](https://stefanosbalaskas.github.io/eyeprocesspy/reference/api/) · [Plotting reference](https://stefanosbalaskas.github.io/eyeprocesspy/reference/plotting/) · [FAQ](https://stefanosbalaskas.github.io/eyeprocesspy/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`](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`](LICENSE).
