Metadata-Version: 2.4
Name: eyetrajectoriespy
Version: 1.1.0rc1
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 :: 5 - Production/Stable
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 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` · **1.1 release candidate under qualification:** `1.1.0rc1` · **Python:** 3.11–3.13

```bash
pip install eyetrajectoriespy
# exact reproducible stable release
pip install eyetrajectoriespy==1.0.0
```

[Documentation](https://stefanosbalaskas.github.io/eyetrajectoriespy/) ·
[Quick start](https://stefanosbalaskas.github.io/eyetrajectoriespy/quickstart/) ·
[Choose a workflow](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/) ·
[Mathematics](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/mathematical-reference/) ·
[Visual gallery](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/visual-gallery/) ·
[Validation](https://stefanosbalaskas.github.io/eyetrajectoriespy/validation/reference-validation-ledger/)

> **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](https://stefanosbalaskas.github.io/eyetrajectoriespy/releases/1.0.0/) and validation records rather than repeated on this landing page.
>
> **1.1 release candidate under qualification: `1.1.0rc1`**  
> The post-1.0 sparse/irregular scientific programme (#158) and integration/readiness tranches R1–R4 (#183) are complete. R4 recorded `eligible_for_rc_decision=true`, so R5 is qualifying the same supported **module-scoped 1.1 APIs** under the literal `1.1.0rc1` identity. The frozen `1.0.0` root compatibility boundary is unchanged, fresh RC evidence is kept separate from historical 1.0/R4 records, and publication readiness remains jointly disarmed.

![Sparse planar covariance structure estimated by eyetrajectoriespy](docs/assets/gallery/sparse-mfpca-covariance-blocks.svg)

## What can it model?

| Scientific object | Main route | Status |
|---|---|---|
| Dense/common-grid continuous x/y gaze | `fit_mfpca()` | stable 1.0 |
| Sparse/irregular single-coordinate gaze | `fit_sparse_fpca()` + PACE | stable 1.0 |
| Sparse/irregular paired planar x/y gaze | `fit_sparse_mfpca()` + joint PACE | stable 1.0 |
| Repeated participant/trial functions | functional mixed effects / multilevel FPCA | stable 1.0 |
| Conditional uncertainty for sparse PACE and joint PACE scores | `sparse_score_uncertainty` / `sparse_multivariate_score_uncertainty` | supported 1.1 RC module API |
| Audited sparse smoothing-bandwidth selection | `sparse_bandwidth_selection` / `sparse_multivariate_bandwidth_selection` | supported 1.1 RC module API |
| Candidate-sample observation-process diagnostics | `observation_process` | supported 1.1 RC module API |
| Sparse participant/trial hierarchical decomposition | `sparse_multilevel` | supported 1.1 RC module API |
| Coordinate-specific asynchronous sparse planar gaze | `sparse_multivariate_async` | supported 1.1 RC module API |
| Future/partially observed sparse trajectory prediction and participant-aware conformal bands | `sparse_partial_prediction` / `sparse_partial_conformal` | supported 1.1 RC module API |

The post-1.0 module-scoped APIs are documented in the [1.1 module API](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/one-dot-one-module-api/) and [integration audit](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/one-dot-one-integration-audit/). They are intentionally not root re-exports and should not be interpreted as already-published `1.1.0` functionality.

## 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/) |

## Minimal dense/common-grid example

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

```python
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](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/capability-inventory/)
- [Public API](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/api/)
- [1.1 module-scoped API](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/one-dot-one-module-api/)
- [1.1 integration audit](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/one-dot-one-integration-audit/)
- [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/)

## 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–R4 work is now being qualified under the non-published `1.1.0rc1` identity; a green RC still does not authorize publication.

- [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/)

## Documentation and reproducibility

- [Sparse planar MFPCA / joint PACE guide](https://stefanosbalaskas.github.io/eyetrajectoriespy/guides/sparse-multivariate-fpca/)
- [Implementation-matched mathematical reference](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/mathematical-reference/)
- [Function → equation index](FUNCTION_EQUATION_INDEX.md)
- [Mathematical contracts](MATHEMATICAL_CONTRACTS.md)
- [Workflow atlas](WORKFLOW_ATLAS.md)
- [Current validation ledger](https://stefanosbalaskas.github.io/eyetrajectoriespy/validation/reference-validation-ledger/)
- [1.0.0 release notes](docs/releases/1.0.0.md)

Development checks:

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

## Citation and license

See [`CITATION.cff`](CITATION.cff) for citation metadata. MIT © 2026 Stefanos Balaskas.
