eyetrajectoriespy

Functional analysis of continuous and sparse eye-tracking trajectories in Python.

Instead of immediately reducing gaze to fixation counts, dwell summaries, or symbolic scanpaths, eyetrajectoriespy treats gaze as a time-indexed functional process

$$ \mathbf G_i(t)= \begin{bmatrix} x_i(t)\ y_i(t) \end{bmatrix}. $$

Stable: 1.0.0 · Published 1.1 release candidate: 1.1.0rc1 · Python: 3.11–3.13

pip install eyetrajectoriespy
# exact reproducible stable release
pip install eyetrajectoriespy==1.0.0
# exact published 1.1 prerelease
pip install eyetrajectoriespy==1.1.0rc1

Documentation · Quick start · Choose a workflow · Mathematics · Visual gallery · Validation

Current stable release: 1.0.0
1.0.0 freezes the evidence-backed 1.0 compatibility boundary over the production-observed 1.0.0rc1 scientific/API surface without adding a new estimator or changing scientific behavior. Release qualification, immutable hashes, OIDC/attestation evidence, and publication chronology are retained in the 1.0.0 release notes and validation records rather than repeated on this landing page.

Published 1.1 release candidate: 1.1.0rc1
The post-1.0 sparse/irregular scientific programme (#158) and integration/readiness programme (#183) are complete through R5. 1.1.0rc1 is published on GitHub and production PyPI from exact protected-main commit f4405897e2a7a2392c03523cc7fa18e43df00e5e; the frozen 1.0.0 root compatibility boundary remains unchanged, and the 1.1 additions remain supported module-scoped APIs. 1.0.0 remains the stable/default release while the RC undergoes production-installed observation before any final 1.1.0 promotion decision.

What can it model?

The post-1.0 module-scoped APIs are documented in the 1.1 module API and integration audit. They are intentionally not root re-exports and should not be interpreted as stable 1.1.0 functionality until final promotion is separately qualified.

Which workflow do I need?

Minimal dense/common-grid example

from eyetrajectoriespy import fit_mfpca, simulate_planar_trajectories

gaze = simulate_planar_trajectories(
    n_participants=20,
    trials_per_participant=6,
    random_state=7,
)
fit = fit_mfpca(gaze, n_components=0.95, scaling="dimension_sd")
print(fit.explained_variance_ratio)

Minimal sparse paired-planar example

import numpy as np
from eyetrajectoriespy import fit_sparse_mfpca

fit = fit_sparse_mfpca(
    irregular,
    dimensions=("x", "y"),
    n_components=2,
    evaluation_grid=np.linspace(0.0, 1.0, 41),
    mean_bandwidth=0.20,
    covariance_bandwidth=0.30,
    measurement_error="diagonal",
    measurement_error_variance=(0.0025, 0.0025),
    psd_action="project",
    score_failure_action="retain_nan",
)

The sparse estimator uses native paired observations to estimate a joint population mean/covariance model. Evaluating fitted population functions at native times for PACE is not raw-trajectory interpolation.

What eyetrajectoriespy refuses to hide

Consequential choices stay explicit: missingness, interpolation, smoothing, registration, time/coordinate normalization, analysis support, measurement-error assumptions, PSD policy, family/model selection, resampling unit, denominator/exposure semantics, and failure/status codes.

Scope

eyetrajectoriespy starts once gaze has a scientifically interpretable time and coordinate representation. Event detection, general gaze QC, survival analysis, AOI perturbation robustness, and symbolic sequence models belong upstream or in specialist packages.

The package deliberately separates stable public methods, advanced diagnostics, external-backend interoperability, and experimental methods. Scientific product qualification matters more than estimator count.

Where is the full advanced API?

The README is intentionally a compact entry point rather than the exhaustive function catalogue.

• Capability inventory
• Public API
• 1.1 module-scoped API
• 1.1 integration audit
• API stability and hierarchy
• Mathematical reference
• Capability status and roadmap
• Reference validation & performance envelope

Release lineage and reproducibility

The stable pre-1.0 sequence remains explicit: 0.10.0 introduced the native sparse univariate FPCA/PACE line, the immutable 0.11.0rc1 prerelease preceded final 0.11 known-truth recovery infrastructure, and 0.12.0 added the native sparse planar MFPCA/joint-PACE line. 1.0.0 closes that stabilization programme as the frozen stable compatibility baseline. Published tags and distributions remain immutable historical records. The completed A1–C1 and R1–R5 1.1 work is published as immutable prerelease 1.1.0rc1; production-installed observation now precedes any separately qualified final 1.1.0 promotion.

• Portable scientific results
• Reproducibility bundle checklist
• Release process

Documentation and reproducibility

• Sparse planar MFPCA / joint PACE guide
• Implementation-matched mathematical reference
• Function → equation index
• Mathematical contracts
• Workflow atlas
• Current validation ledger
• 1.0.0 release notes
• 1.1.0rc1 release notes

Development checks:

python -m pytest --cov=eyetrajectoriespy
python -m compileall -q src
python scripts/generate_function_equation_index.py --check
python scripts/generate_docs_gallery.py
python scripts/generate_sparse_mfpca_docs_figure.py
python scripts/validate_docs_contracts.py
mkdocs build --strict

Citation and license

See CITATION.cff for citation metadata. MIT © 2026 Stefanos Balaskas.