crc-mets-vis 0.1.0__tar.gz

crc_mets_vis-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: crc-mets-vis
+Version: 0.1.0
+Summary: CRC metastasis explorer: Streamlit app with a custom D3 component (overview matrix, organ combinations with survival, swimmer plot).
+Author: Visual Intelligence Lab, University of Minnesota
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: streamlit>=1.40
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+
+# crc-mets-vis: CRC metastasis explorer
+
+A Streamlit app with a custom D3 component, organized as overview → explore → details:
+
+1. **Who has metastases?** A matrix of any two attributes (default: primary site group × race/ethnicity).
+   Each bar shows the share of the cell's patients with metastasis, split into *at diagnosis*
+   (first metastasis within N days, set in the sidebar) and *found later*. The whisker is the
+   95% CI and the dashed tick is the rate for all patients.
+2. **Which organs, and how do patients fare?** A transposed UpSet plot for the selected cell.
+   Each row is one organ combination with its patient count (at diagnosis / later) and a
+   survival curve measured from the first metastasis, drawn against all metastatic patients.
+   The bars above the organ columns show 1-year survival by organ involved.
+3. **Patients.** A swimmer plot for the clicked combination: one lane per patient, with
+   organ markers at the time of each metastasis and follow-up ending in death (×) or alive (›).
+
+Groups smaller than **Hide counts below** (sidebar; default 11, the SEER-Medicare rule) are hidden in
+every view. Lower it only for exploring; anything shared must use at least 11.
+
+## Which data file is used
+
+1. `--data <folder>` / `--file <csv>` given to `crc-mets-vis run` (the launcher does this)
+2. otherwise `DATA_FILE` at the top of `src/crc_mets_vis/app.py` (default `None`)
+
+There is no fallback: without a defined file the app shows nothing. The sidebar always
+shows which file is loaded.
+
+## Layout
+
+```
+crc-mets-vis/                      (same layout as the project folder in the secure environment)
+├── final_CRC_mets_full.csv        (the app reads this file)
+└── vis-app/
+    ├── app.py                     dev entry: streamlit run app.py
+    ├── make_synthetic_data.py     writes fake CSVs to ../
+    ├── pyproject.toml             package metadata (name on PyPI: crc-mets-vis)
+    └── src/crc_mets_vis/
+        ├── app.py                 the Streamlit page
+        ├── analysis.py            loading, summaries, small-cell rule, Kaplan-Meier
+        ├── attributes.py          attribute bins / labels / order  <- edit here
+        ├── cli.py                 crc-mets-vis run | make-launcher | demo-data
+        ├── synth.py               synthetic data generator
+        └── component/frontend/    index.html, main.js, style.css, d3.v7.min.js
+```
+
+## Develop locally
+
+```bash
+cd vis-app
+conda create -y -n crcvis python=3.12 && conda activate crcvis
+python -m pip install -e .
+python make_synthetic_data.py      # fake data in ../ (no real patients)
+python -m streamlit run app.py
+```
+
+After editing `analysis.py` or `attributes.py`, press **C** in the app (clear cache) or restart.
+
+## Publish to PyPI (no file transfer needed)
+
+```bash
+python -m pip install build twine
+# bump __version__ in src/crc_mets_vis/__init__.py first
+python -m build                     # -> dist/*.whl, dist/*.tar.gz
+python -m twine upload dist/*       # username: __token__, password: your PyPI API token
+```
+
+The package contains code only, never data. It's public once uploaded.
+
+## Install in a secure environment (once)
+
+In **Anaconda Prompt** inside the secure environment (set `DATA` to the folder that holds
+`final_CRC_mets_full.csv`):
+
+```bat
+set DATA=<project folder>
+C:\ProgramData\anaconda3\python.exe -m venv "%DATA%\crcvis-env"
+"%DATA%\crcvis-env\Scripts\python.exe" -m pip install crc-mets-vis
+"%DATA%\crcvis-env\Scripts\python.exe" -m crc_mets_vis make-launcher --data "%DATA%"
+```
+
+This writes two files next to the data:
+
+- **Open CRC metastasis explorer.bat**: double-click to start the app. A browser tab opens, and
+  closing the black window stops the app.
+- **Update CRC metastasis explorer.bat**: double-click to install the newest version from PyPI.
+
+The launcher calls the environment's Python by its full path, so users never activate anything.
+Each user gets their own free port, so several people can use it at once on the shared desktop.
+If pip can't reach PyPI, set your environment's proxy first (`set HTTPS_PROXY=...` and `HTTP_PROXY`).

crc_mets_vis-0.1.0/README.md

@@ -0,0 +1,88 @@
+# crc-mets-vis: CRC metastasis explorer
+
+A Streamlit app with a custom D3 component, organized as overview → explore → details:
+
+1. **Who has metastases?** A matrix of any two attributes (default: primary site group × race/ethnicity).
+   Each bar shows the share of the cell's patients with metastasis, split into *at diagnosis*
+   (first metastasis within N days, set in the sidebar) and *found later*. The whisker is the
+   95% CI and the dashed tick is the rate for all patients.
+2. **Which organs, and how do patients fare?** A transposed UpSet plot for the selected cell.
+   Each row is one organ combination with its patient count (at diagnosis / later) and a
+   survival curve measured from the first metastasis, drawn against all metastatic patients.
+   The bars above the organ columns show 1-year survival by organ involved.
+3. **Patients.** A swimmer plot for the clicked combination: one lane per patient, with
+   organ markers at the time of each metastasis and follow-up ending in death (×) or alive (›).
+
+Groups smaller than **Hide counts below** (sidebar; default 11, the SEER-Medicare rule) are hidden in
+every view. Lower it only for exploring; anything shared must use at least 11.
+
+## Which data file is used
+
+1. `--data <folder>` / `--file <csv>` given to `crc-mets-vis run` (the launcher does this)
+2. otherwise `DATA_FILE` at the top of `src/crc_mets_vis/app.py` (default `None`)
+
+There is no fallback: without a defined file the app shows nothing. The sidebar always
+shows which file is loaded.
+
+## Layout
+
+```
+crc-mets-vis/                      (same layout as the project folder in the secure environment)
+├── final_CRC_mets_full.csv        (the app reads this file)
+└── vis-app/
+    ├── app.py                     dev entry: streamlit run app.py
+    ├── make_synthetic_data.py     writes fake CSVs to ../
+    ├── pyproject.toml             package metadata (name on PyPI: crc-mets-vis)
+    └── src/crc_mets_vis/
+        ├── app.py                 the Streamlit page
+        ├── analysis.py            loading, summaries, small-cell rule, Kaplan-Meier
+        ├── attributes.py          attribute bins / labels / order  <- edit here
+        ├── cli.py                 crc-mets-vis run | make-launcher | demo-data
+        ├── synth.py               synthetic data generator
+        └── component/frontend/    index.html, main.js, style.css, d3.v7.min.js
+```
+
+## Develop locally
+
+```bash
+cd vis-app
+conda create -y -n crcvis python=3.12 && conda activate crcvis
+python -m pip install -e .
+python make_synthetic_data.py      # fake data in ../ (no real patients)
+python -m streamlit run app.py
+```
+
+After editing `analysis.py` or `attributes.py`, press **C** in the app (clear cache) or restart.
+
+## Publish to PyPI (no file transfer needed)
+
+```bash
+python -m pip install build twine
+# bump __version__ in src/crc_mets_vis/__init__.py first
+python -m build                     # -> dist/*.whl, dist/*.tar.gz
+python -m twine upload dist/*       # username: __token__, password: your PyPI API token
+```
+
+The package contains code only, never data. It's public once uploaded.
+
+## Install in a secure environment (once)
+
+In **Anaconda Prompt** inside the secure environment (set `DATA` to the folder that holds
+`final_CRC_mets_full.csv`):
+
+```bat
+set DATA=<project folder>
+C:\ProgramData\anaconda3\python.exe -m venv "%DATA%\crcvis-env"
+"%DATA%\crcvis-env\Scripts\python.exe" -m pip install crc-mets-vis
+"%DATA%\crcvis-env\Scripts\python.exe" -m crc_mets_vis make-launcher --data "%DATA%"
+```
+
+This writes two files next to the data:
+
+- **Open CRC metastasis explorer.bat**: double-click to start the app. A browser tab opens, and
+  closing the black window stops the app.
+- **Update CRC metastasis explorer.bat**: double-click to install the newest version from PyPI.
+
+The launcher calls the environment's Python by its full path, so users never activate anything.
+Each user gets their own free port, so several people can use it at once on the shared desktop.
+If pip can't reach PyPI, set your environment's proxy first (`set HTTPS_PROXY=...` and `HTTP_PROXY`).

crc_mets_vis-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "crc-mets-vis"
+dynamic = ["version"]
+description = "CRC metastasis explorer: Streamlit app with a custom D3 component (overview matrix, organ combinations with survival, swimmer plot)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Visual Intelligence Lab, University of Minnesota" }]
+dependencies = ["streamlit>=1.40", "pandas>=2.0", "numpy>=1.24"]
+
+[project.scripts]
+crc-mets-vis = "crc_mets_vis.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "crc_mets_vis.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+crc_mets_vis = ["component/frontend/*"]

crc_mets_vis-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

crc_mets_vis-0.1.0/src/crc_mets_vis/__init__.py

@@ -0,0 +1,2 @@
+"""CRC metastasis explorer: a Streamlit app with a custom D3 component."""
+__version__ = "0.1.0"

crc_mets_vis-0.1.0/src/crc_mets_vis/__main__.py

@@ -0,0 +1,3 @@
+from crc_mets_vis.cli import main
+
+main()

crc_mets_vis-0.1.0/src/crc_mets_vis/analysis.py

@@ -0,0 +1,244 @@
+"""Data loading and the summaries each view needs (all computed in Python).
+
+Only summaries leave this module for the matrix and UpSet views; counts of
+fewer than ``min_n`` patients are hidden (SEER-Medicare: min_n = 11; 0 shows everything).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from crc_mets_vis.attributes import SITES, SITE_LABELS, add_attribute_columns
+
+FULL_FILE = "final_CRC_mets_full.csv"
+DATE_COLS = ["CRC_DiagDate"] + [f"{s}_Mets_Date" for s in SITES]
+TEXT_COLS = ["PATIENT_ID", "PRIMARY_SITE", "Stage", "TStage", "NStage", "MStage"]
+DAY_COLS = [f"{s}_Days" for s in SITES]
+
+SMALL_CELL = 11          # default: never display counts 1-10 (SEER-Medicare)
+SURV_GRID = np.arange(0, 731, 15)   # survival curves: 0-2 years, every 15 days
+
+
+def data_path(configured: str | None = None) -> Path | None:
+    """The data file the user defined, or None. First match wins:
+
+    1. --data / --file given to `crc-mets-vis run` (or the launcher)  -> $CRC_DATA_FILE
+    2. `configured` (DATA_FILE at the top of app.py)
+    There is no fallback: without a defined file the app shows nothing.
+    """
+    for candidate in (os.environ.get("CRC_DATA_FILE"), configured):
+        if candidate:
+            return Path(candidate)
+    if os.environ.get("CRC_DATA_DIR"):
+        return Path(os.environ["CRC_DATA_DIR"]) / FULL_FILE
+    return None
+
+
+def load_data(path: Path) -> pd.DataFrame:
+    df = pd.read_csv(path, dtype={c: str for c in TEXT_COLS}, low_memory=False)
+    for c in DATE_COLS:
+        if c in df:
+            df[c] = pd.to_datetime(df[c], format="%m/%d/%Y", errors="coerce")
+    for c in DAY_COLS + ["OS_Days", "CSS_Days", "Death_Event", "Cancer_Specific_Death_Event",
+                         "Any_Mets", "Number_Met_Sites"]:
+        df[c] = pd.to_numeric(df[c], errors="coerce")
+    days = df[DAY_COLS]
+    df["first_met_day"] = days.min(axis=1)
+    # survival measured from the first metastasis (avoids immortal-time bias)
+    df["OS_from_met"] = df["OS_Days"] - df["first_met_day"]
+    involved = days.notna().to_numpy()
+    df["combo"] = ["|".join(s for s, on in zip(SITES, row) if on) for row in involved]
+    return add_attribute_columns(df)
+
+
+# ---------------------------------------------------------------- helpers
+def apply_filters(df: pd.DataFrame, filters: dict[str, list[str]]) -> pd.DataFrame:
+    mask = np.ones(len(df), bool)
+    for key, values in filters.items():
+        if values:
+            mask &= df[f"a:{key}"].isin(values).to_numpy()
+    return df[mask]
+
+
+def cell_mask(df, x, xv, y, yv) -> np.ndarray:
+    m = np.ones(len(df), bool)
+    if x is not None and xv is not None:
+        m &= (df[f"a:{x}"] == xv).to_numpy()
+    if y is not None and yv is not None:
+        m &= (df[f"a:{y}"] == yv).to_numpy()
+    return m
+
+
+def suppress(n, min_n: int):
+    """None (hidden) for counts 1..min_n-1; 0 and counts >= min_n are shown."""
+    n = int(n)
+    return None if 0 < n < min_n else n
+
+
+def timing(df: pd.DataFrame, cutoff: int) -> np.ndarray:
+    """0 = no metastasis, 1 = at diagnosis (first met <= cutoff days), 2 = later."""
+    mets = (df["Any_Mets"] == 1).to_numpy()
+    early = (df["first_met_day"] <= cutoff).to_numpy()
+    return np.where(~mets, 0, np.where(early, 1, 2))
+
+
+def wilson(k: int, n: int, z: float = 1.96):
+    """95% Wilson score interval for a proportion k/n (well-behaved for small n and rates near 0/1)."""
+    if n == 0:
+        return None, None
+    p = k / n
+    d = 1 + z * z / n
+    c = (p + z * z / (2 * n)) / d
+    h = z * np.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / d
+    return float(max(0, c - h)), float(min(1, c + h))
+
+
+def split_counts(ndx: int, nlate: int, min_n: int):
+    """Hide both parts if either is small (one part + the total would reveal the other)."""
+    sdx, slate = suppress(ndx, min_n), suppress(nlate, min_n)
+    if sdx is None or slate is None:
+        return None, None
+    return sdx, slate
+
+
+# ---------------------------------------------------------------- 1. matrix
+def matrix_payload(df, x, y, min_n: int, cutoff: int) -> dict:
+    xcol = f"a:{x}" if x else None
+    ycol = f"a:{y}" if y else None
+    xcats = list(df[xcol].cat.categories) if xcol else ["All patients"]
+    ycats = list(df[ycol].cat.categories) if ycol else ["All patients"]
+
+    t = timing(df, cutoff)
+    key_x = df[xcol].astype(str).to_numpy() if xcol else np.full(len(df), "All patients")
+    key_y = df[ycol].astype(str).to_numpy() if ycol else np.full(len(df), "All patients")
+    counts = pd.DataFrame({"x": key_x, "y": key_y, "t": t}).groupby(["x", "y", "t"]).size()
+
+    def get(xv, yv, tv):
+        return int(counts.get((str(xv), str(yv), tv), 0))
+
+    cells = []
+    for yi, yv in enumerate(ycats):
+        for xi, xv in enumerate(xcats):
+            n0, ndx, nlate = get(xv, yv, 0), get(xv, yv, 1), get(xv, yv, 2)
+            n1, n = ndx + nlate, n0 + ndx + nlate
+            s0, s1 = suppress(n0, min_n), suppress(n1, min_n)
+            sdx, slate = split_counts(ndx, nlate, min_n)
+            sn = None if (s0 is None or s1 is None) else n
+            lo, hi = wilson(n1, n) if sn else (None, None)
+            cells.append(dict(x=xv, y=yv, xi=xi, yi=yi, n0=s0, n1=s1, ndx=sdx, nlate=slate, n=sn,
+                              rate=(n1 / n if sn else None), lo=lo, hi=hi))
+    n_all = len(df)
+    return dict(xCats=xcats, yCats=ycats, cells=cells, total=n_all, minN=min_n,
+                cohortRate=float(df["Any_Mets"].mean()) if n_all else 0.0, cutoff=cutoff)
+
+
+# ---------------------------------------------------------------- survival
+def km_on_grid(t: np.ndarray, e: np.ndarray, grid=SURV_GRID, min_n=SMALL_CELL):
+    """Kaplan-Meier survival evaluated on a grid; None once fewer than min_n remain at risk."""
+    ok = ~(np.isnan(t) | np.isnan(e))
+    t, e = t[ok], e[ok].astype(int)
+    if len(t) == 0:
+        return [None] * len(grid), None, None
+    ts = np.sort(t)
+    times, deaths = np.unique(t[e == 1], return_counts=True)
+    at_risk = len(ts) - np.searchsorted(ts, times, side="left")
+    surv = np.cumprod(1 - deaths / at_risk) if len(times) else np.array([])
+
+    def s_at(g):
+        i = np.searchsorted(times, g, side="right") - 1
+        return 1.0 if i < 0 else float(surv[i])
+
+    risks = len(ts) - np.searchsorted(ts, np.asarray(grid), side="left")
+    out = [None if r < max(min_n, 1) else round(s_at(g), 4)
+           for g, r in zip(grid, risks)]
+    risk365 = int(len(ts) - np.searchsorted(ts, 365, side="left"))
+    s1 = round(s_at(365), 4) if risk365 >= max(min_n, 1) else None
+    med = None
+    if len(surv) and (surv <= 0.5).any():
+        med = float(times[np.argmax(surv <= 0.5)])
+    return out, s1, med
+
+
+# ---------------------------------------------------------------- 2. UpSet + survival
+def upset_payload(group: pd.DataFrame, min_n: int, cutoff: int,
+                  max_rows: int = 15, sort: str = "count") -> dict:
+    m = group[group["Any_Mets"] == 1]
+    t_met = m["OS_from_met"].to_numpy(float)
+    e_met = m["Death_Event"].to_numpy(float)
+    early = (m["first_met_day"] <= cutoff).to_numpy()
+    combos = m["combo"].to_numpy()
+
+    counts = pd.Series(combos).value_counts()
+    keep = [c for c, n in counts.items() if c and n >= min_n][:max_rows]
+    other_mask = ~np.isin(combos, keep)
+
+    def row(key, mask, label=None):
+        n = int(mask.sum())
+        ndx, nlate = int((mask & early).sum()), int((mask & ~early).sum())
+        sdx, slate = split_counts(ndx, nlate, min_n)
+        curve, s1, med = km_on_grid(t_met[mask], e_met[mask], min_n=min_n)
+        organs = key.split("|") if key and key != "__other" else []
+        return dict(key=key, organs=organs,
+                    label=label or " + ".join(SITE_LABELS[o] for o in organs),
+                    n=suppress(n, min_n), ndx=sdx, nlate=slate, surv=curve, s1=s1, med=med)
+
+    rows = [row(k, combos == k) for k in keep]
+    if sort == "surv":
+        rows.sort(key=lambda r: (r["s1"] is None, -(r["s1"] or 0)))
+    n_other = int(other_mask.sum())
+    if n_other and n_other >= min_n:
+        rows.append(row("__other", other_mask, label="Other combinations"))
+
+    organ_bars = []
+    for s in SITES:
+        mask = m[f"{s}_Days"].notna().to_numpy()
+        _, s1, _ = km_on_grid(t_met[mask], e_met[mask], min_n=min_n)
+        organ_bars.append(dict(site=s, label=SITE_LABELS[s], n=suppress(int(mask.sum()), min_n), s1=s1))
+
+    ref, ref_s1, _ = km_on_grid(t_met, e_met, min_n=min_n)
+    return dict(sites=SITES, siteLabels=SITE_LABELS, rows=rows, organBars=organ_bars,
+                grid=SURV_GRID.tolist(), ref=ref, refS1=ref_s1,
+                nMets=suppress(len(m), min_n), minN=min_n,
+                hidden=int(sum(1 for c, n in counts.items() if 0 < n < min_n)), cutoff=cutoff)
+
+
+def combo_mask(group: pd.DataFrame, key: str, shown_keys: list[str]) -> np.ndarray:
+    mets = (group["Any_Mets"] == 1).to_numpy()
+    combos = group["combo"].to_numpy()
+    if key == "__other":
+        return mets & ~np.isin(combos, [k for k in shown_keys if k != "__other"])
+    return mets & (combos == key)
+
+
+# ---------------------------------------------------------------- 3. swimmer
+def swimmer_payload(pats: pd.DataFrame, max_lanes: int, cutoff: int, sort: str = "first",
+                    seed: int = 0) -> dict:
+    n = len(pats)
+    if n > max_lanes:
+        pats = pats.iloc[np.sort(np.random.default_rng(seed).choice(n, max_lanes, replace=False))]
+    key = {"first": "first_met_day", "os": "OS_Days"}.get(sort, "first_met_day")
+    pats = pats.sort_values([key, "OS_Days"], na_position="last")
+
+    def num(v):
+        return None if pd.isna(v) else int(v)
+
+    lanes = []
+    for _, r in pats.iterrows():
+        lanes.append(dict(
+            days={s: num(r[f"{s}_Days"]) for s in SITES if pd.notna(r[f"{s}_Days"])},
+            os=num(r["OS_Days"]), died=num(r["Death_Event"]),
+            info=dict(age=num(r["Age"]), sex=str(r["a:sex"]), stage=str(r["a:stage"]),
+                      primary=str(r["a:site_group"])),
+        ))
+    max_day = max([l["os"] or 0 for l in lanes] + [max(l["days"].values(), default=0) for l in lanes] + [365])
+    return dict(lanes=lanes, n=n, nShown=len(lanes), maxDay=int(max_day), cutoff=cutoff,
+                sites=SITES, siteLabels=SITE_LABELS)
+
+
+def signature(*parts) -> str:
+    return hashlib.md5(json.dumps(parts, sort_keys=True, default=str).encode()).hexdigest()[:12]

crc_mets_vis-0.1.0/src/crc_mets_vis/app.py

@@ -0,0 +1,152 @@
+"""CRC metastasis explorer: overview (matrix) -> explore (organ combinations) -> details (patients).
+
+Started by `crc-mets-vis run` (or `streamlit run` on this file). The data file is
+DATA_FILE below, unless `--data`/`--file` is given when starting the app.
+"""
+import streamlit as st
+
+from crc_mets_vis import __version__, component
+from crc_mets_vis.analysis import (SMALL_CELL, apply_filters, cell_mask, combo_mask, data_path,
+                                   load_data, matrix_payload, signature, swimmer_payload,
+                                   upset_payload)
+from crc_mets_vis.attributes import ATTRIBUTES, FILTER_GROUPS, label
+
+# ==============================================================================
+# DATA FILE LOCATION
+# The CSV given when starting the app (`crc-mets-vis run --data <folder>` or the
+# launcher) is used first. Otherwise set the file here, e.g.
+#   DATA_FILE = r"C:\path\to\final_CRC_mets_full.csv"
+# With neither, the app shows nothing but these instructions.
+DATA_FILE = None
+# ==============================================================================
+
+
+@st.cache_data(show_spinner="Loading data…")
+def _load(path_str: str, mtime: float):  # mtime: reload automatically when the CSV changes
+    from pathlib import Path
+    return load_data(Path(path_str))
+
+
+def main():
+    st.set_page_config(page_title="CRC metastasis explorer", layout="wide")
+    path = data_path(DATA_FILE)
+    if path is None:
+        st.title("CRC metastasis explorer")
+        st.warning("No data file is defined, so nothing is shown.\n\n"
+                   "Start the app with `crc-mets-vis run --data <folder with final_CRC_mets_full.csv>` "
+                   "(or `--file <csv>`), use the launcher made by `crc-mets-vis make-launcher`, "
+                   "or set `DATA_FILE` at the top of `app.py`.")
+        st.stop()
+    if not path.exists():
+        st.error(f"Data file not found: `{path}`\n\nEdit `DATA_FILE` at the top of `app.py`, or start the "
+                 "app with `crc-mets-vis run --data <folder with final_CRC_mets_full.csv>`.")
+        st.stop()
+    df_all = _load(str(path), path.stat().st_mtime)
+
+    ss = st.session_state
+    ss.setdefault("matrix_nonce", 0)
+    ss.setdefault("filter_nonce", 0)
+
+    # ---------------------------------------------------------------- sidebar
+    with st.sidebar:
+        st.header("Settings")
+        st.caption(f"Data: `{path}`  \n{len(df_all):,} patients · v{__version__}")
+        min_n = int(st.number_input("Hide counts below", min_value=0, max_value=1000, value=SMALL_CELL, step=1,
+                                    help="Groups with fewer patients than this are hidden everywhere "
+                                         "(counts, percentages, survival). 0 shows everything. "
+                                         f"SEER-Medicare requires at least {SMALL_CELL} for anything shared."))
+        if min_n < SMALL_CELL:
+            st.caption(f":orange[Below {SMALL_CELL}: fine for exploring, but don't export or share these views.]")
+        cutoff = st.select_slider("“At diagnosis” = first metastasis within", [0, 30, 60, 90, 180],
+                                  value=90, format_func=lambda d: f"{d} days",
+                                  help="Metastases found within this window after the CRC diagnosis "
+                                       "count as present at diagnosis (synchronous); later ones as "
+                                       "found later (metachronous).")
+        st.header("Filters")
+        if st.button("Reset all filters", use_container_width=True):
+            ss.filter_nonce += 1
+        filters = {}
+        for grp in FILTER_GROUPS:
+            with st.expander(grp, expanded=(grp == "Demographics")):
+                for key, spec in ATTRIBUTES.items():
+                    if spec["group"] == grp:
+                        filters[key] = st.multiselect(spec["label"], list(df_all[f"a:{key}"].cat.categories),
+                                                      default=[], placeholder="All",
+                                                      key=f"f-{key}-{ss.filter_nonce}")
+    df = apply_filters(df_all, filters)
+    active = {k: v for k, v in filters.items() if v}
+
+    # ---------------------------------------------------------------- 1. overview
+    st.title("CRC metastasis explorer")
+    if len(df) == 0:
+        st.warning("No patients match the filters.")
+        st.stop()
+    st.caption(f"{len(df):,} patients after filters · {int(df['Any_Mets'].sum()):,} with metastasis "
+               f"({df['Any_Mets'].mean():.0%})")
+    st.subheader("1 · Who has metastases?")
+    keys = list(ATTRIBUTES)
+    c1, c2, c3, c4 = st.columns([2, 2, 2, 1])
+    x_attr = c1.selectbox("Columns", keys, index=keys.index("site_group"), format_func=label)
+    y_opts = [None] + keys
+    y_attr = c2.selectbox("Rows", y_opts, index=y_opts.index("race"), format_func=label)
+    measure = c3.radio("Show", ["rate", "count"], horizontal=True,
+                       format_func={"rate": "% with metastasis", "count": "Patient counts"}.get)
+    show_ci = c3.checkbox("95% confidence intervals", value=True, disabled=measure != "rate",
+                          help="Uncertainty of each cell's % with metastasis (Wilson score interval). "
+                               "Small cells have wide intervals, so differences between them may be chance.")
+    if c4.button("Clear selection", use_container_width=True):
+        ss.matrix_nonce += 1
+    mat = matrix_payload(df, x_attr, y_attr, min_n, cutoff)
+    clicked = component.matrix(mat, label(x_attr), label(y_attr), measure, show_ci,
+                               key=f"matrix-{x_attr}-{y_attr}-{ss.matrix_nonce}")
+    sel = clicked if clicked and clicked.get("x") in mat["xCats"] and clicked.get("y") in mat["yCats"] else None
+
+    # ---------------------------------------------------------------- 2. explore
+    if sel:
+        xv = sel["x"] if x_attr else None
+        yv = sel["y"] if y_attr else None
+        group = df[cell_mask(df, x_attr, xv, y_attr, yv)]
+        desc = " · ".join(f"{label(a)} = {v}" for a, v in ((x_attr, xv), (y_attr, yv)) if a and v is not None)
+    else:
+        group, xv, yv, desc = df, None, None, "All filtered patients"
+    n_mets = int(group["Any_Mets"].sum())
+
+    st.divider()
+    st.subheader("2 · Which organs, and how do patients fare?")
+    st.markdown(f"**{desc}** — {len(group):,} patients, "
+                + (f"{n_mets:,} with metastasis" if n_mets >= min_n
+                   else f"fewer than {min_n} with metastasis")
+                + ("" if sel else " · click a matrix cell to focus on one group"))
+    if n_mets == 0 or n_mets < min_n:
+        st.stop()
+    s1, s2 = st.columns([1, 3])
+    sort = s1.radio("Sort rows by", ["count", "surv"], horizontal=True,
+                    format_func={"count": "Patients", "surv": "1-year survival"}.get)
+    up = upset_payload(group, min_n, cutoff, sort=sort)
+    up["sig"] = signature(x_attr, y_attr, xv, yv, active, cutoff, min_n)
+    row = component.upset(up, key=f"upset-{up['sig']}")
+    shown = [r["key"] for r in up["rows"]]
+    combo = row.get("key") if row and row.get("sig") == up["sig"] and row.get("key") in shown else None
+
+    # ---------------------------------------------------------------- 3. details
+    st.divider()
+    st.subheader("3 · Patients")
+    if combo is None:
+        st.info("Click a row in the organ-combination chart to see those patients.")
+        return
+    pats = group[combo_mask(group, combo, shown)]
+    combo_label = next(r["label"] for r in up["rows"] if r["key"] == combo)
+    if len(pats) < min_n:
+        st.caption(f"Fewer than {min_n} patients; not shown.")
+        return
+    d1, d2, _ = st.columns([1.4, 1.4, 3])
+    lane_sort = d1.radio("Order lanes by", ["first", "os"], horizontal=True,
+                         format_func={"first": "First metastasis", "os": "Follow-up"}.get)
+    max_lanes = d2.select_slider("Max patients", [50, 100, 200, 500], value=100)
+    st.markdown(f"**{combo_label}** · {desc}")
+    sw = swimmer_payload(pats, max_lanes, cutoff, lane_sort)
+    component.swimmer(sw, key=f"swimmer-{up['sig']}-{combo}-{max_lanes}-{lane_sort}")
+
+
+if __name__ == "__main__":
+    main()