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

{scanpath_studio-0.43.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.43.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.43.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.43.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.43.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.43.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.43.0 → scanpath_studio-0.45.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:
@@ -3966,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.43.0 → scanpath_studio-0.45.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"]
@@ -6281,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``).
@@ -6289,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",
@@ -6309,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."
     )
 
 
@@ -9031,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")
@@ -9553,11 +9589,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
@@ -9745,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)
@@ -9800,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,
@@ -9949,8 +9988,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 +10147,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 +10197,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)
@@ -10310,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.43.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: