scanpath-studio 0.14.0__tar.gz

scanpath_studio-0.14.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Scanpath Studio Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scanpath_studio-0.14.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+recursive-include scanpath_studio/sample_data *.csv
+recursive-include scanpath_studio/sample_data *.parquet
+recursive-include scanpath_studio/sample_data *.feather

scanpath_studio-0.14.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: scanpath-studio
+Version: 0.14.0
+Summary: Interactive Streamlit workbench for visualizing eye-tracking-while-reading scanpaths, computing reading measures, and exporting figures and tabular data.
+Author-email: "Omer Shubi (LACC Lab, Technion)" <lacclab.technion@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Scanpath Studio Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://github.com/lacclab/scanpath-studio
+Project-URL: Issues, https://github.com/lacclab/scanpath-studio/issues
+Keywords: eye-tracking,scanpath,visualization,streamlit,reading,psycholinguistics
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: streamlit>=1.52.2
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: plotly>=6.5.0
+Requires-Dist: numpy>=2.3.5
+Requires-Dist: pyarrow>=22.0.0
+Requires-Dist: kaleido>=1.0
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Dynamic: license-file
+
+# Scanpath Studio
+
+[![PyPI](https://img.shields.io/pypi/v/scanpath-studio.svg)](https://pypi.org/project/scanpath-studio/)
+[![Live demo](https://img.shields.io/badge/Live_demo-Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://scanpath-studio.streamlit.app)
+[![CI](https://github.com/lacclab/scanpath-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/lacclab/scanpath-studio/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+An interactive workbench for visualizing **eye-tracking-while-reading** data.
+Drop in a trial and see the scanpath the way the reader saw it: words at their
+true on-screen positions, fixations and saccades layered on top, a density
+heatmap, side-by-side trial comparisons, and animated replay — all tunable, and
+all exportable as publication-ready figures.
+
+It is **dataset-agnostic** (auto-detects EyeLink / Gazepoint / snake-case
+columns) and ships with a small [OneStop][onestop-paper] demo so you can try it
+with zero setup.
+
+> **Authors:** Omer Shubi, Keren Gruteke Klein, and others (TBD) — LACC Lab, Technion.
+
+![A reading scanpath replayed fixation by fixation](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/scanpath_animation.gif)
+
+*A scanpath replayed fixation by fixation over the text the reader saw (bundled OneStop demo).*
+
+---
+
+## Try it
+
+**Live demo (zero install):** <https://scanpath-studio.streamlit.app>
+
+**Or run locally:**
+
+```bash
+pip install scanpath-studio
+scanpath-studio      # launches the app in your browser
+```
+
+---
+
+## What you can visualize
+
+The plot is built from layers you can toggle independently:
+
+- **Text** — every word drawn at the exact pixel coordinates the participant saw.
+- **Fixations** — where the eye paused, sized and **colored by any column** in your data (duration, GPT-2 surprisal, word frequency, …).
+- **Saccades** — the jumps between fixations; backward jumps (regressions) stand out.
+- **Areas of interest** — word bounding boxes that tie each fixation to a word.
+- **Heatmap** — the trial aggregated into a word-level measure (total fixation duration, fixation count, …).
+
+On top of the layered view:
+
+- **Animated replay** — watch the scanpath unfold fixation by fixation, at real or scaled speed.
+- **Compare two trials** — overlaid on one canvas or side-by-side (e.g. ordinary vs. information-seeking reading, first vs. repeated reading, L1 vs. L2).
+- **Critical-span highlight** — mark a region of interest (e.g. an answer span) by color or border to see at a glance whether it was read.
+- **Out-of-text & by-line** — flag fixations that land outside every word box, or color fixations by the text line they fall on.
+- **Fully customizable** — map any field to color, size, or axes; set the plot background (white or a neutral gray); every toggle, palette, and scale is independent.
+
+![Two readers of the same paragraph, animated on a shared real-time clock](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/demo_dual_scanpath.gif)
+
+*Overlay a second reading to compare two readers of the same text on a shared real-time clock.*
+
+---
+
+## The four tabs
+
+| Tab | What's there |
+|-----|--------------|
+| **Interactive Plot** | The layered scanpath view, trial picker (by trial / text / participant), trial metadata, and two-trial comparison. |
+| **Animated Scanpath** | Frame-by-frame replay; each frame lasts the actual fixation duration ÷ playback speed. |
+| **Raw Data** | Paginated word, fixation, and raw-gaze tables, each with CSV + Parquet download. |
+| **Data Statistics** | Summary stats (mean fixation duration, saccade amplitude, regression rate, reading speed), a fixation-duration distribution, and a per-word reading-measure bar plot. |
+
+![The Scanpath Studio app](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/app_screenshot.png)
+
+---
+
+## Reading measures from raw fixations
+
+If your data only carries raw fixations, the app computes the canonical
+per-word measures itself (pre-aggregated EyeLink columns, if present, take
+precedence):
+
+| Measure | Definition |
+|---------|------------|
+| **FFD** — first fixation duration | duration of the first fixation to land on the word |
+| **FPRT** / gaze duration | sum of fixations from first entry until the eye first leaves |
+| **RPD** / go-past time | sum of fixations from first entry until the eye first moves past the word |
+| **TFD** / dwell | sum of all fixations on the word |
+| fixation count, skip, regression in/out, saccade amplitude | standard reading-research flags and counts |
+
+Definitions follow Rayner (1998) and Inhoff & Radach (1998).
+
+---
+
+## Triage your trials
+
+Filter the trial pool by **condition** — information-seeking *Hunting* vs.
+ordinary *Gathering* reading, difficulty, first vs. repeated reading, answer
+correctness — or by your own annotations. **Star** favorites, **tag** trials
+(e.g. "To exclude"), and jot per-trial **notes**; download everything as a JSON
+sidecar and restore it in a later session.
+
+---
+
+## Your data
+
+Upload **CSV, Parquet, or Feather** tables for words/AoIs, fixations, and
+(optionally) raw gaze. Columns are auto-detected from common EyeLink,
+Gazepoint, and snake-case conventions; a sidebar **Column mapping** panel lets
+you override any guess.
+
+**Areas of interest** come straight from your word boxes — given as
+`(x, y, width, height)` or EyeLink's `IA_LEFT/RIGHT/TOP/BOTTOM` — the app never
+invents them. Fixations are tied to words by bounding-box containment (with a
+small nearest-word fallback); fixations that miss every box are flagged
+*out-of-text*.
+
+## Bulk export
+
+One panel exports artifacts for **every filtered trial** into a single zip —
+per-trial PNG + SVG figures, the exact plot settings (`plot_config.json`),
+fixations, and per-word measures, plus aggregated tables across trials. Ideal
+for paper figures or building an image dataset of scanpaths for vision models.
+
+---
+
+## Run from source
+
+```bash
+git clone https://github.com/lacclab/scanpath-studio.git
+cd scanpath-studio
+pip install -e ".[test]"          # or: uv sync
+streamlit run streamlit_app.py
+```
+
+Tested on Python 3.11–3.13. Run the tests with `pytest`; lint with
+`ruff check --exclude other_vis .`. See [AGENTS.md](AGENTS.md) for an
+architectural overview.
+
+---
+
+## Citation
+
+A system-demo paper is in preparation — **citation TBD**. Until then, cite the
+software via GitHub's **"Cite this repository"** button (generated from
+[`CITATION.cff`](CITATION.cff)).
+
+If you use the bundled demo data, please cite the OneStop corpus:
+
+```bibtex
+@article{berzak2025onestop,
+  title     = {{OneStop}: A 360-Participant {E}nglish Eye Tracking Dataset
+               with Different Reading Regimes},
+  author    = {Berzak, Yevgeni and Malmaud, Jonathan and Shubi, Omer
+               and Meiri, Yoav and Lion, Ella and Levy, Roger},
+  journal   = {Scientific Data},
+  year      = {2025},
+  publisher = {Nature Publishing Group},
+  doi       = {10.1038/s41597-025-06272-2},
+  url       = {https://www.nature.com/articles/s41597-025-06272-2},
+}
+```
+
+The bundled demo is a subset of [OneStop Eye Movements][onestop-corpus], used
+under its original license ([docs][onestop-docs]).
+
+[onestop-paper]: https://www.nature.com/articles/s41597-025-06272-2
+[onestop-corpus]: https://github.com/lacclab/OneStop-Eye-Movements
+[onestop-docs]: https://lacclab.github.io/OneStop-Eye-Movements/
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

scanpath_studio-0.14.0/README.md

@@ -0,0 +1,174 @@
+# Scanpath Studio
+
+[![PyPI](https://img.shields.io/pypi/v/scanpath-studio.svg)](https://pypi.org/project/scanpath-studio/)
+[![Live demo](https://img.shields.io/badge/Live_demo-Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://scanpath-studio.streamlit.app)
+[![CI](https://github.com/lacclab/scanpath-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/lacclab/scanpath-studio/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+An interactive workbench for visualizing **eye-tracking-while-reading** data.
+Drop in a trial and see the scanpath the way the reader saw it: words at their
+true on-screen positions, fixations and saccades layered on top, a density
+heatmap, side-by-side trial comparisons, and animated replay — all tunable, and
+all exportable as publication-ready figures.
+
+It is **dataset-agnostic** (auto-detects EyeLink / Gazepoint / snake-case
+columns) and ships with a small [OneStop][onestop-paper] demo so you can try it
+with zero setup.
+
+> **Authors:** Omer Shubi, Keren Gruteke Klein, and others (TBD) — LACC Lab, Technion.
+
+![A reading scanpath replayed fixation by fixation](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/scanpath_animation.gif)
+
+*A scanpath replayed fixation by fixation over the text the reader saw (bundled OneStop demo).*
+
+---
+
+## Try it
+
+**Live demo (zero install):** <https://scanpath-studio.streamlit.app>
+
+**Or run locally:**
+
+```bash
+pip install scanpath-studio
+scanpath-studio      # launches the app in your browser
+```
+
+---
+
+## What you can visualize
+
+The plot is built from layers you can toggle independently:
+
+- **Text** — every word drawn at the exact pixel coordinates the participant saw.
+- **Fixations** — where the eye paused, sized and **colored by any column** in your data (duration, GPT-2 surprisal, word frequency, …).
+- **Saccades** — the jumps between fixations; backward jumps (regressions) stand out.
+- **Areas of interest** — word bounding boxes that tie each fixation to a word.
+- **Heatmap** — the trial aggregated into a word-level measure (total fixation duration, fixation count, …).
+
+On top of the layered view:
+
+- **Animated replay** — watch the scanpath unfold fixation by fixation, at real or scaled speed.
+- **Compare two trials** — overlaid on one canvas or side-by-side (e.g. ordinary vs. information-seeking reading, first vs. repeated reading, L1 vs. L2).
+- **Critical-span highlight** — mark a region of interest (e.g. an answer span) by color or border to see at a glance whether it was read.
+- **Out-of-text & by-line** — flag fixations that land outside every word box, or color fixations by the text line they fall on.
+- **Fully customizable** — map any field to color, size, or axes; set the plot background (white or a neutral gray); every toggle, palette, and scale is independent.
+
+![Two readers of the same paragraph, animated on a shared real-time clock](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/demo_dual_scanpath.gif)
+
+*Overlay a second reading to compare two readers of the same text on a shared real-time clock.*
+
+---
+
+## The four tabs
+
+| Tab | What's there |
+|-----|--------------|
+| **Interactive Plot** | The layered scanpath view, trial picker (by trial / text / participant), trial metadata, and two-trial comparison. |
+| **Animated Scanpath** | Frame-by-frame replay; each frame lasts the actual fixation duration ÷ playback speed. |
+| **Raw Data** | Paginated word, fixation, and raw-gaze tables, each with CSV + Parquet download. |
+| **Data Statistics** | Summary stats (mean fixation duration, saccade amplitude, regression rate, reading speed), a fixation-duration distribution, and a per-word reading-measure bar plot. |
+
+![The Scanpath Studio app](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/app_screenshot.png)
+
+---
+
+## Reading measures from raw fixations
+
+If your data only carries raw fixations, the app computes the canonical
+per-word measures itself (pre-aggregated EyeLink columns, if present, take
+precedence):
+
+| Measure | Definition |
+|---------|------------|
+| **FFD** — first fixation duration | duration of the first fixation to land on the word |
+| **FPRT** / gaze duration | sum of fixations from first entry until the eye first leaves |
+| **RPD** / go-past time | sum of fixations from first entry until the eye first moves past the word |
+| **TFD** / dwell | sum of all fixations on the word |
+| fixation count, skip, regression in/out, saccade amplitude | standard reading-research flags and counts |
+
+Definitions follow Rayner (1998) and Inhoff & Radach (1998).
+
+---
+
+## Triage your trials
+
+Filter the trial pool by **condition** — information-seeking *Hunting* vs.
+ordinary *Gathering* reading, difficulty, first vs. repeated reading, answer
+correctness — or by your own annotations. **Star** favorites, **tag** trials
+(e.g. "To exclude"), and jot per-trial **notes**; download everything as a JSON
+sidecar and restore it in a later session.
+
+---
+
+## Your data
+
+Upload **CSV, Parquet, or Feather** tables for words/AoIs, fixations, and
+(optionally) raw gaze. Columns are auto-detected from common EyeLink,
+Gazepoint, and snake-case conventions; a sidebar **Column mapping** panel lets
+you override any guess.
+
+**Areas of interest** come straight from your word boxes — given as
+`(x, y, width, height)` or EyeLink's `IA_LEFT/RIGHT/TOP/BOTTOM` — the app never
+invents them. Fixations are tied to words by bounding-box containment (with a
+small nearest-word fallback); fixations that miss every box are flagged
+*out-of-text*.
+
+## Bulk export
+
+One panel exports artifacts for **every filtered trial** into a single zip —
+per-trial PNG + SVG figures, the exact plot settings (`plot_config.json`),
+fixations, and per-word measures, plus aggregated tables across trials. Ideal
+for paper figures or building an image dataset of scanpaths for vision models.
+
+---
+
+## Run from source
+
+```bash
+git clone https://github.com/lacclab/scanpath-studio.git
+cd scanpath-studio
+pip install -e ".[test]"          # or: uv sync
+streamlit run streamlit_app.py
+```
+
+Tested on Python 3.11–3.13. Run the tests with `pytest`; lint with
+`ruff check --exclude other_vis .`. See [AGENTS.md](AGENTS.md) for an
+architectural overview.
+
+---
+
+## Citation
+
+A system-demo paper is in preparation — **citation TBD**. Until then, cite the
+software via GitHub's **"Cite this repository"** button (generated from
+[`CITATION.cff`](CITATION.cff)).
+
+If you use the bundled demo data, please cite the OneStop corpus:
+
+```bibtex
+@article{berzak2025onestop,
+  title     = {{OneStop}: A 360-Participant {E}nglish Eye Tracking Dataset
+               with Different Reading Regimes},
+  author    = {Berzak, Yevgeni and Malmaud, Jonathan and Shubi, Omer
+               and Meiri, Yoav and Lion, Ella and Levy, Roger},
+  journal   = {Scientific Data},
+  year      = {2025},
+  publisher = {Nature Publishing Group},
+  doi       = {10.1038/s41597-025-06272-2},
+  url       = {https://www.nature.com/articles/s41597-025-06272-2},
+}
+```
+
+The bundled demo is a subset of [OneStop Eye Movements][onestop-corpus], used
+under its original license ([docs][onestop-docs]).
+
+[onestop-paper]: https://www.nature.com/articles/s41597-025-06272-2
+[onestop-corpus]: https://github.com/lacclab/OneStop-Eye-Movements
+[onestop-docs]: https://lacclab.github.io/OneStop-Eye-Movements/
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

scanpath_studio-0.14.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=69.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scanpath-studio"
+dynamic = ["version"]
+description = "Interactive Streamlit workbench for visualizing eye-tracking-while-reading scanpaths, computing reading measures, and exporting figures and tabular data."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Omer Shubi (LACC Lab, Technion)", email = "lacclab.technion@gmail.com" }]
+license = { file = "LICENSE" }
+keywords = ["eye-tracking", "scanpath", "visualization", "streamlit", "reading", "psycholinguistics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "streamlit>=1.52.2",
+    "pandas>=2.3.3",
+    "plotly>=6.5.0",
+    "numpy>=2.3.5",
+    "pyarrow>=22.0.0",
+    "kaleido>=1.0",
+    "watchdog>=4.0.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/lacclab/scanpath-studio"
+Issues = "https://github.com/lacclab/scanpath-studio/issues"
+
+[project.scripts]
+scanpath-studio = "scanpath_studio.__main__:main"
+
+[tool.setuptools.dynamic]
+# Single source of truth for the version: scanpath_studio/__version__
+version = { attr = "scanpath_studio.__version__" }
+
+[tool.setuptools]
+include-package-data = true
+package-dir = {"" = "."}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["scanpath_studio"]
+
+[tool.setuptools.package-data]
+"scanpath_studio" = [
+    "sample_data/*.csv",
+    "sample_data/*.parquet",
+    "sample_data/*.feather",
+]

scanpath_studio-0.14.0/scanpath_studio/__init__.py

@@ -0,0 +1,13 @@
+"""Streamlit workbench for scanpath visualization."""
+
+from __future__ import annotations
+
+__all__ = ["__version__", "main"]
+__version__ = "0.14.0"
+
+
+def main() -> None:
+    """Programmatic entry point — `from scanpath_studio import main`."""
+    from .app import main as _main
+
+    _main()

scanpath_studio-0.14.0/scanpath_studio/__main__.py

@@ -0,0 +1,18 @@
+import importlib.resources as resources
+import sys
+from typing import Optional
+
+from streamlit.web import cli as stcli
+
+
+def main(argv: Optional[list[str]] = None) -> None:
+    """Entrypoint that launches the Streamlit app via ``streamlit run``."""
+    extra_args = list(argv) if argv is not None else sys.argv[1:]
+    app_resource = resources.files(__package__).joinpath("app.py")
+    with resources.as_file(app_resource) as app_path:
+        sys.argv = ["streamlit", "run", str(app_path), *extra_args]
+        sys.exit(stcli.main())
+
+
+if __name__ == "__main__":
+    main()