Cookbook¶

Short recipes for common eyeprocesspy tasks. These snippets are intentionally small; use the linked worked examples and articles when the analysis decision itself needs justification.

Import a vendor export¶

import eyeprocesspy as ep

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

Discover supported adapters¶

print(ep.supported_eye_formats())

Inspect one canonical table¶

gaze = ep.get_eye_table(eye, "gaze_samples")

Validate before analysis¶

issues = ep.validate_eye_dataset(eye)
errors = issues.loc[issues["severity"].eq("error")]
if not errors.empty:
    raise RuntimeError(errors.to_string(index=False))

Extract a scanpath¶

seq = ep.scanpath_sequence(
    eye,
    trial_id="T1",
    source="visits",
    collapse_consecutive=True,
)

Build a normalized AOI transition matrix¶

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

Compute gaze entropy¶

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

Plot a gaze trace¶

ax = ep.plot_eye_trace(eye, trial_id="T1")
ax.figure.savefig("gaze-trace.svg", bbox_inches="tight")

Retrieve the data behind a plot¶

plot_data = ax.eyeprocess_plot_data

For matrix plots:

matrix = ax.eyeprocess_plot_matrix

Plot fixations¶

ax = ep.plot_fixations(eye, trial_id="T1")

Plot a scanpath¶

ax = ep.plot_scanpath(eye, trial_id="T1")

Plot a gaze heatmap¶

ax = ep.plot_gaze_heatmap(eye, trial_id="T1", bins=(50, 50))

Plot pupil time series¶

ax = ep.plot_pupil_timeseries(eye, trial_id="T1")

Estimate effective sampling frequency¶

quality = ep.effective_sampling_frequency(
    samples,
    time="timestamp_ms",
    unit="ms",
    by="recording_id",
)

Audit sampling irregularity¶

audit = ep.audit_sampling_irregularity(
    samples,
    time="timestamp_ms",
    unit="ms",
    by="recording_id",
    cv_threshold=0.05,
)

Fit an empirical calibration-error model¶

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

Propagate calibration uncertainty to AOIs¶

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

Estimate repeated-measure reliability¶

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

Inspect the process-measure registry¶

registry = ep.process_measure_registry()
gaze_measures = ep.find_process_measures(registry, channel="gaze")

Read a measure's guardrail card¶

card = ep.process_measure_card("dwell_time")
print(card["interpretation"])
print(card["guardrail"])

Plot an IRT information profile¶

ax = ep.plot_eye_irt_information_profile(profile_table)

Plot item fit¶

ax = ep.plot_eye_irt_item_fit(item_fit, statistic="infit")

Plot a DIF curve¶

ax = ep.plot_eye_irt_dif_curve(dif_curve)

Capture provenance¶

manifest = ep.provenance_manifest(eye)

Verify the bundled benchmark¶

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

Manual-install wheel verification¶

python -c "import eyeprocesspy as ep; print(ep.__version__, ep.__r_reference_version__)"