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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanpath-studio
-Version: 0.44.0
+Version: 0.45.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>
@@ -24,20 +24,20 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: streamlit[performance]>=1.66.0
+Requires-Dist: streamlit[performance]>=1.67.0
 Requires-Dist: packaging>=26.3
-Requires-Dist: pandas>=3.0
+Requires-Dist: pandas>=3.1
 Requires-Dist: plotly>=7.1
 Requires-Dist: numpy>=2.4
 Requires-Dist: scipy>=1.17
-Requires-Dist: pyarrow>=25.0
-Requires-Dist: kaleido>=1.4
-Requires-Dist: watchdog>=6.0.0
+Requires-Dist: pyarrow>=26.0
+Requires-Dist: kaleido>=1.5
+Requires-Dist: watchdog>=7.1.0
 Requires-Dist: streamlit-sortables>=0.3.1
-Requires-Dist: pillow>=12.3
-Requires-Dist: imageio[ffmpeg]>=2.37
+Requires-Dist: pillow>=13.0
+Requires-Dist: imageio[ffmpeg]>=2.38
 Requires-Dist: openpyxl>=3.1.5
-Requires-Dist: truststore>=0.10
+Requires-Dist: truststore>=0.10.5
 Requires-Dist: xlrd>=2.0.2
 Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == "test"
@@ -45,7 +45,7 @@ Requires-Dist: pytest-cov>=4.0.0; extra == "test"
 Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
 Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
 Provides-Extra: lint
-Requires-Dist: ruff==0.16.8; extra == "lint"
+Requires-Dist: ruff==0.17.4; extra == "lint"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material[imaging]>=9.7.7; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=1.0.6; extra == "docs"
@@ -53,7 +53,7 @@ Requires-Dist: markdown-exec>=1.12.3; extra == "docs"
 Requires-Dist: mkdocs-redirects>=1.2.3; extra == "docs"
 Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.6.0; extra == "docs"
 Requires-Dist: mkdocs-llmstxt>=0.5.0; extra == "docs"
-Requires-Dist: ruff==0.16.8; extra == "docs"
+Requires-Dist: ruff==0.17.4; extra == "docs"
 Dynamic: license-file
 
 # Scanpath Studio

{scanpath_studio-0.44.0 → scanpath_studio-0.45.0}/pyproject.toml

@@ -38,34 +38,35 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Visualization",
 ]
 dependencies = [
-    "streamlit[performance]>=1.66.0",
+    "streamlit[performance]>=1.67.0",
     # Build versions sort and compare as PEP 440 (`build_info.py`, `updates.py`).
     "packaging>=26.3",
-    "pandas>=3.0",
+    "pandas>=3.1",
     "plotly>=7.1",
     "numpy>=2.4",
     # The drift-correction port (`alignment.py`); BSD-3, MIT-compatible.
     "scipy>=1.17",
-    "pyarrow>=25.0",
-    "kaleido>=1.4",
+    "pyarrow>=26.0",
+    "kaleido>=1.5",
     # Optional Streamlit runtime dep: enables fast event-based file-watching
     # (hot reload) for `streamlit run`. Not imported by app code — Streamlit
     # auto-detects it and falls back to polling (+ an "install Watchdog" log) if
     # absent.
-    "watchdog>=6.0.0",
+    "watchdog>=7.1.0",
     # Drag-to-reorder the trial chip fields (the chips popover).
     "streamlit-sortables>=0.3.1",
     # Rasterized animation export (GIF/MP4): Pillow encodes GIF; imageio's ffmpeg
     # extra bundles an ffmpeg binary for MP4 (no system package needed).
-    "pillow>=12.3",
-    "imageio[ffmpeg]>=2.37",
+    "pillow>=13.0",
+    "imageio[ffmpeg]>=2.38",
     # pandas' .xlsx engine. Not optional in practice: the upload path reads
-    # spreadsheets (`data._read_one`).
+    # spreadsheets (`data._read_one`), and MultiplEYE's comprehension questions
+    # come as a workbook.
     "openpyxl>=3.1.5",
     # Dataset downloads verify HTTPS against the OS certificate store, so a
     # python.org Python without its CA bundle, or a TLS-inspecting network,
     # can still fetch OneStop / PoTeC (`datasets._open_url`).
-    "truststore>=0.10",
+    "truststore>=0.10.5",
     # The Excel 97–2003 (.xls) engine, for the same readers.
     "xlrd>=2.0.2",
 ]
@@ -84,7 +85,7 @@ test = [
 # unpinned ruff means a local run and CI can disagree — a new release lands new
 # rules and reds a branch that changed nothing. Bump both together.
 lint = [
-    "ruff==0.16.8",
+    "ruff==0.17.4",
 ]
 # Build the documentation site (MkDocs Material + API autodoc from docstrings).
 # Material caps MkDocs below 2.0, which has no plugin system; every plugin here
@@ -101,7 +102,7 @@ docs = [
     "mkdocs-llmstxt>=0.5.0",
     # mkdocstrings wraps the API reference's signatures with it. Pinned with
     # the `lint` extra's, so the two extras resolve together.
-    "ruff==0.16.8",
+    "ruff==0.17.4",
 ]
 
 [project.urls]

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

@@ -19,6 +19,7 @@ __all__ = [
     "list_parts",
     "list_trials",
     "load_authored_scanpath",
+    "load_multipleye",
     "load_onestop",
     "load_participant_metadata",
     "load_potec",
@@ -42,7 +43,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.44.0"
+__release__ = "0.45.0"
 
 # Public headless API (see api.py / datasets.py). Resolved lazily so
 # `import scanpath_studio` stays cheap and doesn't pull in pandas/plotly/
@@ -60,7 +61,7 @@ _HELD_BACK_EXPORTS = frozenset(
         "trial_summary",
     }
 )
-_DATASET_EXPORTS = frozenset({"load_potec", "load_onestop"})
+_DATASET_EXPORTS = frozenset({"load_potec", "load_multipleye", "load_onestop"})
 _API_EXPORTS = (
     (frozenset(__all__) | _HELD_BACK_EXPORTS)
     - {"__version__", "main"}

{scanpath_studio-0.44.0 → scanpath_studio-0.45.0}/scanpath_studio/aggregation.py

@@ -363,7 +363,7 @@ def text_screen_options(frame: pd.DataFrame, text_col: str, text_id) -> list[str
 
     Empty for a single-screen dataset — which is every corpus without
     screen identity, so callers can treat "no options" as "there is nothing to
-    pick". Ordered by ``screen_index`` when present (it can be ranked by first
+    pick". Ordered by ``screen_index`` when present (MultiplEYE ranks it by first
     fixation onset, i.e. the order the reader actually went through the pages),
     else by first appearance.
     """

{scanpath_studio-0.44.0 → scanpath_studio-0.45.0}/scanpath_studio/api.py

@@ -3974,7 +3974,8 @@ def figure_code(
         kind: ``"static"``, ``"animation"`` or ``"comparison"``: the builder the snippet
             calls.
         source: How the data is loaded: ``"demo"``, ``"synthetic"``, ``"files"``,
-            ``"potec"``, ``"onestop"``, ``"author"``, ``"raw_gaze"`` (a dataset recorded
+            ``"potec"``, ``"onestop"``, ``"multipleye"``, ``"author"``, ``"raw_gaze"``
+            (a dataset recorded
             as raw gaze alone, whose samples at ``source_options["raw_gaze"]`` are the
             data), or ``"unknown"`` for data a snippet can't name.
         source_options: That loader's arguments: ``{"root": …}``, ``{"words": [...],

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

@@ -6321,7 +6321,7 @@ def _dataset_added_dialog(message: str) -> None:
 
     Raised once by ``main`` on the run after ✅ Add dataset, once the new
     dataset's frames are loaded, so ``message`` carries its counts. Closing it
-    keeps the user on 🗂️ Data Management, where **Open in Scanpath** under the
+    keeps the user on 🗂️ Data Management, where **Open in Scanpath view** under the
     list of datasets does the same later. Buttons are handled by their return
     value, never ``on_click`` — a dialog body is a fragment (see
     ``_leave_dataset_editor_dialog``).
@@ -6329,7 +6329,7 @@ def _dataset_added_dialog(message: str) -> None:
     st.markdown(message)
     open_col, again_col = st.columns(2, gap="small")
     if open_col.button(
-        f"{ICONS['view_scanpath']} Open in Scanpath",
+        f"{ICONS['view_scanpath']} Open in Scanpath view",
         key="dataset_added_open",
         type="primary",
         width="stretch",
@@ -6349,7 +6349,7 @@ def _dataset_added_dialog(message: str) -> None:
         st.rerun(scope="app")
     st.caption(
         f"Close this to stay on {ICONS['view_data']} Data Management. "
-        "**Open in Scanpath**, under the list of datasets, opens it later."
+        "**Open in Scanpath view**, under the list of datasets, opens it later."
     )
 
 
@@ -9071,12 +9071,8 @@ def _render_backup_reminder(host, active_view: str) -> None:
         return
     box = host.container(key="sps_backup_reminder", border=True)
     box.markdown(
-        f"{ICONS['warning']} **This server saves nothing.** Closing or "
-        "refreshing the tab loses the datasets you added, their column mappings, "
-        "your annotations and designs. Keep the files you uploaded, and export your "
-        f"annotations from {ICONS['view_data']} **Data Management → Annotations** and each "
-        "dataset's mapping from "
-        f"{ICONS['edit']} **Edit dataset → Download setup file**. "
+        f"{ICONS['warning']} **This server saves nothing.** Refreshing or "
+        "closing the tab loses your datasets, annotations and designs. "
         f"[How to keep copies of your work ↗]({BACKUP_GUIDE_URL})"
     )
     row = box.container(horizontal=True, gap="small")
@@ -9788,7 +9784,7 @@ def _run_app() -> None:
     dataset_table_slot = setup_source_slot.container(key="tutorial_available_datasets")
     # The two ways to make a dataset are one **+ Add
     # dataset** menu (the Scanpath picker's + with its name spelled out), under
-    # the list it adds to, beside **Open in Scanpath** for the dataset the list
+    # the list it adds to, beside **Open in Scanpath view** for the dataset the list
     # marks Current. Filled once `data_choice` is known.
     add_dataset_slot = (
         setup_source_slot.container(key="data_page_add", horizontal=True)
@@ -9843,7 +9839,7 @@ def _run_app() -> None:
         # picked from the list: the view switch is a request, since this is
         # an `on_click` callback (see `url_state._go_scanpath`).
         add_dataset_slot.button(
-            "Open in Scanpath",
+            "Open in Scanpath view",
             icon=ICONS["view_scanpath"],
             key="data_open_in_scanpath",
             on_click=_go_scanpath,
@@ -10362,10 +10358,10 @@ def _run_app() -> None:
             st.session_state[TRIAL_IDENTITY_CHECK_KEY] = asked_by
     if added:
         # Say what ✅ Add dataset brought in, and offer the next step: a
-        # dialog with Open in Scanpath / Add another. The Trial ID verdict
+        # dialog with Open in Scanpath view / Add another. The Trial ID verdict
         # takes the run's one dialog when it has something to say, and any
         # other dialog already open wins too; the counts then go to a toast,
-        # and **Open in Scanpath** under the list is the way on.
+        # and **Open in Scanpath view** under the list is the way on.
         message = dataset_added_message(str(added), words_all, fixations_all)
         offered = False
         if not identity_modal:

{scanpath_studio-0.44.0 → scanpath_studio-0.45.0}/scanpath_studio/cli.py

@@ -30,6 +30,7 @@ from . import column_names as _cn
 from .code_snippet import (
     SOURCE_AUTHOR,
     SOURCE_DEMO,
+    SOURCE_MULTIPLEYE,
     SOURCE_ONESTOP,
     SOURCE_POTEC,
     SnippetSource,
@@ -595,6 +596,17 @@ def _render_parser() -> argparse.ArgumentParser:
         "lacclab, a local lab-processed export with no download.",
     )
 
+    src.add_argument(
+        "--multipleye",
+        metavar="DIR",
+        help="Load a MultiplEYE session set from DIR, the folder holding its "
+        "scanpaths/ or fixations/ folder and its stimuli_*/ folder. A participant "
+        "is a session (e.g. 001_ZH_CH_1_ET1) and a trial is one reading of one "
+        "stimulus (e.g. 001_ZH_CH_1_ET1_Lit_Alchemist_4), with its pages and "
+        "comprehension questions as screens. The screen comes from the session "
+        "set's own config; "
+        "set the font with --font-size and --font-family.",
+    )
     src.add_argument(
         "--participant-metadata",
         metavar="FILE",
@@ -1113,7 +1125,8 @@ def _render_parser() -> argparse.ArgumentParser:
         metavar="WxH",
         help="Screen size in px, e.g. 2560x1440 (default: 2560x1440 for "
         "--sample and --onestop, 1680x1050 for --potec, 1200x800 for "
-        "--authoring, otherwise estimated from the data).",
+        "--authoring, the session set's own monitor for --multipleye, "
+        "otherwise estimated from the data).",
     )
     viz.add_argument(
         "--coordinate-grid",
@@ -2377,6 +2390,12 @@ def _snippet_data_source(args) -> SnippetSource:
                 "parts": list(args.onestop_part or ["Paragraph"]),
             },
         )
+    if args.multipleye:
+        return cs.SnippetSource(
+            kind=cs.SOURCE_MULTIPLEYE,
+            label="MultiplEYE",
+            options={"root": args.multipleye},
+        )
     if args.words or args.fixations:
         options = {
             "words": list(args.words or []),
@@ -2574,6 +2593,36 @@ def _parse_xy(value: str | None, flag: str = "--stimulus-image-origin") -> tuple
     return (x, y)
 
 
+def _load_multipleye_render(root: str, participant: str | None):
+    """`render --multipleye`: the session set, normalized like the app's.
+
+    ``participant`` is a session id, matched case-insensitively; given one, only
+    that session is read. Returns ``(data, participant)`` — the loaded frames
+    and the session id as the export spells it.
+    """
+    from .datasets import load_multipleye, multipleye_inventory
+
+    sessions, _ = multipleye_inventory(root)
+    if not sessions:
+        raise FileNotFoundError(
+            f"No MultiplEYE sessions under {root}: expected a scanpaths/ or "
+            "fixations/ folder holding one folder per session."
+        )
+    session = None
+    if participant is not None:
+        want = str(participant).strip().lower()
+        session = next((s for s in sessions if s.lower() == want), None)
+        if session is None:
+            raise ValueError(
+                f"No MultiplEYE session {participant!r} under {root} "
+                f"(sessions: {', '.join(sessions)})."
+            )
+    data = load_multipleye(
+        root, sessions=[session] if session else None, names="canonical"
+    )
+    return data, session
+
+
 def _apply_shared_colorbar_flags(args: argparse.Namespace) -> None:
     """Hand v0.33.0's shared ``--colorbar-*`` values to each bar that was not
     given its own; a bar's own flag wins, wherever it sits on the line.
@@ -2628,6 +2677,7 @@ def render(argv: list[str]) -> None:
         bool(args.authoring),
         bool(args.potec),
         bool(args.onestop),
+        bool(args.multipleye),
     ]
     # Your own tables are words and/or fixations — or raw gaze alone, for a
     # dataset recorded as samples only. Beside any other input, --raw-gaze is
@@ -2636,7 +2686,13 @@ def render(argv: list[str]) -> None:
         bool(args.raw_gaze) and not any(corpus_inputs)
     )
     if sum([*corpus_inputs, own_tables]) != 1:
-        inputs = ["--sample", "--authoring PATH", "--potec DIR", "--onestop DIR"]
+        inputs = [
+            "--sample",
+            "--authoring PATH",
+            "--potec DIR",
+            "--onestop DIR",
+            "--multipleye DIR",
+        ]
         raise SystemExit(
             f"Provide exactly one input: {', '.join(inputs)}, or your own tables "
             "(--words and/or --fixations; one of them is enough for "
@@ -2831,6 +2887,18 @@ def render(argv: list[str]) -> None:
         words, fixations = data
         column_names = dict(data.column_names)
         canvas = canvas or source_canvas(SOURCE_ONESTOP)
+    elif args.multipleye:
+        try:
+            data, args.participant = _load_multipleye_render(
+                args.multipleye, args.participant
+            )
+        except (ValueError, FileNotFoundError, OSError) as exc:
+            raise SystemExit(str(exc))
+        words, fixations = data
+        column_names = dict(data.column_names)
+        # Each fixation carries the session set's monitor (`canvas_width`), so
+        # the screen is read off the data.
+        canvas = canvas or source_canvas(SOURCE_MULTIPLEYE)
     else:
         manifest = None
         if args.trial_parts_manifest:

{scanpath_studio-0.44.0 → scanpath_studio-0.45.0}/scanpath_studio/code_snippet.py

@@ -87,6 +87,7 @@ SOURCE_FILES = "files"
 SOURCE_AUTHOR = "author"
 SOURCE_POTEC = "potec"
 SOURCE_ONESTOP = "onestop"
+SOURCE_MULTIPLEYE = "multipleye"
 #: A dataset recorded as raw gaze alone — no words or fixations table,
 #: so its data half is the samples (``options["raw_gaze"]``, the paths) and the
 #: builder is handed ``None`` for the other two.
@@ -155,6 +156,8 @@ def source_canvas(kind: str) -> tuple[int, int] | None:
         return (1680, 1050)  # PoTeC monitor (DELL P2210)
     if kind == SOURCE_AUTHOR:
         return (1200, 800)
+    # MultiplEYE stamps each session set's own monitor on its fixations, so it
+    # is read off the data like any other dataset's.
     return None
 
 
@@ -306,6 +309,19 @@ def _onestop_python(source: SnippetSource) -> list[str]:
     return lines
 
 
+#: The folder a MultiplEYE snippet loads when the dataset was uploaded, and so
+#: has no folder the server could quote.
+MULTIPLEYE_ROOT_PLACEHOLDER = "path/to/MultiplEYE_session_set"
+
+
+def _multipleye_python(source: SnippetSource) -> list[str]:
+    return [
+        "words, fixations = sps.load_multipleye(",
+        f"    {_py(_root(source, MULTIPLEYE_ROOT_PLACEHOLDER))},",
+        ")",
+    ]
+
+
 def _unknown_python(source: SnippetSource) -> list[str]:
     if source.options.get("keep_columns"):
         return [
@@ -356,6 +372,10 @@ def _onestop_cli(source: SnippetSource) -> list[str]:
     return argv
 
 
+def _multipleye_cli(source: SnippetSource) -> list[str]:
+    return ["--multipleye", _root(source, MULTIPLEYE_ROOT_PLACEHOLDER)]
+
+
 def _unknown_cli(source: SnippetSource) -> list[str]:
     return ["--words", "words.csv", "--fixations", "fixations.csv", *_keep_cli(source)]
 
@@ -392,6 +412,8 @@ def upload_source(
     placeholders: an upload has no path the server could quote.
     """
     recipe = recipe if isinstance(recipe, dict) else {}
+    if isinstance(multipleye := recipe.get("multipleye"), dict):
+        return multipleye_source(label, multipleye, edited=bool(recipe.get("schemas")))
     schemas = recipe.get("schemas") if isinstance(recipe.get("schemas"), dict) else {}
     steps = [str(s) for s in recipe.get("steps") or ()]
     notes = [
@@ -452,6 +474,42 @@ def upload_source(
     )
 
 
+def multipleye_source(
+    label: str, recipe: dict, *, edited: bool = False
+) -> SnippetSource:
+    """The data half for a MultiplEYE session set added through the app.
+
+    ``recipe`` is the dataset's ``source_recipe["multipleye"]``: the ``root``
+    folder it was read from, ``None`` for an upload. ``load_multipleye`` reads
+    the same files the app did, so a folder-added dataset's snippet runs as it
+    is; an uploaded
+    one names a placeholder folder instead, and the whole session set there may
+    hold more than the files uploaded. ``edited`` says ✏️ Edit dataset changed
+    the mapping since, which the loader does not replay."""
+    root = recipe.get("root")
+    notes = []
+    if not root:
+        notes.append(
+            "This dataset was added from uploaded files, so the snippet can't "
+            f"name their folder. Replace `{MULTIPLEYE_ROOT_PLACEHOLDER}` with the "
+            "MultiplEYE session set they came from. The loader reads the whole "
+            "session set, so it can include trials, question screens, reading "
+            "measures and page images that the upload left out."
+        )
+    if edited:
+        notes.append(
+            "Its mapping was changed in Edit dataset after it was added. The "
+            "loader reads the session set as it was added, so make the same "
+            "change in your script."
+        )
+    return SnippetSource(
+        kind=SOURCE_MULTIPLEYE,
+        label=label,
+        options={"root": str(root) if root else None},
+        note=" ".join(notes),
+    )
+
+
 def _compact_schema(schema: dict) -> dict:
     """A mapping without its unmapped fields, so the snippet stays readable.
 
@@ -551,6 +609,7 @@ _SOURCE_WRITERS: dict[str, tuple[Any, Any]] = {
     SOURCE_AUTHOR: (_author_python, _author_cli),
     SOURCE_POTEC: (_potec_python, _potec_cli),
     SOURCE_ONESTOP: (_onestop_python, _onestop_cli),
+    SOURCE_MULTIPLEYE: (_multipleye_python, _multipleye_cli),
     SOURCE_RAW_GAZE: (_raw_gaze_only_python, _raw_gaze_only_cli),
     SOURCE_UPLOAD: (_upload_python, _upload_cli),
     SOURCE_UNKNOWN: (_unknown_python, _unknown_cli),

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

@@ -1012,6 +1012,14 @@ def stored_source_recipe(stored: Mapping) -> dict:
     return {"schemas": schemas, "unresolved": unresolved}
 
 
+def is_multipleye_entry(stored) -> bool:
+    """Whether a stored dataset was added as a MultiplEYE session set: its
+    ``source_recipe`` records the session set (``"multipleye"``), not a
+    mapping of the user's files."""
+    recipe = stored.get("source_recipe") if isinstance(stored, Mapping) else None
+    return isinstance(recipe, Mapping) and isinstance(recipe.get("multipleye"), Mapping)
+
+
 # --- A frame that carries its own names ---------------------------------------
 
 #: The `DataFrame.attrs` key a frame under the dataset's own names carries its

{scanpath_studio-0.44.0 → scanpath_studio-0.45.0}/scanpath_studio/controls.py

@@ -8142,8 +8142,8 @@ def render_plot_controls(
                 label_visibility="collapsed",
             )
 
-        # A stimulus image can come from the dataset (a per-trial
-        # `image_path`) OR be uploaded here for any dataset (a
+        # A stimulus image can come from the dataset (MultiplEYE stamps a
+        # per-trial `image_path`) OR be uploaded here for any dataset (a
         # full-monitor screenshot of the reading screen). The upload's `data:`
         # URI is stashed in session for the tab to place + the (pure) collector
         # to read; the switch is enabled whenever either source exists.
@@ -9319,7 +9319,7 @@ _DEFAULT_FILTER_FIELDS = [
     # on every export) and worth filtering on — it is how you exclude the start
     # or the tail of a session when you suspect practice or fatigue effects.
     "TRIAL_INDEX",
-    # Common trial-level facets (offered only when the data has them).
+    # MultiplEYE facets (present only when that corpus is loaded).
     "genre",
     "session",
     "is_practice",
@@ -9693,9 +9693,11 @@ _CHIP_DEFAULT_CONDITIONS = [
     "question_preview",
     "repeated_reading_trial",
     "is_correct",
-    # Common trial-level facets (shown only when the data has them).
+    # MultiplEYE facets + reader metadata (present only for that corpus).
     "genre",
     "session",
+    "pp_age",
+    "pp_gender",
 ]
 # Virtual chip fields → label. These are computed per trial (not data columns)
 # and always trial-level.

{scanpath_studio-0.44.0 → scanpath_studio-0.45.0}/scanpath_studio/data.py

@@ -3813,7 +3813,7 @@ def source_labels(paths: Sequence[str]) -> list[str]:
 def source_file_name(label: str) -> str:
     """The file stem inside a :func:`source_labels` label — without the folders
     that qualify it, its ``#n`` occurrence number or a kept extension — for
-    code that parses identity out of a file's name."""
+    code that parses identity out of a file's name (MultiplEYE uploads)."""
     name = re.sub(r"#\d+$", "", str(label).rsplit("/", 1)[-1])
     stem = Path(name).stem
     return stem if Path(name).suffix.lower().lstrip(".") in UPLOAD_FILE_TYPES else name
@@ -5744,7 +5744,7 @@ def detect_word_id_offset(words: pd.DataFrame, fixations: pd.DataFrame) -> int:
         .groupby(keys, sort=False)["_id"]
         .agg(["min", "max"])
     )
-    joined = w_stats.join(f_stats, how="inner", lsuffix="_w", rsuffix="_f")
+    joined = w_stats.join(f_stats, how="inner", suffixes=("_w", "_f"))
     if joined.empty:
         return 0
     zero_based = joined["min_w"] == 0
@@ -6245,9 +6245,9 @@ WORD_OPTIONAL_FIELDS = [
     ("dspan_ind_end", "dspan_ind_end", "passthrough", "meta"),
     ("is_in_aspan", "is_in_aspan", "boolean", "meta"),
     ("is_in_dspan", "is_in_dspan", "boolean", "meta"),
-    # Side data (also see FIX_OPTIONAL_FIELDS): the comprehension questions
-    # JSON + the per-trial stimulus-image path + the genre facet, kept so the
-    # panels / image layer can read them off the word frame too.
+    # MultiplEYE side-data (also see FIX_OPTIONAL_FIELDS): the comprehension
+    # questions JSON + the per-trial stimulus-image path + the genre facet, kept
+    # so the panels / image layer can read them off the word frame too.
     ("comprehension_questions", "comprehension_questions", "passthrough", "meta"),
     ("image_path", "image_path", "passthrough", "meta"),
     ("image_x", "image_x", "numeric", "meta"),
@@ -6257,9 +6257,12 @@ WORD_OPTIONAL_FIELDS = [
     ("stimulus_font_px", "stimulus_font_px", "numeric", "meta"),
     ("stimulus_font_family", "stimulus_font_family", "passthrough", "meta"),
     ("genre", "genre", "string", "meta"),
-    # Multipart screens: what a screen *is* (e.g. `reading` / `question` — a
-    # trial can mix both, and their fixations can have different provenance).
+    # Multipart screens: what a screen *is* (`reading` / `question` on
+    # MultiplEYE — a trial mixes both, and their fixations have different
+    # provenance), and which block of a question screen a word belongs to
+    # (`stem` / `target` / `distractor_a`… — a per-word facet).
     ("screen_kind", "screen_kind", "passthrough", "meta"),
+    ("aoi_block", "aoi_block", "passthrough", "meta"),
 ]
 
 FIX_OPTIONAL_FIELDS = [
@@ -6303,9 +6306,10 @@ FIX_OPTIONAL_FIELDS = [
     ("blink", "is_blink", "boolean", "fixation"),
     ("blink_flag", "is_blink", "boolean", "fixation"),
     ("BLINK", "is_blink", "boolean", "fixation"),
-    # Trial-level facets + side data → Trial Info chips / filter facets / the
-    # comprehension panel / the stimulus-image layer. Carried only when the
-    # data has them, so they're inert for other corpora.
+    # MultiplEYE trial-level facets + side-data → Trial Info chips / filter
+    # facets / the comprehension panel / the stimulus-image layer. All are
+    # MultiplEYE-specific source names (carried only when the loader emits them),
+    # so they're inert for other corpora.
     ("genre", "genre", "string", "meta"),
     ("session", "session", "string", "meta"),
     ("participant", "participant", "string", "meta"),
@@ -6317,6 +6321,12 @@ FIX_OPTIONAL_FIELDS = [
     ("image_y", "image_y", "numeric", "meta"),
     ("stimulus_font_px", "stimulus_font_px", "numeric", "meta"),
     ("stimulus_font_family", "stimulus_font_family", "passthrough", "meta"),
+    # Reader metadata merged from participant_data.csv (namespaced pp_*).
+    ("pp_age", "pp_age", "numeric", "meta"),
+    ("pp_gender", "pp_gender", "string", "meta"),
+    ("pp_native_language", "pp_native_language", "string", "meta"),
+    ("pp_years_education", "pp_years_education", "numeric", "meta"),
+    ("pp_education_level", "pp_education_level", "string", "meta"),
     # Which kind of screen a fixation happened on (see the word table).
     ("screen_kind", "screen_kind", "passthrough", "meta"),
 ]