fusiqc 0.0.1a1__tar.gz

fusiqc-0.0.1a1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: fusiqc
+Version: 0.0.1a1
+Summary: Browser-based QC for fUSI-BIDS datasets.
+Author: Samuel Le Meur-Diebolt
+Author-email: Samuel Le Meur-Diebolt <samuel@diebolt.io>
+License-Expression: BSD-3-Clause
+Requires-Dist: confusius==0.0.1a21
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pybids>=0.18.1
+Requires-Dist: rich>=14.2.0
+Requires-Python: >=3.11, <3.14
+Description-Content-Type: text/markdown
+
+[![PyPI version](https://img.shields.io/pypi/v/fusiqc)](https://pypi.org/project/fusiqc/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fusiqc)](https://pypi.org/project/fusiqc/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+
+# fUSIQC
+
+> [!NOTE]
+> fUSIQC explores what a web-based QC app for [ConfUSIus](https://confusius.tools) could
+> look like. Although it is a proof of concept, it may still be useful if you need to
+> perform quick quality control of a fUSI-BIDS dataset.
+
+Browser-based quality control for fUSI-BIDS datasets, powered by
+[ConfUSIus](https://confusius.tools). Generates QC plots (mean power Doppler,
+coefficient of variation, carpet plot, DVARS) for each recording and serves a local web
+app to review and annotate them. QC figures are saved to a derivatives folder for easy
+inspection, and annotations are persisted to a TSV file for downstream analyses.
+
+![fUSIQC interface](docs/screenshot.png)
+
+## Usage
+
+```bash
+uv run fusiqc /path/to/bids-root
+```
+
+On first run, QC plots are generated for all recordings. Subsequent runs reuse existing
+plots and only compute missing ones. Pass `--refresh` to force regeneration.
+
+### Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--output-dir` | `<bids_root>/derivatives/fusiqc/` | QC output directory |
+| `--host` | `127.0.0.1` | Host to bind the web app |
+| `--port` | `8765` | Port to bind the web app |
+| `--workers` | `min(8, cpu_count - 1)` | Parallel workers for plot generation |
+| `--refresh` | | Force regeneration of all QC plots |
+| `--no-browser` | | Don't open a browser automatically |
+
+## Output
+
+- `<output_dir>/figures/` — QC plot PNGs organized by subject/session
+- `<output_dir>/quality-control.tsv` — QC status and annotations

fusiqc-0.0.1a1/README.md

@@ -0,0 +1,43 @@
+[![PyPI version](https://img.shields.io/pypi/v/fusiqc)](https://pypi.org/project/fusiqc/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fusiqc)](https://pypi.org/project/fusiqc/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+
+# fUSIQC
+
+> [!NOTE]
+> fUSIQC explores what a web-based QC app for [ConfUSIus](https://confusius.tools) could
+> look like. Although it is a proof of concept, it may still be useful if you need to
+> perform quick quality control of a fUSI-BIDS dataset.
+
+Browser-based quality control for fUSI-BIDS datasets, powered by
+[ConfUSIus](https://confusius.tools). Generates QC plots (mean power Doppler,
+coefficient of variation, carpet plot, DVARS) for each recording and serves a local web
+app to review and annotate them. QC figures are saved to a derivatives folder for easy
+inspection, and annotations are persisted to a TSV file for downstream analyses.
+
+![fUSIQC interface](docs/screenshot.png)
+
+## Usage
+
+```bash
+uv run fusiqc /path/to/bids-root
+```
+
+On first run, QC plots are generated for all recordings. Subsequent runs reuse existing
+plots and only compute missing ones. Pass `--refresh` to force regeneration.
+
+### Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--output-dir` | `<bids_root>/derivatives/fusiqc/` | QC output directory |
+| `--host` | `127.0.0.1` | Host to bind the web app |
+| `--port` | `8765` | Port to bind the web app |
+| `--workers` | `min(8, cpu_count - 1)` | Parallel workers for plot generation |
+| `--refresh` | | Force regeneration of all QC plots |
+| `--no-browser` | | Don't open a browser automatically |
+
+## Output
+
+- `<output_dir>/figures/` — QC plot PNGs organized by subject/session
+- `<output_dir>/quality-control.tsv` — QC status and annotations

fusiqc-0.0.1a1/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "fusiqc"
+version = "0.0.1-a1"
+description = "Browser-based QC for fUSI-BIDS datasets."
+readme = "README.md"
+authors = [
+    { name = "Samuel Le Meur-Diebolt", email = "samuel@diebolt.io" }
+]
+license = "BSD-3-Clause"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "confusius==0.0.1a21",
+    "pandas>=2.2.3",
+    "pybids>=0.18.1",
+    "rich>=14.2.0",
+]
+
+[project.scripts]
+fusiqc = "fusiqc:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.8.0",
+    "ty>=0.0.10,<0.1.0",
+    "prek>=0.3.0",
+    "codespell>=2.4.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12.0"]
+build-backend = "uv_build"

fusiqc-0.0.1a1/src/fusiqc/__init__.py

@@ -0,0 +1,5 @@
+"""fusiqc package."""
+
+from fusiqc._cli import main
+
+__all__ = ["main"]

fusiqc-0.0.1a1/src/fusiqc/_cli.py

@@ -0,0 +1,64 @@
+"""fusiqc command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from rich.console import Console
+
+from fusiqc._config import make_config
+from fusiqc._qc import refresh_qc_table
+from fusiqc._web import launch_web_app
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser."""
+    parser = argparse.ArgumentParser(
+        prog="fusiqc",
+        description="Generate and review QC plots for a fUSI-BIDS dataset.",
+    )
+    parser.add_argument("bids_root", type=Path, help="Path to the BIDS dataset root.")
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=None,
+        help="QC output directory. Defaults to <bids_root>/derivatives/fusiqc.",
+    )
+    parser.add_argument(
+        "--host", default="127.0.0.1", help="Host to bind the local web app."
+    )
+    parser.add_argument(
+        "--port", type=int, default=8765, help="Port to bind the local web app."
+    )
+    parser.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Force regeneration of all QC plots instead of only computing missing ones.",
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Do not open a browser automatically.",
+    )
+    parser.add_argument(
+        "--workers",
+        type=int,
+        default=None,
+        help="Number of worker processes to use while refreshing QC assets.",
+    )
+    return parser
+
+
+def main() -> None:
+    """Run the fusiqc CLI."""
+    args = build_parser().parse_args()
+    console = Console()
+    config = make_config(
+        args.bids_root, output_dir=args.output_dir, workers=args.workers
+    )
+    table, tsv_path = refresh_qc_table(config, force=args.refresh)
+    console.print(f"QC table with {len(table)} recording(s): {tsv_path}")
+    launch_web_app(
+        config, host=args.host, port=args.port, open_browser=not args.no_browser
+    )

fusiqc-0.0.1a1/src/fusiqc/_config.py

@@ -0,0 +1,46 @@
+"""Configuration helpers for fusiqc."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class QcConfig:
+    """Runtime configuration for one QC session."""
+
+    bids_root: Path
+    output_dir: Path
+    workers: int | None = None
+
+    @property
+    def tsv_path(self) -> Path:
+        """Return the QC TSV output path."""
+        return self.output_dir / "quality-control.tsv"
+
+    @property
+    def figures_dir(self) -> Path:
+        """Return the QC figures output directory."""
+        return self.output_dir / "figures"
+
+
+def resolve_output_dir(bids_root: Path, output_dir: Path | None = None) -> Path:
+    """Return the resolved QC output directory."""
+    if output_dir is None:
+        return bids_root / "derivatives" / "fusiqc"
+    return output_dir.expanduser().resolve()
+
+
+def make_config(
+    bids_root: Path,
+    output_dir: Path | None = None,
+    workers: int | None = None,
+) -> QcConfig:
+    """Create a QC configuration object."""
+    bids_root = bids_root.expanduser().resolve()
+    return QcConfig(
+        bids_root=bids_root,
+        output_dir=resolve_output_dir(bids_root, output_dir),
+        workers=workers,
+    )

fusiqc-0.0.1a1/src/fusiqc/_dataset.py

@@ -0,0 +1,68 @@
+"""Dataset discovery for fusiqc."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+from bids import BIDSLayout
+from bids.layout import BIDSLayoutIndexer
+
+from fusiqc._config import QcConfig
+
+ALLOWED_PWD_SUFFIXES = ("_pwd.nii", "_pwd.nii.gz", "_pwd.zarr", "_pwd.scan")
+
+
+@dataclass(frozen=True)
+class PwdRecording:
+    """One power-Doppler recording discovered in a BIDS dataset."""
+
+    pwd_path: Path
+    session_label: str
+    subject: str
+    session: str
+    task: str
+    run: str
+
+
+@lru_cache(maxsize=8)
+def get_bids_layout(bids_root: Path) -> BIDSLayout:
+    """Return a cached PyBIDS layout for one dataset root."""
+    return BIDSLayout(
+        bids_root,
+        validate=False,
+        indexer=BIDSLayoutIndexer(force_index=[r".*\.zarr(?:/.*)?$", r".*\.scan$"]),
+    )
+
+
+def get_session_label_from_pwd_path(pwd_path: Path) -> str:
+    """Return the basename without the power-Doppler suffix."""
+    name = pwd_path.name
+    for suffix in ALLOWED_PWD_SUFFIXES:
+        if name.endswith(suffix):
+            return name.removesuffix(suffix)
+    return pwd_path.stem
+
+
+def discover_pwd_recordings(config: QcConfig) -> list[PwdRecording]:
+    """Return all supported power-Doppler recordings in the dataset."""
+    layout = get_bids_layout(config.bids_root)
+    files = layout.get(suffix="pwd", return_type="filename")
+    recordings: list[PwdRecording] = []
+    for filename in sorted(files):
+        pwd_path = Path(filename)
+        if not pwd_path.name.endswith(ALLOWED_PWD_SUFFIXES):
+            continue
+        entities = layout.parse_file_entities(str(pwd_path))
+        recordings.append(
+            PwdRecording(
+                pwd_path=pwd_path,
+                session_label=get_session_label_from_pwd_path(pwd_path),
+                subject=str(entities.get("subject", entities.get("sub", ""))),
+                session=str(entities.get("session", entities.get("ses", ""))),
+                task=str(entities.get("task", "")),
+                run=str(entities.get("run", "")),
+            )
+        )
+    return recordings

fusiqc-0.0.1a1/src/fusiqc/_qc.py

@@ -0,0 +1,352 @@
+"""QC refresh and plotting helpers for fusiqc."""
+
+from __future__ import annotations
+
+import os
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+
+import confusius as cf
+import matplotlib.figure
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import xarray as xr
+from confusius.qc import compute_cv, compute_dvars
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+    track,
+)
+
+from fusiqc._config import QcConfig
+from fusiqc._dataset import PwdRecording, discover_pwd_recordings
+
+QC_PANELS = ("mean_power_doppler", "cv", "carpet", "dvars")
+QC_COLUMNS = (
+    "pwd_path",
+    "session_label",
+    "subject",
+    "session",
+    "task",
+    "run",
+    "n_timepoints",
+    "qc_status",
+    "qc_notes",
+)
+CONSOLE = Console()
+
+
+def load_qc_table(config: QcConfig) -> pd.DataFrame:
+    """Load the QC TSV, returning an empty table when absent."""
+    if not config.tsv_path.exists():
+        return pd.DataFrame(columns=QC_COLUMNS)
+    table = pd.read_csv(config.tsv_path, sep="\t", dtype=str).fillna("")
+    for column in QC_COLUMNS:
+        if column not in table.columns:
+            table[column] = ""
+    return table.loc[:, QC_COLUMNS]
+
+
+def save_qc_table(config: QcConfig, table: pd.DataFrame) -> Path:
+    """Save the QC TSV."""
+    config.output_dir.mkdir(parents=True, exist_ok=True)
+    table.loc[:, QC_COLUMNS].to_csv(config.tsv_path, sep="\t", index=False)
+    return config.tsv_path
+
+
+def get_qc_plot_paths(config: QcConfig, recording: PwdRecording) -> dict[str, Path]:
+    """Return output paths for all QC panels."""
+    base_dir = (
+        config.figures_dir / f"sub-{recording.subject}" / f"ses-{recording.session}"
+    )
+    return {
+        panel: base_dir / f"{recording.session_label}_{panel}.png"
+        for panel in QC_PANELS
+    }
+
+
+def _default_workers() -> int:
+    """Return a conservative default worker count for QC refresh."""
+    cpu_count = os.cpu_count() or 1
+    return max(1, min(8, cpu_count - 1))
+
+
+def _prepare_preview_map(data: xr.DataArray) -> tuple[xr.DataArray, str, float]:
+    """Return a 3D preview volume plus slice settings for one spatial map."""
+    preview = data.squeeze()
+    if preview.ndim == 2:
+        return preview.expand_dims(z=[0.0]), "z", 0.0
+    if preview.ndim == 3:
+        return (
+            preview,
+            "z",
+            float(preview.coords["z"].values[len(preview.coords["z"]) // 2]),
+        )
+    raise ValueError(
+        f"Expected 2D or 3D preview map, got shape {preview.shape} with dims {list(preview.dims)}."
+    )
+
+
+def _get_map_figsize(preview: xr.DataArray, slice_mode: str) -> tuple[float, float]:
+    """Return a figure size that keeps the colorbar close to image height."""
+    display_dims = [dim for dim in preview.dims if dim != slice_mode]
+    if len(display_dims) != 2:
+        return (5.4, 4.8)
+    row_dim, col_dim = display_dims
+    row_extent = float(preview.sizes[row_dim])
+    col_extent = float(preview.sizes[col_dim])
+    if row_dim in preview.coords and preview.coords[row_dim].size > 1:
+        row_coords = np.asarray(preview.coords[row_dim].values, dtype=float)
+        row_extent = float(np.abs(row_coords[-1] - row_coords[0]))
+    if col_dim in preview.coords and preview.coords[col_dim].size > 1:
+        col_coords = np.asarray(preview.coords[col_dim].values, dtype=float)
+        col_extent = float(np.abs(col_coords[-1] - col_coords[0]))
+    if row_extent <= 0 or col_extent <= 0:
+        return (5.4, 4.8)
+    image_aspect = col_extent / row_extent
+    figure_height = 4.8
+    figure_width = float(np.clip(1.8 + figure_height * image_aspect, 5.0, 8.8))
+    return figure_width, figure_height
+
+
+def _save_map_plot(
+    data: xr.DataArray,
+    output_path: Path,
+    cmap: str,
+    cbar_label: str,
+    vmin: float | None = None,
+    vmax: float | None = None,
+) -> Path:
+    """Save one dark-themed spatial QC plot."""
+    preview, slice_mode, slice_coord = _prepare_preview_map(data)
+    figure = plt.figure(
+        figsize=_get_map_figsize(preview, slice_mode),
+        constrained_layout=True,
+    )
+    try:
+        figure.patch.set_alpha(0.0)
+        subfig: matplotlib.figure.Figure = figure.subfigures(1, 1)[0]
+        subfig.patch.set_alpha(0.0)
+        ax = subfig.subplots(1, 1)
+        if vmin is None or vmax is None:
+            vmin, vmax = np.nanpercentile(preview.values, [1.0, 99.0])
+        cf.plotting.plot_volume(
+            preview,
+            slice_mode=slice_mode,
+            slice_coords=[slice_coord],
+            figure=subfig,
+            axes=np.asarray([[ax]]),
+            cmap=cmap,
+            black_bg=True,
+            show_titles=False,
+            show_colorbar=True,
+            cbar_label=cbar_label,
+            vmin=vmin,
+            vmax=vmax,
+        )
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        figure.savefig(output_path, dpi=150, bbox_inches="tight", transparent=True)
+        return output_path
+    finally:
+        plt.close(figure)
+
+
+def _save_dvars_plot(power_doppler: xr.DataArray, output_path: Path) -> Path:
+    """Save one dark-themed DVARS plot."""
+    figure, ax = plt.subplots(figsize=(8.6, 3.6), constrained_layout=True)
+    try:
+        figure.patch.set_alpha(0.0)
+        ax.set_facecolor("none")
+        dvars = compute_dvars(power_doppler)
+        ax.plot(dvars.coords["time"], dvars.values, linewidth=1.2, color="white")
+        ax.set_xlabel("Time (s)")
+        ax.set_ylabel("DVARS")
+        ax.grid(alpha=0.25, color="white")
+        ax.tick_params(colors="white")
+        ax.xaxis.label.set_color("white")
+        ax.yaxis.label.set_color("white")
+        for spine in ax.spines.values():
+            spine.set_color("white")
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        figure.savefig(output_path, dpi=150, bbox_inches="tight", transparent=True)
+        return output_path
+    finally:
+        plt.close(figure)
+
+
+def _save_carpet_plot(power_doppler: xr.DataArray, output_path: Path) -> Path:
+    """Save one dark-themed carpet plot."""
+    figure, ax = plt.subplots(figsize=(9.2, 3.8), constrained_layout=True)
+    try:
+        figure.patch.set_alpha(0.0)
+        power_doppler.fusi.plot.carpet(ax=ax, title=None, black_bg=True)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        figure.savefig(output_path, dpi=150, bbox_inches="tight", transparent=True)
+        return output_path
+    finally:
+        plt.close(figure)
+
+
+def _save_recording_plots(
+    config: QcConfig,
+    recording: PwdRecording,
+    pwd: xr.DataArray,
+) -> dict[str, Path]:
+    """Save all QC plots for one recording."""
+    output_paths = get_qc_plot_paths(config, recording)
+    mean_image = pwd.mean(dim="time").compute().fusi.scale.db()
+    cv_map = compute_cv(pwd)
+    _save_map_plot(
+        mean_image,
+        output_paths["mean_power_doppler"],
+        "gray",
+        "Mean power Doppler (dB)",
+    )
+    _save_map_plot(cv_map, output_paths["cv"], "magma", "CV", vmin=0.0, vmax=1.0)
+    _save_carpet_plot(pwd, output_paths["carpet"])
+    _save_dvars_plot(pwd, output_paths["dvars"])
+    return output_paths
+
+
+def _plots_exist(config: QcConfig, recording: PwdRecording) -> bool:
+    """Return True if all QC plot files exist for a recording."""
+    return all(p.exists() for p in get_qc_plot_paths(config, recording).values())
+
+
+def _refresh_one_recording(
+    bids_root: str,
+    output_dir: str,
+    recording_dict: dict[str, str],
+    existing_row: dict[str, str] | None,
+    force: bool,
+) -> dict[str, str]:
+    """Refresh one recording row in a worker process."""
+    config = QcConfig(bids_root=Path(bids_root), output_dir=Path(output_dir))
+    recording = PwdRecording(
+        pwd_path=Path(recording_dict["pwd_path"]),
+        session_label=recording_dict["session_label"],
+        subject=recording_dict["subject"],
+        session=recording_dict["session"],
+        task=recording_dict["task"],
+        run=recording_dict["run"],
+    )
+    if not force and _plots_exist(config, recording) and existing_row is not None:
+        return existing_row
+    pwd = cf.load(recording.pwd_path).compute()
+    if not _plots_exist(config, recording) or force:
+        _save_recording_plots(config, recording, pwd)
+    qc_status = "pending"
+    qc_notes = ""
+    if existing_row is not None:
+        qc_status = existing_row.get("qc_status", "") or "pending"
+        qc_notes = existing_row.get("qc_notes", "") or ""
+    return {
+        "pwd_path": str(recording.pwd_path),
+        "session_label": recording.session_label,
+        "subject": recording.subject,
+        "session": recording.session,
+        "task": recording.task,
+        "run": recording.run,
+        "n_timepoints": str(pwd.sizes["time"]),
+        "qc_status": qc_status,
+        "qc_notes": qc_notes,
+    }
+
+
+def refresh_qc_table(
+    config: QcConfig, force: bool = False
+) -> tuple[pd.DataFrame, Path]:
+    """Refresh plots and the QC TSV."""
+    recordings = discover_pwd_recordings(config)
+    if not recordings:
+        raise FileNotFoundError(
+            f"No supported *_pwd recordings found under {config.bids_root}."
+        )
+    existing = load_qc_table(config)
+    existing_rows = {
+        row["pwd_path"]: row.to_dict()
+        for _, row in existing.iterrows()
+        if row.get("pwd_path", "")
+    }
+    rows: list[dict[str, str]] = []
+    worker_count = (
+        _default_workers() if config.workers is None else max(1, config.workers)
+    )
+    action = "Refreshing QC table" if not force else "Generating QC assets"
+    CONSOLE.log(f"{action} for {len(recordings)} recording(s)")
+    if worker_count == 1:
+        for recording in track(recordings, description=action, console=CONSOLE):
+            rows.append(
+                _refresh_one_recording(
+                    str(config.bids_root),
+                    str(config.output_dir),
+                    {
+                        "pwd_path": str(recording.pwd_path),
+                        "session_label": recording.session_label,
+                        "subject": recording.subject,
+                        "session": recording.session,
+                        "task": recording.task,
+                        "run": recording.run,
+                    },
+                    existing_rows.get(str(recording.pwd_path)),
+                    force,
+                )
+            )
+    else:
+        CONSOLE.log(f"Using {worker_count} worker(s)")
+        with ProcessPoolExecutor(max_workers=worker_count) as executor:
+            future_to_recording = {
+                executor.submit(
+                    _refresh_one_recording,
+                    str(config.bids_root),
+                    str(config.output_dir),
+                    {
+                        "pwd_path": str(recording.pwd_path),
+                        "session_label": recording.session_label,
+                        "subject": recording.subject,
+                        "session": recording.session,
+                        "task": recording.task,
+                        "run": recording.run,
+                    },
+                    existing_rows.get(str(recording.pwd_path)),
+                    force,
+                ): recording
+                for recording in recordings
+            }
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(),
+                MofNCompleteColumn(),
+                TimeElapsedColumn(),
+                console=CONSOLE,
+            ) as progress:
+                task_id = progress.add_task(action, total=len(future_to_recording))
+                for future in as_completed(future_to_recording):
+                    rows.append(future.result())
+                    progress.advance(task_id)
+    table = pd.DataFrame(rows, columns=QC_COLUMNS).sort_values(
+        ["subject", "session", "task", "run", "session_label"]
+    )
+    tsv_path = save_qc_table(config, table)
+    CONSOLE.log(f"Saved QC table: {tsv_path}")
+    return table, tsv_path
+
+
+def update_qc_entry(
+    config: QcConfig, pwd_path: str, qc_status: str, qc_notes: str
+) -> Path:
+    """Update one QC row and save the TSV."""
+    table = load_qc_table(config).copy()
+    row_mask = table["pwd_path"] == pwd_path
+    if not row_mask.any():
+        raise ValueError(f"No QC row found for recording {pwd_path!r}.")
+    table.loc[row_mask, "qc_status"] = qc_status
+    table.loc[row_mask, "qc_notes"] = qc_notes
+    return save_qc_table(config, table)

fusiqc-0.0.1a1/src/fusiqc/_web.py

@@ -0,0 +1,248 @@
+"""Small local QC review web app."""
+
+from __future__ import annotations
+
+import html
+import json
+import mimetypes
+import urllib.parse
+import webbrowser
+from pathlib import Path
+from wsgiref.simple_server import make_server
+
+from rich.console import Console
+
+from fusiqc._config import QcConfig
+from fusiqc._dataset import PwdRecording, get_session_label_from_pwd_path
+from fusiqc._qc import (
+    QC_PANELS,
+    get_qc_plot_paths,
+    load_qc_table,
+    update_qc_entry,
+)
+
+QC_STATUSES = ("pending", "good", "bad")
+METADATA_FIELDS = (
+    "session_label",
+    "subject",
+    "session",
+    "task",
+    "run",
+    "n_timepoints",
+)
+CONSOLE = Console()
+
+
+def _ok(start_response, payload: str = "ok") -> list[bytes]:
+    start_response("200 OK", [("Content-Type", "text/plain; charset=utf-8")])
+    return [payload.encode("utf-8")]
+
+
+def _get_filtered_table(config: QcConfig, status_filter: str):
+    table = load_qc_table(config)
+    if status_filter == "all":
+        return table, table
+    filtered = table.loc[table["qc_status"] == status_filter].reset_index(drop=True)
+    return table, filtered
+
+
+def _render_filter_links(status_filter: str, counts: dict[str, int]) -> str:
+    labels = (("pending", "Pending"), ("good", "Good"), ("bad", "Bad"), ("all", "All"))
+    links = []
+    for value, label in labels:
+        active_class = "active" if value == status_filter else ""
+        links.append(
+            f'<a class="filter-chip {active_class}" href="/?status={value}&index=0&panel=mean_power_doppler">{label} <span>{counts[value]}</span></a>'
+        )
+    return "".join(links)
+
+
+def _render_empty_page(status_filter: str, table) -> str:
+    counts = {
+        "pending": int((table["qc_status"] == "pending").sum()),
+        "good": int((table["qc_status"] == "good").sum()),
+        "bad": int((table["qc_status"] == "bad").sum()),
+        "all": int(len(table)),
+    }
+    filter_links = _render_filter_links(status_filter, counts)
+    return f"""
+<!doctype html>
+<html><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>fUSIQC</title><link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
+<style>
+:root {{ --pico-font-size: 95%; --panel-bg: #0e1420; --panel-border: #243247; }}
+main {{ max-width: 1400px; margin: 0 auto; padding: 1.5rem 1rem 3rem; }}
+.toolbar {{ display: flex; justify-content: space-between; gap: 1rem; align-items: center; flex-wrap: wrap; margin-bottom: 1rem; }}
+.filter-bar {{ display: flex; gap: 0.75rem; flex-wrap: wrap; }}
+.filter-chip {{ padding: 0.45rem 0.8rem; border-radius: 0.35rem; text-decoration: none; background: var(--pico-muted-border-color); color: inherit; }}
+.filter-chip.active {{ background: var(--pico-primary); color: white; }}
+.filter-chip span {{ opacity: 0.8; margin-left: 0.35rem; }}
+.muted {{ color: var(--pico-muted-color); }}
+</style></head>
+<body><main><header><h1>fUSIQC</h1><p class="muted">Review quicklooks and update the TSV directly from the browser.</p></header>
+<div class="toolbar"><div class="filter-bar">{filter_links}</div></div>
+<article><h2>No {html.escape(status_filter)} recordings left.</h2><p><a href="/?status=all&index=0&panel=mean_power_doppler">Open all recordings</a></p></article></main></body></html>
+"""
+
+
+def _serve_qc_plot(
+    config: QcConfig, start_response, query: dict[str, list[str]]
+) -> list[bytes]:
+    pwd_path = query.get("pwd_path", [""])[0]
+    panel = query.get("panel", ["mean_power_doppler"])[0]
+    allowed_panels = set(QC_PANELS)
+    if not pwd_path or panel not in allowed_panels:
+        start_response("404 Not Found", [("Content-Type", "text/plain; charset=utf-8")])
+        return [b"QC plot not found."]
+    recording = Path(pwd_path)
+    rec = PwdRecording(
+        pwd_path=recording,
+        session_label=get_session_label_from_pwd_path(recording),
+        subject=recording.parts[-4].removeprefix("sub-"),
+        session=recording.parts[-3].removeprefix("ses-"),
+        task="",
+        run="",
+    )
+    plot_path = get_qc_plot_paths(config, rec)[panel]
+    figures_root = config.figures_dir.resolve()
+    if not plot_path.exists() or not plot_path.resolve().is_relative_to(figures_root):
+        start_response("404 Not Found", [("Content-Type", "text/plain; charset=utf-8")])
+        return [b"QC plot not found."]
+    mime_type = mimetypes.guess_type(plot_path.name)[0] or "image/png"
+    start_response("200 OK", [("Content-Type", mime_type)])
+    return [plot_path.read_bytes()]
+
+
+def _render_page(config: QcConfig, query: dict[str, list[str]]) -> str:
+    status_filter = query.get("status", [""])[0] or "pending"
+    if status_filter not in (*QC_STATUSES, "all"):
+        status_filter = "pending"
+    table, filtered = _get_filtered_table(config, status_filter)
+    if filtered.empty:
+        return _render_empty_page(status_filter, table)
+    counts = {
+        "pending": int((table["qc_status"] == "pending").sum()),
+        "good": int((table["qc_status"] == "good").sum()),
+        "bad": int((table["qc_status"] == "bad").sum()),
+        "all": int(len(table)),
+    }
+    initial_index = int(query.get("index", ["0"])[0])
+    initial_index = max(0, min(initial_index, len(filtered) - 1))
+    initial_panel = query.get("panel", [QC_PANELS[0]])[0]
+    if initial_panel not in QC_PANELS:
+        initial_panel = QC_PANELS[0]
+    status_links = _render_filter_links(status_filter, counts)
+    rows_json = json.dumps(table.to_dict(orient="records"))
+    filtered_indices_json = json.dumps(
+        table.index[table["qc_status"] == status_filter].to_list()
+        if status_filter != "all"
+        else table.index.to_list()
+    )
+    panel_labels_json = json.dumps(
+        {
+            "mean_power_doppler": "Power Doppler",
+            "cv": "CV",
+            "carpet": "Carpet plot",
+            "dvars": "DVARS",
+        }
+    )
+    metadata_fields_json = json.dumps(METADATA_FIELDS)
+    initial_filter_json = json.dumps(status_filter)
+    initial_index_json = json.dumps(initial_index)
+    initial_panel_json = json.dumps(initial_panel)
+    return f"""
+<!doctype html>
+<html><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>fUSIQC</title><link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
+<style>
+:root {{ --pico-font-size: 95%; --panel-bg: #0e1420; --panel-border: #243247; }}
+main {{ max-width: 1400px; margin: 0 auto; padding: 1.5rem 1rem 3rem; }}
+.layout {{ display: grid; grid-template-columns: 1fr; gap: 1.25rem; align-items: start; }}
+.toolbar {{ display: flex; justify-content: space-between; gap: 1rem; align-items: center; flex-wrap: wrap; margin-bottom: 1rem; }}
+.filter-bar {{ display: flex; gap: 0.75rem; flex-wrap: wrap; }}
+.filter-chip {{ padding: 0.45rem 0.8rem; border-radius: 0.35rem; text-decoration: none; background: var(--pico-muted-border-color); color: inherit; }}
+.filter-chip.active {{ background: var(--pico-primary); color: white; }}
+.filter-chip span {{ opacity: 0.8; margin-left: 0.35rem; }}
+.nav-links {{ display: flex; gap: 1.15rem; align-items: center; flex-wrap: wrap; }}
+.quicklook-panel {{ background: var(--panel-bg); border: 1px solid var(--panel-border); border-radius: 0.5rem; padding: 1rem 1rem 0.45rem; }}
+.viewer-footer {{ display: flex; justify-content: flex-start; margin-top: 0.75rem; padding-left: 0.15rem; }}
+.panel-tabs {{ display: flex; gap: 0.5rem; flex-wrap: wrap; justify-content: flex-start; }}
+.panel-tab {{ border-radius: 0.35rem; padding: 0.35rem 0.8rem; border: 1px solid var(--panel-border); background: rgba(255,255,255,0.04); color: white; cursor: pointer; }}
+.panel-tab.active {{ background: rgba(255,255,255,0.16); }}
+.session-nav-button {{ border-radius: 0.35rem; padding: 0.45rem 0.8rem; }}
+.quicklook-container {{ display: flex; justify-content: center; align-items: center; min-height: 360px; }}
+.quicklook-panel img {{ width: auto; max-width: 100%; max-height: 380px; height: auto; border-radius: 0.35rem; display: block; }}
+.quicklook-empty {{ display: flex; align-items: center; justify-content: center; min-height: 360px; color: white; opacity: 0.8; }}
+.controls-stack {{ display: grid; grid-template-columns: minmax(0, 1fr) minmax(320px, 1fr); gap: 1rem; align-items: start; }}
+.status-buttons {{ display: flex; gap: 0.75rem; flex-wrap: nowrap; margin-bottom: 1rem; }}
+.status-button {{ flex: 1 1 0; min-width: 0; border-radius: 0.35rem; font-weight: 600; }}
+.status-button.good {{ border-color: #2f9e44; color: #2f9e44; background: rgba(47, 158, 68, 0.08); }}
+.status-button.good.selected {{ background: #2f9e44; color: white; }}
+.status-button.bad {{ border-color: #d9485f; color: #d9485f; background: rgba(217, 72, 95, 0.08); }}
+.status-button.bad.selected {{ background: #d9485f; color: white; }}
+.status-button.pending {{ border-color: #f08c00; color: #c76b00; background: rgba(240, 140, 0, 0.1); }}
+.status-button.pending.selected {{ background: #f08c00; color: white; }}
+.metadata-table th {{ width: 36%; }}
+textarea {{ min-height: 150px; }}
+.muted {{ color: var(--pico-muted-color); }}
+.autosave-status {{ min-height: 1.2rem; font-size: 0.9rem; }}
+@media (max-width: 980px) {{ .controls-stack {{ grid-template-columns: 1fr; }} }}
+</style></head>
+<body><main><header><h1>fUSIQC</h1><p class="muted">Review quicklooks and update the TSV directly from the browser.</p></header>
+<div class="toolbar"><div class="filter-bar">{status_links}</div><div class="nav-links"><span id="position-label" class="muted"></span><button id="previous-button" type="button" class="secondary outline session-nav-button">Previous</button><button id="next-button" type="button" class="secondary outline session-nav-button">Next</button></div></div>
+<div class="layout"><article class="quicklook-panel"><div><h2 id="session-title" style="margin-bottom: 0.25rem; color: white;"></h2></div><div id="quicklook-container" class="quicklook-container"></div><div class="viewer-footer"><div id="panel-tabs" class="panel-tabs"></div></div></article>
+<section class="controls-stack"><article><label><strong>QC status</strong></label><div id="status-buttons" class="status-buttons"></div><label for="qc_notes"><strong>Notes</strong></label><textarea id="qc_notes" name="qc_notes"></textarea><div id="autosave-status" class="autosave-status muted"></div></article><article><table id="metadata-table" class="metadata-table"></table></article></section></div></main>
+<script>
+const qcRows = {rows_json}; let currentFilter = {initial_filter_json}; let currentPanel = {initial_panel_json}; let filteredRowIndices = {filtered_indices_json}; let currentPosition = {initial_index_json};
+const panelLabels = {panel_labels_json}; const metadataFields = {metadata_fields_json};
+const notesArea = document.getElementById('qc_notes'); const autosaveStatus = document.getElementById('autosave-status'); const quicklookContainer = document.getElementById('quicklook-container'); const metadataTable = document.getElementById('metadata-table'); const statusButtonsContainer = document.getElementById('status-buttons'); const previousButton = document.getElementById('previous-button'); const nextButton = document.getElementById('next-button'); const positionLabel = document.getElementById('position-label'); const sessionTitle = document.getElementById('session-title'); const panelTabs = document.getElementById('panel-tabs'); let autosaveTimer = null; let autosaveCounter = 0; let suppressNotesAutosave = false;
+function filterIndices() {{ if (currentFilter === 'all') return qcRows.map((_, idx) => idx); return qcRows.flatMap((row, idx) => row.qc_status === currentFilter ? [idx] : []); }}
+function getCurrentRow() {{ return qcRows[filteredRowIndices[currentPosition]]; }}
+function qcPlotUrl(pwdPath, panel) {{ return `/qc_plot?pwd_path=${{encodeURIComponent(pwdPath)}}&panel=${{encodeURIComponent(panel)}}`; }}
+function updateUrl() {{ const params = new URLSearchParams({{ status: currentFilter, index: String(currentPosition), panel: currentPanel }}); window.history.replaceState(null, '', `/?${{params.toString()}}`); }}
+function renderFilterCounts() {{ const counts = {{ pending: 0, good: 0, bad: 0, all: qcRows.length }}; qcRows.forEach((row) => {{ if (row.qc_status in counts) counts[row.qc_status] += 1; }}); document.querySelectorAll('.filter-chip').forEach((chip) => {{ const href = chip.getAttribute('href') || ''; const status = new URL(href, window.location.origin).searchParams.get('status'); chip.classList.toggle('active', status === currentFilter); const span = chip.querySelector('span'); if (span && status in counts) span.textContent = counts[status]; }}); }}
+function renderPanelTabs() {{ panelTabs.innerHTML = Object.entries(panelLabels).map(([panel, label]) => `<button type="button" class="panel-tab ${{panel === currentPanel ? 'active' : ''}}" data-panel="${{panel}}">${{label}}</button>`).join(''); panelTabs.querySelectorAll('[data-panel]').forEach((button) => {{ button.addEventListener('click', () => {{ currentPanel = button.dataset.panel; renderCurrentRow(false); }}); }}); }}
+function renderMetadata(row) {{ metadataTable.innerHTML = metadataFields.map((field) => `<tr><th>${{field}}</th><td>${{row[field] ?? ''}}</td></tr>`).join(''); }}
+async function updateStatus(nextStatus) {{ const row = getCurrentRow(); await fetch('/update_status', {{ method: 'POST', headers: {{ 'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8' }}, body: new URLSearchParams({{ pwd_path: row.pwd_path, qc_status: nextStatus, qc_notes: notesArea.value }}) }}); row.qc_status = nextStatus; row.qc_notes = notesArea.value; filteredRowIndices = filterIndices(); if (filteredRowIndices.length === 0) {{ window.location.href = `/?status=${{encodeURIComponent(currentFilter)}}&index=0&panel=${{encodeURIComponent(currentPanel)}}`; return; }} const currentRowIndex = qcRows.indexOf(row); const nextFilteredPosition = filteredRowIndices.indexOf(currentRowIndex); currentPosition = nextFilteredPosition === -1 ? Math.min(currentPosition, filteredRowIndices.length - 1) : nextFilteredPosition; renderCurrentRow(); }}
+function renderStatusButtons(row) {{ statusButtonsContainer.innerHTML = ['good', 'bad', 'pending'].map((status) => `<button type="button" class="status-button ${{status}} ${{row.qc_status === status ? 'selected' : ''}}" data-status="${{status}}">${{status.charAt(0).toUpperCase() + status.slice(1)}}</button>`).join(''); statusButtonsContainer.querySelectorAll('[data-status]').forEach((button) => {{ button.addEventListener('click', async () => {{ await updateStatus(button.dataset.status); }}); }}); }}
+function preloadAdjacentImages() {{ [currentPosition - 1, currentPosition + 1].forEach((position) => {{ if (position < 0 || position >= filteredRowIndices.length) return; const adjacentRow = qcRows[filteredRowIndices[position]]; const image = new Image(); image.src = qcPlotUrl(adjacentRow.pwd_path, currentPanel); }}); }}
+function renderQuicklook(row) {{ const img = document.createElement('img'); img.src = qcPlotUrl(row.pwd_path, currentPanel); img.alt = panelLabels[currentPanel]; img.onerror = () => {{ quicklookContainer.innerHTML = '<div class="quicklook-empty">No QC plot available for this recording.</div>'; }}; quicklookContainer.innerHTML = ''; quicklookContainer.appendChild(img); }}
+function renderCurrentRow(updateNotes = true) {{ const row = getCurrentRow(); updateUrl(); renderFilterCounts(); renderPanelTabs(); positionLabel.textContent = `Viewing ${{currentPosition + 1}} / ${{filteredRowIndices.length}} in filter "${{currentFilter}}".`; previousButton.disabled = currentPosition === 0; nextButton.disabled = currentPosition >= filteredRowIndices.length - 1; sessionTitle.textContent = row.session_label; renderMetadata(row); renderStatusButtons(row); if (updateNotes) {{ suppressNotesAutosave = true; notesArea.value = row.qc_notes || ''; suppressNotesAutosave = false; }} renderQuicklook(row); preloadAdjacentImages(); }}
+function scheduleAutosave() {{ if (suppressNotesAutosave) return; autosaveStatus.textContent = 'Saving notes...'; const requestId = ++autosaveCounter; clearTimeout(autosaveTimer); autosaveTimer = setTimeout(async () => {{ const row = getCurrentRow(); const body = new URLSearchParams({{ pwd_path: row.pwd_path, qc_status: row.qc_status, qc_notes: notesArea.value }}); try {{ await fetch('/update_notes', {{ method: 'POST', headers: {{ 'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8' }}, body }}); row.qc_notes = notesArea.value; if (requestId === autosaveCounter) autosaveStatus.textContent = 'Notes saved.'; }} catch (error) {{ autosaveStatus.textContent = 'Failed to save notes.'; }} }}, 400); }}
+notesArea.addEventListener('input', scheduleAutosave); previousButton.addEventListener('click', () => {{ if (currentPosition > 0) {{ currentPosition -= 1; renderCurrentRow(); }} }}); nextButton.addEventListener('click', () => {{ if (currentPosition < filteredRowIndices.length - 1) {{ currentPosition += 1; renderCurrentRow(); }} }}); renderCurrentRow();
+</script></body></html>
+"""
+
+
+def launch_web_app(
+    config: QcConfig, host: str, port: int, open_browser: bool = True
+) -> None:
+    """Launch the local QC review app."""
+
+    def app(environ, start_response):
+        method = environ.get("REQUEST_METHOD", "GET")
+        path = environ.get("PATH_INFO", "/")
+        query = urllib.parse.parse_qs(environ.get("QUERY_STRING", ""))
+        if method == "GET" and path == "/qc_plot":
+            return _serve_qc_plot(config, start_response, query)
+        if method == "POST" and path in {"/update_notes", "/update_status"}:
+            content_length = int(environ.get("CONTENT_LENGTH", "0") or "0")
+            body = environ["wsgi.input"].read(content_length).decode("utf-8")
+            form = urllib.parse.parse_qs(body)
+            update_qc_entry(
+                config,
+                pwd_path=form.get("pwd_path", [""])[0],
+                qc_status=form.get("qc_status", ["pending"])[0],
+                qc_notes=form.get("qc_notes", [""])[0],
+            )
+            return _ok(start_response)
+        page = _render_page(config, query)
+        start_response("200 OK", [("Content-Type", "text/html; charset=utf-8")])
+        return [page.encode("utf-8")]
+
+    url = f"http://{host}:{port}"
+    if open_browser:
+        webbrowser.open(url)
+    CONSOLE.log(f"Starting QC web app at {url}")
+    with make_server(host, port, app) as server:
+        server.serve_forever()