Runnable examples

eyeprocesspy ships deterministic examples that require no private participant data. The focused workflows below have been executed against the CI-built 0.1.0 wheel; the gallery generators produce the figures shown throughout this site.

• :material-vector-link: Trial-level mediation preparation

  Preserve every repeated-measures trial while separating within- and between-participant exposure/gaze components and auditing zero, missingness, and quality states.

  Open mediation guide

• :material-crosshairs-gps: Measurement validity and dynamic gaze

  Audit calibration error, pupil-size artefact, moving AOIs, pursuit/microsaccade classification, naturalistic coordinates, scanpath metric dependence, and synthetic measurement stress.

  Open worked workflow

• :material-eye: Core gaze, AOI and provenance

  Validate a canonical EyeDataset, recover scanpaths and transitions, compute gaze entropy, render auditable plots and inspect provenance.

  Open worked workflow

• :material-target: Calibration uncertainty → probabilistic AOIs

  Fit an empirical calibration-error model, propagate coordinate uncertainty and diagnose boundary-sensitive AOI assignments.

  Open worked workflow

• :material-chart-scatter-plot: Standardized data quality

  Use a synthetic 9-point validation to separate accuracy from precision, inspect realized sampling and data loss, apply review-only thresholds, and carry quality decisions into sensitivity analysis.

  Open validation workflow · Open plot gallery · Open sensitivity workflow

• :material-chart-timeline-variant: Process-measure reliability

  Estimate repeated-measure ICC, Bland–Altman agreement and temporal stability without confusing reliability with construct validity.

  Open worked workflow

• :material-timer-sand: Censored gaze latency

  Build event/censor rows from trial windows and fixation/AOI events, retain never-inspected valid trials, fit clustered Cox/AFT models, inspect diagnostics, and produce manuscript-ready reporting.

  Open worked workflow

• :material-source-branch: Evidence-verification survival

  Model time to first source/evidence AOI entry under repeated conditions, retain valid never-inspected trials as censored observations, and compare clustered Cox with explicit AFT sensitivity models.

  Open verification workflow

• :material-clipboard-text-outline: AOI analysis plan

  Fix the perturbation envelope, denominator rules, model specification, failure handling, and interpretation language before branch-specific results are inspected.

  Open worked plan

• :material-package-variant-closed-check: AOI reporting bundle

  Package the declared plan, branch audit, assignment/model evidence, failures, provenance, report, figures, and deterministic hashes for manuscript or reviewer handoff.

  Open reporting bundle

• :material-vector-polygon: AOI perturbation sensitivity

  Perturb AOI geometry in pixels or degrees, remap fixations, recompute features, propagate the same model, and inspect robustness visually.

  Open worked workflow

• :material-alert-circle-check: AOI failure clinic

  Trigger geometry failure, overlap ambiguity, non-convergence, callback failure, and missing coordinates deliberately, then inspect the retained audit trail.

  Open failure clinic

• :material-chart-bell-curve-cumulative: IRT diagnostics

  Inspect conditional information, item fit and DIF with publication-ready Matplotlib diagnostics.

  Open worked workflow

• :material-tune-variant: Detector choice → inference

  Compare defensible event detectors, propagate differences into AOI features, fit the same model across branches, and report coefficient stability rather than significance counts.

  Open worked workflow

• :material-alert-circle-outline: Detector failure clinic

  Exercise explicit detector failure, quality exclusion, outcome missingness, and callback-contract failure while retaining every state in audit tables.

  Open failure clinic

For short task-oriented snippets, use the Cookbook. For visual output, browse the visual gallery.

Verify the installation

import eyeprocesspy as ep

print(ep.__version__)
print(ep.__r_reference_version__)

study = ep.eyeprocess_benchmark_study()
audit = ep.validate_benchmark_study(study)
print(audit["valid"])

Import and validate an export

import eyeprocesspy as ep

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

if not issues.empty:
    print(issues)

The canonical EyeDataset keeps recordings, streams, gaze, eye samples, episodes, events, intervals, responses, coordinate spaces, AOIs, features, quality and provenance in explicit tables.

Scanpath and transition analysis

sequence = ep.scanpath_sequence(
    eye,
    trial_id="trial-01",
    source="visits",
    collapse_consecutive=True,
)

matrix = ep.transition_matrix(
    eye,
    source="visits",
    normalize="row",
)

entropy = ep.gaze_entropy(
    eye,
    level="trial",
    source="samples",
)

Plot gaze, fixations and pupil data

import matplotlib.pyplot as plt
import eyeprocesspy as ep

ax = ep.plot_eye_trace(eye, trial_id="trial-01")
plt.show()

ax = ep.plot_scanpath(eye, trial_id="trial-01")
plt.show()

ax = ep.plot_pupil_timeseries(eye, trial_id="trial-01")
plt.show()

The plotting surface preserves its numerical payload on the returned axes where relevant:

plot_data = ax.eyeprocess_plot_data

Matrix plots additionally expose ax.eyeprocess_plot_matrix.

Process-measure reliability

profile = ep.process_reliability_profile(
    repeated,
    person="person",
    session="session",
    measure="dwell_score",
)

print(profile["icc"])
print(profile["bland_altman"]["summary"])

Reliability is population- and design-dependent; it does not establish construct validity.

Calibration uncertainty and probabilistic AOIs

model = ep.calibration_error_model(calibration_validation_data)
uncertainty = ep.gaze_uncertainty_ellipse(model, level=0.95)

assignment = ep.probabilistic_aoi_assignment(
    gaze_points,
    aois,
    model,
    draws=500,
    seed=1,
    min_probability=0.50,
)

This workflow quantifies coordinate uncertainty under the fitted calibration-error model; it does not estimate a posterior probability of psychological attention.

IRT diagnostic plotting

ax = ep.plot_eye_irt_information_profile(information_profile)
ax = ep.plot_eye_irt_item_fit(item_fit, statistic="infit")
ax = ep.plot_eye_irt_dif_curve(dif_curve)

The wider IRT surface also includes person fit, Q3/local dependence, score uncertainty, adaptive traces, link stability, DTF, recovery/SBC evidence, bank coverage, prior sensitivity and process-alignment diagnostics.

Provenance and reproducibility

manifest = ep.provenance_manifest(eye)
print(manifest["schema_version"])
print(manifest["sources"])
print(manifest["validation"])

For release-level verification, use the deterministic benchmark, validation evidence, reproducibility manifest and software-paper evidence workflows documented in the article library.

Executable programs

Script	Purpose	Output
examples/data_quality_validation.py	Standardized 9-point quality report with review-only thresholds	console report
examples/detector_multiverse_worked.py	Detector specs → events → AOIs/features → identical model → robustness report	detector-multiverse-output/*.svg + Markdown
examples/detector_multiverse_failure_clinic.py	Deliberate detector/model failures → retained status, warnings, input audit, callback validation	console audit tables
examples/calibration_probabilistic_aoi.py	Calibration error → uncertainty ellipse → probabilistic AOI	workflow-output/*.svg
examples/process_reliability.py	ICC, Bland–Altman and temporal stability	workflow-output/process-reliability.svg
examples/irt_diagnostics.py	Information, item fit and DIF diagnostics	workflow-output/*.svg
examples/core_gallery.py	Eight core gaze/AOI/pupil plots	gallery-output/*.svg
examples/advanced_gallery.py	Reliability, uncertainty, quality and IRT plot families	gallery-output/*.svg
examples/worked_gaze_survival_analysis.py	Raw trial/event inputs → censoring → Kaplan–Meier → clustered Cox/AFT → diagnostics/reporting	console summaries + survival plots
examples/worked_gaze_verification_survival.py	Source/evidence AOI entry → censoring → clustered Cox/AFT → diagnostics/reporting	CSV/JSON summaries + Kaplan–Meier SVG
examples/aoi_perturbation_sensitivity.py	AOI geometry → reassignment → feature/model sensitivity → robustness plots	workflow-output/aoi-*.svg
examples/aoi_reporting_bundle.py	AOI result → manuscript/reviewer evidence bundle → deterministic SHA-256 manifest	workflow-output/aoi-reporting-bundle/*
examples/aoi_perturbation_failure_clinic.py	Deliberate AOI geometry/model failures → retained audits → troubleshooting report	workflow-output/aoi-failure-clinic/*

| examples/multilevel_mediation_preparation.py | Trial-level gaze-mediator preparation, within/between decomposition, zero/missing/quality audit | console audit tables |

All listed examples are deterministic and use no private participant data.

AOI uncertainty

• AOI analysis plan: filled preregistration-style plan with API mapping and planned interpretation rules.
• AOI reporting bundle: deterministic evidence package for manuscript, reviewer, and replication handoff.
• AOI perturbation sensitivity: fixation-level end-to-end geometry, assignment, feature, model, and plotting workflow.
• AOI perturbation failure clinic: deliberate geometry/model failure, ambiguity, non-convergence, and retained audit trails.
• Sample-level AOI sensitivity: explicit sample semantics, zero-versus-missing cells, and when to separate geometry from detector uncertainty.

AOI robustness learning path

Step	Question	Start here
1. Plan	What boundary changes are scientifically defensible?	Filled analysis plan
2. Run	How do assignments, features, and the same model change?	Perturbation sensitivity workflow
3. Diagnose	What if geometry, assignment, or model branches fail?	Failure clinic
4. Report	What evidence should accompany the manuscript/reviewer response?	Reporting bundle

Measurement layer. Check how frequently observations keep, gain, lose, or change AOI assignment.

Inference layer. Compare coefficient magnitude and intervals across evaluable AOI branches.

Standardized data quality

• Worked 9-point validation: six synthetic quality profiles separating target error, short-term precision, timing instability, and missingness.
• Data Quality plot gallery: focused accuracy, RMS-S2S, BCEA, sampling-interval, and dashboard visuals with interpretation boundaries.
• Quality-rule sensitivity: compare defensible review/exclusion specifications while keeping the canonical quality report intact.
• Methodological guide: equations, units, interpretation boundaries, and when not to use each metric.
• Reporting guideline: manuscript items, suggested wording, limitations, and long-gap versus estimated dropped-sample reporting.

Bayesian-network examples

• Multimodal Bayesian-network example: Condition, gaze, pupil, EDA, trust, and choice with fixed-DAG fitting, constrained structure learning, and posterior evidence propagation.
• Bayesian-network sensitivity: compare graph robustness across detector and AOI specifications while keeping preprocessing outside the BN layer.