scanpath-studio 0.31.2__tar.gz → 0.32.0__tar.gz

{scanpath_studio-0.31.2 → scanpath_studio-0.32.0}/MANIFEST.in

@@ -5,5 +5,5 @@ recursive-include scanpath_studio/sample_data *.csv
 recursive-include scanpath_studio/sample_data *.parquet
 recursive-include scanpath_studio/sample_data *.png
 # ENG-61: the suite needs the whole repository (streamlit_app.py, docs/,
-# CITATION.cff, tracker/), so a partial copy in the sdist could never run.
+# CITATION.cff), so a partial copy in the sdist could never run.
 prune tests

{scanpath_studio-0.31.2/scanpath_studio.egg-info → scanpath_studio-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanpath-studio
-Version: 0.31.2
+Version: 0.32.0
 Summary: Interactive Streamlit workbench for visualizing eye-tracking-while-reading scanpaths, computing reading measures, and exporting figures and tabular data.
 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>
@@ -83,7 +83,7 @@ paper.
   ```
 
 - **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.tar.gz) ·
+  [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).
 
 The pip and desktop installs keep your data on your own machine; the hosted demo
@@ -180,6 +180,9 @@ covers setup, the checks that gate CI, and how work is tracked in
 the architectural map. To preview the docs site locally, run
 `pip install -e ".[docs]"` and then `mkdocs serve`.
 
+Taking part means following the
+[Code of Conduct](https://github.com/lacclab/scanpath-studio/blob/main/CODE_OF_CONDUCT.md).
+
 ## Citation
 
 A paper is in preparation. Until then, cite the software by its DOI,

{scanpath_studio-0.31.2 → scanpath_studio-0.32.0}/README.md

@@ -29,7 +29,7 @@ paper.
   ```
 
 - **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.tar.gz) ·
+  [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).
 
 The pip and desktop installs keep your data on your own machine; the hosted demo
@@ -126,6 +126,9 @@ covers setup, the checks that gate CI, and how work is tracked in
 the architectural map. To preview the docs site locally, run
 `pip install -e ".[docs]"` and then `mkdocs serve`.
 
+Taking part means following the
+[Code of Conduct](https://github.com/lacclab/scanpath-studio/blob/main/CODE_OF_CONDUCT.md).
+
 ## Citation
 
 A paper is in preparation. Until then, cite the software by its DOI,

{scanpath_studio-0.31.2 → scanpath_studio-0.32.0}/pyproject.toml

@@ -177,7 +177,7 @@ ignore = [
     # each already carrying a comment saying why the failure is ignorable.
     "S110", "S112",
     # Naive local timestamps are correct here: these stamp a local recovery
-    # cache and a local tracker, both single-machine by design. Making them
+    # cache, single-machine by design. Making them
     # tz-aware would imply a portability this data does not have.
     "DTZ005", "DTZ006",
     # Fires on scripts with a shebang that are run via `python <script>`; the

{scanpath_studio-0.31.2 → scanpath_studio-0.32.0}/scanpath_studio/__init__.py

@@ -40,7 +40,7 @@ __all__ = [
     "save_figure_layers",
     "trial_summary",
 ]
-__version__ = "0.31.2"
+__version__ = "0.32.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/

{scanpath_studio-0.31.2 → scanpath_studio-0.32.0}/scanpath_studio/annotations.py

@@ -2,9 +2,9 @@
 
 Annotations are keyed by ``(participant_id, trial_id)`` and live in Streamlit
 session state, so they persist across reruns within a session. There is no
-backend; to keep annotations across sessions or share them, the 💾 Session
-dialog offers a JSON **download** (a portable sidecar) and **restore**
-(re-upload).
+backend; a local run keeps them in the recovery cache, and to share them 🗂️
+Data → **Annotations** exports and imports a dataset's as JSON (UX-174). The
+Scanpath view's Export bundle can include the same file (UX-179).
 
 The module is split into a *pure* core (``records_to_store`` /
 ``store_to_records`` / ``serialize`` / ``deserialize`` — no Streamlit, unit
@@ -15,17 +15,19 @@ tested) and a thin session-backed layer plus the small render helpers used by
 from __future__ import annotations
 
 import json
+from collections.abc import Iterable
 
+import pandas as pd
 import streamlit as st
 
-from .constants import ICONS
+from .constants import ICONS, upload_limit_mb
 from .fields import PANEL_LABEL_W, panel_field, row_label
 
 ANNOTATIONS_STATE_KEY = "trial_annotations"
 SCHEMA_VERSION = 2
 
 # Per-trial annotation widgets use this prefix so they can be cleared on import
-# (forcing a re-seed from the freshly loaded store), e.g. by `restore_records`.
+# (forcing a re-seed from the freshly loaded store), e.g. by `forget_records`.
 _WIDGET_PREFIX = "annotrial_"
 
 # Always-available tag suggestions (users can add their own on top).
@@ -120,6 +122,59 @@ def deserialize(text: str) -> dict[Key, Entry]:
     return records_to_store(records)
 
 
+def _trial_of(key: Key) -> tuple[str, str]:
+    return (key[0], key[1])
+
+
+def _trial_set(trials: Iterable[tuple[object, object]]) -> frozenset[tuple[str, str]]:
+    if isinstance(trials, frozenset):
+        return trials  # already built by the caller, as strings
+    return frozenset((str(pid), str(tid)) for pid, tid in trials)
+
+
+def records_in(store: dict[Key, Entry], trials) -> list[dict]:
+    """The records of ``store`` on the trials in ``trials``, sorted.
+
+    ``trials`` is ``(participant_id, trial_id)`` pairs — one dataset's trials.
+    The store is one per session and keyed by those two ids alone, so this is
+    what *a dataset's annotations* means: the ones on trials it has. A screen
+    annotation belongs to its parent trial.
+    """
+    keep = _trial_set(trials)
+    return store_to_records(
+        {key: entry for key, entry in store.items() if _trial_of(key) in keep}
+    )
+
+
+def merge_records(
+    store: dict[Key, Entry], records: list[dict], trials
+) -> tuple[int, int]:
+    """Add ``records`` on the trials in ``trials`` to ``store``, in place.
+
+    An imported entry replaces the one already on its key — the file is the
+    newer statement about that trial — and a record for a trial the dataset
+    does not have is skipped, as a backup restore skips what does not match
+    (UX-174 r2). Returns ``(applied, skipped)``.
+    """
+    keep = _trial_set(trials)
+    incoming = records_to_store(records)
+    applied = {key: entry for key, entry in incoming.items() if _trial_of(key) in keep}
+    store.update(applied)
+    return len(applied), len(incoming) - len(applied)
+
+
+def drop_records(store: dict[Key, Entry], records: list[dict]) -> int:
+    """Remove the entries ``records`` name from ``store``. Returns how many."""
+    removed = 0
+    for record in records:
+        pid, tid = str(record["participant_id"]), str(record["trial_id"])
+        screen_id = record.get("screen_id")
+        key = (pid, tid, str(screen_id)) if screen_id not in (None, "") else (pid, tid)
+        if store.pop(key, None) is not None:
+            removed += 1
+    return removed
+
+
 # ---------------------------------------------------------------------------
 # Session-backed layer
 # ---------------------------------------------------------------------------
@@ -172,21 +227,29 @@ def known_tags() -> list[str]:
 
 
 def current_records() -> list[dict]:
-    """All annotations as a flat record list — for embedding in a saved config."""
+    """All annotations as a flat record list — for the Export bundle (UX-179)."""
     return store_to_records(_store())
 
 
-def restore_records(records: list[dict]) -> int:
-    """Replace the session annotation store from a record list (e.g. a restored
-    config) and clear the per-trial widget state so editors re-seed. Returns the
-    number of annotations loaded."""
-    store = records_to_store(records or [])
-    st.session_state[ANNOTATIONS_STATE_KEY] = store
+def forget_records(records: list[dict]) -> int:
+    """Drop ``records`` from the session store; the trial editors re-seed.
+
+    Returns how many entries were removed.
+    """
+    removed = drop_records(_store(), records)
+    if removed:
+        _reseed_trial_editors()
+    return removed
+
+
+def _reseed_trial_editors() -> None:
+    """Drop the per-trial editors' widget state, so they re-seed from the store."""
     for key in [
-        k for k in list(st.session_state.keys()) if k.startswith(_WIDGET_PREFIX)
+        k
+        for k in list(st.session_state.keys())
+        if isinstance(k, str) and k.startswith(_WIDGET_PREFIX)
     ]:
         del st.session_state[key]
-    return len(store)
 
 
 # ---------------------------------------------------------------------------
@@ -345,14 +408,11 @@ def render_trial_annotations(
             note=note,
             screen_id=annotation_screen,
         )
-        # UX-76: no 💾 Open Session button under this. It was a shortcut to a nav
-        # entry that is one click away in the header (#UX-63), and it sat at the
-        # foot of a panel about *this trial* pointing at a session-wide one. The
-        # caption names where the annotations go instead — and no longer says
-        # "the sidebar", which has not existed since #UX-38.
+        # UX-76: no shortcut button under this — the caption names where the
+        # whole dataset's annotations are listed instead.
         st.caption(
-            "Annotations can be downloaded or restored from **💾 Session** in "
-            "the top menu."
+            "Every annotation on this dataset is listed on 🗂️ **Data → "
+            "Annotations**, to export, import or delete."
         )
 
 
@@ -402,3 +462,172 @@ def filter_keys(
         required_tags=required_tags,
         excluded_tags=excluded_tags,
     )
+
+
+# ---------------------------------------------------------------------------
+# 🗂️ Data → Annotations (UX-174 r2)
+# ---------------------------------------------------------------------------
+
+#: The dataset tab's widget keys. The nonce is bumped after an import or a
+#: delete, which gives the uploader and the table fresh keys: an uploader keeps
+#: its file (and would import it again on every rerun), and a table's row
+#: selection is by position, so it would point at other rows once some are gone.
+_DATASET_NONCE_KEY = "_dataset_annotations_nonce"
+_DATASET_NOTE_KEY = "_dataset_annotations_note"
+
+
+def _dataset_widget_key(name: str) -> str:
+    return f"dataset_annotations_{name}_{st.session_state.get(_DATASET_NONCE_KEY, 0)}"
+
+
+def _refresh_dataset_widgets(note: str) -> None:
+    st.session_state[_DATASET_NONCE_KEY] = (
+        int(st.session_state.get(_DATASET_NONCE_KEY, 0)) + 1
+    )
+    st.session_state[_DATASET_NOTE_KEY] = note
+    _reseed_trial_editors()
+
+
+def _plural(count: int, noun: str) -> str:
+    return f"{count:,} {noun}{'' if count == 1 else 's'}"
+
+
+def _import_dataset_annotations(uploader_key: str, trials: frozenset) -> None:
+    upload = st.session_state.get(uploader_key)
+    if upload is None:
+        return
+    try:
+        records = store_to_records(deserialize(upload.getvalue().decode("utf-8")))
+    except (UnicodeDecodeError, ValueError):
+        st.session_state[_DATASET_NOTE_KEY] = (
+            "error:That file is not an annotations JSON file."
+        )
+        st.session_state[_DATASET_NONCE_KEY] = (
+            int(st.session_state.get(_DATASET_NONCE_KEY, 0)) + 1
+        )
+        return
+    applied, skipped = merge_records(_store(), records, trials)
+    note = f"Imported {_plural(applied, 'annotation')}."
+    if skipped:
+        note += (
+            f" Skipped {_plural(skipped, 'annotation')} on trials this dataset "
+            "doesn't have."
+        )
+    _refresh_dataset_widgets(note)
+
+
+def _delete_dataset_annotations(records: list[dict]) -> None:
+    removed = drop_records(_store(), records)
+    _refresh_dataset_widgets(f"Deleted {_plural(removed, 'annotation')}.")
+
+
+def _annotations_frame(records: list[dict]) -> pd.DataFrame:
+    frame = pd.DataFrame(
+        {
+            "Participant": [r["participant_id"] for r in records],
+            "Trial": [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],
+            "Note": [r["note"] for r in records],
+        }
+    )
+    if not frame["Screen"].astype(bool).any():
+        frame = frame.drop(columns="Screen")
+    return frame
+
+
+def render_dataset_annotations(trials, *, dataset_name: str) -> None:
+    """🗂️ Data → **Annotations**: every annotation on the open dataset's trials.
+
+    One table — participant, trial, favorite, tags, note — with **Export** (this
+    dataset's annotations as JSON), **Import** (the same file, or the
+    ``annotations.json`` of an Export bundle: entries on trials the dataset has
+    are added, the rest are skipped)
+    and **Delete**, for the rows ticked in the table. Annotations are still made
+    per trial, on 🗺️ Scanpath → Annotations; this is where they are seen whole.
+    """
+    trials = _trial_set(trials)
+    records = records_in(_store(), trials)
+    note = st.session_state.pop(_DATASET_NOTE_KEY, None)
+    if note and note.startswith("error:"):
+        st.error(note.removeprefix("error:"), icon=ICONS["error"])
+    elif note:
+        st.success(note, icon=ICONS["confirm"])
+
+    toolbar = st.container(
+        key="dataset_annotations_toolbar",
+        horizontal=True,
+        vertical_alignment="center",
+        gap="small",
+    )
+    toolbar.download_button(
+        "Export",
+        icon=ICONS["download"],
+        data=serialize(records_to_store(records)),
+        file_name=f"{_file_slug(dataset_name)}_annotations.json",
+        mime="application/json",
+        key="dataset_annotations_export",
+        disabled=not records,
+        help="Download this dataset's annotations as a JSON file.",
+    )
+    with toolbar.popover("Import", icon=ICONS["upload"]):
+        uploader_key = _dataset_widget_key("import")
+        st.file_uploader(
+            "Annotations file (JSON)",
+            type=["json"],
+            key=uploader_key,
+            on_change=_import_dataset_annotations,
+            args=(uploader_key, trials),
+            max_upload_size=upload_limit_mb(),
+        )
+        st.caption(
+            "A file exported here or in an Export bundle. Annotations on trials "
+            "this dataset doesn't have are skipped, and an imported one replaces "
+            "what its trial already had."
+        )
+    delete_slot = toolbar.container(width="content")
+
+    if not records:
+        st.caption(
+            "No annotations on this dataset yet. Star, tag or note a trial on "
+            "🗺️ **Scanpath → Annotations**."
+        )
+        return
+    event = st.dataframe(
+        _annotations_frame(records),
+        hide_index=True,
+        width="stretch",
+        on_select="rerun",
+        selection_mode="multi-row",
+        key=_dataset_widget_key("table"),
+        column_config={
+            "Favorite": st.column_config.CheckboxColumn("Favorite", width="small"),
+            "Tags": st.column_config.ListColumn("Tags"),
+            "Note": st.column_config.TextColumn("Note", width="large"),
+        },
+    )
+    picked = [records[i] for i in event.selection.rows if i < len(records)]
+    with delete_slot.popover(
+        f"Delete ({len(picked)})" if picked else "Delete",
+        icon=ICONS["delete"],
+        disabled=not picked,
+        help="Tick rows in the table to delete them.",
+    ):
+        st.write(
+            f"Delete {_plural(len(picked), 'annotation')}? This cannot be undone "
+            "— **Export** first to keep a copy."
+        )
+        st.button(
+            "Delete",
+            icon=ICONS["delete"],
+            key="dataset_annotations_delete",
+            type="primary",
+            on_click=_delete_dataset_annotations,
+            args=(picked,),
+        )
+
+
+def _file_slug(name: str) -> str:
+    slug = "".join(ch if ch.isalnum() else "_" for ch in str(name)).strip("_")
+    return slug.lower() or "dataset"

{scanpath_studio-0.31.2 → scanpath_studio-0.32.0}/scanpath_studio/api.py

@@ -477,7 +477,9 @@ def _schema_error(
     if not explicit:
         lines.append(
             "Matching ignores case and separators (IA_LEFT == ia_left == 'Ia Left') "
-            "and takes the first candidate that matches."
+            "and takes the first candidate that matches; failing that, a vendor "
+            "prefix or suffix on a known name (AOI_LEFT, LEFT_px) is tried next, "
+            "accepted only when exactly one column qualifies."
         )
     hint = (
         f"An explicit {param} replaces auto-detection wholesale, so it needs every "
@@ -1662,6 +1664,7 @@ def animate_scanpath(
     playback_speed: float = 1.0,
     autoplay: bool = True,
     fix_index_range: tuple[int, int] | None = None,
+    fix_index_range_b: tuple[int, int] | None = None,
     illustration_label: str = "auto",
     title: str = "",
     caption: str = "",
@@ -1695,6 +1698,11 @@ def animate_scanpath(
     the replay timing was changed. ``illustration_label`` accepts ``"auto"``,
     ``"show"``, or ``"hide"`` like [`plot_scanpath`][scanpath_studio.api.plot_scanpath].
 
+    CMP-24: in a co-animation ``fix_index_range`` windows A only (the app's
+    rule — A's slider never cuts B), ``fix_index_range_b`` windows B, and
+    ``fixation_flags_b`` gives B flags of its own (``None``: A's
+    ``fixation_flags``).
+
     ``trial_b=(participant, trial)`` co-animates a second reading on the same
     clock, like the app's Animate + Compare. It is looked up in ``words_b`` /
     ``fixations_b`` when given, else in ``words`` / ``fixations`` — the way
@@ -1790,6 +1798,20 @@ def animate_scanpath(
             fixations_b,
             a_inferred=setup is None and canvas_size is None,
         )
+    full_fix_range_b = None
+    if (
+        fixations_b is not None
+        and not fixations_b.empty
+        and "order_in_trial" in fixations_b.columns
+    ):
+        order_b = pd.to_numeric(fixations_b["order_in_trial"], errors="coerce").dropna()
+        if not order_b.empty:
+            full_fix_range_b = (int(order_b.min()), int(order_b.max()))
+    if fix_index_range_b is not None and fixations_b is not None:
+        pid_b, tid_b = (str(v) for v in (trial_b or ("B", "B")))
+        fixations_b = _apply_fix_index_range(
+            fixations_b, fix_index_range_b, pid_b, tid_b
+        )
     if dataset_b is not None:
         # As `compare_scanpaths` and the app do: B's readers carry their
         # dataset's name, so a hover says whose reader it is.
@@ -1809,6 +1831,12 @@ def animate_scanpath(
             {**animation_overrides, "playback_speed": playback_speed},
             fix_index_range=fix_index_range,
             full_fixation_range=full_fix_range,
+            # CMP-24: B's own flags and window, when it co-animates.
+            fixation_flags_b=animation_overrides.get("fixation_flags_b")
+            if fixations_b is not None
+            else None,
+            fix_index_range_b=fix_index_range_b,
+            full_fixation_range_b=full_fix_range_b,
         )
         animation_overrides["illustration_reasons"] = resolve_label_reasons(
             label_mode, reasons
@@ -2096,6 +2124,7 @@ def compare_scanpaths(
     base_font_size: int = 16,
     font_family: str = FONT_FAMILY,
     fix_index_range: tuple[int, int] | None = None,
+    fix_index_range_b: tuple[int, int] | None = None,
     drift_correction: str | None = None,
     title: str = "",
     caption: str = "",
@@ -2129,6 +2158,16 @@ def compare_scanpaths(
     when the text is identical. Split layouts ignore it; each panel owns its own
     stimulus.
 
+    **Filters, per scanpath (CMP-24).** ``fixation_flags`` and
+    ``saccade_classes`` filter both scanpaths, as they filter
+    [`plot_scanpath`][scanpath_studio.api.plot_scanpath]'s one; the same two keys
+    in ``style_a`` / ``style_b`` give that scanpath its own, overriding them —
+    e.g. ``style_b={"fixation_flags": {"short": {"mode": "Discard",
+    "threshold_ms": 80}}, "saccade_classes": ["regression"]}``. The app's
+    Compare mode draws A under the rail's filters and B under B's own.
+    ``fix_index_range`` windows both scanpaths; ``fix_index_range_b`` gives B a
+    window of its own (the app's B slider).
+
     Remaining keywords are forwarded to `plots.make_comparison_figure`
     (e.g. ``show_words=False``, ``color_by="duration_ms"``); an unknown one
     raises ``TypeError`` naming the closest valid options;
@@ -2217,7 +2256,12 @@ def compare_scanpaths(
             else pid_b
         )
     trial_fix_a = _apply_fix_index_range(trial_fix_a, fix_index_range, pid_a, tid_a)
-    trial_fix_b = _apply_fix_index_range(trial_fix_b, fix_index_range, pid_b, tid_b)
+    trial_fix_b = _apply_fix_index_range(
+        trial_fix_b,
+        fix_index_range if fix_index_range_b is None else fix_index_range_b,
+        pid_b,
+        tid_b,
+    )
     if drift_correction:
         # PRE-21: same contract as plot_scanpath — raise, don't silently skip.
         if not drift_correction_enabled():
@@ -2522,7 +2566,8 @@ def cache_status() -> dict:
     ``settings``, ``bytes``, ``saved_at``, plus ``exists`` / ``readable`` for a
     missing or unreadable manifest. Delete it with
     [`clear_cache`][scanpath_studio.api.clear_cache]; the same information is in the
-    app's 💾 Session → 🗄️ Automatic recovery panel and in ``scanpath-studio cache``."""
+    app's 🗂️ Data → *Saved on this computer* section and in
+    ``scanpath-studio cache``."""
     from .persistence import cache_status as _cache_status
 
     return _cache_status(url="http://localhost")
@@ -2533,10 +2578,9 @@ def clear_cache() -> dict:
 
     Removes only the files this app wrote (``manifest.json`` and the dataset
     Parquet files); anything else in the folder is left alone. A *running* local
-    app writes its session back out at the end of its next run — turn off **Save
-    changes automatically** in its 💾 Session → 🗄️ Automatic recovery panel (the
-    panel's **Clear recovery cache** button, like this function, leaves saving on),
-    or set ``SCANPATH_STUDIO_PERSIST=0``, to stop that."""
+    app writes its session back out at the end of its next change — start it
+    with ``scanpath-studio run --no-persist`` or ``SCANPATH_STUDIO_PERSIST=0`` to
+    stop that."""
     from .persistence import clear_local_state
 
     clear_local_state()