itasc 0.2.0.dev0__py3-none-any.whl

itasc/napari/contact_analysis/__init__.py

@@ -0,0 +1,6 @@
+"""napari layer for Contact Analysis.
+
+Hosts the analysis-plugin contract and built-in plugins (see
+:mod:`itasc.napari.contact_analysis.plugins`) used by the Aggregate
+Quantification studio.
+"""

itasc/napari/contact_analysis/curation_controller.py

@@ -0,0 +1,94 @@
+"""The Qt-free editing controller behind the napari curation tool.
+
+It is the single seam the :class:`CurationWidget` talks to: it owns the curation
+CSV path, loads it on construction (empty when absent), mutates it through the
+pure authoring ops in :mod:`itasc.contact_analysis.curation`, and
+**auto-saves** after every change so the table is always the source of truth. It
+exposes per-position queries so the widget renders badges/lists without touching
+pandas. Keeping it Qt-free keeps the table logic unit-testable headless.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from itasc.contact_analysis.curation import (
+    append_exclusion,
+    empty_curation,
+    read_curation,
+    remove_exclusion,
+    write_curation,
+)
+
+
+class CurationController:
+    """Load → mutate-and-autosave → query over one curation CSV."""
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path)
+        loaded = read_curation(self.path)
+        self.curation = empty_curation() if loaded is None else loaded
+
+    # --------------------------------------------------------------- mutations
+    def exclude_frame(
+        self, *, experiment_id: str, position_id: str, frame: int, reason: str
+    ) -> None:
+        self.curation = append_exclusion(
+            self.curation,
+            experiment_id=experiment_id,
+            position_id=position_id,
+            frame=int(frame),
+            reason=reason,
+        )
+        self._save()
+
+    def exclude_position(
+        self, *, experiment_id: str, position_id: str, reason: str
+    ) -> None:
+        self.curation = append_exclusion(
+            self.curation,
+            experiment_id=experiment_id,
+            position_id=position_id,
+            frame=None,
+            reason=reason,
+        )
+        self._save()
+
+    def remove(
+        self, *, experiment_id: str, position_id: str, frame: int | None
+    ) -> None:
+        self.curation = remove_exclusion(
+            self.curation,
+            experiment_id=experiment_id,
+            position_id=position_id,
+            frame=None if frame is None else int(frame),
+        )
+        self._save()
+
+    # ----------------------------------------------------------------- queries
+    def exclusions_for(self, *, experiment_id: str, position_id: str) -> pd.DataFrame:
+        """The exclusion rows for one position (reset index), for the widget list."""
+        cur = self.curation
+        key = (cur["experiment_id"].astype(str) == str(experiment_id)) & (
+            cur["position_id"].astype(str) == str(position_id)
+        )
+        return cur.loc[key].reset_index(drop=True)
+
+    def is_position_excluded(self, *, experiment_id: str, position_id: str) -> bool:
+        rows = self.exclusions_for(experiment_id=experiment_id, position_id=position_id)
+        return bool(rows["frame"].isna().any())
+
+    def is_frame_excluded(
+        self, *, experiment_id: str, position_id: str, frame: int
+    ) -> bool:
+        rows = self.exclusions_for(experiment_id=experiment_id, position_id=position_id)
+        if rows.empty:
+            return False
+        if rows["frame"].isna().any():
+            return True
+        return bool((pd.to_numeric(rows["frame"], errors="coerce") == float(frame)).any())
+
+    # -------------------------------------------------------------------- save
+    def _save(self) -> None:
+        write_curation(self.path, self.curation)

itasc/napari/contact_analysis/plugins/__init__.py

@@ -0,0 +1,102 @@
+"""Analysis-plugin contract and in-process registry.
+
+The Contact Analysis studio is a thin base that manages a *catalog* of
+positions and hosts pluggable analysis views on top. A plugin is a ``QWidget``
+subclass of :class:`AnalysisPlugin` that declares a ``plugin_id`` +
+``display_name`` and implements :meth:`~AnalysisPlugin.set_context`; the base
+instantiates it and feeds it the currently-selected catalog records.
+
+Plugins are **not** napari manifest contributions — they must not show up as
+top-level dock widgets alongside the real tools. Instead, subclassing
+:class:`AnalysisPlugin` auto-registers the plugin (via ``__init_subclass__``),
+and :func:`available_analysis_plugins` imports every module in this package so
+that dropping a new ``*.py`` file here is all it takes to add a plugin.
+"""
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar
+
+from qtpy.QtWidgets import QWidget
+
+__all__ = [
+    "AnalysisContext",
+    "AnalysisPlugin",
+    "available_analysis_plugins",
+]
+
+
+@dataclass
+class AnalysisContext:
+    """What the base hands a plugin: the in-scope catalog rows + a cached loader.
+
+    ``records`` are normalized catalog dicts (see
+    :mod:`itasc.contact_analysis.catalog`); each has at least
+    ``contact_analysis_path``, ``condition``, ``date``, ``id`` and
+    ``contact_analysis_status``. ``load`` reads (and caches) the
+    :class:`~itasc.contact_analysis.contacts.reader.PositionContactAnalysis` for a row,
+    so plugins do not each re-open the same HDF5.
+    """
+
+    records: list[dict] = field(default_factory=list)
+    viewer: Any | None = None
+    #: Injected by the base; maps a contact-analysis path to its parsed object.
+    loader: Callable[[Path], Any] | None = None
+
+    def load(self, record: dict) -> Any:
+        if self.loader is None:
+            raise RuntimeError("AnalysisContext has no loader configured")
+        return self.loader(Path(record["contact_analysis_path"]))
+
+
+#: plugin_id -> plugin class, populated by ``__init_subclass__``.
+_REGISTRY: dict[str, type[AnalysisPlugin]] = {}
+
+
+class AnalysisPlugin(QWidget):
+    """Base class for Contact Analysis analysis plugins.
+
+    Subclasses set the ``plugin_id`` / ``display_name`` class attributes and
+    override :meth:`set_context`. Defining a subclass with a non-empty
+    ``plugin_id`` registers it; the Contact Analysis studio discovers it
+    via :func:`available_analysis_plugins`.
+    """
+
+    #: Stable key; an empty value marks an intermediate (non-registered) base.
+    plugin_id: ClassVar[str] = ""
+    #: Human-readable label shown in the studio plugin list.
+    display_name: ClassVar[str] = ""
+    #: ``PositionInputs`` field names this plugin needs; the studio greys its
+    #: checkbox for a selection where no in-scope position supplies them. Empty
+    #: means "always available" (e.g. a cohort summary).
+    requires: ClassVar[tuple[str, ...]] = ()
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if cls.plugin_id:
+            _REGISTRY[cls.plugin_id] = cls
+
+    def __init__(self, viewer: object | None = None, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self.viewer = viewer
+
+    def set_context(self, ctx: AnalysisContext) -> None:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+
+def _import_plugin_modules() -> None:
+    """Import every (non-private) submodule so its plugins self-register."""
+    for info in pkgutil.iter_modules(__path__):
+        if info.name.startswith("_"):
+            continue
+        importlib.import_module(f"{__name__}.{info.name}")
+
+
+def available_analysis_plugins() -> list[type[AnalysisPlugin]]:
+    """Return registered plugin classes, sorted by display name."""
+    _import_plugin_modules()
+    return sorted(_REGISTRY.values(), key=lambda cls: cls.display_name.lower())

itasc/napari/contact_analysis/plugins/catalog_summary.py

@@ -0,0 +1,56 @@
+"""Trivial analysis plugin: summarise the in-scope catalog.
+
+This plugin does no per-position analysis; it exists to prove the base ↔ plugin
+seam end-to-end. It reports how many positions are in scope, how they break down
+by condition, and how many are contact-analysis ``ready`` vs ``incomplete``.
+"""
+from __future__ import annotations
+
+from collections import Counter
+
+from qtpy.QtWidgets import QLabel, QVBoxLayout, QWidget
+
+from itasc.contact_analysis.catalog import STATUS_READY
+from itasc.napari.contact_analysis.plugins import AnalysisContext, AnalysisPlugin
+
+
+class CatalogSummaryPlugin(AnalysisPlugin):
+    """Show counts for the currently-selected catalog records."""
+
+    plugin_id = "catalog_summary"
+    display_name = "Catalog Summary"
+
+    def __init__(self, viewer=None, parent: QWidget | None = None) -> None:
+        super().__init__(viewer=viewer, parent=parent)
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(2, 2, 2, 2)
+        layout.setSpacing(4)
+        self._summary_lbl = QLabel("No positions in scope.")
+        self._summary_lbl.setWordWrap(True)
+        layout.addWidget(self._summary_lbl)
+        layout.addStretch()
+
+    def set_context(self, ctx: AnalysisContext) -> None:
+        records = list(ctx.records)
+        if not records:
+            self._summary_lbl.setText("No positions in scope.")
+            return
+
+        total = len(records)
+        ready = sum(
+            1
+            for record in records
+            if record.get("contact_analysis_status") == STATUS_READY
+        )
+        by_condition = Counter(
+            str(record.get("condition", "unknown_condition")) for record in records
+        )
+        condition_lines = "\n".join(
+            f"  • {condition}: {count}"
+            for condition, count in sorted(by_condition.items())
+        )
+        self._summary_lbl.setText(
+            f"{total} position(s) in scope\n"
+            f"  ready: {ready}    incomplete: {total - ready}\n"
+            f"by condition:\n{condition_lines}"
+        )

itasc/napari/contact_analysis/plugins/curation.py

@@ -0,0 +1,247 @@
+"""Curation tool: author the exclusion table by eye, over the contact display.
+
+The image-linked judgement ("scrub through a position, see a bad frame, exclude
+it with a note") is what re-earns napari for Contact Analysis. This
+plugin embeds the contact-visualization display for one selected position and
+turns exclude actions into rows of the curation CSV — via the Qt-free
+:class:`~itasc.napari.contact_analysis.curation_controller.CurationController`,
+which auto-saves so the table is always the source of truth. No plots live here
+(plotting is a downstream concern).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from qtpy.QtWidgets import (
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QListWidget,
+    QListWidgetItem,
+    QPushButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from itasc.contact_analysis.shape_tables import catalogue_root
+from itasc.napari.contact_analysis.curation_controller import (
+    CurationController,
+)
+from itasc.napari.contact_analysis.plugins import (
+    AnalysisContext,
+    AnalysisPlugin,
+)
+from itasc.napari.ui_style import action_button, status_label
+
+#: Qt.UserRole — stores the row's frame (int) or None (whole position) on a list item.
+_FRAME_ROLE = 256
+
+
+class CurationWidget(AnalysisPlugin):
+    """Mark a frame / a whole position excluded with a reason, over the image."""
+
+    plugin_id = "curation"
+    display_name = "Curation"
+
+    def __init__(self, viewer=None, parent: QWidget | None = None) -> None:
+        super().__init__(viewer=viewer, parent=parent)
+        from itasc.napari.contact_analysis_widget import (
+            ContactAnalysisWidget,
+        )
+
+        self._experiment_id: str | None = None
+        self._position_id: str | None = None
+        self._controller: CurationController | None = None
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(2, 2, 2, 2)
+        layout.setSpacing(6)
+
+        self._scope_lbl = QLabel("Select a single position to curate.")
+        self._scope_lbl.setWordWrap(True)
+        layout.addWidget(self._scope_lbl)
+
+        self._path_edit = QLineEdit()
+        self._path_edit.setPlaceholderText("curation.csv (defaults beside the tables)…")
+        self._path_edit.editingFinished.connect(self._on_path_edited)
+        layout.addLayout(self._labelled_row("Curation file:", self._path_edit))
+
+        self._view = ContactAnalysisWidget(viewer=viewer, standalone=False)
+        self._view.pipeline_files_header.setVisible(False)
+        self._view._pipeline_files_section.setVisible(False)
+        layout.addWidget(self._view, 1)
+
+        self._reason_edit = QLineEdit()
+        self._reason_edit.setPlaceholderText("Reason (required)…")
+        self._reason_edit.textChanged.connect(self._update_enabled)
+        layout.addLayout(self._labelled_row("Reason:", self._reason_edit))
+
+        actions = QHBoxLayout()
+        actions.setContentsMargins(0, 0, 0, 0)
+        actions.setSpacing(4)
+        self._exclude_frame_btn = QPushButton("Exclude this frame")
+        action_button(self._exclude_frame_btn, expand=True)
+        self._exclude_frame_btn.clicked.connect(self._on_exclude_frame)
+        self._exclude_position_btn = QPushButton("Exclude this position")
+        action_button(self._exclude_position_btn, expand=True)
+        self._exclude_position_btn.clicked.connect(self._on_exclude_position)
+        actions.addWidget(self._exclude_frame_btn)
+        actions.addWidget(self._exclude_position_btn)
+        layout.addLayout(actions)
+
+        layout.addWidget(QLabel("Exclusions for this position:"))
+        self._exclusions_list = QListWidget()
+        self._exclusions_list.setMaximumHeight(120)
+        layout.addWidget(self._exclusions_list)
+        self._remove_btn = QPushButton("Remove selected")
+        action_button(self._remove_btn)
+        self._remove_btn.clicked.connect(self._on_remove_selected)
+        layout.addWidget(self._remove_btn)
+
+        self._status_lbl = QLabel("")
+        self._status_lbl.setWordWrap(True)
+        status_label(self._status_lbl)
+        layout.addWidget(self._status_lbl)
+
+        self._update_enabled()
+
+    @staticmethod
+    def _labelled_row(label: str, edit: QWidget) -> QHBoxLayout:
+        row = QHBoxLayout()
+        row.setContentsMargins(0, 0, 0, 0)
+        row.setSpacing(4)
+        lbl = QLabel(label)
+        lbl.setFixedWidth(90)
+        row.addWidget(lbl)
+        row.addWidget(edit, 1)
+        return row
+
+    def _current_frame(self) -> int:
+        dims = getattr(self.viewer, "dims", None)
+        step = getattr(dims, "current_step", (0,))
+        return int(step[0]) if step else 0
+
+    def _has_single_position(self) -> bool:
+        return self._position_id is not None and self._controller is not None
+
+    def _reason(self) -> str:
+        return self._reason_edit.text().strip()
+
+    def set_context(self, ctx: AnalysisContext) -> None:
+        if ctx.viewer is not None:
+            self.viewer = ctx.viewer
+        records = list(ctx.records)
+        if len(records) == 1:
+            record = records[0]
+            self._experiment_id = str(record.get("experiment_id", ""))
+            self._position_id = str(record.get("id", ""))
+            self._ensure_controller(records)
+            self._update_display(record)
+            self._scope_lbl.setText(f"Curating position: {self._position_id}")
+        else:
+            self._experiment_id = None
+            self._position_id = None
+            self._controller = None
+            self._clear_display()
+            self._scope_lbl.setText(
+                "Select a single position to curate."
+                if not records
+                else f"{len(records)} positions selected — pick exactly one to curate."
+            )
+        self._refresh_exclusions()
+        self._update_enabled()
+
+    def _ensure_controller(self, records: list[dict]) -> None:
+        text = self._path_edit.text().strip()
+        if text:
+            path = Path(text)
+        else:
+            path = catalogue_root(records) / "curation.csv"
+            self._path_edit.setText(str(path))
+        self._controller = CurationController(path)
+
+    def _on_path_edited(self) -> None:
+        text = self._path_edit.text().strip()
+        if text:
+            self._controller = CurationController(Path(text))
+            self._refresh_exclusions()
+            self._update_enabled()
+
+    def _update_display(self, record: dict) -> None:
+        self._view.set_context(
+            cell_labels=record.get("cell_tracked_labels_path"),
+            nucleus_labels=record.get("nucleus_tracked_labels_path"),
+            out_path=record.get("contact_analysis_path"),
+            status_root=record.get("position_path"),
+        )
+
+    def _clear_display(self) -> None:
+        self._view.set_context(
+            cell_labels=None, nucleus_labels=None, out_path=None, status_root=None
+        )
+
+    def _update_enabled(self) -> None:
+        can_act = self._has_single_position() and bool(self._reason())
+        self._exclude_frame_btn.setEnabled(can_act)
+        self._exclude_position_btn.setEnabled(can_act)
+        self._remove_btn.setEnabled(self._has_single_position())
+
+    def _on_exclude_frame(self) -> None:
+        if not self._has_single_position() or not self._reason():
+            return
+        frame = self._current_frame()
+        self._controller.exclude_frame(
+            experiment_id=self._experiment_id,
+            position_id=self._position_id,
+            frame=frame,
+            reason=self._reason(),
+        )
+        self._status_lbl.setText(f"Status: excluded frame {frame}.")
+        self._refresh_exclusions()
+
+    def _on_exclude_position(self) -> None:
+        if not self._has_single_position() or not self._reason():
+            return
+        self._controller.exclude_position(
+            experiment_id=self._experiment_id,
+            position_id=self._position_id,
+            reason=self._reason(),
+        )
+        self._status_lbl.setText("Status: excluded whole position.")
+        self._refresh_exclusions()
+
+    def _on_remove_selected(self) -> None:
+        if not self._has_single_position():
+            return
+        item = self._exclusions_list.currentItem()
+        if item is None:
+            return
+        frame = item.data(_FRAME_ROLE)
+        self._controller.remove(
+            experiment_id=self._experiment_id,
+            position_id=self._position_id,
+            frame=frame,
+        )
+        self._status_lbl.setText("Status: removed exclusion.")
+        self._refresh_exclusions()
+
+    def _refresh_exclusions(self) -> None:
+        self._exclusions_list.clear()
+        if not self._has_single_position():
+            return
+        rows = self._controller.exclusions_for(
+            experiment_id=self._experiment_id, position_id=self._position_id
+        )
+        import pandas as pd
+
+        for _, row in rows.iterrows():
+            frame = row["frame"]
+            if pd.isna(frame):
+                text = f"whole position — {row['exclusion_reason']}"
+                payload = None
+            else:
+                text = f"frame {int(frame)} — {row['exclusion_reason']}"
+                payload = int(frame)
+            item = QListWidgetItem(text)
+            item.setData(_FRAME_ROLE, payload)
+            self._exclusions_list.addItem(item)

itasc/napari/contact_analysis/plugins/visualize_contacts.py

@@ -0,0 +1,64 @@
+"""Per-position contact visualizer, as an analysis plugin.
+
+This was a hardwired "Visualize position" section inside the studio's Catalogue
+region. It is now a regular :class:`AnalysisPlugin` so it lives in the same list
+as every other analysis (one plugin = one collapsible), instead of being a
+special case the studio assembles by hand.
+
+It wraps the embedded :class:`ContactAnalysisWidget` and drives it from
+the catalogue scope: a single in-scope position is visualized; zero or several
+are ambiguous for one viewer, so the view is cleared.
+"""
+from __future__ import annotations
+
+from qtpy.QtWidgets import QVBoxLayout, QWidget
+
+from itasc.napari.contact_analysis.plugins import AnalysisContext, AnalysisPlugin
+
+
+class VisualizeContactsPlugin(AnalysisPlugin):
+    """Visualize (and compute-if-missing) one selected position's contacts."""
+
+    plugin_id = "visualize_contacts"
+    display_name = "Visualize Contacts"
+    # Deliberately no ``requires``: a row may carry only a loose ``.h5`` (show an
+    # existing result, no labels to gate on) or carry labels (compute on demand).
+    # Gating on ``cell_labels_path`` would wrongly hide it for visualize-only
+    # catalogues; the plugin self-handles missing inputs instead.
+
+    def __init__(self, viewer=None, parent: QWidget | None = None) -> None:
+        super().__init__(viewer=viewer, parent=parent)
+        # Imported lazily: keep the plugin module import cheap and avoid an
+        # import cycle with the widget/studio modules.
+        from itasc.napari.contact_analysis_widget import (
+            ContactAnalysisWidget,
+        )
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        self._view = ContactAnalysisWidget(viewer=viewer, standalone=False)
+        # The embedded widget's own "Pipeline Files" panel is an orchestrator
+        # concept; here the catalogue table is the position source instead.
+        self._view.pipeline_files_header.setVisible(False)
+        self._view._pipeline_files_section.setVisible(False)
+        layout.addWidget(self._view)
+
+    def set_context(self, ctx: AnalysisContext) -> None:
+        """Point the embedded view at the single in-scope position, else clear.
+
+        Catalogue rows from a study scan carry the cell/nucleus label paths; rows
+        from a loose ``.h5`` add or a reloaded CSV carry only the ``.h5``, so
+        those support showing an existing result but not compute-on-demand.
+        """
+        records = list(ctx.records)
+        if len(records) != 1:
+            # Zero or several positions is ambiguous for a single viewer.
+            self._view.set_context(cell_labels=None, nucleus_labels=None, out_path=None)
+            return
+        record = records[0]
+        self._view.set_context(
+            cell_labels=record.get("cell_tracked_labels_path"),
+            nucleus_labels=record.get("nucleus_tracked_labels_path"),
+            out_path=record.get("contact_analysis_path"),
+            status_root=record.get("position_path"),
+        )