pycat-napari 1.6.332__tar.gz → 1.6.333__tar.gz

{pycat_napari-1.6.332 → pycat_napari-1.6.333}/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [1.6.333] - 2026-07-24
+### Added — **Navigator execution-adapter layer, Phase 2: an honest parameter review — seeded, editable, provenance-recorded.**
+The navigator asks *what* to do, not *with which parameters* — but a guided run that silently picks a
+rolling-ball radius (or a segmentation method) the user never saw is worse than asking. Phase 2 adds the
+minimal parameter review, Qt-free at its core:
+- New **`navigator/parameters.py`**: each adapter-covered step declares its **material** parameters (the handful
+  the science turns on, not every argument). `build_param_review(plan, ctx)` seeds them by a declared
+  precedence — **a matching preset → a session value → the grounded function default** — never an invented one.
+  `ReviewedStep` generalises the preset `populate-but-never-lock` contract to the no-preset case too: the user
+  may edit any value, and the edit is tracked as **provenance in the exact `PresetApplication.record()` shape**
+  (`preset_key`, `modified_parameters`, `is_modified`, `parameters`), `preset_key=None` when no preset seeded it.
+- **The reviewed values drive the run.** `run_plan(…, params_by_step=, provenance_by_step=)` merges the reviewed
+  values over the adapter's derived params (routing keys like `active_layer` still come from the adapter) and
+  records the provenance onto each ran step's `StepOutcome`. `tests/navigator/test_navigator_parameters.py`
+  (`base`, 9) pins it: an edited rolling-ball radius makes the guided result equal the **manual operation at
+  that radius** — and *not* at the default — so the edit provably reaches the computation.
+- **The dock surfaces it**: the plan view renders an editable "Review parameters" form (a spin/combo per
+  material parameter, seeded, tooltip-documented) above Run; the Run passes the `ParamReview` through
+  `run_plan_via_central_manager`, which also reports which steps ran with modified parameters. A programmatic
+  run with no form still builds a default-seeded review, so provenance is recorded either way.
+- **Later phases** (per the `navigator_execution_adapters` spec): more adapters one workflow at a time (each
+  behind its route-equivalence test), then dock progress + cancel.
+
 ## [1.6.332] - 2026-07-24
 ### Added — **Navigator execution-adapter layer, Phase 1: "Run analysis" computes a plan through the batch handlers, gate-respecting (guided == batch == manual).**
 `selection_scale` Part 2 established there is no uniform "run this op" — but the batch `_STEP_MAP` handlers ARE

{pycat_napari-1.6.332 → pycat_napari-1.6.333}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycat-napari
-Version: 1.6.332
+Version: 1.6.333
 Summary: Python Condensate Analysis Toolbox - A napari-based tool for biomolecular condensate analysis
 Project-URL: Homepage, https://github.com/BanerjeeLab-repertoire/pycat-napari
 Project-URL: Repository, https://github.com/BanerjeeLab-repertoire/pycat-napari

{pycat_napari-1.6.332 → pycat_napari-1.6.333}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycat-napari"
-version = "1.6.332"
+version = "1.6.333"
 description = "Python Condensate Analysis Toolbox - A napari-based tool for biomolecular condensate analysis"
 readme = "README.md"
 # 3.13 is BLOCKED UPSTREAM, not by PyCAT's own code (which compiles and passes core on 3.13).

{pycat_napari-1.6.332 → pycat_napari-1.6.333}/src/pycat/central_manager.py

@@ -124,7 +124,7 @@ class CentralManager:
         from pycat.ui.navigator_dock import install_navigator_action, run_plan_via_central_manager
         self._navigator_action = install_navigator_action(
             self.viewer, central_manager=self,
-            on_run=lambda plan: run_plan_via_central_manager(self, plan))
+            on_run=lambda plan, review=None: run_plan_via_central_manager(self, plan, review))
         # Populate the feature registry so any consumer (the beginner home dock, a capability query) sees
         # every surfaced-but-otherwise-hidden feature (navigator inc 4). Guarded: a registration hiccup must
         # never break startup, and the cards' openers import Qt/toolbox lazily so this stays cheap.

{pycat_napari-1.6.332 → pycat_napari-1.6.333}/src/pycat/navigator/executor.py

@@ -58,10 +58,13 @@ def has_adapter(step_name: str) -> bool:
 @dataclasses.dataclass(frozen=True)
 class StepOutcome:
     """What happened to one step. ``outcome`` is ``'ran'`` / ``'ran_with_caveat'`` / ``'blocked'`` (the run
-    stops here) / ``'skipped'`` (after a blocker) / ``'needs_panel'`` (no adapter yet) / ``'error'``."""
+    stops here) / ``'skipped'`` (after a blocker) / ``'needs_panel'`` (no adapter yet) / ``'error'``.
+    ``provenance`` (Phase 2) records how the step was parameterised — the ``PresetApplication.record()`` shape
+    (which preset, if any, seeded it and what the user changed) — empty when the step carried no review."""
     name: str
     outcome: str
     detail: str = ""
+    provenance: dict = dataclasses.field(default_factory=dict)
 
 
 @dataclasses.dataclass
@@ -96,6 +99,7 @@ def _build_step_registry() -> dict:
 
 
 def run_plan(plan, state, *, intent=None, ctx=None, image_path=None, output_dir=None, runner=None,
+             params_by_step: Optional[dict] = None, provenance_by_step: Optional[dict] = None,
              on_step: Optional[Callable] = None) -> ExecReport:
     """Execute ``plan``'s steps in gate order by driving the batch handlers, threading ``state`` (a dict the
     handlers read/write, exactly as a batch replay). Returns an :class:`ExecReport`.
@@ -104,7 +108,11 @@ def run_plan(plan, state, *, intent=None, ctx=None, image_path=None, output_dir=
     run at that step (nothing after it runs); a **caveat** runs with the caveat recorded; **probes** run first.
     A step with no :class:`ExecAdapter` is reported ``'needs_panel'`` — never invoked with guessed arguments.
     A step that raises halts the run (downstream depends on its output). ``runner`` (an ``OperationRunner``)
-    runs each handler off the Qt thread when given; otherwise handlers run synchronously (headless / tests)."""
+    runs each handler off the Qt thread when given; otherwise handlers run synchronously (headless / tests).
+
+    ``params_by_step`` (Phase 2) overrides the adapter's derived params per step with the user-reviewed values
+    (:mod:`pycat.navigator.parameters`); ``provenance_by_step`` records how each ran step was parameterised
+    (the ``PresetApplication.record()`` shape) onto its :class:`StepOutcome`."""
     intent = intent if intent is not None else getattr(plan, "intent", None)
     registry = _build_step_registry()
     report = ExecReport()
@@ -143,6 +151,10 @@ def run_plan(plan, state, *, intent=None, ctx=None, image_path=None, output_dir=
                 continue
 
             params = adapter.params_from(intent, ctx, state)
+            if params_by_step and es.name in params_by_step:
+                # Reviewed values override the adapter's derived params, but the adapter still supplies the
+                # non-reviewed routing keys (e.g. active_layer) — merge, don't replace.
+                params = {**params, **params_by_step[es.name]}
             try:
                 if runner is not None:
                     runner.execute(fn, state, image_path, params, output_dir)
@@ -153,8 +165,9 @@ def run_plan(plan, state, *, intent=None, ctx=None, image_path=None, output_dir=
                 halted = True
                 continue
 
+            prov = (provenance_by_step or {}).get(es.name, {})
             report.steps.append(StepOutcome(
-                es.name, "ran_with_caveat" if es.status == "caveat" else "ran", es.reason))
+                es.name, "ran_with_caveat" if es.status == "caveat" else "ran", es.reason, prov))
             if on_step:
                 on_step(report.steps[-1])
     finally:

pycat_napari-1.6.333/src/pycat/navigator/parameters.py

@@ -0,0 +1,192 @@
+"""**The minimal parameter review — surface the handful of parameters that change the result, seeded honestly.**
+
+Execution-adapter layer, Phase 2. The navigator asks *what* to do, not *with which parameters* — but a guided
+run that silently picks a rolling-ball radius (or a segmentation method) the user never saw is worse than
+asking. So before a run, each adapter-covered step surfaces its **material** parameters — the handful that
+materially change the result — in a small editable set, seeded by a declared precedence:
+
+1. **A matching preset** (:mod:`pycat.utils.analysis_presets`) — if one ``applies_to`` this step's workflow,
+   its parameters seed the values (the populate-but-never-lock contract).
+2. **A session value** — a measured/derived value already in the context (e.g. a ``ball_radius`` the user
+   measured on their data) seeds an un-preset parameter.
+3. **The grounded function default** — the same default the batch handler falls back to; never an invented one.
+
+The user may edit any value; the edit is tracked so the run records **which preset (if any) seeded each step
+and what the user changed** — the exact ``PresetApplication.record()`` shape, so a guided result states how it
+was parameterised and a saved template can carry those params. Qt-free: this is the model the dock's editable
+form and :func:`pycat.navigator.executor.run_plan` both read; the dock only builds widgets over it.
+
+Phase 2 ships the model + the one shipped adapter's material set (``background_removal`` → ``ball_radius``);
+later adapters declare their material params here as they land, each still behind a route-equivalence test."""
+from __future__ import annotations
+
+import dataclasses
+from typing import Optional
+
+from .execution import execution_order
+from .executor import has_adapter
+
+
+@dataclasses.dataclass(frozen=True)
+class StepParam:
+    """One material parameter of a step — declared, so the review shows the same handful the science turns on
+    (not every argument the function takes). ``kind`` is ``'int'`` / ``'float'`` / ``'choice'``; ``default`` is
+    the grounded function default (what the batch handler falls back to), never an invented value."""
+    name: str
+    label: str
+    kind: str
+    default: object
+    choices: tuple = ()
+    help: str = ""
+    minimum: object = None
+    maximum: object = None
+
+
+#: The material parameters per plan step — the ONLY place a step declares which of its arguments are surfaced
+#: for review. Grows one adapter at a time (each behind its route-equivalence test), mirroring ``executor._ADAPTERS``.
+_MATERIAL: dict = {
+    "background_removal": (
+        StepParam("ball_radius", "Rolling-ball radius (px)", "int", 50, minimum=1,
+                  help="The rolling-ball structuring radius for background estimation. Larger keeps more "
+                       "low-frequency structure; too small eats real signal. Default 50 px."),
+    ),
+}
+
+
+#: Plan step → the ``analysis_presets`` workflow id whose presets seed it (preset precedence, source 1). Empty
+#: for the shipped adapter (no preset applies to ``background_removal``); entries land with the adapters that a
+#: preset actually configures (e.g. ``condensate_puncta_refinement``), one per phase.
+_PRESET_WORKFLOW: dict = {}
+
+
+def material_params(step_name: str) -> tuple:
+    """The declared material parameters of ``step_name`` (empty if none/unknown)."""
+    return _MATERIAL.get(step_name, ())
+
+
+def _coerce(param: StepParam, value):
+    """Coerce a value to the parameter's kind, falling back to the default on a bad value (never raise into a
+    run) — an int param must not carry a float that changes ``ceil`` downstream."""
+    try:
+        if param.kind == "int":
+            return int(round(float(value)))
+        if param.kind == "float":
+            return float(value)
+    except (TypeError, ValueError):
+        return param.default
+    return value
+
+
+def _applicable_preset(step_name: str):
+    """The single preset that applies to this step's workflow, or ``None``. If more than one applies we return
+    ``None`` (picking one silently would be dishonest — that is a preset-picker choice, not a default)."""
+    workflow = _PRESET_WORKFLOW.get(step_name)
+    if not workflow:
+        return None
+    try:
+        from pycat.utils.analysis_presets import presets_for
+        applicable = presets_for(workflow)
+    except Exception:      # broad-ok: optional_probe — no preset registry → seed from defaults, not a crash
+        return None
+    return applicable[0] if len(applicable) == 1 else None
+
+
+def _seed_value(param: StepParam, preset, ctx):
+    """Seed one parameter by the declared precedence: preset → session value → grounded default."""
+    if preset is not None and param.name in getattr(preset, "parameters", {}):
+        return _coerce(param, preset.parameters[param.name])
+    if ctx is not None:
+        try:
+            cv = ctx.get(param.name)
+        except Exception:      # broad-ok: optional_probe — a non-mapping context just means no session value
+            cv = None
+        if cv is not None:
+            return _coerce(param, cv)
+    return param.default
+
+
+class ReviewedStep:
+    """One step's reviewable parameters: seeded honestly, editable, tracking the deviation from the seed. The
+    populate-but-never-lock contract of :class:`PresetApplication`, generalised to also cover the no-preset
+    case (``preset_key`` is ``None`` then) — because provenance is owed whether or not a preset seeded it."""
+
+    def __init__(self, step_name: str, params, *, preset=None, ctx=None):
+        self.step_name = step_name
+        self.params = tuple(params)
+        self.preset = preset
+        self._seed = {p.name: _seed_value(p, preset, ctx) for p in self.params}
+        self.values = dict(self._seed)
+        self._modified: set = set()
+
+    def _param(self, name) -> Optional[StepParam]:
+        return next((p for p in self.params if p.name == name), None)
+
+    def set(self, name, value):
+        """Set a value (coerced to its kind); mark it modified iff it differs from the seed. Setting it back to
+        the seeded value clears the modification — a result that matches the seed was not 'modified'."""
+        param = self._param(name)
+        if param is None:
+            return self
+        v = _coerce(param, value)
+        if self._seed.get(name) != v:
+            self._modified.add(name)
+        else:
+            self._modified.discard(name)
+        self.values[name] = v
+        return self
+
+    @property
+    def is_modified(self) -> bool:
+        return bool(self._modified)
+
+    def provenance(self) -> dict:
+        """The recorded provenance — the exact :meth:`PresetApplication.record` shape, with ``preset_key``
+        ``None`` when no preset seeded the step. Travels into the run report and a saved template."""
+        return {"preset_key": self.preset.key if self.preset is not None else None,
+                "modified_parameters": sorted(self._modified),
+                "is_modified": self.is_modified,
+                "parameters": dict(self.values)}
+
+
+class ParamReview:
+    """The reviewable parameter set for a whole plan — the adapter-covered, runnable steps that declare
+    material params, each a :class:`ReviewedStep`. The dock renders an editable form over it; the executor
+    reads :meth:`params_by_step` / :meth:`provenance_by_step`."""
+
+    def __init__(self, steps):
+        self.steps = list(steps)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.steps
+
+    def step(self, name) -> Optional[ReviewedStep]:
+        return next((s for s in self.steps if s.step_name == name), None)
+
+    def params_by_step(self) -> dict:
+        return {s.step_name: dict(s.values) for s in self.steps}
+
+    def provenance_by_step(self) -> dict:
+        return {s.step_name: s.provenance() for s in self.steps}
+
+
+def build_param_review(plan, ctx=None) -> ParamReview:
+    """Build the reviewable parameter set for ``plan``: one :class:`ReviewedStep` per adapter-covered step that
+    will actually run (``run`` / ``caveat`` in :func:`execution_order`) and declares material params, seeded by
+    the declared precedence. Blocked/skipped steps carry no review (they will not run). Never invents a
+    parameter — a step with no declared material params contributes nothing to review."""
+    reviewed = []
+    try:
+        order = execution_order(plan)
+    except Exception:      # broad-ok: optional_probe — an un-orderable plan yields an empty review, not a crash
+        order = []
+    for es in order:
+        if es.status not in ("run", "caveat"):
+            continue
+        if not has_adapter(es.name):
+            continue
+        params = material_params(es.name)
+        if not params:
+            continue
+        reviewed.append(ReviewedStep(es.name, params, preset=_applicable_preset(es.name), ctx=ctx))
+    return ParamReview(reviewed)

{pycat_napari-1.6.332 → pycat_napari-1.6.333}/src/pycat/ui/navigator_dock.py

@@ -128,17 +128,25 @@ def _render_observations(widget, body_layout):
                                  "color: gray; font-size: 10px; margin-bottom: 4px;"))
 
 
-def run_plan_via_central_manager(central_manager, plan):
+def run_plan_via_central_manager(central_manager, plan, review=None):
     """Execute a compiled plan against the session's data through the execution-adapter layer, and report
     per-step outcomes. Adapter-covered steps run through the batch handlers (the proven 'same computation'
-    route); a step with no adapter yet is reported as 'run from its panel' — never invoked with guessed args.
-    Safe on an uncovered plan (nothing runs); best-effort, never crashes the UI. This is the wired ``on_run``."""
+    route) with the user-reviewed parameters (Phase 2); a step with no adapter yet is reported as 'run from its
+    panel' — never invoked with guessed args. ``review`` is the :class:`ParamReview` the dock built from its
+    editable form; when ``None`` (a programmatic run), one is built from the plan so parameters are still
+    preset/default-seeded and provenance is still recorded. Safe on an uncovered plan (nothing runs);
+    best-effort, never crashes the UI. This is the wired ``on_run``."""
     try:
         from pycat.navigator.executor import run_plan
         dr = getattr(getattr(central_manager, "active_data_class", None), "data_repository", None)
         if dr is None:
             return
-        report = run_plan(plan, dr, ctx=dr)
+        if review is None:
+            from pycat.navigator.parameters import build_param_review
+            review = build_param_review(plan, ctx=dr)
+        report = run_plan(plan, dr, ctx=dr,
+                          params_by_step=review.params_by_step(),
+                          provenance_by_step=review.provenance_by_step())
         ran = [s.name for s in report.ran]
         panel = [s.name for s in report.needs_panel]
         blocked = [s for s in report.steps if s.outcome == "blocked"]
@@ -149,6 +157,9 @@ def run_plan_via_central_manager(central_manager, plan):
             parts.append(f"Stopped at {blocked[0].name} — {blocked[0].detail}")
         if panel:
             parts.append("Run these from their method panels, in order: " + ", ".join(panel) + ".")
+        modified = [s.name for s in report.ran if s.provenance.get("is_modified")]
+        if modified:
+            parts.append("Parameters modified for: " + ", ".join(modified) + ".")
         from napari.utils.notifications import show_info
         show_info(" ".join(parts) or "Nothing to run.")
     except Exception as exc:      # broad-ok: ui_cleanup — a run attempt must never crash the guided panel
@@ -199,6 +210,68 @@ def _add_template_save(widget, body_layout):
     body_layout.addWidget(btn)
 
 
+def _param_input(param, value, on_change):
+    """One editable control for a material parameter, seeded at ``value``; ``on_change(new_value)`` fires on
+    edit. int → spin box, float → double spin, choice → combo. Returns the widget (or ``None`` on an odd kind)."""
+    from PyQt5.QtWidgets import QSpinBox, QDoubleSpinBox, QComboBox
+    if param.kind == "int":
+        w = QSpinBox()
+        w.setMinimum(int(param.minimum) if param.minimum is not None else 0)
+        w.setMaximum(int(param.maximum) if param.maximum is not None else 100000)
+        w.setValue(int(value))
+        w.valueChanged.connect(lambda v: on_change(v))
+        return w
+    if param.kind == "float":
+        w = QDoubleSpinBox()
+        w.setDecimals(3)
+        w.setMinimum(float(param.minimum) if param.minimum is not None else 0.0)
+        w.setMaximum(float(param.maximum) if param.maximum is not None else 1e9)
+        w.setValue(float(value))
+        w.valueChanged.connect(lambda v: on_change(v))
+        return w
+    if param.kind == "choice":
+        w = QComboBox()
+        w.addItems([str(c) for c in param.choices])
+        if str(value) in [str(c) for c in param.choices]:
+            w.setCurrentText(str(value))
+        w.currentTextChanged.connect(lambda v: on_change(v))
+        return w
+    return None
+
+
+def _add_param_review(widget, body_layout, plan):
+    """Render the editable parameter-review form (Phase 2) and stash the :class:`ParamReview` on the widget as
+    ``_review`` for the run. Surfaces the handful of material parameters per adapter-covered step, seeded from a
+    preset/session value/grounded default (never invented); an edit is tracked so the run records provenance.
+    Renders nothing when no adapter-covered step has material params — the honest 'nothing to review' case."""
+    from PyQt5.QtWidgets import QFrame, QVBoxLayout, QHBoxLayout
+    from pycat.navigator.parameters import build_param_review, material_params
+    try:
+        review = build_param_review(plan, ctx=widget._session.ctx)
+    except Exception:      # broad-ok: ui_cleanup — a review failure must not break the plan view
+        review = None
+    widget._review = review
+    if review is None or review.is_empty:
+        return
+    body_layout.addWidget(_label("⚙  Review parameters", "font-weight: bold; font-size: 12px; margin-top: 6px;"))
+    body_layout.addWidget(_label("Seeded from your data and grounded defaults — edit before running.",
+                                 "color: gray; font-size: 10px;"))
+    for step in review.steps:
+        body_layout.addWidget(_label(step.step_name, "font-weight: bold; font-size: 11px; color: #2a7ab0;"))
+        for param in material_params(step.step_name):
+            frame = QFrame()
+            row = QHBoxLayout(frame)
+            row.setContentsMargins(0, 0, 0, 0)
+            row.addWidget(_label(param.label, "font-size: 11px;"))
+            inp = _param_input(param, step.values.get(param.name, param.default),
+                               lambda v, s=step, n=param.name: s.set(n, v))
+            if inp is not None:
+                if param.help:
+                    inp.setToolTip(param.help)
+                row.addWidget(inp)
+            body_layout.addWidget(frame)
+
+
 def build_navigator_widget(session, *, on_run=None, central_manager=None, parent=None):
     """Build (do not mount) the Navigator widget over ``session``, or return ``None`` if Qt is unavailable
     (headless). ``on_run(plan)`` is called when the user runs the compiled plan. When ``central_manager`` is
@@ -235,6 +308,7 @@ def build_navigator_widget(session, *, on_run=None, central_manager=None, parent
     widget._rows = []
     widget._choice_buttons = []
     widget._run_button = None
+    widget._review = None               # Phase 2: the ParamReview built at plan render, passed to the run
     widget._regate_only = False         # a viewer event re-gates; answering/restart recompiles
     widget._reeval_pending = False
 
@@ -267,6 +341,7 @@ def build_navigator_widget(session, *, on_run=None, central_manager=None, parent
         body_layout.addWidget(_label(_PLAN_LEGEND, "color: gray; font-size: 10px; margin-bottom: 4px;"))
         for row in widget._rows:
             body_layout.addWidget(_row_frame(row))
+        _add_param_review(widget, body_layout, plan)     # Phase 2: the editable, seeded material params
         run = QPushButton("▶  Run analysis")
         reason = widget._session.run_blocked_reason()
         run.setEnabled(reason is None and callable(widget._on_run))
@@ -289,7 +364,11 @@ def build_navigator_widget(session, *, on_run=None, central_manager=None, parent
 
     def _run():
         if callable(widget._on_run) and widget._plan is not None:
-            widget._on_run(widget._plan)
+            review = getattr(widget, "_review", None)
+            try:
+                widget._on_run(widget._plan, review)     # Phase 2: pass the reviewed params
+            except TypeError:
+                widget._on_run(widget._plan)             # a 1-arg on_run (older callers) still works
 
     def _restart():
         widget._session = NavigatorSession()