gp3tools 0.1.0a1__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 (160) hide show
  1. gp3tools-0.1.0a1/CHANGELOG.md +12 -0
  2. gp3tools-0.1.0a1/CITATION.cff +22 -0
  3. gp3tools-0.1.0a1/CONTRIBUTING.md +3 -0
  4. gp3tools-0.1.0a1/LICENSE +21 -0
  5. gp3tools-0.1.0a1/MANIFEST.in +7 -0
  6. gp3tools-0.1.0a1/PKG-INFO +149 -0
  7. gp3tools-0.1.0a1/README.md +100 -0
  8. gp3tools-0.1.0a1/R_NAMESPACE_REFERENCE.txt +287 -0
  9. gp3tools-0.1.0a1/docs/API_PARITY.md +286 -0
  10. gp3tools-0.1.0a1/docs/API_REFERENCE.md +1949 -0
  11. gp3tools-0.1.0a1/docs/PARITY_STATUS.md +46 -0
  12. gp3tools-0.1.0a1/docs/articles/advanced-aoi-assignment.md +30 -0
  13. gp3tools-0.1.0a1/docs/articles/aoi-modelling-workflow.md +34 -0
  14. gp3tools-0.1.0a1/docs/articles/aoi-sequence-reliability.md +30 -0
  15. gp3tools-0.1.0a1/docs/articles/aoi-sliding-fixation-simulation.md +30 -0
  16. gp3tools-0.1.0a1/docs/articles/aoi-workflow.md +30 -0
  17. gp3tools-0.1.0a1/docs/articles/bayesian-planning.md +34 -0
  18. gp3tools-0.1.0a1/docs/articles/binocular-pupil-fusion.md +31 -0
  19. gp3tools-0.1.0a1/docs/articles/binocular-pupil-reconstruction.md +12 -0
  20. gp3tools-0.1.0a1/docs/articles/cluster-permutation-timecourse.md +34 -0
  21. gp3tools-0.1.0a1/docs/articles/complete-python-workflow.md +39 -0
  22. gp3tools-0.1.0a1/docs/articles/ecosystem-exports.md +30 -0
  23. gp3tools-0.1.0a1/docs/articles/end-to-end-workflow.md +30 -0
  24. gp3tools-0.1.0a1/docs/articles/event-detector-comparison.md +30 -0
  25. gp3tools-0.1.0a1/docs/articles/expanded-plot-gallery.md +30 -0
  26. gp3tools-0.1.0a1/docs/articles/experimental-bayesian-bridge.md +34 -0
  27. gp3tools-0.1.0a1/docs/articles/face-complete-workflow.md +30 -0
  28. gp3tools-0.1.0a1/docs/articles/face-export-import.md +30 -0
  29. gp3tools-0.1.0a1/docs/articles/face-quality-audit.md +30 -0
  30. gp3tools-0.1.0a1/docs/articles/face-reporting.md +30 -0
  31. gp3tools-0.1.0a1/docs/articles/face-synchronisation.md +30 -0
  32. gp3tools-0.1.0a1/docs/articles/face-window-summaries.md +30 -0
  33. gp3tools-0.1.0a1/docs/articles/fixation-transitions-scanpaths.md +30 -0
  34. gp3tools-0.1.0a1/docs/articles/full-api-migration.md +12 -0
  35. gp3tools-0.1.0a1/docs/articles/gpbiometrics-integration.md +12 -0
  36. gp3tools-0.1.0a1/docs/articles/heatmaps-spatial.md +30 -0
  37. gp3tools-0.1.0a1/docs/articles/integrated-signal-preprocessing.md +30 -0
  38. gp3tools-0.1.0a1/docs/articles/metric-extraction-model-boundaries.md +34 -0
  39. gp3tools-0.1.0a1/docs/articles/missingness-data-coverage.md +30 -0
  40. gp3tools-0.1.0a1/docs/articles/model-readiness-sensitivity.md +34 -0
  41. gp3tools-0.1.0a1/docs/articles/multimodal-modelling.md +34 -0
  42. gp3tools-0.1.0a1/docs/articles/naming-policy.md +12 -0
  43. gp3tools-0.1.0a1/docs/articles/paper-grade-synthetic-showcase.md +30 -0
  44. gp3tools-0.1.0a1/docs/articles/performance-benchmarking.md +12 -0
  45. gp3tools-0.1.0a1/docs/articles/plot-gallery.md +58 -0
  46. gp3tools-0.1.0a1/docs/articles/private-data-safety.md +34 -0
  47. gp3tools-0.1.0a1/docs/articles/pupil-baseline-audit.md +31 -0
  48. gp3tools-0.1.0a1/docs/articles/pupil-workflow.md +31 -0
  49. gp3tools-0.1.0a1/docs/articles/qc-dashboard-workflow.md +30 -0
  50. gp3tools-0.1.0a1/docs/articles/qc-reporting-bundle.md +30 -0
  51. gp3tools-0.1.0a1/docs/articles/scanpath-cluster-stability.md +34 -0
  52. gp3tools-0.1.0a1/docs/articles/scanpath-clustering.md +34 -0
  53. gp3tools-0.1.0a1/docs/articles/scanpath-qc-quick-wins.md +30 -0
  54. gp3tools-0.1.0a1/docs/articles/statistical-extensions-plots.md +30 -0
  55. gp3tools-0.1.0a1/docs/articles/stimulus-layout-qc.md +30 -0
  56. gp3tools-0.1.0a1/docs/articles/task-phase-coverage.md +30 -0
  57. gp3tools-0.1.0a1/docs/articles/validation-release.md +23 -0
  58. gp3tools-0.1.0a1/docs/articles/velocity-fixations-blinks.md +31 -0
  59. gp3tools-0.1.0a1/docs/assets/binocular.png +0 -0
  60. gp3tools-0.1.0a1/docs/assets/heatmap.png +0 -0
  61. gp3tools-0.1.0a1/docs/assets/missingness.png +0 -0
  62. gp3tools-0.1.0a1/docs/assets/pupil-timecourse.png +0 -0
  63. gp3tools-0.1.0a1/docs/assets/scanpath.png +0 -0
  64. gp3tools-0.1.0a1/docs/assets/transition-matrix.png +0 -0
  65. gp3tools-0.1.0a1/docs/index.md +49 -0
  66. gp3tools-0.1.0a1/examples/binocular_pupil.py +5 -0
  67. gp3tools-0.1.0a1/examples/full_workflow.py +21 -0
  68. gp3tools-0.1.0a1/examples/plot_gallery.py +22 -0
  69. gp3tools-0.1.0a1/examples/pupil_qc.py +17 -0
  70. gp3tools-0.1.0a1/examples/quickstart.py +10 -0
  71. gp3tools-0.1.0a1/examples/timecourse.py +7 -0
  72. gp3tools-0.1.0a1/mkdocs.yml +30 -0
  73. gp3tools-0.1.0a1/pyproject.toml +80 -0
  74. gp3tools-0.1.0a1/setup.cfg +4 -0
  75. gp3tools-0.1.0a1/src/gp3tools/__init__.py +136 -0
  76. gp3tools-0.1.0a1/src/gp3tools/_behavioral_r2.py +5347 -0
  77. gp3tools-0.1.0a1/src/gp3tools/_behavioral_r3a.py +3198 -0
  78. gp3tools-0.1.0a1/src/gp3tools/_behavioral_r3b.py +2900 -0
  79. gp3tools-0.1.0a1/src/gp3tools/_behavioral_r4.py +2428 -0
  80. gp3tools-0.1.0a1/src/gp3tools/_compat.py +77 -0
  81. gp3tools-0.1.0a1/src/gp3tools/_exports.py +282 -0
  82. gp3tools-0.1.0a1/src/gp3tools/_r4_dual_contract.py +194 -0
  83. gp3tools-0.1.0a1/src/gp3tools/_rbridge.py +42 -0
  84. gp3tools-0.1.0a1/src/gp3tools/_utils.py +205 -0
  85. gp3tools-0.1.0a1/src/gp3tools/aoi.py +8544 -0
  86. gp3tools-0.1.0a1/src/gp3tools/api_manifest.csv +279 -0
  87. gp3tools-0.1.0a1/src/gp3tools/data/gazepoint_example_aoi_geometry.csv +4 -0
  88. gp3tools-0.1.0a1/src/gp3tools/data/gazepoint_example_aoi_windows.csv +41 -0
  89. gp3tools-0.1.0a1/src/gp3tools/data/gazepoint_example_fixations.csv +25 -0
  90. gp3tools-0.1.0a1/src/gp3tools/data/gazepoint_example_master.csv +1441 -0
  91. gp3tools-0.1.0a1/src/gp3tools/data/gazepoint_example_pupil_windows.csv +17 -0
  92. gp3tools-0.1.0a1/src/gp3tools/datasets.py +30 -0
  93. gp3tools-0.1.0a1/src/gp3tools/events.py +1881 -0
  94. gp3tools-0.1.0a1/src/gp3tools/face.py +1247 -0
  95. gp3tools-0.1.0a1/src/gp3tools/interop.py +153 -0
  96. gp3tools-0.1.0a1/src/gp3tools/io.py +261 -0
  97. gp3tools-0.1.0a1/src/gp3tools/misc.py +265 -0
  98. gp3tools-0.1.0a1/src/gp3tools/plotting.py +401 -0
  99. gp3tools-0.1.0a1/src/gp3tools/pupil.py +8390 -0
  100. gp3tools-0.1.0a1/src/gp3tools/py.typed +0 -0
  101. gp3tools-0.1.0a1/src/gp3tools/qc.py +4931 -0
  102. gp3tools-0.1.0a1/src/gp3tools/reporting.py +2794 -0
  103. gp3tools-0.1.0a1/src/gp3tools/simulation.py +298 -0
  104. gp3tools-0.1.0a1/src/gp3tools/stats.py +3185 -0
  105. gp3tools-0.1.0a1/src/gp3tools.egg-info/PKG-INFO +149 -0
  106. gp3tools-0.1.0a1/src/gp3tools.egg-info/SOURCES.txt +158 -0
  107. gp3tools-0.1.0a1/src/gp3tools.egg-info/dependency_links.txt +1 -0
  108. gp3tools-0.1.0a1/src/gp3tools.egg-info/requires.txt +30 -0
  109. gp3tools-0.1.0a1/src/gp3tools.egg-info/top_level.txt +1 -0
  110. gp3tools-0.1.0a1/tests/conftest.py +3 -0
  111. gp3tools-0.1.0a1/tests/test_api.py +14 -0
  112. gp3tools-0.1.0a1/tests/test_core.py +115 -0
  113. gp3tools-0.1.0a1/tests/test_core_coverage90.py +789 -0
  114. gp3tools-0.1.0a1/tests/test_exports.py +17 -0
  115. gp3tools-0.1.0a1/tests/test_extended_core.py +200 -0
  116. gp3tools-0.1.0a1/tests/test_extended_events_face_interop.py +150 -0
  117. gp3tools-0.1.0a1/tests/test_extended_pupil_aoi.py +279 -0
  118. gp3tools-0.1.0a1/tests/test_extended_stats_reporting.py +245 -0
  119. gp3tools-0.1.0a1/tests/test_gazepoint_native_pupil_aliases.py +176 -0
  120. gp3tools-0.1.0a1/tests/test_plot_smoke_catalog.py +56 -0
  121. gp3tools-0.1.0a1/tests/test_r_alias_compat.py +498 -0
  122. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r1.py +513 -0
  123. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r1_edges.py +659 -0
  124. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r2.py +956 -0
  125. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r2_edges.py +1822 -0
  126. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r3a.py +1043 -0
  127. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r3a_edges.py +675 -0
  128. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r3b.py +568 -0
  129. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r3b_edges.py +1346 -0
  130. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r4.py +269 -0
  131. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r4_deep_edges.py +841 -0
  132. gp3tools-0.1.0a1/tests/test_r_behavioral_parity_tranche_r4_helper_edges.py +1183 -0
  133. gp3tools-0.1.0a1/tests/test_r_semantic_parity_aoi_coding_matrix.py +457 -0
  134. gp3tools-0.1.0a1/tests/test_r_semantic_parity_fixation_reliability.py +338 -0
  135. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard11_tranche_o.py +407 -0
  136. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard14_tranche_n.py +242 -0
  137. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard16_tranche_m.py +279 -0
  138. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard20_tranche_l.py +191 -0
  139. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard23_tranche_k.py +393 -0
  140. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard27_tranche_j.py +162 -0
  141. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard30_tranche_i.py +191 -0
  142. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard33_tranche_h.py +340 -0
  143. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard36_tranche_g.py +127 -0
  144. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard3_tranche_q.py +315 -0
  145. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard42_tranche_f.py +327 -0
  146. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard44_tranche_e.py +190 -0
  147. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard48_tranche_d.py +274 -0
  148. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard53_tranche_c.py +269 -0
  149. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard67_tranche_b.py +766 -0
  150. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard6_tranche_p.py +316 -0
  151. gp3tools-0.1.0a1/tests/test_r_semantic_parity_hard92_tranche_a.py +396 -0
  152. gp3tools-0.1.0a1/tests/test_r_semantic_parity_performance.py +316 -0
  153. gp3tools-0.1.0a1/tests/test_r_semantic_parity_polygon_network.py +503 -0
  154. gp3tools-0.1.0a1/tests/test_r_semantic_parity_pupil_trio.py +643 -0
  155. gp3tools-0.1.0a1/tests/test_r_semantic_parity_qc_summaries.py +296 -0
  156. gp3tools-0.1.0a1/tests/test_r_semantic_parity_scanpath_integrated.py +545 -0
  157. gp3tools-0.1.0a1/tests/test_r_semantic_parity_tranche2a.py +333 -0
  158. gp3tools-0.1.0a1/tests/test_r_semantic_parity_tranche3a.py +585 -0
  159. gp3tools-0.1.0a1/tests/test_r_semantic_parity_transition_matrix.py +283 -0
  160. gp3tools-0.1.0a1/tests/test_whole_surface_smoke.py +38 -0
@@ -0,0 +1,12 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0a1 — comprehensive migration alpha
4
+
5
+ - froze the 278-name public API from R gp3tools v2.3.0;
6
+ - implemented native Python import, QC, pupil, binocular, AOI, sequence, fixation/saccade, plotting, reporting, simulation, face, and interoperability layers;
7
+ - added Python-native statistical adaptations for mixed-model, spline/GAM-like, Bayesian, cluster-permutation, bootstrap, and sensitivity workflows;
8
+ - bundled five synthetic example datasets;
9
+ - added article set, API/parity manifests, examples, tests, build metadata, and CI configuration;
10
+ - added wheel and source-distribution validation workflow.
11
+
12
+ This is an alpha migration build; it does not claim exact inferential parity for R-backend-specific models.
@@ -0,0 +1,22 @@
1
+ cff-version: 1.2.0
2
+ message: "If you use gp3tools for Python, cite the gp3tools software paper and report the Python package version."
3
+ title: "gp3tools for Python"
4
+ type: software
5
+ version: "0.1.0a1"
6
+ authors:
7
+ - family-names: "Balaskas"
8
+ given-names: "Stefanos"
9
+ license: MIT
10
+ repository-code: "https://github.com/stefanosbalaskas/gp3tools"
11
+ preferred-citation:
12
+ type: article
13
+ title: "gp3tools: An R Package for Reproducible Analysis and Reporting of Gazepoint GP3 Eye-Tracking Exports"
14
+ authors:
15
+ - family-names: "Balaskas"
16
+ given-names: "Stefanos"
17
+ year: 2026
18
+ journal: "Journal of Eye Movement Research"
19
+ volume: 19
20
+ issue: 4
21
+ start: 76
22
+ doi: "10.3390/jemr19040076"
@@ -0,0 +1,3 @@
1
+ # Contributing
2
+
3
+ Changes should preserve the frozen public API, add tests for behavioural changes, avoid silent imputation, expose failure states, and document statistical backend differences. For deterministic functions, cross-language fixtures from the R implementation are preferred. For model functions, compare estimands and diagnostics rather than assuming numerical identity across engines.
@@ -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,7 @@
1
+ include README.md LICENSE CITATION.cff CHANGELOG.md CONTRIBUTING.md R_NAMESPACE_REFERENCE.txt mkdocs.yml
2
+ recursive-include docs *.md *.png
3
+ recursive-include examples *.py
4
+ recursive-include tests *.py
5
+ recursive-include src/gp3tools/data *.csv
6
+ include src/gp3tools/api_manifest.csv
7
+ include src/gp3tools/py.typed
@@ -0,0 +1,149 @@
1
+ Metadata-Version: 2.4
2
+ Name: gp3tools
3
+ Version: 0.1.0a1
4
+ Summary: Python implementation and compatibility layer for reproducible Gazepoint GP3 analysis
5
+ Author: Stefanos Balaskas
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/stefanosbalaskas/gp3tools-python
8
+ Project-URL: Documentation, https://stefanosbalaskas.github.io/gp3tools-python/
9
+ Project-URL: Repository, https://github.com/stefanosbalaskas/gp3tools-python
10
+ Project-URL: Issues, https://github.com/stefanosbalaskas/gp3tools-python/issues
11
+ Project-URL: R implementation, https://github.com/stefanosbalaskas/gp3tools
12
+ Keywords: eye-tracking,eyetracking,Gazepoint,GP3,pupillometry,AOI,scanpath,HCI
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: numpy>=2.0
24
+ Requires-Dist: pandas>=2.2
25
+ Requires-Dist: scipy>=1.13
26
+ Requires-Dist: matplotlib>=3.9
27
+ Requires-Dist: statsmodels>=0.14
28
+ Requires-Dist: scikit-learn>=1.5
29
+ Requires-Dist: networkx>=3.3
30
+ Requires-Dist: shapely>=2.0
31
+ Requires-Dist: jinja2>=3.1
32
+ Provides-Extra: bayes
33
+ Requires-Dist: pymc>=5; extra == "bayes"
34
+ Requires-Dist: arviz>=0.19; extra == "bayes"
35
+ Requires-Dist: bambi>=0.15; extra == "bayes"
36
+ Provides-Extra: rbridge
37
+ Requires-Dist: rpy2>=3.6; extra == "rbridge"
38
+ Provides-Extra: dashboard
39
+ Requires-Dist: shiny>=1.2; extra == "dashboard"
40
+ Provides-Extra: dev
41
+ Requires-Dist: pytest>=8; extra == "dev"
42
+ Requires-Dist: pytest-cov>=5; extra == "dev"
43
+ Requires-Dist: ruff>=0.8; extra == "dev"
44
+ Requires-Dist: build>=1.2; extra == "dev"
45
+ Provides-Extra: docs
46
+ Requires-Dist: mkdocs>=1.6; extra == "docs"
47
+ Requires-Dist: mkdocs-material>=9.6; extra == "docs"
48
+ Dynamic: license-file
49
+
50
+ # gp3tools for Python
51
+
52
+ A Python implementation of the public workflow of **gp3tools**, the R package for importing, inspecting, analysing, visualising, modelling, and reporting Gazepoint GP3 / Gazepoint Analysis exports.
53
+
54
+ > **Status: 0.1.0a1 comprehensive migration build.** The complete 278-function public name surface frozen from the R `v2.3.0` `NAMESPACE` is present. Core data, QC, pupil, AOI, sequence, event, plotting, reporting, face, simulation, and export workflows are native Python. Statistical functions tied to R-specific backends are **Python-native adaptations**, not claims of coefficient-for-coefficient equivalence to `lme4`, `glmmTMB`, `mgcv`, or `brms`.
55
+
56
+ ## Install a local wheel
57
+
58
+ ```powershell
59
+ uv pip install .\gp3tools-0.1.0a1-py3-none-any.whl
60
+ ```
61
+
62
+ or
63
+
64
+ ```powershell
65
+ pip install .\gp3tools-0.1.0a1-py3-none-any.whl
66
+ ```
67
+
68
+ ## Quick start
69
+
70
+ ```python
71
+ import gp3tools as gp3
72
+
73
+ master = gp3.load_example_master()
74
+
75
+ sampling = gp3.check_sampling_rate(
76
+ master,
77
+ time_col="TIME",
78
+ group_cols=["subject", "trial_global"],
79
+ )
80
+
81
+ pupil = gp3.preprocess_gazepoint_signals(
82
+ master,
83
+ pupil_col="pupil",
84
+ time_col="TIME",
85
+ )
86
+
87
+ transitions = gp3.compute_gazepoint_aoi_transition_matrix(
88
+ master,
89
+ aoi_col="aoi_current",
90
+ )
91
+
92
+ fig = gp3.plot_gazepoint_heatmap(master)
93
+ ```
94
+
95
+ ## Public API contract
96
+
97
+ ```python
98
+ import gp3tools as gp3
99
+
100
+ len(gp3.R_EXPORTS)
101
+ # 278
102
+
103
+ gp3.api_status()["status"].value_counts()
104
+ ```
105
+
106
+ The build distinguishes:
107
+
108
+ - `native`: direct Python implementation;
109
+ - `native-adapted`: implemented in Python but the R package used a backend or algorithm whose exact numerical identity is not asserted;
110
+ - `native-adapter`: interoperability adapter expressed natively in Python.
111
+
112
+ See `docs/API_PARITY.md` and the bundled `api_manifest.csv` for every exported function.
113
+
114
+ ## Main modules
115
+
116
+ - `io`: Gazepoint CSV, folder, summary, and face-export import
117
+ - `qc`: master tables, sampling, tracking, missingness, screen bounds, exclusions, readiness
118
+ - `pupil`: artifact flags, blinks, interpolation, baseline correction, smoothing, binocular reconstruction
119
+ - `aoi`: static/dynamic/polygon AOIs, entries, windows, transitions, entropy, scanpaths, clustering
120
+ - `events`: fixation/saccade detection, agreement and benchmark workflows
121
+ - `stats`: model preparation, LMM/GLM/spline adaptations, Bayesian adapters, cluster permutation, bootstrap and sensitivity
122
+ - `face`: external facial-analysis QC and time synchronisation
123
+ - `interop`: eyetrackingR/pupillometryR/gazer/eyetools/HDDM/BIDS/gpbiometrics adapters
124
+ - `plotting`: Matplotlib visualisations
125
+ - `reporting`: CSV/HTML outputs, reporting checklists and end-to-end workflow
126
+ - `simulation`: synthetic Gazepoint data for examples and tests
127
+
128
+ ## Scientific compatibility note
129
+
130
+ A Python port should preserve scientific intent without pretending different statistical engines are identical. Accordingly, the modelling layer documents backend adaptation explicitly. The package is suitable for software migration, workflow prototyping, reproducible preprocessing, data/QC/plotting tasks, and validation development; advanced inferential parity should be checked against the R reference implementation before confirmatory use.
131
+
132
+ ## R reference
133
+
134
+ The public API was frozen against `gp3tools` R `v2.3.0`. `R_NAMESPACE_REFERENCE.txt` is included in the source distribution for auditability.
135
+
136
+ ## Citation
137
+
138
+ Balaskas, S. (2026). *gp3tools: An R Package for Reproducible Analysis and Reporting of Gazepoint GP3 Eye-Tracking Exports*. Journal of Eye Movement Research, 19(4), 76. DOI: 10.3390/jemr19040076.
139
+
140
+ ## License
141
+
142
+ MIT.
143
+
144
+ <!-- GP3TOOLS_PARITY_STATUS -->
145
+ ## R 2.3.0 parity and validation
146
+
147
+ The Python package freezes the **278-export** R 2.3.0 public API while exposing **285** Python public names in the validated parity branch. Behavioral equality is evidence graded: exact and numerical-tolerance claims are made only where frozen R oracles exist; backend-adapted statistical families are labelled accordingly.
148
+
149
+ The release gate includes R1–R3 frozen behavioral regressions, R4 canonical structure/compatibility tests plus frozen-oracle integrity checks, whole-surface smoke, plot catalog smoke, runnable examples, Ruff, compilation, strict documentation build, **≥90% test coverage**, wheel/sdist construction and isolated-wheel validation. See `docs/PARITY_STATUS.md`.
@@ -0,0 +1,100 @@
1
+ # gp3tools for Python
2
+
3
+ A Python implementation of the public workflow of **gp3tools**, the R package for importing, inspecting, analysing, visualising, modelling, and reporting Gazepoint GP3 / Gazepoint Analysis exports.
4
+
5
+ > **Status: 0.1.0a1 comprehensive migration build.** The complete 278-function public name surface frozen from the R `v2.3.0` `NAMESPACE` is present. Core data, QC, pupil, AOI, sequence, event, plotting, reporting, face, simulation, and export workflows are native Python. Statistical functions tied to R-specific backends are **Python-native adaptations**, not claims of coefficient-for-coefficient equivalence to `lme4`, `glmmTMB`, `mgcv`, or `brms`.
6
+
7
+ ## Install a local wheel
8
+
9
+ ```powershell
10
+ uv pip install .\gp3tools-0.1.0a1-py3-none-any.whl
11
+ ```
12
+
13
+ or
14
+
15
+ ```powershell
16
+ pip install .\gp3tools-0.1.0a1-py3-none-any.whl
17
+ ```
18
+
19
+ ## Quick start
20
+
21
+ ```python
22
+ import gp3tools as gp3
23
+
24
+ master = gp3.load_example_master()
25
+
26
+ sampling = gp3.check_sampling_rate(
27
+ master,
28
+ time_col="TIME",
29
+ group_cols=["subject", "trial_global"],
30
+ )
31
+
32
+ pupil = gp3.preprocess_gazepoint_signals(
33
+ master,
34
+ pupil_col="pupil",
35
+ time_col="TIME",
36
+ )
37
+
38
+ transitions = gp3.compute_gazepoint_aoi_transition_matrix(
39
+ master,
40
+ aoi_col="aoi_current",
41
+ )
42
+
43
+ fig = gp3.plot_gazepoint_heatmap(master)
44
+ ```
45
+
46
+ ## Public API contract
47
+
48
+ ```python
49
+ import gp3tools as gp3
50
+
51
+ len(gp3.R_EXPORTS)
52
+ # 278
53
+
54
+ gp3.api_status()["status"].value_counts()
55
+ ```
56
+
57
+ The build distinguishes:
58
+
59
+ - `native`: direct Python implementation;
60
+ - `native-adapted`: implemented in Python but the R package used a backend or algorithm whose exact numerical identity is not asserted;
61
+ - `native-adapter`: interoperability adapter expressed natively in Python.
62
+
63
+ See `docs/API_PARITY.md` and the bundled `api_manifest.csv` for every exported function.
64
+
65
+ ## Main modules
66
+
67
+ - `io`: Gazepoint CSV, folder, summary, and face-export import
68
+ - `qc`: master tables, sampling, tracking, missingness, screen bounds, exclusions, readiness
69
+ - `pupil`: artifact flags, blinks, interpolation, baseline correction, smoothing, binocular reconstruction
70
+ - `aoi`: static/dynamic/polygon AOIs, entries, windows, transitions, entropy, scanpaths, clustering
71
+ - `events`: fixation/saccade detection, agreement and benchmark workflows
72
+ - `stats`: model preparation, LMM/GLM/spline adaptations, Bayesian adapters, cluster permutation, bootstrap and sensitivity
73
+ - `face`: external facial-analysis QC and time synchronisation
74
+ - `interop`: eyetrackingR/pupillometryR/gazer/eyetools/HDDM/BIDS/gpbiometrics adapters
75
+ - `plotting`: Matplotlib visualisations
76
+ - `reporting`: CSV/HTML outputs, reporting checklists and end-to-end workflow
77
+ - `simulation`: synthetic Gazepoint data for examples and tests
78
+
79
+ ## Scientific compatibility note
80
+
81
+ A Python port should preserve scientific intent without pretending different statistical engines are identical. Accordingly, the modelling layer documents backend adaptation explicitly. The package is suitable for software migration, workflow prototyping, reproducible preprocessing, data/QC/plotting tasks, and validation development; advanced inferential parity should be checked against the R reference implementation before confirmatory use.
82
+
83
+ ## R reference
84
+
85
+ The public API was frozen against `gp3tools` R `v2.3.0`. `R_NAMESPACE_REFERENCE.txt` is included in the source distribution for auditability.
86
+
87
+ ## Citation
88
+
89
+ Balaskas, S. (2026). *gp3tools: An R Package for Reproducible Analysis and Reporting of Gazepoint GP3 Eye-Tracking Exports*. Journal of Eye Movement Research, 19(4), 76. DOI: 10.3390/jemr19040076.
90
+
91
+ ## License
92
+
93
+ MIT.
94
+
95
+ <!-- GP3TOOLS_PARITY_STATUS -->
96
+ ## R 2.3.0 parity and validation
97
+
98
+ The Python package freezes the **278-export** R 2.3.0 public API while exposing **285** Python public names in the validated parity branch. Behavioral equality is evidence graded: exact and numerical-tolerance claims are made only where frozen R oracles exist; backend-adapted statistical families are labelled accordingly.
99
+
100
+ The release gate includes R1–R3 frozen behavioral regressions, R4 canonical structure/compatibility tests plus frozen-oracle integrity checks, whole-surface smoke, plot catalog smoke, runnable examples, Ruff, compilation, strict documentation build, **≥90% test coverage**, wheel/sdist construction and isolated-wheel validation. See `docs/PARITY_STATUS.md`.
@@ -0,0 +1,287 @@
1
+ # Generated by roxygen2: do not edit by hand
2
+
3
+ S3method(print,gazepoint_cross_package_workflow)
4
+ S3method(print,gazepoint_gpbiometrics_bridge)
5
+ S3method(print,gazepoint_naming_audit)
6
+ S3method(print,gazepoint_performance_benchmark)
7
+ S3method(print,gazepoint_performance_regression)
8
+ S3method(print,gp3tools_naming_policy)
9
+ export(add_gazepoint_aoi)
10
+ export(add_gazepoint_dynamic_aoi)
11
+ export(add_gazepoint_polygon_aoi)
12
+ export(analyse_gazepoint_binocular_sensitivity)
13
+ export(analyze_gazepoint_window)
14
+ export(as_gazepoint_master)
15
+ export(audit_gazepoint_aoi_coding_matrix)
16
+ export(audit_gazepoint_aoi_geometry)
17
+ export(audit_gazepoint_aoi_margin_sensitivity)
18
+ export(audit_gazepoint_aoi_overlap)
19
+ export(audit_gazepoint_aoi_screen_coverage)
20
+ export(audit_gazepoint_aoi_window_denominators)
21
+ export(audit_gazepoint_binocular_reconstruction)
22
+ export(audit_gazepoint_condition_quality_imbalance)
23
+ export(audit_gazepoint_design_balance)
24
+ export(audit_gazepoint_dynamic_aoi_coverage)
25
+ export(audit_gazepoint_event_sync)
26
+ export(audit_gazepoint_exclusion_flow)
27
+ export(audit_gazepoint_face_quality)
28
+ export(audit_gazepoint_face_sync)
29
+ export(audit_gazepoint_fixation_reliability)
30
+ export(audit_gazepoint_gaze_signal_quality)
31
+ export(audit_gazepoint_master)
32
+ export(audit_gazepoint_naming_consistency)
33
+ export(audit_gazepoint_post_exclusion_balance)
34
+ export(audit_gazepoint_pupil_baseline)
35
+ export(audit_gazepoint_pupil_drift)
36
+ export(audit_gazepoint_pupil_gaps)
37
+ export(audit_gazepoint_pupil_imbalance)
38
+ export(audit_gazepoint_pupil_overlap_risk)
39
+ export(audit_gazepoint_pupil_reliability)
40
+ export(audit_gazepoint_screen_bounds)
41
+ export(audit_gazepoint_stimulus_luminance)
42
+ export(audit_gazepoint_timecourse_grid)
43
+ export(baseline_correct_gazepoint_pupil)
44
+ export(benchmark_gazepoint_event_detectors)
45
+ export(benchmark_gazepoint_export_performance)
46
+ export(bootstrap_gazepoint_scanpath_clusters)
47
+ export(bootstrap_gazepoint_timecourse)
48
+ export(check_gazepoint_bayesian_readiness)
49
+ export(check_gazepoint_file_pairs)
50
+ export(check_gazepoint_model_convergence)
51
+ export(check_gazepoint_model_overdispersion)
52
+ export(check_gazepoint_model_singularity)
53
+ export(check_gazepoint_performance_regression)
54
+ export(check_gazepoint_real_data_readiness)
55
+ export(check_sampling_rate)
56
+ export(classify_gazepoint_events_hmm)
57
+ export(classify_gazepoint_export)
58
+ export(clean_gazepoint_by_trackloss)
59
+ export(cluster_gazepoint_scanpaths)
60
+ export(collect_gazepoint_qc_summaries)
61
+ export(combine_gazepoint_eyes)
62
+ export(compare_gazepoint_event_detectors)
63
+ export(compare_gazepoint_nested_models)
64
+ export(compute_gazepoint_aoi_entropy)
65
+ export(compute_gazepoint_aoi_sequence_metrics)
66
+ export(compute_gazepoint_aoi_transition_matrix)
67
+ export(compute_gazepoint_saccade_metrics)
68
+ export(compute_gazepoint_scanpath_geometry)
69
+ export(compute_gazepoint_scanpath_similarity)
70
+ export(compute_gazepoint_sequence_complexity)
71
+ export(compute_gazepoint_sequence_distance)
72
+ export(compute_gazepoint_sequence_recurrence)
73
+ export(compute_gazepoint_time_varying_transition_matrix)
74
+ export(compute_gazepoint_transition_network_metrics)
75
+ export(compute_transition_matrix)
76
+ export(construct_gazepoint_combined_pupil)
77
+ export(create_gazepoint_analysis_decision_audit)
78
+ export(create_gazepoint_bayesian_sap)
79
+ export(create_gazepoint_brms_template)
80
+ export(create_gazepoint_cross_package_report)
81
+ export(create_gazepoint_event_review_template)
82
+ export(create_gazepoint_face_reporting_checklist)
83
+ export(create_gazepoint_hddm_fit_script)
84
+ export(create_gazepoint_markovchain_object)
85
+ export(create_gazepoint_master)
86
+ export(create_gazepoint_preprocessing_multiverse)
87
+ export(create_gazepoint_preprocessing_registry)
88
+ export(create_gazepoint_report)
89
+ export(create_gazepoint_reporting_checklist)
90
+ export(detect_gazepoint_blinks)
91
+ export(detect_gazepoint_fixations_ivt)
92
+ export(detect_gazepoint_fixations_velocity)
93
+ export(diagnose_gazepoint_binocular_pupil)
94
+ export(diagnose_gazepoint_cluster_design)
95
+ export(diagnose_gazepoint_gamm)
96
+ export(diagnose_gazepoint_glmm)
97
+ export(downsample_gazepoint_pupil)
98
+ export(estimate_gazepoint_cluster_offset)
99
+ export(estimate_gazepoint_cluster_onset)
100
+ export(estimate_gazepoint_divergence_point)
101
+ export(export_gazepoint_cluster_results)
102
+ export(export_gazepoint_heatmap_png)
103
+ export(export_gazepoint_master_audit)
104
+ export(export_gazepoint_mne_cluster_input)
105
+ export(export_gazepoint_model_tables)
106
+ export(export_gazepoint_permuco_cluster_input)
107
+ export(export_gazepoint_permutes_cluster_input)
108
+ export(export_gazepoint_tables)
109
+ export(export_gazepoint_to_bids)
110
+ export(extract_gazepoint_representative_scanpaths)
111
+ export(filter_gazepoint_cnn_uncertainty)
112
+ export(fit_gazepoint_aoi_brms)
113
+ export(fit_gazepoint_aoi_gamm)
114
+ export(fit_gazepoint_aoi_model_sensitivity)
115
+ export(fit_gazepoint_aoi_window_glmm)
116
+ export(fit_gazepoint_binocular_calibration)
117
+ export(fit_gazepoint_brms_model)
118
+ export(fit_gazepoint_face_window_lmm)
119
+ export(fit_gazepoint_gca)
120
+ export(fit_gazepoint_multimodal_response_model)
121
+ export(fit_gazepoint_pupil_gamm)
122
+ export(fit_gazepoint_pupil_pfe_gamm)
123
+ export(fit_gazepoint_pupil_window_lmm)
124
+ export(fit_gazepoint_pupil_window_sensitivity)
125
+ export(fit_gazepoint_transition_count_nb_sensitivity)
126
+ export(flag_gazepoint_pupil)
127
+ export(flag_gazepoint_pupil_artifacts)
128
+ export(flag_gazepoint_pupil_hampel)
129
+ export(flag_gazepoint_sequence_anomalies)
130
+ export(flag_tracking_quality)
131
+ export(gp3tools_naming_policy)
132
+ export(gp3tools_performance_limits)
133
+ export(harmonize_gazepoint_screen_coordinates)
134
+ export(impute_gazepoint_pupil_gp)
135
+ export(inspect_gazepoint_columns)
136
+ export(interpolate_gazepoint_blinks)
137
+ export(interpolate_gazepoint_pupil)
138
+ export(interpolate_gazepoint_pupil_pchip)
139
+ export(launch_gazepoint_qc_dashboard)
140
+ export(mean_gazepoint_pupil)
141
+ export(plot_gazepoint_aoi_gamm)
142
+ export(plot_gazepoint_aoi_timeline)
143
+ export(plot_gazepoint_aoi_transition_matrix)
144
+ export(plot_gazepoint_aoi_verification)
145
+ export(plot_gazepoint_binocular_diagnostics)
146
+ export(plot_gazepoint_cluster_null_distribution)
147
+ export(plot_gazepoint_cluster_permutation)
148
+ export(plot_gazepoint_cluster_results)
149
+ export(plot_gazepoint_event_detector_agreement)
150
+ export(plot_gazepoint_event_detector_benchmark)
151
+ export(plot_gazepoint_face_quality)
152
+ export(plot_gazepoint_gca)
153
+ export(plot_gazepoint_heatmap)
154
+ export(plot_gazepoint_heatmap_overlay)
155
+ export(plot_gazepoint_missingness_profile)
156
+ export(plot_gazepoint_model_predictions)
157
+ export(plot_gazepoint_model_residuals)
158
+ export(plot_gazepoint_multiverse_results)
159
+ export(plot_gazepoint_phase_timeline)
160
+ export(plot_gazepoint_pupil_preprocessing)
161
+ export(plot_gazepoint_pupil_status)
162
+ export(plot_gazepoint_pupil_timecourse)
163
+ export(plot_gazepoint_qc_overview)
164
+ export(plot_gazepoint_scanpath)
165
+ export(plot_gazepoint_scanpath_cluster_stability)
166
+ export(plot_gazepoint_scanpath_clusters)
167
+ export(plot_gazepoint_scanpaths)
168
+ export(plot_gazepoint_stimulus_layout_qc)
169
+ export(plot_gazepoint_time_series)
170
+ export(plot_gazepoint_time_varying_effect)
171
+ export(plot_sampling_rate)
172
+ export(plot_tracking_quality)
173
+ export(plot_transition_heatmap)
174
+ export(prepare_gazepoint_aoi_gamm_data)
175
+ export(prepare_gazepoint_aoi_glmm_data)
176
+ export(prepare_gazepoint_aoi_sequences)
177
+ export(prepare_gazepoint_cluster_data)
178
+ export(prepare_gazepoint_eyetools_data)
179
+ export(prepare_gazepoint_eyetrackingr_data)
180
+ export(prepare_gazepoint_fixation_aligned_data)
181
+ export(prepare_gazepoint_gazer_data)
182
+ export(prepare_gazepoint_gca_data)
183
+ export(prepare_gazepoint_gpbiometrics_bridge)
184
+ export(prepare_gazepoint_hddm_export)
185
+ export(prepare_gazepoint_heatmap_data)
186
+ export(prepare_gazepoint_hmm_data)
187
+ export(prepare_gazepoint_multimodal_data)
188
+ export(prepare_gazepoint_pupil_gamm_data)
189
+ export(prepare_gazepoint_pupil_window_model_data)
190
+ export(prepare_gazepoint_pupillometryr_data)
191
+ export(prepare_gazepoint_semimarkov_data)
192
+ export(prepare_gazepoint_timecourse_test_data)
193
+ export(prepare_gazepoint_traminer_data)
194
+ export(preprocess_gazepoint_signals)
195
+ export(read_gazepoint)
196
+ export(read_gazepoint_face_export)
197
+ export(read_gazepoint_folder)
198
+ export(read_gazepoint_summary)
199
+ export(recalibrate_gazepoint_gaze)
200
+ export(recommend_gazepoint_exclusions)
201
+ export(recommend_gazepoint_model_family)
202
+ export(reconstruct_gazepoint_binocular_pupil)
203
+ export(regress_gazepoint_pupils)
204
+ export(report_gazepoint_cluster_permutation)
205
+ export(report_gazepoint_face_qc)
206
+ export(report_gazepoint_missingness)
207
+ export(report_gazepoint_multiverse)
208
+ export(report_gazepoint_phase_coverage)
209
+ export(report_gazepoint_qc_overview)
210
+ export(run_gazepoint_aoi_multiverse)
211
+ export(run_gazepoint_cluster_permutation)
212
+ export(run_gazepoint_cluster_permutation_anova)
213
+ export(run_gazepoint_cluster_permutation_covariate_adjusted)
214
+ export(run_gazepoint_cluster_permutation_lmer)
215
+ export(run_gazepoint_cluster_permutation_parallel)
216
+ export(run_gazepoint_cluster_threshold_sensitivity)
217
+ export(run_gazepoint_eyetools_fixation_detection)
218
+ export(run_gazepoint_gazer_crosscheck)
219
+ export(run_gazepoint_gpbiometrics_workflow)
220
+ export(run_gazepoint_model_leave_one_out)
221
+ export(run_gazepoint_multidimensional_cluster_permutation)
222
+ export(run_gazepoint_pupil_multiverse)
223
+ export(run_gazepoint_tfce)
224
+ export(run_gazepoint_workflow)
225
+ export(save_gazepoint_plots)
226
+ export(segment_gazepoint_task_phases)
227
+ export(select_gazepoint_adaptive_trial)
228
+ export(select_gazepoint_scanpath_clusters)
229
+ export(simulate_gazepoint_cluster_timecourse_data)
230
+ export(simulate_gazepoint_data)
231
+ export(simulate_gazepoint_fixations)
232
+ export(simulate_gazepoint_pupil_data)
233
+ export(smooth_gazepoint_coordinate)
234
+ export(smooth_gazepoint_pupil)
235
+ export(standardise_gazepoint_names)
236
+ export(standardize_gazepoint_face_columns)
237
+ export(stress_test_gazepoint_binocular_reconstruction)
238
+ export(summarise_aoi_samples)
239
+ export(summarise_fixations)
240
+ export(summarise_gazepoint_aoi)
241
+ export(summarise_gazepoint_aoi_entries)
242
+ export(summarise_gazepoint_aoi_transitions)
243
+ export(summarise_gazepoint_aoi_trial_features)
244
+ export(summarise_gazepoint_aoi_windows)
245
+ export(summarise_gazepoint_binocular_reporting)
246
+ export(summarise_gazepoint_clusters)
247
+ export(summarise_gazepoint_coordinate_coverage)
248
+ export(summarise_gazepoint_emmeans)
249
+ export(summarise_gazepoint_event_detector_agreement)
250
+ export(summarise_gazepoint_event_detector_benchmark)
251
+ export(summarise_gazepoint_face_quality)
252
+ export(summarise_gazepoint_face_reactivity)
253
+ export(summarise_gazepoint_face_windows)
254
+ export(summarise_gazepoint_fixation_trials)
255
+ export(summarise_gazepoint_fixed_effects)
256
+ export(summarise_gazepoint_markovchain)
257
+ export(summarise_gazepoint_missingness)
258
+ export(summarise_gazepoint_multiverse_results)
259
+ export(summarise_gazepoint_phase_coverage)
260
+ export(summarise_gazepoint_pupil)
261
+ export(summarise_gazepoint_pupil_response_features)
262
+ export(summarise_gazepoint_pupil_trial_features)
263
+ export(summarise_gazepoint_pupil_windows)
264
+ export(summarise_gazepoint_qc_status)
265
+ export(summarise_gazepoint_scanpath_cluster_stability)
266
+ export(summarise_gazepoint_semimarkov)
267
+ export(summarise_gazepoint_time_clusters)
268
+ export(summarise_gazepoint_workflow)
269
+ export(summarise_tracking_quality)
270
+ export(summarize_gazepoint_coordinate_coverage)
271
+ export(summarize_gazepoint_face_quality)
272
+ export(summarize_gazepoint_face_reactivity)
273
+ export(summarize_gazepoint_face_windows)
274
+ export(summarize_gazepoint_missingness)
275
+ export(summarize_gazepoint_phase_coverage)
276
+ export(summarize_gazepoint_pupil_response_features)
277
+ export(summarize_gazepoint_qc_status)
278
+ export(summarize_gazepoint_time_clusters)
279
+ export(sync_gazepoint_face_data)
280
+ export(tidy_gazepoint_model_summary)
281
+ export(transform_gazepoint_aoi_empirical_logit)
282
+ export(validate_gazepoint_binocular_reconstruction)
283
+ export(validate_gazepoint_master)
284
+ export(write_gazepoint_naming_audit)
285
+ export(write_gazepoint_outputs)
286
+ export(write_gazepoint_performance_benchmark)
287
+ importFrom(rlang,.data)