scanpath-studio 0.34.0__tar.gz → 0.35.0__tar.gz

{scanpath_studio-0.34.0/scanpath_studio.egg-info → scanpath_studio-0.35.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: scanpath-studio
-Version: 0.34.0
-Summary: Interactive Streamlit workbench for visualizing eye-tracking-while-reading scanpaths, computing reading measures, and exporting figures and tabular data.
+Version: 0.35.0
+Summary: Interactive workbench for eye-tracking-while-reading data: draw, replay and compare scanpaths over the text, and export figures and tables.
 Author: Keren Gruteke Klein, Maya Grossman, Ella Lion, Deborah N. Jakobi, David R. Reich, Lena Jäger, Yevgeni Berzak
 Author-email: Omer Shubi <lacclab.technion@gmail.com>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: streamlit>=1.64.0
+Requires-Dist: streamlit>=1.65.0
 Requires-Dist: pandas>=3.0
 Requires-Dist: plotly>=7.1
 Requires-Dist: numpy>=2.4
@@ -65,16 +65,18 @@ Dynamic: license-file
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22933884.svg)](https://doi.org/10.5281/zenodo.22933884)
 
 **Scanpath Studio shows you how people read.** Load eye-tracking-while-reading
-data and watch each reading unfold over the text, exactly where it sat on the
-screen — then compare readers, analyse a corpus, and export figures ready for a
-paper.
+data and watch each trial unfold over the text, exactly where it sat on the
+screen — then compare participants, analyze a corpus, and export figures ready
+for a paper.
 
-![Using Scanpath Studio: stepping through trials, a heatmap, a replay, a two-reader comparison and Corpus Analysis](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/docs/assets/app_demo.gif)
+![Using Scanpath Studio: stepping through trials, a heatmap, a replay, a two-participant comparison and Corpus Analysis](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/docs/assets/app_demo.gif)
 
 ## Get started
 
-- **In the browser:** the live demo at
-  <https://scanpath-studio.streamlit.app>.
+- **As a desktop app**, the easiest way to work with your own data:
+  [Windows](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-windows-x86_64.zip) ·
+  [macOS (Apple silicon)](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-macos-arm64.dmg) ·
+  [Linux](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-linux-x86_64.tar.gz).
 - **With pip** (Python 3.11–3.14):
 
   ```bash
@@ -82,30 +84,31 @@ paper.
   scanpath-studio      # opens the app in your browser
   ```
 
-- **As a desktop app:** [Windows](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-windows-x86_64.zip) ·
-  [macOS (Apple silicon)](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-macos-arm64.dmg) ·
-  [Linux](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-linux-x86_64.tar.gz).
+- **In the browser**, to try it on the bundled demo data: the live demo at
+  <https://scanpath-studio.streamlit.app>.
 
-The pip and desktop installs keep your data on your own machine; the hosted demo
-runs on Streamlit Community Cloud.
+The desktop and pip installs keep your data on your own machine, handle large
+datasets, and download the public corpora (PoTeC, OneStop) in one click. The
+hosted demo runs on Streamlit Community Cloud, with limited memory and no
+corpus downloads.
 
 ## What you can do
 
 - **See the reading:** fixations, saccades, heatmaps and raw gaze over the text
   at its true on-screen position, with fixations colored by any column.
 - **Replay it** in real time or faster, and export it as HTML, GIF or MP4.
-- **Compare readers:** overlay two trials or place them side by side — even
+- **Compare participants:** overlay two trials or place them side by side — even
   from two different datasets.
-- **Analyse a corpus** per text, reader or group, with every measure
-  documented in the
+- **Analyze a corpus** per text, participant or group, from the reading
+  measures your data brings, each defined in the
   [computation register](https://lacclab.github.io/scanpath-studio/computations/).
 - **Triage, export and share:** tag and filter trials, export one figure or a
   zip for every trial, and share a link that reopens the exact view.
 
 | | |
 |:---:|:---:|
-| ![A reading scanpath replayed fixation by fixation](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/scanpath_animation.gif) | ![Two readers of the same paragraph, overlaid on one canvas](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/demo_dual_scanpath.png) |
-| A reading, replayed fixation by fixation | Two readers of one paragraph, overlaid ([animated](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/docs/assets/demo_dual_scanpath.gif)) |
+| ![A scanpath replayed fixation by fixation](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/scanpath_animation.gif) | ![Two participants reading the same paragraph, overlaid on one canvas](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/demo_dual_scanpath.png) |
+| A trial, replayed fixation by fixation | Two participants on one paragraph, overlaid ([animated](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/docs/assets/demo_dual_scanpath.gif)) |
 
 The app has three views: 🗺️ **Scanpath** for one trial at a time, 📊 **Corpus
 Analysis** for the whole dataset, and 🗂️ **Data Management** for loading and configuring
@@ -143,8 +146,8 @@ sps.save_figure(fig, "scanpath.html")
 
 For your own files, pass `--words ia.csv --fixations fix.csv` to `render`, or
 use `sps.load_scanpath_data("ia.csv", "fix.csv")`. HTML output needs nothing
-else; PNG, SVG, PDF, GIF and MP4 go through Kaleido, which needs Chrome once:
-`plotly_get_chrome -y`. The
+else; PNG, SVG and PDF (and GIF/MP4 replays) go through Kaleido, which needs
+Chrome, Chromium or Edge, or run `plotly_get_chrome -y` once. The
 [CLI reference](https://lacclab.github.io/scanpath-studio/cli/) and the
 [Python API reference](https://lacclab.github.io/scanpath-studio/api/) list
 every flag and parameter.

{scanpath_studio-0.34.0 → scanpath_studio-0.35.0}/README.md

@@ -11,16 +11,18 @@
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22933884.svg)](https://doi.org/10.5281/zenodo.22933884)
 
 **Scanpath Studio shows you how people read.** Load eye-tracking-while-reading
-data and watch each reading unfold over the text, exactly where it sat on the
-screen — then compare readers, analyse a corpus, and export figures ready for a
-paper.
+data and watch each trial unfold over the text, exactly where it sat on the
+screen — then compare participants, analyze a corpus, and export figures ready
+for a paper.
 
-![Using Scanpath Studio: stepping through trials, a heatmap, a replay, a two-reader comparison and Corpus Analysis](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/docs/assets/app_demo.gif)
+![Using Scanpath Studio: stepping through trials, a heatmap, a replay, a two-participant comparison and Corpus Analysis](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/docs/assets/app_demo.gif)
 
 ## Get started
 
-- **In the browser:** the live demo at
-  <https://scanpath-studio.streamlit.app>.
+- **As a desktop app**, the easiest way to work with your own data:
+  [Windows](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-windows-x86_64.zip) ·
+  [macOS (Apple silicon)](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-macos-arm64.dmg) ·
+  [Linux](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-linux-x86_64.tar.gz).
 - **With pip** (Python 3.11–3.14):
 
   ```bash
@@ -28,30 +30,31 @@ paper.
   scanpath-studio      # opens the app in your browser
   ```
 
-- **As a desktop app:** [Windows](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-windows-x86_64.zip) ·
-  [macOS (Apple silicon)](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-macos-arm64.dmg) ·
-  [Linux](https://github.com/lacclab/scanpath-studio/releases/latest/download/ScanpathStudio-linux-x86_64.tar.gz).
+- **In the browser**, to try it on the bundled demo data: the live demo at
+  <https://scanpath-studio.streamlit.app>.
 
-The pip and desktop installs keep your data on your own machine; the hosted demo
-runs on Streamlit Community Cloud.
+The desktop and pip installs keep your data on your own machine, handle large
+datasets, and download the public corpora (PoTeC, OneStop) in one click. The
+hosted demo runs on Streamlit Community Cloud, with limited memory and no
+corpus downloads.
 
 ## What you can do
 
 - **See the reading:** fixations, saccades, heatmaps and raw gaze over the text
   at its true on-screen position, with fixations colored by any column.
 - **Replay it** in real time or faster, and export it as HTML, GIF or MP4.
-- **Compare readers:** overlay two trials or place them side by side — even
+- **Compare participants:** overlay two trials or place them side by side — even
   from two different datasets.
-- **Analyse a corpus** per text, reader or group, with every measure
-  documented in the
+- **Analyze a corpus** per text, participant or group, from the reading
+  measures your data brings, each defined in the
   [computation register](https://lacclab.github.io/scanpath-studio/computations/).
 - **Triage, export and share:** tag and filter trials, export one figure or a
   zip for every trial, and share a link that reopens the exact view.
 
 | | |
 |:---:|:---:|
-| ![A reading scanpath replayed fixation by fixation](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/scanpath_animation.gif) | ![Two readers of the same paragraph, overlaid on one canvas](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/demo_dual_scanpath.png) |
-| A reading, replayed fixation by fixation | Two readers of one paragraph, overlaid ([animated](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/docs/assets/demo_dual_scanpath.gif)) |
+| ![A scanpath replayed fixation by fixation](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/scanpath_animation.gif) | ![Two participants reading the same paragraph, overlaid on one canvas](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/assets/demo_dual_scanpath.png) |
+| A trial, replayed fixation by fixation | Two participants on one paragraph, overlaid ([animated](https://raw.githubusercontent.com/lacclab/scanpath-studio/main/docs/assets/demo_dual_scanpath.gif)) |
 
 The app has three views: 🗺️ **Scanpath** for one trial at a time, 📊 **Corpus
 Analysis** for the whole dataset, and 🗂️ **Data Management** for loading and configuring
@@ -89,8 +92,8 @@ sps.save_figure(fig, "scanpath.html")
 
 For your own files, pass `--words ia.csv --fixations fix.csv` to `render`, or
 use `sps.load_scanpath_data("ia.csv", "fix.csv")`. HTML output needs nothing
-else; PNG, SVG, PDF, GIF and MP4 go through Kaleido, which needs Chrome once:
-`plotly_get_chrome -y`. The
+else; PNG, SVG and PDF (and GIF/MP4 replays) go through Kaleido, which needs
+Chrome, Chromium or Edge, or run `plotly_get_chrome -y` once. The
 [CLI reference](https://lacclab.github.io/scanpath-studio/cli/) and the
 [Python API reference](https://lacclab.github.io/scanpath-studio/api/) list
 every flag and parameter.

{scanpath_studio-0.34.0 → scanpath_studio-0.35.0}/pyproject.toml

@@ -5,7 +5,7 @@ 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."
+description = "Interactive workbench for eye-tracking-while-reading data: draw, replay and compare scanpaths over the text, and export figures and tables."
 readme = "README.md"
 requires-python = ">=3.11"
 authors = [
@@ -34,7 +34,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Visualization",
 ]
 dependencies = [
-    "streamlit>=1.64.0",
+    "streamlit>=1.65.0",
     "pandas>=3.0",
     "plotly>=7.1",
     "numpy>=2.4",

{scanpath_studio-0.34.0 → scanpath_studio-0.35.0}/scanpath_studio/__init__.py

@@ -5,15 +5,12 @@ from __future__ import annotations
 __all__ = [
     "ScanpathData",
     "__version__",
-    "alignment_sensitivity",
-    "analysis_tables",
     "animate_scanpath",
     "build_authored_scanpath",
     "cache_status",
     "check_data_health",
     "clear_cache",
     "compare_scanpaths",
-    "compute_word_metrics",
     "figure_code",
     "figure_options",
     "list_parts",
@@ -31,15 +28,12 @@ __all__ = [
     "main",
     "plot_corpus_figure",
     "plot_scanpath",
-    "preprocess_data",
     "propose_schema",
-    "reader_summary",
     "render_parent_trial",
     "save_figure",
     "save_figure_layers",
-    "trial_summary",
 ]
-__version__ = "0.34.0"
+__version__ = "0.35.0"
 
 # Public headless API (see api.py / datasets.py / eyegenbench.py). Resolved lazily so
 # `import scanpath_studio` stays cheap and doesn't pull in pandas/plotly/
@@ -47,10 +41,23 @@ __version__ = "0.34.0"
 # The MultiplEYE and benchmark-corpus loaders stay importable but are left out
 # of `__all__`: those corpora are held back from this release
 # (`constants.multipleye_enabled` / `benchmark_corpora_enabled`).
+# The app's own computed measures are held back the same way
+# (`constants.computed_measures_enabled`): importable, but not advertised —
+# they raise without SCANPATH_EXPERIMENTAL=1 (#374).
+_HELD_BACK_EXPORTS = frozenset(
+    {
+        "alignment_sensitivity",
+        "analysis_tables",
+        "compute_word_metrics",
+        "preprocess_data",
+        "reader_summary",
+        "trial_summary",
+    }
+)
 _DATASET_EXPORTS = frozenset({"load_potec", "load_multipleye", "load_onestop"})
 _EYEGENBENCH_EXPORTS = frozenset({"load_eyegenbench", "eyegenbench_datasets"})
 _API_EXPORTS = (
-    frozenset(__all__)
+    (frozenset(__all__) | _HELD_BACK_EXPORTS)
     - {"__version__", "main"}
     - _DATASET_EXPORTS
     - _EYEGENBENCH_EXPORTS
@@ -78,7 +85,8 @@ def __dir__() -> list:
 
 
 def main() -> None:
-    """Programmatic entry point — `from scanpath_studio import main`."""
+    """The app's Streamlit script body. To open the app, run `scanpath-studio`;
+    from Python, use the headless API instead."""
     from .app import main as _main
 
     _main()

{scanpath_studio-0.34.0 → scanpath_studio-0.35.0}/scanpath_studio/aggregation.py

@@ -127,7 +127,7 @@ MEASURES: dict[str, Measure] = {
         ),
         Measure(
             "fprt",
-            "First-pass gaze — FPRT",
+            "First-pass reading time — FPRT",
             "words",
             "first_pass_gaze_duration_ms",
             "ms",
@@ -171,7 +171,7 @@ MEASURES: dict[str, Measure] = {
         ),
         Measure(
             "landing_distance",
-            "Centred landing distance",
+            "Centered landing distance",
             "words",
             "initial_landing_distance",
             "letters",
@@ -737,7 +737,7 @@ def reader_vs_cohort_values(
     *,
     normalize: bool = False,
 ) -> dict[str, np.ndarray]:
-    """``{"This reader": …, "Cohort": …}`` value arrays for a measure (AN-7)."""
+    """``{"This participant": …, "Cohort": …}`` value arrays for a measure (AN-7)."""
     if frame is None or frame.empty or "participant_id" not in frame.columns:
         return {}
     work = frame.copy()
@@ -749,7 +749,7 @@ def reader_vs_cohort_values(
     me = work.loc[is_target, "_m"].dropna().to_numpy()
     others = work.loc[~is_target, "_m"].dropna().to_numpy()
     if me.size:
-        out["This reader"] = me
+        out["This participant"] = me
     if others.size:
         out["Cohort"] = others
     return out
@@ -1286,7 +1286,7 @@ def landing_positions(
     way the letter position is: counted from where the glyphs end.
 
     Not clipped: a first fixation the word got although it lies outside the box
-    horizontally (the 50 px nearest-word fallback, or an imported ``word_id``)
+    horizontally (an imported ``word_id``)
     reads below 0 or above 1, rather than piling onto an edge it did not land on.
     """
     from .measures import word_glyph_span
@@ -1578,18 +1578,21 @@ def paired_group_summary(
     spec_b: Mapping,
     *,
     agg: str = "mean",
-    spread: str = "SEM",
     label_a: str = "Group A",
     label_b: str = "Group B",
     words: pd.DataFrame | None = None,
     fixations: pd.DataFrame | None = None,
     normalize: bool = False,
 ) -> pd.DataFrame:
-    """Per-measure group means + error for the paired bars (AN-20).
-
-    Returns ``[measure, group, value, err_lo, err_hi, n]``. ``measures`` may mix
-    word- and fixation-level measures; pass ``words``/``fixations`` so each reads
-    its backing frame (``frame`` is the fallback).
+    """Per-measure group summaries for the paired bars (AN-20).
+
+    Returns ``[measure, group, value, n_observations]``: ``value`` is ``agg``
+    over every word or fixation of the group pooled across participants, and
+    ``n_observations`` counts those pooled values. No error bars this release
+    (#374): a spread over pooled words from the same few participants reads as
+    a precision the data does not have. ``measures`` may mix word- and
+    fixation-level measures; pass ``words``/``fixations`` so each reads its
+    backing frame (``frame`` is the fallback).
     """
     label_a, label_b = distinct_group_labels(label_a, label_b)
     rows = []
@@ -1603,24 +1606,15 @@ def paired_group_summary(
             continue
         for spec, label in ((spec_a, label_a), (spec_b, label_b)):
             vals = measure_values(apply_group(src, spec), m, normalize=normalize)
-            center = aggregate_value(vals, agg)
-            lo, hi = spread_bounds(vals, center, spread, agg=agg)
             rows.append(
                 {
                     "measure": m.label,
                     "group": label,
-                    # Clamp to ≥0: an asymmetric band (e.g. mean + IQR on skewed
-                    # data) can put the centre outside [lo, hi], and a negative
-                    # Plotly error-bar length renders in the wrong direction.
-                    "value": center,
-                    "err_lo": max(center - lo, 0.0),
-                    "err_hi": max(hi - center, 0.0),
-                    "n": int(vals.size),
+                    "value": aggregate_value(vals, agg),
+                    "n_observations": int(vals.size),
                 }
             )
-    return pd.DataFrame(
-        rows, columns=["measure", "group", "value", "err_lo", "err_hi", "n"]
-    )
+    return pd.DataFrame(rows, columns=["measure", "group", "value", "n_observations"])
 
 
 def group_mean_difference(

{scanpath_studio-0.34.0 → scanpath_studio-0.35.0}/scanpath_studio/analysis_recipe.py

@@ -35,8 +35,8 @@ RECIPE_VERSION = 1
 #: What the recipe deliberately leaves out, written into every one.
 EXCLUDES = {
     "figure_settings": (
-        "Palette, canvas and fonts are not recorded here. Save them with "
-        "Share → File, which holds no trial filters."
+        "Palette, canvas and fonts live in the settings file (Scanpath → "
+        "Share → File), which holds no trial filters."
     ),
     "data": (
         "No table rows and no annotation notes. The dataset is referenced by "
@@ -133,7 +133,7 @@ def analysis_choices(
     if normalize is not None:
         rate = bool(getattr(measure, "is_rate", False))
         out["normalization"] = (
-            "z-score within reader" if normalize and not rate else "none"
+            "z-score per participant" if normalize and not rate else "none"
         )
     if spread:
         out["spread"] = spread

{scanpath_studio-0.34.0 → scanpath_studio-0.35.0}/scanpath_studio/animation_export.py

@@ -121,7 +121,7 @@ class AnimationBudgetError(AnimationExportError):
 # `chromium_browser_path` finds an installed Chrome, Chromium or Edge there too.
 CHROME_INSTALL_HINT = (
     "Image export needs Chrome, Chromium or Edge, and none was found. Install one "
-    "of them and try again — a pip install can instead run `plotly_get_chrome -y`. "
+    "of them and try again — or, with a pip install, run `plotly_get_chrome -y`. "
     "The **HTML** export needs no browser."
 )
 
@@ -130,7 +130,7 @@ def chromium_browser_path() -> str | None:
     """Return the browser path Kaleido would use, without launching it.
 
     ``Chromium.find_browser`` is Choreographer's complete discovery path: it
-    honours ``BROWSER_PATH``, searches ``PATH``, checks platform-specific
+    honors ``BROWSER_PATH``, searches ``PATH``, checks platform-specific
     locations for Chrome, Chromium, Edge, Brave, and Vivaldi, and can fall back
     to Choreographer's managed Chrome download. We prefer a system browser: a
     stale managed download must not shadow a working installed Edge/Chrome.
@@ -187,7 +187,7 @@ def _static_base(fig: go.Figure) -> go.Figure:
     truncate the existing entries), so we assign the attributes directly. The
     reserved control band is then reclaimed so the clip isn't topped by an empty
     strip; a slim margin remains for the "Elapsed" annotation. Only the control
-    band is reclaimed: the other margins hold a title, a caption, a colour bar or
+    band is reclaimed: the other margins hold a title, a caption, a color bar or
     the coordinate-grid ticks, and are kept as they are. The replay's clock
     on ``layout.meta`` (BUG-93) goes too — only the live player reads it, and it
     would otherwise ride into every frame Kaleido renders.
@@ -286,14 +286,14 @@ def check_gif_budget(
     if total <= budget:
         return
     fits = int(budget) // per_frame
-    shorter = f"cap it at {fits} frames or fewer, " if fits >= 1 else ""
+    shorter = f"cap it at {fits} frames or fewer, or " if fits >= 1 else ""
     raise AnimationBudgetError(
         f"a {n_frames}-frame GIF at {width}×{height} px and {scale:g}× comes to "
         f"{total / 1e6:,.0f} megapixels of frames, over the "
         f"{budget / 1e6:,.0f}-megapixel limit for one GIF"
         f"{' on this shared server' if shared else ''}. Export **MP4** instead — "
         f"its frames stream straight to the encoder and the file stays small — or "
-        f"{shorter}or lower the resolution."
+        f"{shorter}lower the resolution."
     )
 
 
@@ -406,7 +406,8 @@ def render_png_frames(
                     raise AnimationExportError(
                         CHROME_INSTALL_HINT
                         if not chrome_available()
-                        else f"Rendering frame {k + 1}/{len(frames)} failed: {exc}."
+                        else f"Frame {k + 1} of {len(frames)} couldn't be drawn "
+                        f"({exc}). Try again, or export the HTML replay."
                     ) from exc
                 pngs.append(bytes(png))
                 if progress_callback is not None:
@@ -432,7 +433,7 @@ def encode_gif(
 ) -> bytes:
     """Encode PNG frames into an animated GIF with a uniform per-frame delay.
 
-    **Streams** (SEC1 / BUG-74): each PNG is decoded, quantized to a 256-colour
+    **Streams** (SEC1 / BUG-74): each PNG is decoded, quantized to a 256-color
     palette and written before the next is read, so memory holds one decoded frame
     and one palette frame, not the whole clip. Pillow's ``save(save_all=True)``
     cannot do that — it keeps every normalized frame until the end to diff them —
@@ -556,8 +557,7 @@ def encode_mp4(pngs: list[bytes], frame_duration_ms: float) -> bytes:
         raise
     except Exception as exc:
         raise AnimationExportError(
-            f"MP4 encoding failed: {exc}. Try the GIF format, or check that "
-            "imageio-ffmpeg is installed."
+            f"The MP4 couldn't be made ({exc}). Try GIF, or the HTML replay."
         ) from exc
     finally:
         try:
@@ -580,12 +580,12 @@ def export_animation(
     """Render a scanpath-animation figure to GIF or MP4 bytes.
 
     Args:
-        fig: the figure from :func:`make_scanpath_animation` (must have ``.frames``).
+        fig: a replay from ``scanpath_studio.animate_scanpath`` (it must have frames).
         fmt: ``"gif"`` or ``"mp4"``.
         frame_duration_ms: uniform per-frame duration. By default the replay's
             own (:func:`plots.animation_clip_frame_ms`), so the clip lasts what
             the on-screen replay does — ``reading span / playback speed``.
-            Required for a figure :func:`make_scanpath_animation` didn't build.
+            Required for a figure ``animate_scanpath`` didn't build.
         scale: Kaleido render scale (1.0 = on-screen px; <1 is faster/smaller,
             >1 is crisper/larger).
         show_elapsed: draw the "Elapsed: X.Xs" readout in the top margin.
@@ -679,7 +679,7 @@ def export_animation(
         emit_status(
             status_callback,
             ExportStage.FINALIZING,
-            "Finalizing animation bytes…",
+            "Finishing the animation…",
             started_at=started,
         )
         result = bytes(result)

{scanpath_studio-0.34.0 → scanpath_studio-0.35.0}/scanpath_studio/annotations.py

@@ -172,7 +172,7 @@ def _check_record(index: int, record: object) -> None:
         not isinstance(tags, list)
         or any(isinstance(t, bool) or not isinstance(t, _ID_TYPES) for t in tags)
     ):
-        raise AnnotationsFileError(f"{where}: tags must be a list of words")
+        raise AnnotationsFileError(f"{where}: tags must be a list of text labels")
     note = record.get("note", "")
     if note is not None and not isinstance(note, str):
         raise AnnotationsFileError(f"{where}: note must be text")
@@ -851,10 +851,14 @@ def render_trial_annotations(
             "radio",
             "Annotation scope",
             options=["Parent trial", "This screen"],
+            # #374: the stored option keeps its name; "parent" is internal.
+            format_func=lambda option: (
+                "Whole trial" if option == "Parent trial" else option
+            ),
             key=scope_key,
             horizontal=True,
-            help="Parent annotations follow the logical trial; screen annotations "
-            "describe only the active coordinate space.",
+            help="Whole trial: every screen of this trial. This screen: only the "
+            "screen on view.",
         )
         if scope == "This screen":
             annotation_screen = str(screen_id)
@@ -897,7 +901,7 @@ def render_trial_annotations(
             f"{ICONS['favorite']} Favorite (star this trial)",
             display=f"{ICONS['favorite']} Favorite",
             key=star_key,
-            help="Mark this trial as a favorite.",
+            help="Star this trial (with scope *This screen*, this screen only).",
             on_change=_save_entry_callback,
             args=save_args,
         )
@@ -1137,11 +1141,18 @@ def _delete_dataset_annotations(records: list[dict]) -> None:
     _refresh_dataset_widgets(f"Deleted {_plural(removed, 'annotation')}.")
 
 
-def _annotations_frame(records: list[dict], trials: frozenset) -> pd.DataFrame:
+def _annotations_frame(
+    records: list[dict], trials: frozenset, trial_labels=None
+) -> pd.DataFrame:
+    """The Annotations table. ``trial_labels`` maps a trial id to the trial
+    picker's label for it (#374 F5: one trial label everywhere)."""
+    shown = trial_labels or {}
     frame = pd.DataFrame(
         {
             "Participant": [r["participant_id"] for r in records],
-            "Trial": [r["trial_id"] for r in records],
+            "Trial": [
+                shown.get(str(r["trial_id"]), str(r["trial_id"])) for r in records
+            ],
             "Screen": [r.get("screen_id", "") for r in records],
             "Favorite": [r["star"] for r in records],
             "Tags": [r["tags"] for r in records],
@@ -1159,7 +1170,9 @@ def _annotations_frame(records: list[dict], trials: frozenset) -> pd.DataFrame:
     return frame
 
 
-def render_dataset_annotations(trials, *, dataset_name: str, open_trials=None) -> None:
+def render_dataset_annotations(
+    trials, *, dataset_name: str, open_trials=None, trial_labels=None
+) -> None:
     """🗂️ Data → **Annotations**: every annotation the open dataset holds.
 
     One table — participant, trial, favorite, tags, note — with **Export** (this
@@ -1178,7 +1191,8 @@ def render_dataset_annotations(trials, *, dataset_name: str, open_trials=None) -
 
     ``open_trials`` — the trials the Scanpath picker can show, after the trial
     filters — gives each row an **Open** button (:func:`_open_annotation`);
-    without it the table has none.
+    without it the table has none. ``trial_labels`` writes each trial as
+    the trial picker does.
     """
     trials = _trial_set(trials)
     records = store_to_records(_store())
@@ -1232,12 +1246,11 @@ def render_dataset_annotations(trials, *, dataset_name: str, open_trials=None) -
         st.caption(
             f"{_plural(elsewhere, 'annotation')} here "
             f"{'is' if elsewhere == 1 else 'are'} on trials this dataset hasn't "
-            "loaded (*In dataset* unticked) — from an earlier load of it, or "
-            "saved before annotations were kept per dataset. They stay with this "
+            "loaded (*In dataset* unticked). They stay with this "
             "dataset; to move them to another, **Export** them here and "
             "**Import** them there."
         )
-    frame = _annotations_frame(records, trials)
+    frame = _annotations_frame(records, trials, trial_labels)
     column_config = {}
     if open_trials is not None:
         frame.insert(0, "Open", _OPEN_LABEL)
@@ -1246,7 +1259,7 @@ def render_dataset_annotations(trials, *, dataset_name: str, open_trials=None) -
             "",
             type="tertiary",
             width="small",
-            help="Show this reading — and its screen, for a screen annotation — "
+            help="Show this trial — and its screen, for a screen annotation — "
             "in the Scanpath view.",
             on_click=_open_annotation,
             args=(open_key, records, trials, _trial_set(open_trials)),