Metadata-Version: 2.4
Name: eyetrajectoriespy
Version: 0.9.0
Summary: Functional and continuous trajectory analysis for eye-tracking data in Python
Author: Stefanos Balaskas
License-Expression: MIT
Project-URL: Homepage, https://stefanosbalaskas.github.io/eyetrajectoriespy/
Project-URL: Repository, https://github.com/stefanosbalaskas/eyetrajectoriespy
Project-URL: Documentation, https://stefanosbalaskas.github.io/eyetrajectoriespy/
Project-URL: Issues, https://github.com/stefanosbalaskas/eyetrajectoriespy/issues
Keywords: eye-tracking,gaze,functional-data-analysis,FPCA,MFPCA,trajectory-analysis,curve-registration,recurrence-analysis,nonlinear-dynamics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: scipy>=1.11
Requires-Dist: scikit-learn>=1.4
Requires-Dist: matplotlib>=3.8
Requires-Dist: statsmodels>=0.14
Provides-Extra: fda
Requires-Dist: scikit-fda<0.11,>=0.10.1; extra == "fda"
Requires-Dist: multimethod<2,>=1.12; extra == "fda"
Provides-Extra: sparse
Requires-Dist: FDApy<1.1,>=1.0.3; python_version < "3.13" and extra == "sparse"
Provides-Extra: elastic
Requires-Dist: fdasrsf>=2.7; extra == "elastic"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.7.7; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"
Requires-Dist: PyYAML>=6.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Provides-Extra: all
Requires-Dist: scikit-fda<0.11,>=0.10.1; extra == "all"
Requires-Dist: multimethod<2,>=1.12; extra == "all"
Requires-Dist: FDApy<1.1,>=1.0.3; python_version < "3.13" and extra == "all"
Requires-Dist: fdasrsf>=2.7; extra == "all"
Dynamic: license-file

# eyetrajectoriespy

[![PyPI version](https://img.shields.io/pypi/v/eyetrajectoriespy.svg)](https://pypi.org/project/eyetrajectoriespy/)
[![GitHub Release](https://img.shields.io/github/v/release/stefanosbalaskas/eyetrajectoriespy)](https://github.com/stefanosbalaskas/eyetrajectoriespy/releases)
[![Python](https://img.shields.io/pypi/pyversions/eyetrajectoriespy.svg)](https://pypi.org/project/eyetrajectoriespy/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://stefanosbalaskas.github.io/eyetrajectoriespy/)

**Functional and continuous trajectory analysis for eye-tracking data in Python.**

`eyetrajectoriespy` treats gaze as a function of trial time rather than immediately reducing it to fixation counts, dwell summaries, or symbolic scanpaths. It supports continuous planar paths

```text
G_i(t) = [x_i(t), y_i(t)]^T
```

derived univariate functions, compositional AOI-probability trajectories, repeated-trial multilevel decompositions, explicit registration, and optional elastic phase–amplitude analysis.

> **Status:** stable pre-1.0 release (`0.9.0`). The scientific platform, reference-validation layer, reproducibility contracts, packaging checks, and five canonical workflows are qualified.

## What scientific problem does this solve?

`eyetrajectoriespy` is for analyses where the **trajectory itself is a
scientific object**. It keeps temporal structure visible instead of immediately
collapsing gaze into scalar summaries, while making repeated-measures hierarchy,
uncertainty and analytical provenance explicit.

The central design rule is that consequential choices stay visible: no silent
interpolation, missing-to-zero conversion, smoothing, registration, time or
coordinate normalization, family/model selection, denominator inference or
exposure inference.

## Which workflow do I need?

| Scientific question | Start here |
|---|---|
| What are the dominant modes of continuous gaze variation? | [Continuous gaze exploration + FPCA](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/fpca-exploration/) |
| How does an experimental predictor change a continuous functional response? | [Experimental functional regression](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/experimental-functional-regression/) |
| How do repeated participant trials affect functional inference? | [Repeated-trial functional mixed effects](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/repeated-trial-mixed-effects/) |
| How do predictors change repeated binary or count functional responses? | [Generalized binary/count responses](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/generalized-responses/) |
| Is recurrence or nonlinear temporal organization the scientific target? | [Nonlinear/recurrence analysis](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/nonlinear-recurrence/) |

The canonical workflow index is the recommended entry point for new analyses.
It separates default routes from advanced, diagnostic and experimental
branches.

## What assumptions does the workflow make?

Every canonical route documents its observation unit, hierarchy, estimand,
uncertainty/resampling unit and major failure conditions. Before interpreting a
result, use the package's [assumptions and diagnostics](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/assumptions/)
and [limitations](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/limitations/)
alongside the workflow-specific page.

The package prefers explicit failure or review over silently manufacturing a
convenient answer.

## Where is the full advanced API?

The README is intentionally no longer the exhaustive function catalogue.

- [Capability inventory](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/capability-inventory/)
- [Public API](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/api/)
- [API stability and hierarchy](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/api-stability/)
- [Mathematical reference](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/mathematical-reference/)
- [Capability status and roadmap](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/status-roadmap/)
- [Reference validation & performance envelope](https://stefanosbalaskas.github.io/eyetrajectoriespy/validation/reference-validation-ledger/)

## Install

Stable release:

```bash
pip install eyetrajectoriespy==0.9.0
```

Or install the current stable release:

```bash
pip install eyetrajectoriespy
```

Development checkout:

```bash
pip install -e .
```

Development and documentation:

```bash
pip install -e ".[dev,docs]"
```

Optional interoperability:

```bash
pip install -e ".[fda]"       # scikit-fda
pip install -e ".[sparse]"    # FDApy sparse/PACE FPCA; Python 3.11–3.12
pip install -e ".[elastic]"   # fdasrsf
```

The core package remains Python 3.11–3.13. The current FDApy 1.0.3 sparse backend is qualified separately on Python 3.11–3.12 because FDApy pins NumPy <2.0, while NumPy 1.26.x does not support Python 3.13.

## Quick start

```python
from eyetrajectoriespy import fit_mfpca, simulate_planar_trajectories, summarise_fpca

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(summarise_fpca(fit))
```

## Documentation

The repository-level [mathematical contracts](MATHEMATICAL_CONTRACTS.md), generated [function → equation index](FUNCTION_EQUATION_INDEX.md), and [workflow atlas](WORKFLOW_ATLAS.md) render directly on GitHub. The site expands them with assumptions, API mappings, worked examples, and a [Visual gallery](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/visual-gallery/).

The methods site is configured for GitHub Pages:

**https://stefanosbalaskas.github.io/eyetrajectoriespy/**

Use the site for the five canonical workflows, advanced method guides, worked
examples, assumptions/limitations, validation ledger, implementation-matched
mathematical reference, API documentation and reproducible SVG plot gallery.

## Scope boundary

`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 generalized observation-family line is intentionally closed at Bernoulli /
grouped-binomial logit and Poisson expected-count/rate GEE. Negative binomial,
zero-inflated, hurdle and Tweedie families are not automatic next features.
Classical Floquet/monodromy and bifurcation analysis remain outside the raw-gaze
API without an explicitly identified dynamical model.

Version 0.55 began the stabilization line; version 0.56 added
evidence-typed independent/reference validation, an explicit numerical-tolerance
policy, and a repeated runtime/peak-memory reference envelope. Version 0.57 adds
portable scientific-result snapshots, explicit environment capture, five
qualified canonical end-to-end examples, and coordinated GitHub/PyPI release
machinery. Version 0.9.0 is the first stable pre-1.0 release after the qualified
0.9.0rc1 publication. Scientific product qualification remains more important
than estimator count. See the
[release-readiness checklist](https://stefanosbalaskas.github.io/eyetrajectoriespy/release-readiness/).

- [Portable scientific results](https://stefanosbalaskas.github.io/eyetrajectoriespy/reproducibility/portable-results/)
- [Reproducibility bundle checklist](https://stefanosbalaskas.github.io/eyetrajectoriespy/reproducibility/checklist/)
- [Release process](https://stefanosbalaskas.github.io/eyetrajectoriespy/release-process/)

## Validation

Current local/CI qualification status and the exact pending re-check list are maintained in [VALIDATION.md](VALIDATION.md).

```bash
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/validate_docs_contracts.py
mkdocs build --strict
```

## License

MIT © 2026 Stefanos Balaskas.
