scanpath-studio 0.43.0__tar.gz → 0.44.0__tar.gz

{scanpath_studio-0.43.0/scanpath_studio.egg-info → scanpath_studio-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanpath-studio
-Version: 0.43.0
+Version: 0.44.0
 Summary: Interactive visualization of eye-tracking data from reading studies: draw, replay and compare scanpaths, fixations, saccades and gaze heatmaps 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>

{scanpath_studio-0.43.0 → scanpath_studio-0.44.0}/scanpath_studio/__init__.py

@@ -42,7 +42,7 @@ __all__ = [
 # against. `__version__` is the exact build, worked out from it lazily
 # (build_info.py) — "0.35.0" at the release itself,
 # "0.35.0.post3+g8f18219" three commits after it.
-__release__ = "0.43.0"
+__release__ = "0.44.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.43.0 → scanpath_studio-0.44.0}/scanpath_studio/api.py

@@ -840,6 +840,13 @@ def load_scanpath_data(
       Trials that match none raise a ``data.StimulusJoinWarning`` (a ``UserWarning``).
     - **Fixations without x/y** but with a word ID are placed at the centers of their
       word boxes.
+    - **Text word IDs.** A word ID column that holds text and no numbers (``w1``,
+      ``Hello_3``) is read as keys, kept in a ``word_key`` column (under the column's
+      own name with ``names="source"``). Each word's ``word_id`` is then its position
+      in its text, 1, 2, … in the Words table's row order (the order of the reading
+      that lists the most of the text), one number for every reader, and a
+      fixation's is the number of the word with the same text ID in its trial —
+      exactly the same text, else none. A text ID never matches a number.
     - **Bookkeeping columns.** Columns named in ``data.INTERNAL_COLUMNS`` are the
       pipeline's own; ``data.drop_internal_columns`` removes them.
 
@@ -887,8 +894,9 @@ def load_scanpath_data(
         data.StimulusJoinError: A stimulus-level Words table shares neither a trial ID
             nor a ``text_id`` with any trial (or, multipart, with every screen a trial
             has fixations on). A ``ValueError``.
-        data.UnplacedFixationsError: The fixations map no x/y and their word ID column
-            holds no numbers, so none could be placed. A ``ValueError``.
+        data.UnplacedFixationsError: The fixations have no x/y, and not one of their
+            word IDs names a word: text IDs the Words table does not have, or numbers
+            against a Words table of text IDs. A ``ValueError``.
     """
     _check_names_choice(names)
     if words is None and fixations is None:

{scanpath_studio-0.43.0 → scanpath_studio-0.44.0}/scanpath_studio/app.py

@@ -158,6 +158,7 @@ from scanpath_studio.controls import (
     background_swatch,
     clear_trial_filter,
     clear_trial_filters,
+    column_mapping_from_state,
     column_mapping_ui,
     has_active_trial_filters,
     read_trial_filters,
@@ -304,7 +305,7 @@ from scanpath_studio.session_keys import (
     PARAM_CORPUS,
     PARAM_DATASET,
 )
-from scanpath_studio.styles import get_app_css, widen_menu
+from scanpath_studio.styles import compact_css, get_app_css, widen_menu
 from scanpath_studio.tabs import (
     _EDITOR_KEY_NOISE,
     _REMAP_DIRTY_KEY,
@@ -730,7 +731,7 @@ def configure_page() -> None:
         page_icon="👀",
         layout="wide",
     )
-    st.markdown(get_app_css(), unsafe_allow_html=True)
+    st.html(_app_stylesheet())
     # Seeded here, not later in the run: the stylesheet below hides one mode's
     # containers, so it needs the mode on the very first run.
     ui_mode.seed_mode(st.session_state, st.query_params, _cookies())
@@ -752,6 +753,19 @@ LOGO_PATH = Path(__file__).parent / "assets" / "scanpath_studio_title_logo.png"
 LOGO_DARK_PATH = LOGO_PATH.with_name("scanpath_studio_title_logo_dark.png")
 
 
+@functools.cache
+def _app_stylesheet() -> str:
+    """The app stylesheet as sent: compacted, for a style-only `st.html`.
+
+    Not a markdown block: Streamlit applies a markdown block's raw HTML only
+    once its own HTML renderer has loaded and parsed the whole block, which on
+    a slow connection left the first screen unstyled for seconds. Built once
+    per process — the sheet depends on nothing but module constants, and
+    compacting it costs ~10 ms, on every rerun otherwise.
+    """
+    return compact_css(get_app_css())
+
+
 @functools.cache
 def _logo_theme_css() -> str:
     """CSS that swaps the header wordmark for its dark variant in dark mode.
@@ -3775,7 +3789,8 @@ def reset_column_mapping() -> None:
 #: ✕ Cancel puts the keys back.
 BUILTIN_MAPPING_HELD_KEY = "_builtin_mapping_held"
 #: The panels' current picks, ``{"words": schema, "fixations": schema}``,
-#: written by `prepare_data` on every run that draws them.
+#: written by `prepare_data` on every run of a source that has them, drawn or
+#: read from their keys.
 BUILTIN_MAPPING_PENDING_KEY = "_builtin_mapping_pending"
 #: Set by ✅ Save changes for the success line on the screen it returns to.
 BUILTIN_MAPPING_SAVED_KEY = "_builtin_mapping_saved"
@@ -4040,12 +4055,18 @@ def prepare_data(
     declared_fix_schema: dict | None = None,
     mapping_dataset: object = None,
     held_schemas: dict | None = None,
+    render_mapping: bool = True,
 ) -> tuple[pd.DataFrame, pd.DataFrame, list]:
     """Infer schemas and normalize incoming dataframes to canonical column names.
 
-    When ``allow_override`` is True, render the mapping panels that let the
-    user pick the exact column names for each field (pre-filled with auto-detection).
-    Otherwise just auto-detect.
+    When ``allow_override`` is True, the user's picks in the mapping panels
+    (pre-filled with auto-detection) decide each field. Otherwise just
+    auto-detect.
+
+    ``render_mapping`` says whether those panels are drawn this run. They are
+    only on screen while ✏️ Edit dataset is open, so every other run reads the
+    same picks from session state (`controls.column_mapping_from_state`)
+    instead of building sixty-odd hidden selectboxes.
 
     Returns ``(words_norm, fixations_norm, problems)``. ``problems`` is a list
     of human-readable strings; when it's non-empty the column mapping isn't
@@ -4066,8 +4087,9 @@ def prepare_data(
     happen to match (``controls.forget_mapping_for_other_table``).
 
     ``held_schemas`` (``{"words": …, "fixations": …}``) is the mapping the
-    dataset keeps while ✏️ Edit dataset is open: the panels still render and
-    their picks are published as the draft (``BUILTIN_MAPPING_PENDING_KEY``),
+    dataset keeps while ✏️ Edit dataset is open: the panels' picks (drawn, or
+    read from their keys on another view) are published as the draft
+    (``BUILTIN_MAPPING_PENDING_KEY``),
     but the frames are normalized under the held mapping until ✅ Save changes.
     """
     has_words = not words_df.empty
@@ -4081,7 +4103,15 @@ def prepare_data(
         word_proposed = _apply_declared_schema(
             _proposed_schema("words", words_df), declared_word_schema
         )
-        if allow_override:
+        if allow_override and not render_mapping:
+            word_schema = column_mapping_from_state(
+                words_df,
+                "col_map_words",
+                WORD_FIELD_SPECS,
+                word_proposed,
+                dataset=mapping_dataset,
+            )
+        elif allow_override:
             word_schema = column_mapping_ui(
                 words_df,
                 table_label="Words (interest areas)",
@@ -4099,6 +4129,7 @@ def prepare_data(
                 stack_labels=True,
                 dataset=mapping_dataset,
             )
+        if allow_override:
             pending["words"] = word_schema
             if held_schemas and held_schemas.get("words") is not None:
                 word_schema = held_schemas["words"]
@@ -4112,7 +4143,15 @@ def prepare_data(
         fix_proposed = _apply_declared_schema(
             _proposed_schema("fixations", fixations_df), declared_fix_schema
         )
-        if allow_override:
+        if allow_override and not render_mapping:
+            fix_schema = column_mapping_from_state(
+                fixations_df,
+                "col_map_fix",
+                FIX_FIELD_SPECS,
+                fix_proposed,
+                dataset=mapping_dataset,
+            )
+        elif allow_override:
             fix_schema = column_mapping_ui(
                 fixations_df,
                 table_label="Fixations",
@@ -4126,6 +4165,7 @@ def prepare_data(
                 stack_labels=True,
                 dataset=mapping_dataset,
             )
+        if allow_override:
             pending["fixations"] = fix_schema
             if held_schemas and held_schemas.get("fixations") is not None:
                 fix_schema = held_schemas["fixations"]
@@ -9553,11 +9593,14 @@ def _run_app() -> None:
     # The page is built on EVERY run and merely hidden when another view is
     # active (`DATA_PAGE_OFFSCREEN_KEY` → `display: none` in styles.py). That is
     # not laziness: the slots below are filled by the loaders' directory input,
-    # ⬇ Download button, source options and column-mapping selectboxes, all of
-    # which *drive* `prepare_data` on every rerun — and Streamlit drops the key
-    # of a widget that did not render. Rendering-then-hiding keeps every
-    # loader's every-run semantics without splitting each into a render/resolve
-    # pair.
+    # ⬇ Download button and source options, all of which *drive* the load on
+    # every rerun — and Streamlit drops the key of a widget that did not
+    # render. Rendering-then-hiding keeps every loader's every-run semantics
+    # without splitting each into a render/resolve pair. The one exception is
+    # the built-in sources' column-mapping panels, sixty-odd selectboxes and a
+    # sixth of every rerun's bytes: they are split that way
+    # (`controls.column_mapping_from_state`) and drawn only while ✏️ Edit
+    # dataset shows them.
     #
     # The page has two *parts*, both built every run for the same reason the
     # page itself is (above): the overview always shows, and the editor opens
@@ -9949,8 +9992,9 @@ def _run_app() -> None:
     else:
         deep_link_pid = None
     raw_gaze_df: pd.DataFrame | None = None
-    # Did this load already draw the editable pre-normalization mapping panels
-    # into the page's Column mapping section? (Mode A — see the dispatch below.)
+    # Is the open source one whose mapping the editable pre-normalization
+    # panels decide, in the page's Column mapping section? (Mode A — see the
+    # dispatch below. They are drawn only while ✏️ Edit dataset is open.)
     mapping_editor_rendered = False
     # Start each load with a clean column-mapping stash; each branch below
     # records the schema it used for the Data page's mapping section.
@@ -10107,8 +10151,11 @@ def _run_app() -> None:
             # default first-load source; pre-filled with auto-detection, so an
             # untouched mapping normalizes identically.
             allow_override=mapping_editor_rendered,
-            # Mode A of the Data page's one Column mapping section.
+            # Mode A of the Data page's one Column mapping section, drawn only
+            # while ✏️ Edit dataset shows it; every other run reads the same
+            # picks from their keys.
             mapping_host=mapping_body_slot,
+            render_mapping=data_view and editing,
             # A corpus that publishes its schema starts from it, not from
             # auto-detection. The panels stay editable — this only changes what
             # they start at.
@@ -10154,6 +10201,11 @@ def _run_app() -> None:
                 _render_dataset_load_failure(
                     _dataset_display_name(_dataset_owner), mapping_problems
                 )
+        # The mapping panels on ✏️ Edit dataset are a draft until ✅ Save
+        # changes, and the dataset keeps the mapping that cannot load — so the
+        # editor needs its Save here too, or a field fixed there never applies.
+        if data_view and editing and mapping_editor_rendered:
+            _render_builtin_editor_footer(editor_footer_slot)
         _render_offpage_setup_notice(data_view)
         _finish_page()
         _render_datasets_table(None, None, None)

{scanpath_studio-0.43.0 → scanpath_studio-0.44.0}/scanpath_studio/column_names.py

@@ -19,7 +19,7 @@ import json
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
 
-from .constants import SAMPLE_INDEX
+from .constants import SAMPLE_INDEX, WORD_KEY
 
 #: How a canonical column came to be.
 MAPPED = "mapped"  # read from one source column, unchanged
@@ -104,6 +104,7 @@ _CANONICAL_LABELS: dict[str, str] = {
     "line_idx": "Line",
     "text": "Word",
     "word_id": "Word #",
+    WORD_KEY: "Word ID",
     "x": "X",
     "y": "Y",
     "saccade_amplitude": "Saccade amplitude (px)",
@@ -147,6 +148,7 @@ ROLE_LABELS: dict[str, str] = {
     "unique_text_id": "Text",
     "screen_id": "Screen",
     "word_id": "Word #",
+    WORD_KEY: "Word ID",
     "text": "Word",
     "line_idx": "Line",
     "x": "X",
@@ -205,10 +207,23 @@ IDENTITY_COLUMNS = frozenset(
         "unique_text_id",
         "screen_id",
         "word_id",
+        WORD_KEY,
     }
 )
 
 
+def _text_word_id_entries(entry: SourceName | None, how: str) -> dict:
+    """The entries for a Word ID read as text (:meth:`ColumnNames.with_rewrites`),
+    from the ``word_id`` entry the schema implied; none unless that names the
+    file's column."""
+    if entry is None or entry.kind != MAPPED or len(entry.sources) != 1:
+        return {}
+    return {
+        WORD_KEY: SourceName(entry.sources, MAPPED),
+        "word_id": SourceName((), GENERATED, entry.display + how),
+    }
+
+
 def canonical_label(column) -> str:
     """A readable label for a column the app made (a measure, a run, an angle …)."""
     from .data import READING_MEASURE_FIELDS
@@ -446,9 +461,17 @@ class ColumnNames:
         ``table``) marked converted: a padded id, a shifted word id, positions
         filled from word boxes are no longer what the file held under its name,
         so the column is labelled "<source><how>" and exported under its
-        internal name."""
+        internal name.
+
+        A rewrite of :data:`~scanpath_studio.constants.WORD_KEY` is a Word ID
+        read as text: the text is the file's column, so ``word_key`` takes
+        the Word ID's source name, and ``word_id`` — the number the app gave
+        each text id — becomes generated, "<source><how>" its note."""
         changed = dict(self.entries)
         for rewritten_table, column, how in rewrites or ():
+            if rewritten_table == table and column == WORD_KEY:
+                changed.update(_text_word_id_entries(changed.get("word_id"), how))
+                continue
             entry = changed.get(column)
             if rewritten_table != table or entry is None or entry.kind != MAPPED:
                 continue

{scanpath_studio-0.43.0 → scanpath_studio-0.44.0}/scanpath_studio/computations.py

@@ -267,15 +267,50 @@ REGISTER: tuple[Computation, ...] = (
         unit="px",
         precedence="Only when x/y are absent; recorded coordinates always win.",
         missing=(
-            "No matching word box, or no word id (blank, or not a number) ⇒ the "
-            "fixation keeps no coordinates — a missing id never matches a box "
-            "with none. No x/y mapped and a Word ID column with no numbers "
-            "at all ⇒ UnplacedFixationsError, never an empty figure."
+            "No matching word box, or no word id (blank, or a text id that names "
+            "no word) ⇒ the fixation keeps no coordinates — a missing id never "
+            "matches a box with none. No x/y, text Word IDs involved "
+            "(`norm.text_word_ids`) and not one fixation placed ⇒ "
+            "UnplacedFixationsError, never an empty figure."
         ),
         tiers="A, C",
         status=STATUS_VERIFIED,
         consumers=(_UI, _API, _CLI),
-        tests=("tests/test_data.py",),
+        tests=("tests/test_data.py", "tests/test_text_word_ids.py"),
+    ),
+    Computation(
+        id="norm.text_word_ids",
+        name="Text word IDs",
+        category=CATEGORY_NORMALIZATION,
+        summary="Read a Word ID column of text (w1, Hello_3) as keys, and number them.",
+        formula=(
+            "A Word ID column with filled cells and not one number is text: "
+            "each cell, stripped, is kept in `word_key`. Words: `word_id` = 1, "
+            "2, … per text (`text_id`, else the trial; and screen), one number "
+            "for every reader: the keys of the reading that lists the most of "
+            "them in its row order, then any other reading's keys in the order "
+            "the table first lists them. Fixations: `word_id` = the `word_id` "
+            "of the word whose key equals the fixation's exactly, in the same "
+            "trial."
+        ),
+        code="scanpath_studio/data.py:match_text_word_ids",
+        output="word_id, word_key",
+        grouping="Words: (text_id[, screen_id]); fixations: (participant_id, trial_id[, screen_id])",
+        precedence=(
+            "Only for a column with no number in it: a column with any number is "
+            "read as numbers, its other cells as blanks."
+        ),
+        missing=(
+            "A blank cell or `.` is no key, so no number. A fixation key its "
+            "trial does not list ⇒ no word, warned with the count. A text id "
+            "never matches a number: numeric fixation ids against text word ids "
+            "are set aside (warned), and with x/y the word is then assigned by "
+            "geometry. A key a trial lists twice is one word."
+        ),
+        tiers="A, C",
+        status=STATUS_VERIFIED,
+        consumers=(_UI, _API, _CLI, _EXPORT),
+        tests=("tests/test_text_word_ids.py",),
     ),
     Computation(
         id="norm.participant_metadata",

{scanpath_studio-0.43.0 → scanpath_studio-0.44.0}/scanpath_studio/constants.py

@@ -13,6 +13,14 @@ PACKAGE_NAME = "scanpath_studio"
 #: number, so the plot can colour by order without calling it time.
 SAMPLE_INDEX = "sample_index"
 
+#: A Word ID the data spells as text (``w1``, ``Hello_3``) rather than as a
+#: number, as the file spells it. The numeric ``word_id`` every consumer joins
+#: on is then the word's position in its text, one number for every reader
+#: (`data.normalize_words`), and a fixation's is looked up through this key
+#: (`data.match_text_word_ids`). A
+#: column the user sees and exports, under the Word ID column's own name.
+WORD_KEY = "word_key"
+
 
 # --- Experimental features ----------------------------------------------------
 # Features that are built but not yet validated or fully integrated are off
@@ -849,7 +857,8 @@ RAW_GAZE_LINK_FOR_KEY = "_raw_gaze_link_for"
 #: metadata tables, preprocessing). Both are built every run and switched by key,
 #: for exactly the reason the page itself is (see below): the editor is nothing
 #: but widgets that drive `prepare_data`, and Streamlit drops the key of a widget
-#: that did not render.
+#: that did not render. The built-in sources' column-mapping panels are the
+#: exception, drawn only while it is open (`controls.column_mapping_from_state`).
 DATASET_EDITOR_OPEN_KEY = "_dataset_editor_open"
 DATA_OVERVIEW_KEY = "data_overview"
 DATA_EDITOR_KEY = "data_dataset_editor"
@@ -859,8 +868,8 @@ DATA_EDITOR_OFFSCREEN_KEY = "data_dataset_editor_offscreen"
 # that view is active, off-screen otherwise.
 #
 # The setup widgets (the loaders' directory input and ⬇ Download button, the
-# source options, the column-mapping selectboxes) *drive* `prepare_data` on
-# every rerun, and Streamlit drops the key of a widget that did not render. A
+# source options) *drive* the load on every rerun, and Streamlit drops the key
+# of a widget that did not render. A
 # page body would only execute while its view is selected, so the page is
 # rendered every run either way and simply hidden — `styles.py` gives the
 # off-screen key `display: none` — rather than splitting every loader into a