eyetrajectoriespy 0.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (148) hide show
  1. eyetrajectoriespy-0.9.0/LICENSE +21 -0
  2. eyetrajectoriespy-0.9.0/PKG-INFO +230 -0
  3. eyetrajectoriespy-0.9.0/README.md +178 -0
  4. eyetrajectoriespy-0.9.0/pyproject.toml +74 -0
  5. eyetrajectoriespy-0.9.0/setup.cfg +4 -0
  6. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/__init__.py +913 -0
  7. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/analysis.py +694 -0
  8. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/backends.py +178 -0
  9. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/component_inference.py +307 -0
  10. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/compositional.py +123 -0
  11. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/conditional_transfer_entropy.py +575 -0
  12. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/conformal.py +348 -0
  13. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/elastic.py +92 -0
  14. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/embedding.py +463 -0
  15. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/fpca.py +229 -0
  16. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/function_on_scalar.py +621 -0
  17. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/functional_mixed_effects.py +932 -0
  18. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/functional_mixed_effects_covariance_sensitivity.py +1216 -0
  19. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/functional_mixed_effects_diagnostics.py +685 -0
  20. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/functional_mixed_effects_full_refit.py +920 -0
  21. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/functional_mixed_effects_inference.py +564 -0
  22. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/functional_mixed_effects_nested.py +1594 -0
  23. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/functional_rqa.py +412 -0
  24. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/generalized_function_on_scalar.py +1169 -0
  25. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/generalized_function_on_scalar_prediction.py +1145 -0
  26. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/inference.py +219 -0
  27. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/io.py +199 -0
  28. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/irregular.py +233 -0
  29. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/joint_recurrence.py +336 -0
  30. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/kinematics.py +496 -0
  31. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/mathematical_contracts.py +908 -0
  32. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/multilevel.py +96 -0
  33. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/multivariate_surrogates.py +561 -0
  34. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/nonlinear_dynamics.py +660 -0
  35. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/nonlinear_plotting.py +664 -0
  36. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/nonlinear_reporting.py +515 -0
  37. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/nonlinear_sensitivity.py +1099 -0
  38. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/nonlinear_types.py +477 -0
  39. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/outliers.py +271 -0
  40. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/phase.py +203 -0
  41. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/plotting.py +1464 -0
  42. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/portable_results.py +447 -0
  43. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/prediction.py +610 -0
  44. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/preprocessing.py +307 -0
  45. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/py.typed +0 -0
  46. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/recurrence.py +1074 -0
  47. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/recurrence_networks.py +287 -0
  48. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/registration.py +128 -0
  49. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/regression_inference.py +766 -0
  50. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/reporting.py +1181 -0
  51. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/return_maps.py +282 -0
  52. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/rqa_inference.py +451 -0
  53. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/score_uncertainty.py +251 -0
  54. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/selection.py +230 -0
  55. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/similarity_sensitivity.py +537 -0
  56. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/simulate.py +100 -0
  57. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/sparse.py +288 -0
  58. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/spectrum_inference.py +322 -0
  59. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/stability.py +435 -0
  60. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/subspace.py +325 -0
  61. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/transfer_entropy.py +375 -0
  62. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/transfer_entropy_sensitivity.py +410 -0
  63. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/types.py +1584 -0
  64. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/validation.py +90 -0
  65. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/wild_regression.py +448 -0
  66. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/wild_selection.py +533 -0
  67. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/wild_simultaneous.py +133 -0
  68. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy/wild_testing.py +465 -0
  69. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy.egg-info/PKG-INFO +230 -0
  70. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy.egg-info/SOURCES.txt +146 -0
  71. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy.egg-info/dependency_links.txt +1 -0
  72. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy.egg-info/requires.txt +39 -0
  73. eyetrajectoriespy-0.9.0/src/eyetrajectoriespy.egg-info/top_level.txt +1 -0
  74. eyetrajectoriespy-0.9.0/tests/test_api_consistency_policy.py +37 -0
  75. eyetrajectoriespy-0.9.0/tests/test_backends_optional.py +24 -0
  76. eyetrajectoriespy-0.9.0/tests/test_basis_projection.py +86 -0
  77. eyetrajectoriespy-0.9.0/tests/test_canonical_workflows.py +74 -0
  78. eyetrajectoriespy-0.9.0/tests/test_conditional_transfer_entropy_contracts.py +185 -0
  79. eyetrajectoriespy-0.9.0/tests/test_conditional_transfer_entropy_truths.py +203 -0
  80. eyetrajectoriespy-0.9.0/tests/test_conformal_fpca_anomaly.py +209 -0
  81. eyetrajectoriespy-0.9.0/tests/test_discrete_frechet.py +164 -0
  82. eyetrajectoriespy-0.9.0/tests/test_dtw_hardening_helpers.py +89 -0
  83. eyetrajectoriespy-0.9.0/tests/test_dynamic_time_warping.py +280 -0
  84. eyetrajectoriespy-0.9.0/tests/test_edge_contracts.py +146 -0
  85. eyetrajectoriespy-0.9.0/tests/test_fdapy_sparse_optional.py +61 -0
  86. eyetrajectoriespy-0.9.0/tests/test_fpc_simultaneous_bands.py +186 -0
  87. eyetrajectoriespy-0.9.0/tests/test_fpca.py +55 -0
  88. eyetrajectoriespy-0.9.0/tests/test_fpca_score_uncertainty.py +208 -0
  89. eyetrajectoriespy-0.9.0/tests/test_fpca_spectrum_uncertainty.py +217 -0
  90. eyetrajectoriespy-0.9.0/tests/test_fpcr_future_prediction_intervals.py +173 -0
  91. eyetrajectoriespy-0.9.0/tests/test_fpcr_regression_uncertainty.py +290 -0
  92. eyetrajectoriespy-0.9.0/tests/test_fpcr_slope_simultaneous_band.py +167 -0
  93. eyetrajectoriespy-0.9.0/tests/test_fpcr_wild_bootstrap_family_test.py +313 -0
  94. eyetrajectoriespy-0.9.0/tests/test_fpcr_wild_bootstrap_projection.py +239 -0
  95. eyetrajectoriespy-0.9.0/tests/test_fpcr_wild_bootstrap_selection.py +259 -0
  96. eyetrajectoriespy-0.9.0/tests/test_fpcr_wild_bootstrap_simultaneous.py +147 -0
  97. eyetrajectoriespy-0.9.0/tests/test_function_on_scalar.py +323 -0
  98. eyetrajectoriespy-0.9.0/tests/test_functional_mean_bands.py +248 -0
  99. eyetrajectoriespy-0.9.0/tests/test_functional_mixed_effects.py +289 -0
  100. eyetrajectoriespy-0.9.0/tests/test_functional_mixed_effects_covariance_sensitivity.py +492 -0
  101. eyetrajectoriespy-0.9.0/tests/test_functional_mixed_effects_diagnostics.py +273 -0
  102. eyetrajectoriespy-0.9.0/tests/test_functional_mixed_effects_full_refit.py +363 -0
  103. eyetrajectoriespy-0.9.0/tests/test_functional_mixed_effects_inference.py +293 -0
  104. eyetrajectoriespy-0.9.0/tests/test_functional_mixed_effects_random_slope.py +376 -0
  105. eyetrajectoriespy-0.9.0/tests/test_functional_mixed_effects_residual_correlation.py +512 -0
  106. eyetrajectoriespy-0.9.0/tests/test_functional_mixed_effects_trial_random_effect.py +680 -0
  107. eyetrajectoriespy-0.9.0/tests/test_generalized_function_on_scalar.py +1674 -0
  108. eyetrajectoriespy-0.9.0/tests/test_io_preprocessing.py +67 -0
  109. eyetrajectoriespy-0.9.0/tests/test_irregular_native.py +155 -0
  110. eyetrajectoriespy-0.9.0/tests/test_joint_recurrence.py +286 -0
  111. eyetrajectoriespy-0.9.0/tests/test_kantz_lle.py +195 -0
  112. eyetrajectoriespy-0.9.0/tests/test_kinematics_reporting_plotting.py +53 -0
  113. eyetrajectoriespy-0.9.0/tests/test_mathematical_contracts.py +81 -0
  114. eyetrajectoriespy-0.9.0/tests/test_multilevel_analysis.py +55 -0
  115. eyetrajectoriespy-0.9.0/tests/test_multivariate_surrogates.py +302 -0
  116. eyetrajectoriespy-0.9.0/tests/test_new_reporting_plotting.py +54 -0
  117. eyetrajectoriespy-0.9.0/tests/test_nonlinear_dynamics.py +186 -0
  118. eyetrajectoriespy-0.9.0/tests/test_nonlinear_embedding.py +211 -0
  119. eyetrajectoriespy-0.9.0/tests/test_nonlinear_parameter_sensitivity.py +379 -0
  120. eyetrajectoriespy-0.9.0/tests/test_nonlinear_plotting.py +163 -0
  121. eyetrajectoriespy-0.9.0/tests/test_nonlinear_reporting.py +167 -0
  122. eyetrajectoriespy-0.9.0/tests/test_outlier_influence.py +181 -0
  123. eyetrajectoriespy-0.9.0/tests/test_outlier_reporting_plotting.py +48 -0
  124. eyetrajectoriespy-0.9.0/tests/test_phase.py +110 -0
  125. eyetrajectoriespy-0.9.0/tests/test_portable_results.py +169 -0
  126. eyetrajectoriespy-0.9.0/tests/test_predictive_fpca_selection.py +296 -0
  127. eyetrajectoriespy-0.9.0/tests/test_public_api.py +59 -0
  128. eyetrajectoriespy-0.9.0/tests/test_qualification_ledgers.py +117 -0
  129. eyetrajectoriespy-0.9.0/tests/test_recurrence.py +368 -0
  130. eyetrajectoriespy-0.9.0/tests/test_recurrence_networks.py +251 -0
  131. eyetrajectoriespy-0.9.0/tests/test_recurrence_radius_profile.py +263 -0
  132. eyetrajectoriespy-0.9.0/tests/test_reference_validation.py +441 -0
  133. eyetrajectoriespy-0.9.0/tests/test_registration_compositional.py +46 -0
  134. eyetrajectoriespy-0.9.0/tests/test_release_hardening.py +173 -0
  135. eyetrajectoriespy-0.9.0/tests/test_return_maps.py +139 -0
  136. eyetrajectoriespy-0.9.0/tests/test_rqa_functional_sensitivity.py +227 -0
  137. eyetrajectoriespy-0.9.0/tests/test_rqa_functional_trajectories.py +136 -0
  138. eyetrajectoriespy-0.9.0/tests/test_rqa_population_bootstrap.py +358 -0
  139. eyetrajectoriespy-0.9.0/tests/test_selection_uncertainty.py +287 -0
  140. eyetrajectoriespy-0.9.0/tests/test_similarity_sensitivity.py +276 -0
  141. eyetrajectoriespy-0.9.0/tests/test_skfda_outliers.py +66 -0
  142. eyetrajectoriespy-0.9.0/tests/test_sparse_pace_contracts.py +294 -0
  143. eyetrajectoriespy-0.9.0/tests/test_stability.py +118 -0
  144. eyetrajectoriespy-0.9.0/tests/test_subspace_stability.py +240 -0
  145. eyetrajectoriespy-0.9.0/tests/test_trajectory_geometry.py +203 -0
  146. eyetrajectoriespy-0.9.0/tests/test_transfer_entropy.py +191 -0
  147. eyetrajectoriespy-0.9.0/tests/test_transfer_entropy_sensitivity.py +303 -0
  148. eyetrajectoriespy-0.9.0/tests/test_types_validation.py +75 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Stefanos Balaskas
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,230 @@
1
+ Metadata-Version: 2.4
2
+ Name: eyetrajectoriespy
3
+ Version: 0.9.0
4
+ Summary: Functional and continuous trajectory analysis for eye-tracking data in Python
5
+ Author: Stefanos Balaskas
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://stefanosbalaskas.github.io/eyetrajectoriespy/
8
+ Project-URL: Repository, https://github.com/stefanosbalaskas/eyetrajectoriespy
9
+ Project-URL: Documentation, https://stefanosbalaskas.github.io/eyetrajectoriespy/
10
+ Project-URL: Issues, https://github.com/stefanosbalaskas/eyetrajectoriespy/issues
11
+ Keywords: eye-tracking,gaze,functional-data-analysis,FPCA,MFPCA,trajectory-analysis,curve-registration,recurrence-analysis,nonlinear-dynamics
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
19
+ Requires-Python: >=3.11
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: numpy>=1.26
23
+ Requires-Dist: pandas>=2.1
24
+ Requires-Dist: scipy>=1.11
25
+ Requires-Dist: scikit-learn>=1.4
26
+ Requires-Dist: matplotlib>=3.8
27
+ Requires-Dist: statsmodels>=0.14
28
+ Provides-Extra: fda
29
+ Requires-Dist: scikit-fda<0.11,>=0.10.1; extra == "fda"
30
+ Requires-Dist: multimethod<2,>=1.12; extra == "fda"
31
+ Provides-Extra: sparse
32
+ Requires-Dist: FDApy<1.1,>=1.0.3; python_version < "3.13" and extra == "sparse"
33
+ Provides-Extra: elastic
34
+ Requires-Dist: fdasrsf>=2.7; extra == "elastic"
35
+ Provides-Extra: docs
36
+ Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
37
+ Requires-Dist: mkdocs-material<10,>=9.7.7; extra == "docs"
38
+ Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"
39
+ Requires-Dist: PyYAML>=6.0; extra == "docs"
40
+ Provides-Extra: dev
41
+ Requires-Dist: pytest>=8; extra == "dev"
42
+ Requires-Dist: pytest-cov>=5; extra == "dev"
43
+ Requires-Dist: ruff>=0.9; extra == "dev"
44
+ Requires-Dist: build>=1.2; extra == "dev"
45
+ Requires-Dist: twine>=6; extra == "dev"
46
+ Provides-Extra: all
47
+ Requires-Dist: scikit-fda<0.11,>=0.10.1; extra == "all"
48
+ Requires-Dist: multimethod<2,>=1.12; extra == "all"
49
+ Requires-Dist: FDApy<1.1,>=1.0.3; python_version < "3.13" and extra == "all"
50
+ Requires-Dist: fdasrsf>=2.7; extra == "all"
51
+ Dynamic: license-file
52
+
53
+ # eyetrajectoriespy
54
+
55
+ [![PyPI version](https://img.shields.io/pypi/v/eyetrajectoriespy.svg)](https://pypi.org/project/eyetrajectoriespy/)
56
+ [![GitHub Release](https://img.shields.io/github/v/release/stefanosbalaskas/eyetrajectoriespy)](https://github.com/stefanosbalaskas/eyetrajectoriespy/releases)
57
+ [![Python](https://img.shields.io/pypi/pyversions/eyetrajectoriespy.svg)](https://pypi.org/project/eyetrajectoriespy/)
58
+ [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://stefanosbalaskas.github.io/eyetrajectoriespy/)
59
+
60
+ **Functional and continuous trajectory analysis for eye-tracking data in Python.**
61
+
62
+ `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
63
+
64
+ ```text
65
+ G_i(t) = [x_i(t), y_i(t)]^T
66
+ ```
67
+
68
+ derived univariate functions, compositional AOI-probability trajectories, repeated-trial multilevel decompositions, explicit registration, and optional elastic phase–amplitude analysis.
69
+
70
+ > **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.
71
+
72
+ ## What scientific problem does this solve?
73
+
74
+ `eyetrajectoriespy` is for analyses where the **trajectory itself is a
75
+ scientific object**. It keeps temporal structure visible instead of immediately
76
+ collapsing gaze into scalar summaries, while making repeated-measures hierarchy,
77
+ uncertainty and analytical provenance explicit.
78
+
79
+ The central design rule is that consequential choices stay visible: no silent
80
+ interpolation, missing-to-zero conversion, smoothing, registration, time or
81
+ coordinate normalization, family/model selection, denominator inference or
82
+ exposure inference.
83
+
84
+ ## Which workflow do I need?
85
+
86
+ | Scientific question | Start here |
87
+ |---|---|
88
+ | What are the dominant modes of continuous gaze variation? | [Continuous gaze exploration + FPCA](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/fpca-exploration/) |
89
+ | How does an experimental predictor change a continuous functional response? | [Experimental functional regression](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/experimental-functional-regression/) |
90
+ | How do repeated participant trials affect functional inference? | [Repeated-trial functional mixed effects](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/repeated-trial-mixed-effects/) |
91
+ | How do predictors change repeated binary or count functional responses? | [Generalized binary/count responses](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/generalized-responses/) |
92
+ | Is recurrence or nonlinear temporal organization the scientific target? | [Nonlinear/recurrence analysis](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/nonlinear-recurrence/) |
93
+
94
+ The canonical workflow index is the recommended entry point for new analyses.
95
+ It separates default routes from advanced, diagnostic and experimental
96
+ branches.
97
+
98
+ ## What assumptions does the workflow make?
99
+
100
+ Every canonical route documents its observation unit, hierarchy, estimand,
101
+ uncertainty/resampling unit and major failure conditions. Before interpreting a
102
+ result, use the package's [assumptions and diagnostics](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/assumptions/)
103
+ and [limitations](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/limitations/)
104
+ alongside the workflow-specific page.
105
+
106
+ The package prefers explicit failure or review over silently manufacturing a
107
+ convenient answer.
108
+
109
+ ## Where is the full advanced API?
110
+
111
+ The README is intentionally no longer the exhaustive function catalogue.
112
+
113
+ - [Capability inventory](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/capability-inventory/)
114
+ - [Public API](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/api/)
115
+ - [API stability and hierarchy](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/api-stability/)
116
+ - [Mathematical reference](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/mathematical-reference/)
117
+ - [Capability status and roadmap](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/status-roadmap/)
118
+ - [Reference validation & performance envelope](https://stefanosbalaskas.github.io/eyetrajectoriespy/validation/reference-validation-ledger/)
119
+
120
+ ## Install
121
+
122
+ Stable release:
123
+
124
+ ```bash
125
+ pip install eyetrajectoriespy==0.9.0
126
+ ```
127
+
128
+ Or install the current stable release:
129
+
130
+ ```bash
131
+ pip install eyetrajectoriespy
132
+ ```
133
+
134
+ Development checkout:
135
+
136
+ ```bash
137
+ pip install -e .
138
+ ```
139
+
140
+ Development and documentation:
141
+
142
+ ```bash
143
+ pip install -e ".[dev,docs]"
144
+ ```
145
+
146
+ Optional interoperability:
147
+
148
+ ```bash
149
+ pip install -e ".[fda]" # scikit-fda
150
+ pip install -e ".[sparse]" # FDApy sparse/PACE FPCA; Python 3.11–3.12
151
+ pip install -e ".[elastic]" # fdasrsf
152
+ ```
153
+
154
+ 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.
155
+
156
+ ## Quick start
157
+
158
+ ```python
159
+ from eyetrajectoriespy import fit_mfpca, simulate_planar_trajectories, summarise_fpca
160
+
161
+ gaze = simulate_planar_trajectories(
162
+ n_participants=20,
163
+ trials_per_participant=6,
164
+ random_state=7,
165
+ )
166
+
167
+ fit = fit_mfpca(
168
+ gaze,
169
+ n_components=0.95,
170
+ scaling="dimension_sd",
171
+ )
172
+
173
+ print(summarise_fpca(fit))
174
+ ```
175
+
176
+ ## Documentation
177
+
178
+ 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/).
179
+
180
+ The methods site is configured for GitHub Pages:
181
+
182
+ **https://stefanosbalaskas.github.io/eyetrajectoriespy/**
183
+
184
+ Use the site for the five canonical workflows, advanced method guides, worked
185
+ examples, assumptions/limitations, validation ledger, implementation-matched
186
+ mathematical reference, API documentation and reproducible SVG plot gallery.
187
+
188
+ ## Scope boundary
189
+
190
+ `eyetrajectoriespy` starts once gaze has a scientifically interpretable time
191
+ and coordinate representation. Event detection, general gaze QC, survival
192
+ analysis, AOI perturbation robustness and symbolic sequence models belong
193
+ upstream or in specialist packages.
194
+
195
+ The generalized observation-family line is intentionally closed at Bernoulli /
196
+ grouped-binomial logit and Poisson expected-count/rate GEE. Negative binomial,
197
+ zero-inflated, hurdle and Tweedie families are not automatic next features.
198
+ Classical Floquet/monodromy and bifurcation analysis remain outside the raw-gaze
199
+ API without an explicitly identified dynamical model.
200
+
201
+ Version 0.55 began the stabilization line; version 0.56 added
202
+ evidence-typed independent/reference validation, an explicit numerical-tolerance
203
+ policy, and a repeated runtime/peak-memory reference envelope. Version 0.57 adds
204
+ portable scientific-result snapshots, explicit environment capture, five
205
+ qualified canonical end-to-end examples, and coordinated GitHub/PyPI release
206
+ machinery. Version 0.9.0 is the first stable pre-1.0 release after the qualified
207
+ 0.9.0rc1 publication. Scientific product qualification remains more important
208
+ than estimator count. See the
209
+ [release-readiness checklist](https://stefanosbalaskas.github.io/eyetrajectoriespy/release-readiness/).
210
+
211
+ - [Portable scientific results](https://stefanosbalaskas.github.io/eyetrajectoriespy/reproducibility/portable-results/)
212
+ - [Reproducibility bundle checklist](https://stefanosbalaskas.github.io/eyetrajectoriespy/reproducibility/checklist/)
213
+ - [Release process](https://stefanosbalaskas.github.io/eyetrajectoriespy/release-process/)
214
+
215
+ ## Validation
216
+
217
+ Current local/CI qualification status and the exact pending re-check list are maintained in [VALIDATION.md](VALIDATION.md).
218
+
219
+ ```bash
220
+ python -m pytest --cov=eyetrajectoriespy
221
+ python -m compileall -q src
222
+ python scripts/generate_function_equation_index.py --check
223
+ python scripts/generate_docs_gallery.py
224
+ python scripts/validate_docs_contracts.py
225
+ mkdocs build --strict
226
+ ```
227
+
228
+ ## License
229
+
230
+ MIT © 2026 Stefanos Balaskas.
@@ -0,0 +1,178 @@
1
+ # eyetrajectoriespy
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/eyetrajectoriespy.svg)](https://pypi.org/project/eyetrajectoriespy/)
4
+ [![GitHub Release](https://img.shields.io/github/v/release/stefanosbalaskas/eyetrajectoriespy)](https://github.com/stefanosbalaskas/eyetrajectoriespy/releases)
5
+ [![Python](https://img.shields.io/pypi/pyversions/eyetrajectoriespy.svg)](https://pypi.org/project/eyetrajectoriespy/)
6
+ [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://stefanosbalaskas.github.io/eyetrajectoriespy/)
7
+
8
+ **Functional and continuous trajectory analysis for eye-tracking data in Python.**
9
+
10
+ `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
11
+
12
+ ```text
13
+ G_i(t) = [x_i(t), y_i(t)]^T
14
+ ```
15
+
16
+ derived univariate functions, compositional AOI-probability trajectories, repeated-trial multilevel decompositions, explicit registration, and optional elastic phase–amplitude analysis.
17
+
18
+ > **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.
19
+
20
+ ## What scientific problem does this solve?
21
+
22
+ `eyetrajectoriespy` is for analyses where the **trajectory itself is a
23
+ scientific object**. It keeps temporal structure visible instead of immediately
24
+ collapsing gaze into scalar summaries, while making repeated-measures hierarchy,
25
+ uncertainty and analytical provenance explicit.
26
+
27
+ The central design rule is that consequential choices stay visible: no silent
28
+ interpolation, missing-to-zero conversion, smoothing, registration, time or
29
+ coordinate normalization, family/model selection, denominator inference or
30
+ exposure inference.
31
+
32
+ ## Which workflow do I need?
33
+
34
+ | Scientific question | Start here |
35
+ |---|---|
36
+ | What are the dominant modes of continuous gaze variation? | [Continuous gaze exploration + FPCA](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/fpca-exploration/) |
37
+ | How does an experimental predictor change a continuous functional response? | [Experimental functional regression](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/experimental-functional-regression/) |
38
+ | How do repeated participant trials affect functional inference? | [Repeated-trial functional mixed effects](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/repeated-trial-mixed-effects/) |
39
+ | How do predictors change repeated binary or count functional responses? | [Generalized binary/count responses](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/generalized-responses/) |
40
+ | Is recurrence or nonlinear temporal organization the scientific target? | [Nonlinear/recurrence analysis](https://stefanosbalaskas.github.io/eyetrajectoriespy/workflows/nonlinear-recurrence/) |
41
+
42
+ The canonical workflow index is the recommended entry point for new analyses.
43
+ It separates default routes from advanced, diagnostic and experimental
44
+ branches.
45
+
46
+ ## What assumptions does the workflow make?
47
+
48
+ Every canonical route documents its observation unit, hierarchy, estimand,
49
+ uncertainty/resampling unit and major failure conditions. Before interpreting a
50
+ result, use the package's [assumptions and diagnostics](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/assumptions/)
51
+ and [limitations](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/limitations/)
52
+ alongside the workflow-specific page.
53
+
54
+ The package prefers explicit failure or review over silently manufacturing a
55
+ convenient answer.
56
+
57
+ ## Where is the full advanced API?
58
+
59
+ The README is intentionally no longer the exhaustive function catalogue.
60
+
61
+ - [Capability inventory](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/capability-inventory/)
62
+ - [Public API](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/api/)
63
+ - [API stability and hierarchy](https://stefanosbalaskas.github.io/eyetrajectoriespy/reference/api-stability/)
64
+ - [Mathematical reference](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/mathematical-reference/)
65
+ - [Capability status and roadmap](https://stefanosbalaskas.github.io/eyetrajectoriespy/methods/status-roadmap/)
66
+ - [Reference validation & performance envelope](https://stefanosbalaskas.github.io/eyetrajectoriespy/validation/reference-validation-ledger/)
67
+
68
+ ## Install
69
+
70
+ Stable release:
71
+
72
+ ```bash
73
+ pip install eyetrajectoriespy==0.9.0
74
+ ```
75
+
76
+ Or install the current stable release:
77
+
78
+ ```bash
79
+ pip install eyetrajectoriespy
80
+ ```
81
+
82
+ Development checkout:
83
+
84
+ ```bash
85
+ pip install -e .
86
+ ```
87
+
88
+ Development and documentation:
89
+
90
+ ```bash
91
+ pip install -e ".[dev,docs]"
92
+ ```
93
+
94
+ Optional interoperability:
95
+
96
+ ```bash
97
+ pip install -e ".[fda]" # scikit-fda
98
+ pip install -e ".[sparse]" # FDApy sparse/PACE FPCA; Python 3.11–3.12
99
+ pip install -e ".[elastic]" # fdasrsf
100
+ ```
101
+
102
+ 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.
103
+
104
+ ## Quick start
105
+
106
+ ```python
107
+ from eyetrajectoriespy import fit_mfpca, simulate_planar_trajectories, summarise_fpca
108
+
109
+ gaze = simulate_planar_trajectories(
110
+ n_participants=20,
111
+ trials_per_participant=6,
112
+ random_state=7,
113
+ )
114
+
115
+ fit = fit_mfpca(
116
+ gaze,
117
+ n_components=0.95,
118
+ scaling="dimension_sd",
119
+ )
120
+
121
+ print(summarise_fpca(fit))
122
+ ```
123
+
124
+ ## Documentation
125
+
126
+ 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/).
127
+
128
+ The methods site is configured for GitHub Pages:
129
+
130
+ **https://stefanosbalaskas.github.io/eyetrajectoriespy/**
131
+
132
+ Use the site for the five canonical workflows, advanced method guides, worked
133
+ examples, assumptions/limitations, validation ledger, implementation-matched
134
+ mathematical reference, API documentation and reproducible SVG plot gallery.
135
+
136
+ ## Scope boundary
137
+
138
+ `eyetrajectoriespy` starts once gaze has a scientifically interpretable time
139
+ and coordinate representation. Event detection, general gaze QC, survival
140
+ analysis, AOI perturbation robustness and symbolic sequence models belong
141
+ upstream or in specialist packages.
142
+
143
+ The generalized observation-family line is intentionally closed at Bernoulli /
144
+ grouped-binomial logit and Poisson expected-count/rate GEE. Negative binomial,
145
+ zero-inflated, hurdle and Tweedie families are not automatic next features.
146
+ Classical Floquet/monodromy and bifurcation analysis remain outside the raw-gaze
147
+ API without an explicitly identified dynamical model.
148
+
149
+ Version 0.55 began the stabilization line; version 0.56 added
150
+ evidence-typed independent/reference validation, an explicit numerical-tolerance
151
+ policy, and a repeated runtime/peak-memory reference envelope. Version 0.57 adds
152
+ portable scientific-result snapshots, explicit environment capture, five
153
+ qualified canonical end-to-end examples, and coordinated GitHub/PyPI release
154
+ machinery. Version 0.9.0 is the first stable pre-1.0 release after the qualified
155
+ 0.9.0rc1 publication. Scientific product qualification remains more important
156
+ than estimator count. See the
157
+ [release-readiness checklist](https://stefanosbalaskas.github.io/eyetrajectoriespy/release-readiness/).
158
+
159
+ - [Portable scientific results](https://stefanosbalaskas.github.io/eyetrajectoriespy/reproducibility/portable-results/)
160
+ - [Reproducibility bundle checklist](https://stefanosbalaskas.github.io/eyetrajectoriespy/reproducibility/checklist/)
161
+ - [Release process](https://stefanosbalaskas.github.io/eyetrajectoriespy/release-process/)
162
+
163
+ ## Validation
164
+
165
+ Current local/CI qualification status and the exact pending re-check list are maintained in [VALIDATION.md](VALIDATION.md).
166
+
167
+ ```bash
168
+ python -m pytest --cov=eyetrajectoriespy
169
+ python -m compileall -q src
170
+ python scripts/generate_function_equation_index.py --check
171
+ python scripts/generate_docs_gallery.py
172
+ python scripts/validate_docs_contracts.py
173
+ mkdocs build --strict
174
+ ```
175
+
176
+ ## License
177
+
178
+ MIT © 2026 Stefanos Balaskas.
@@ -0,0 +1,74 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "eyetrajectoriespy"
7
+ version = "0.9.0"
8
+ description = "Functional and continuous trajectory analysis for eye-tracking data in Python"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{name = "Stefanos Balaskas"}]
13
+ requires-python = ">=3.11"
14
+ dependencies = [
15
+ "numpy>=1.26",
16
+ "pandas>=2.1",
17
+ "scipy>=1.11",
18
+ "scikit-learn>=1.4",
19
+ "matplotlib>=3.8",
20
+ "statsmodels>=0.14",
21
+ ]
22
+ classifiers = [
23
+ "Development Status :: 3 - Alpha",
24
+ "Intended Audience :: Science/Research",
25
+ "Programming Language :: Python :: 3",
26
+ "Programming Language :: Python :: 3.11",
27
+ "Programming Language :: Python :: 3.12",
28
+ "Programming Language :: Python :: 3.13",
29
+ "Topic :: Scientific/Engineering :: Information Analysis",
30
+ ]
31
+ keywords = ["eye-tracking", "gaze", "functional-data-analysis", "FPCA", "MFPCA", "trajectory-analysis", "curve-registration", "recurrence-analysis", "nonlinear-dynamics"]
32
+
33
+ [project.optional-dependencies]
34
+ fda = ["scikit-fda>=0.10.1,<0.11", "multimethod>=1.12,<2"]
35
+ sparse = ["FDApy>=1.0.3,<1.1; python_version < '3.13'"]
36
+ elastic = ["fdasrsf>=2.7"]
37
+ docs = ["mkdocs>=1.6,<2", "mkdocs-material>=9.7.7,<10", "mkdocstrings[python]>=0.27", "PyYAML>=6.0"]
38
+ dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.9", "build>=1.2", "twine>=6"]
39
+ all = ["scikit-fda>=0.10.1,<0.11", "multimethod>=1.12,<2", "FDApy>=1.0.3,<1.1; python_version < '3.13'", "fdasrsf>=2.7"]
40
+
41
+ [project.urls]
42
+ Homepage = "https://stefanosbalaskas.github.io/eyetrajectoriespy/"
43
+ Repository = "https://github.com/stefanosbalaskas/eyetrajectoriespy"
44
+ Documentation = "https://stefanosbalaskas.github.io/eyetrajectoriespy/"
45
+ Issues = "https://github.com/stefanosbalaskas/eyetrajectoriespy/issues"
46
+
47
+ [tool.setuptools]
48
+ package-dir = {"" = "src"}
49
+
50
+ [tool.setuptools.packages.find]
51
+ where = ["src"]
52
+
53
+ [tool.setuptools.package-data]
54
+ eyetrajectoriespy = ["py.typed"]
55
+
56
+ [tool.pytest.ini_options]
57
+ pythonpath = ["src"]
58
+ testpaths = ["tests"]
59
+ addopts = "-ra"
60
+
61
+ [tool.coverage.run]
62
+ source = ["eyetrajectoriespy"]
63
+ omit = ["src/eyetrajectoriespy/elastic.py"]
64
+
65
+ [tool.coverage.report]
66
+ fail_under = 90
67
+ show_missing = true
68
+
69
+ [tool.ruff]
70
+ target-version = "py311"
71
+ line-length = 120
72
+
73
+ [tool.ruff.lint]
74
+ select = ["E9", "F63", "F7", "F82"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+