scanpath-studio 0.27.2__tar.gz → 0.28.0__tar.gz

{scanpath_studio-0.27.2/scanpath_studio.egg-info → scanpath_studio-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanpath-studio
-Version: 0.27.2
+Version: 0.28.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
@@ -44,7 +44,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: streamlit>=1.58.0
+Requires-Dist: streamlit>=1.61.1
 Requires-Dist: pandas>=2.3.3
 Requires-Dist: plotly>=6.5.2
 Requires-Dist: numpy>=2.4.1
@@ -72,6 +72,7 @@ Dynamic: license-file
 [![Live demo](https://img.shields.io/badge/Live_demo-Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://scanpath-studio.streamlit.app)
 [![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://lacclab.github.io/scanpath-studio/)
 [![CI](https://github.com/lacclab/scanpath-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/lacclab/scanpath-studio/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Flacclab.github.io%2Fscanpath-studio%2Fcoverage%2Fbadge.json)](https://lacclab.github.io/scanpath-studio/coverage/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 An interactive workbench for visualizing **eye-tracking-while-reading** data.

{scanpath_studio-0.27.2 → scanpath_studio-0.28.0}/README.md

@@ -5,6 +5,7 @@
 [![Live demo](https://img.shields.io/badge/Live_demo-Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://scanpath-studio.streamlit.app)
 [![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://lacclab.github.io/scanpath-studio/)
 [![CI](https://github.com/lacclab/scanpath-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/lacclab/scanpath-studio/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Flacclab.github.io%2Fscanpath-studio%2Fcoverage%2Fbadge.json)](https://lacclab.github.io/scanpath-studio/coverage/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 An interactive workbench for visualizing **eye-tracking-while-reading** data.

{scanpath_studio-0.27.2 → scanpath_studio-0.28.0}/pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Visualization",
 ]
 dependencies = [
-    "streamlit>=1.58.0",
+    "streamlit>=1.61.1",
     "pandas>=2.3.3",
     "plotly>=6.5.2",
     "numpy>=2.4.1",
@@ -92,3 +92,29 @@ include = ["scanpath_studio"]
     "sample_data/images/*.png",
     "sample_data/images/*.csv",
 ]
+
+[tool.coverage.run]
+source = ["scanpath_studio"]
+# Two one-shot data-prep scripts, deliberately untested and deliberately not
+# counted. Both are run by hand, once per data refresh, against corpora that are
+# not in the repo and cannot be in CI: `onestop_shard` needs the ~15 GB OneStop
+# lacclab CSVs, `update_sample_data` needs the full OneStop release to
+# regenerate the bundled demo. Testing them would mean mocking the file layout
+# they exist to walk, which pins the mock rather than the script (ENG-37).
+omit = [
+    "scanpath_studio/onestop_shard.py",
+    "scanpath_studio/update_sample_data.py",
+]
+
+[tool.coverage.report]
+# A floor, not a target: it fails the build when a change drops coverage
+# meaningfully, without turning every PR into a coverage negotiation. Raise it
+# when the real number has been comfortably above for a while.
+fail_under = 89
+show_missing = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+]

{scanpath_studio-0.27.2 → scanpath_studio-0.28.0}/scanpath_studio/__init__.py

@@ -27,7 +27,7 @@ __all__ = [
     "load_multipleye",
     "load_onestop",
 ]
-__version__ = "0.27.2"
+__version__ = "0.28.0"
 
 # Public headless API (see api.py / datasets.py). Resolved lazily so
 # `import scanpath_studio` stays cheap and doesn't pull in pandas/plotly/

{scanpath_studio-0.27.2 → scanpath_studio-0.28.0}/scanpath_studio/annotations.py

@@ -141,18 +141,6 @@ def known_tags() -> List[str]:
     return sorted(tags)
 
 
-def starred_keys() -> Set[Key]:
-    return {k for k, v in _store().items() if v.get("star")}
-
-
-def keys_with_tag(tag: str) -> Set[Key]:
-    return {k for k, v in _store().items() if tag in v.get("tags", [])}
-
-
-def annotated_count() -> int:
-    return len(_store())
-
-
 def current_records() -> List[dict]:
     """All annotations as a flat record list — for embedding in a saved config."""
     return store_to_records(_store())

{scanpath_studio-0.27.2 → scanpath_studio-0.28.0}/scanpath_studio/api.py

@@ -63,17 +63,19 @@ from .constants import (  # noqa: E402
     DEFAULT_SACCADE_WIDTH,
     FONT_FAMILY,
     PALETTES,
+    SACCADE_CLASS_ORDER,
     SACCADE_COLOR,
     UNIFORM_COLOR_FIELD,
     palette_settings,
 )
+from .export import annotate_figure  # noqa: E402
 from .plots import (  # noqa: E402
     animation_autoplay_frame_duration,
     animation_autoplay_post_script,
-    make_scanpath_animation,
-    make_scanpath_figure,
     make_difference_profile_figure,
     make_distribution_figure,
+    make_scanpath_animation,
+    make_scanpath_figure,
     make_word_profile_figure,
     split_scanpath_layers,
 )
@@ -161,6 +163,12 @@ CANONICAL_FIGURE_DEFAULTS: dict = dict(
     saccade_color_mode="Uniform",
     saccade_class_colors=None,
     saccade_type_legend=True,
+    # VIZ-31: the reading-class filter — which classes are drawn at all, as
+    # opposed to what colour they are drawn in. Spelled out as the full list
+    # rather than the equivalent `None` so this matches what the app's
+    # all-selected multiselect resolves to key-for-key; the builder treats a
+    # complete list as "no filter" and skips the classification pass.
+    saccade_classes=list(SACCADE_CLASS_ORDER),
     saccade_render_mode="Straight",
     fixation_snap_to_word=False,
     # VIZ-17 uniform fixation colour · VIZ-15 marker shape — the flat colour and
@@ -923,7 +931,7 @@ def _expand_palette(overrides: dict) -> dict:
     any colour the caller also passes explicitly wins over it::
 
         sps.plot_scanpath(w, f, palette="Print / greyscale")
-        sps.plot_scanpath(w, f, palette="Colourblind-safe", saccade_color="#000")
+        sps.plot_scanpath(w, f, palette="Default (colourblind-safe)", saccade_color="#000")
 
     The palette itself isn't a figure kwarg, so it's consumed here rather than
     forwarded. Raises on an unknown name — a silent fallback to the default
@@ -1082,6 +1090,8 @@ def plot_scanpath(
     fix_index_range: Optional[Tuple[int, int]] = None,
     illustration: bool = False,
     illustration_label: str = "auto",
+    title: str = "",
+    caption: str = "",
     **figure_overrides,
 ) -> go.Figure:
     """Build the canonical scanpath figure for one trial.
@@ -1106,6 +1116,11 @@ def plot_scanpath(
     the app's fixation-index window. It is applied before the drift correction,
     like the app.
 
+    ``title`` / ``caption`` (EXP-5) stamp a title/caption band onto the figure
+    without shrinking the plot area, exactly like the rail's *Title & caption on
+    the figure* control — literal text here, not the rail's ``{trial_id}``-style
+    pattern, since the caller already knows which trial this is.
+
     Remaining keywords override the app's defaults and are forwarded to
     :func:`plots.make_scanpath_figure` (e.g. ``show_heatmap=False``,
     ``color_by="pass_index"``, ``x_field="order_in_trial"``); an unknown keyword
@@ -1177,7 +1192,7 @@ def plot_scanpath(
         _require_normalized(raw_gaze, "raw_gaze")
         raw_gaze = _data.filter_raw_gaze(raw_gaze, [pid], [tid])
         settings.setdefault("show_raw_gaze", True)
-    return make_scanpath_figure(
+    fig = make_scanpath_figure(
         trial_words,
         trial_fixations,
         canvas_width=int(canvas_size[0]),
@@ -1189,6 +1204,8 @@ def plot_scanpath(
         raw_gaze=raw_gaze,
         **settings,
     )
+    annotate_figure(fig, title=title, caption=caption)
+    return fig
 
 
 def animate_scanpath(
@@ -1203,6 +1220,8 @@ def animate_scanpath(
     playback_speed: float = 1.0,
     autoplay: bool = True,
     fix_index_range: Optional[Tuple[int, int]] = None,
+    title: str = "",
+    caption: str = "",
     **animation_overrides,
 ) -> go.Figure:
     """Build the animated scanpath replay for one trial.
@@ -1230,6 +1249,8 @@ def animate_scanpath(
     matches the static figure. ``palette=`` (VIZ-18) works here too; the colours
     it implies that the animation doesn't support are dropped rather than
     raising, since the caller named a look, not those individual keys.
+
+    ``title`` / ``caption`` (EXP-5) — same as :func:`plot_scanpath`.
     """
     valid = set(_ANIMATION_FIGURE_PARAMS)
     explicit = set(animation_overrides) - {"palette"}
@@ -1256,7 +1277,7 @@ def animate_scanpath(
     trial_fixations = _apply_fix_index_range(trial_fixations, fix_index_range, pid, tid)
     if canvas_size is None:
         canvas_size = _data.compute_canvas_size(trial_words, trial_fixations)
-    return make_scanpath_animation(
+    fig = make_scanpath_animation(
         trial_words,
         trial_fixations,
         canvas_width=int(canvas_size[0]),
@@ -1267,6 +1288,8 @@ def animate_scanpath(
         autoplay=autoplay,
         **animation_overrides,
     )
+    annotate_figure(fig, title=title, caption=caption)
+    return fig
 
 
 def save_figure(