nirspy 0.2.0__tar.gz → 0.3.0__tar.gz

{nirspy-0.2.0 → nirspy-0.3.0}/CHANGELOG.md

@@ -7,6 +7,28 @@ versionamento por [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-24
+
+### Added
+- **T-023 — PipelineRunner stepable** (PR #36): refactor `execution.py` into stepable executor supporting block-by-block interactive runs.
+- **T-024 — ConditionGroup domain + engine** (PR #37): `ConditionGroup` dataclass, `BlockAverageParams` extension with `event_indices`, `create_epochs_per_group` in `MNEAdapter`, YAML round-trip.
+- **T-025 — Condition groups editor** (PR #39): radio toggle HRF mode + builder editor for condition groups in ParamEditor.
+- **T-027 — Run Interactive button + generic dialog** (PR #40): toggle button, per-block runtime dialog with ParamEditor.
+- **T-028 — HRF specialized 2-stage dialog** (PR #41): grouped conditions + time windows per group in dedicated HRF dialog.
+- **T-030 — Condition timeline selection** (PR #43): individual event occurrence selection via Plotly scatter timeline.
+- **Probe distance check on .nirs→.snirf conversion**: warns about inter-optode distances outside physiological range during format conversion.
+
+### Fixed
+- Preserve `0.0` values in group time fields (falsy fallback bug).
+- Auto-select new group + timeline-first card layout.
+- Wire `snirf_path` through to T-030 timeline in builder.
+- Use correct per-instance key for active group lookup.
+- Clear condition windows/groups on SNIRF path change.
+- Merge probe click callbacks to fix anchor race condition.
+
+### Removed
+- Probe head silhouette, 10-20 grid, and channel interaction (T-026/T-029) — reverted for redesign in future milestone.
+
 ## [0.2.0] - 2026-05-22
 
 ### Added

{nirspy-0.2.0 → nirspy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nirspy
-Version: 0.2.0
+Version: 0.3.0
 Summary: GUI fNIRS-first em Python — builder modular de pipeline sobre MNE-NIRS
 Project-URL: Homepage, https://github.com/BrunoFurlanetto/nirspy
 Project-URL: Repository, https://github.com/BrunoFurlanetto/nirspy

{nirspy-0.2.0 → nirspy-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nirspy"
-version = "0.2.0"
+version = "0.3.0"
 description = "GUI fNIRS-first em Python — builder modular de pipeline sobre MNE-NIRS"
 readme = "README.md"
 license = { file = "LICENSE" }

{nirspy-0.2.0 → nirspy-0.3.0}/src/nirspy/__init__.py

@@ -1,3 +1,3 @@
 """NIRSPY — NIRS Processing in Python."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{nirspy-0.2.0 → nirspy-0.3.0}/src/nirspy/blocks/analysis.py

@@ -55,6 +55,70 @@ def _validate_condition_window(name: str, window: ConditionWindow) -> None:
         )
 
 
+@dataclass(frozen=True)
+class ConditionGroup:
+    """A named group of SNIRF conditions sharing temporal parameters.
+
+    Used by ``BlockAverageParams.per_condition_groups`` to let users
+    aggregate multiple SNIRF condition keys under a custom label with
+    shared tmin/tmax/baseline windows. The label becomes the key in
+    the resulting ``dict[str, Evoked]``.
+
+    Modes (D8)
+    ----------
+    Exactly one of ``condition_names`` or ``event_indices`` must be
+    non-empty.  Using both simultaneously is forbidden — ``__post_init__``
+    raises :class:`~nirspy.domain.exceptions.ValidationError`.
+
+    condition_names:
+        Classic mode (T-024): groups all occurrences of the listed
+        SNIRF condition keys together.
+    event_indices:
+        Timeline mode (T-030): groups specific occurrences identified by
+        their chronological index in ``raw.annotations`` (sorted by onset).
+        Index 0 = first occurrence across *all* stim annotations.
+    """
+
+    label: str
+    condition_names: list[str] = field(default_factory=list)
+    tmin: float = -2.0
+    tmax: float = 18.0
+    baseline_tmin: float = -2.0
+    baseline_tmax: float = 0.0
+    event_indices: list[int] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        """Enforce mutual exclusion between condition_names and event_indices."""
+        has_names = bool(self.condition_names)
+        has_indices = bool(self.event_indices)
+        if has_names and has_indices:
+            raise ValidationError(
+                f"ConditionGroup {self.label!r}: condition_names and "
+                "event_indices are mutually exclusive (D8). "
+                "Populate one or the other, not both."
+            )
+        if not has_names and not has_indices:
+            raise ValidationError(
+                f"ConditionGroup {self.label!r}: either condition_names or "
+                "event_indices must be non-empty."
+            )
+
+
+def _validate_condition_group(name: str, group: ConditionGroup) -> None:
+    """Raise :class:`ValidationError` if *group* has invalid ranges."""
+    if group.tmin >= group.tmax:
+        raise ValidationError(
+            f"ConditionGroup {name!r}: tmin ({group.tmin}) "
+            f"must be < tmax ({group.tmax})."
+        )
+    if group.baseline_tmin > group.baseline_tmax:
+        raise ValidationError(
+            f"ConditionGroup {name!r}: baseline_tmin "
+            f"({group.baseline_tmin}) must be <= baseline_tmax "
+            f"({group.baseline_tmax})."
+        )
+
+
 @dataclass(frozen=True)
 class BlockAverageParams:
     """Parameters for block averaging (HRF computation).
@@ -90,6 +154,9 @@ class BlockAverageParams:
     per_condition_windows: dict[str, ConditionWindow] = field(
         default_factory=dict,
     )
+    per_condition_groups: dict[str, ConditionGroup] = field(
+        default_factory=dict,
+    )
 
     def __post_init__(self) -> None:
         """Coerce raw dicts to ConditionWindow for YAML round-trip.
@@ -125,6 +192,26 @@ class BlockAverageParams:
                     coerced[key] = val
             object.__setattr__(self, "per_condition_windows", coerced)
 
+        # Mutual exclusion: per_condition_windows OR per_condition_groups (D3)
+        if self.per_condition_windows and self.per_condition_groups:
+            raise ValidationError(
+                "BlockAverageParams: per_condition_windows and "
+                "per_condition_groups are mutually exclusive (D3). "
+                "Use one or the other, not both."
+            )
+
+        # Coerce raw dicts to ConditionGroup for YAML round-trip.
+        # event_indices defaults to [] when absent so legacy YAML (T-024,
+        # condition_names only) continues to deserialise without changes.
+        if self.per_condition_groups:
+            coerced_groups: dict[str, ConditionGroup] = {}
+            for grp_key, grp_val in self.per_condition_groups.items():
+                if isinstance(grp_val, dict):
+                    coerced_groups[grp_key] = ConditionGroup(**grp_val)
+                else:
+                    coerced_groups[grp_key] = grp_val
+            object.__setattr__(self, "per_condition_groups", coerced_groups)
+
 
 _BA_SPEC = BlockSpec(
     block_id="block_average",
@@ -244,17 +331,34 @@ class BlockAverageBlock:
         else:
             used_event_id = event_id
 
-        # Validate per_condition_windows keys exist in event_id
-        if self.params.per_condition_windows:
-            unknown = (
-                set(self.params.per_condition_windows) - set(used_event_id)
-            )
+        # Filter per_condition_windows to only keys present in event_id.
+        # Stale keys can appear when the user swaps the SNIRF file while
+        # per-condition windows are already configured. Raising would give
+        # a confusing error; silently discarding (with warning) is correct
+        # because the GUI sync callback (sync_conditions_on_path_change)
+        # already removed them in the GUI path -- this is defence-in-depth
+        # for YAML-loaded pipelines or any other path that bypasses the GUI.
+        # Restores T-012 hotfix (2d7b63d) regressed by T-024 (#37).
+        filtered_pcw: dict[str, ConditionWindow] = dict(
+            self.params.per_condition_windows
+        )
+        if filtered_pcw:
+            unknown = set(filtered_pcw) - set(used_event_id)
             if unknown:
-                raise ValidationError(
+                import warnings
+
+                warnings.warn(
                     f"BlockAverageBlock: per_condition_windows contains "
-                    f"condition(s) {sorted(unknown)} not found in "
-                    f"event_id {sorted(used_event_id.keys())}."
+                    f"condition(s) {sorted(unknown)} not found in the current "
+                    f"SNIRF event_id {sorted(used_event_id.keys())}. "
+                    f"These entries will be skipped (stale keys from a "
+                    f"previous SNIRF file).",
+                    UserWarning,
+                    stacklevel=2,
                 )
+                filtered_pcw = {
+                    k: v for k, v in filtered_pcw.items() if k in used_event_id
+                }
 
         # Build rejection dict
         reject: dict[str, float] | None = None
@@ -264,8 +368,34 @@ class BlockAverageBlock:
                 "hbr": self.params.amplitude_threshold,
             }
 
+        # ---- Per-condition-groups path (T-024) ----
+        if self.params.per_condition_groups:
+            # Validate each group
+            for grp_name, grp in self.params.per_condition_groups.items():
+                _validate_condition_group(grp_name, grp)
+
+            epochs_dict = self._adapter.create_epochs_per_group(
+                raw,
+                groups=self.params.per_condition_groups,
+                reject=reject,
+            )
+            evoked_dict = self._adapter.average_epochs(epochs_dict)
+
+            metadata: dict[str, Any] = {
+                "conditions": list(evoked_dict.keys()),
+                "n_conditions": len(evoked_dict),
+                "n_epochs_total": sum(
+                    len(ep.events) for ep in epochs_dict.values()
+                ),
+                "per_condition_groups_used": True,
+                "tmin": self.params.tmin,
+                "tmax": self.params.tmax,
+            }
+            for grp_label, ep in epochs_dict.items():
+                metadata[f"n_epochs_{grp_label}"] = len(ep.events)
+
         # ---- Per-condition path vs legacy single-Epochs path ----
-        if self.params.per_condition_windows:
+        elif filtered_pcw:
             default_window = (
                 self.params.tmin,
                 self.params.tmax,
@@ -276,7 +406,7 @@ class BlockAverageBlock:
                 raw,
                 used_event_id,
                 default_window=default_window,
-                per_condition_windows=self.params.per_condition_windows,
+                per_condition_windows=filtered_pcw,
                 reject=reject,
             )
             evoked_dict = self._adapter.average_epochs(epochs_dict)
@@ -285,11 +415,11 @@ class BlockAverageBlock:
             windows_used: dict[str, dict[str, float]] = {}
             n_epochs_total = 0
             skipped_conditions: list[str] = []
-            metadata: dict[str, Any] = {}
+            metadata = {}
 
             for cond in used_event_id:
-                if cond in self.params.per_condition_windows:
-                    w = self.params.per_condition_windows[cond]
+                if cond in filtered_pcw:
+                    w = filtered_pcw[cond]
                     windows_used[cond] = {
                         "tmin": w.tmin,
                         "tmax": w.tmax,

{nirspy-0.2.0 → nirspy-0.3.0}/src/nirspy/domain/__init__.py

@@ -4,7 +4,12 @@ from nirspy.domain.block import Block, BlockResult, BlockSpec
 from nirspy.domain.cache import CacheProtocol
 from nirspy.domain.data_types import DataType
 from nirspy.domain.exceptions import DomainError, ExecutionError, NirspyError, ValidationError
-from nirspy.domain.execution import ExecutionContext, ProgressCallback, run_pipeline_sync
+from nirspy.domain.execution import (
+    ExecutionContext,
+    PipelineRunner,
+    ProgressCallback,
+    run_pipeline_sync,
+)
 from nirspy.domain.pipeline import Pipeline, RegistryProtocol
 from nirspy.domain.validation import validate_io_chain
 
@@ -17,6 +22,7 @@ __all__ = [
     "DomainError",
     "NirspyError",
     "ExecutionContext",
+    "PipelineRunner",
     "ExecutionError",
     "Pipeline",
     "ProgressCallback",

nirspy-0.3.0/src/nirspy/domain/execution.py

@@ -0,0 +1,297 @@
+"""ExecutionContext, PipelineRunner and run_pipeline_sync."""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from nirspy.domain.cache import CacheProtocol
+    from nirspy.domain.pipeline import Pipeline
+
+from nirspy.domain.block import Block, BlockResult, BlockSpec
+from nirspy.domain.exceptions import ExecutionError, ValidationError
+
+# Signature: (block_id, step_index, total_steps) -> None
+ProgressCallback = Callable[[str, int, int], None]
+
+
+def _noop_progress(block_id: str, step: int, total: int) -> None:  # noqa: ARG001
+    pass
+
+
+@dataclass
+class ExecutionContext:
+    """Carries runtime dependencies injected into each block's ``run`` call.
+
+    All fields are optional — blocks must handle ``None`` gracefully when
+    optional resources are absent.
+    """
+
+    cache: CacheProtocol | None = None
+    """Optional cache adapter; ``None`` means caching is disabled for this run."""
+
+    progress: ProgressCallback = field(default=_noop_progress)
+    """Callback invoked after each block completes. Defaults to a no-op."""
+
+    extra: dict[str, Any] = field(default_factory=dict)
+    """Extension point for future runners (e.g. distributed context IDs).
+
+    The linear runner stores the previous block's metadata here under
+    ``"prev_metadata"`` so downstream blocks can access upstream diagnostics
+    (e.g. SCI values for channel pruning). Individual metadata keys are also
+    promoted to top-level extra keys when present (e.g. ``"sci_values"``).
+    """
+
+
+
+class PipelineRunner:
+    """Step-by-step pipeline executor.
+
+    Allows the GUI to advance block-by-block, optionally injecting
+    ``params_override`` dicts before each execution step. The override
+    is **transient** --- it does not mutate the original block's params.
+
+    Usage (interactive)::
+
+        runner = PipelineRunner(pipeline, context)
+        runner.start()
+        while not runner.is_complete:
+            spec = runner.next_block()
+            if spec is None:
+                break
+            result = runner.execute_current(params_override={"tmin": -5.0})
+
+    Usage (headless) --- equivalent to the old ``run_pipeline_sync``::
+
+        runner = PipelineRunner(pipeline, context)
+        runner.start()
+        while not runner.is_complete:
+            runner.next_block()
+            runner.execute_current()
+    """
+
+    def __init__(
+        self,
+        pipeline: Pipeline,
+        context: ExecutionContext | None = None,
+    ) -> None:
+        self._pipeline = pipeline
+        self._context = context or ExecutionContext()
+        self._enabled_steps: list[Block] = []
+        self._current_idx: int = -1
+        self._results: list[BlockResult] = []
+        self._prev_result: BlockResult | None = None
+        self._started: bool = False
+        self._block_ready: bool = False
+
+    def start(self) -> None:
+        """Initialize the runner. Must be called before ``next_block``."""
+        self._enabled_steps = [
+            step for step in self._pipeline.steps if step.spec.enabled
+        ]
+        self._current_idx = -1
+        self._results = []
+        self._prev_result = None
+        self._started = True
+        self._block_ready = False
+
+    def next_block(self) -> BlockSpec | None:
+        """Advance to the next block and return its spec.
+
+        Returns ``None`` when all blocks have been executed (pipeline
+        complete).
+
+        Raises
+        ------
+        RuntimeError
+            If ``start()`` was not called first.
+        """
+        if not self._started:
+            raise RuntimeError(
+                "PipelineRunner.start() must be called before next_block()."
+            )
+        next_idx = self._current_idx + 1
+        if next_idx >= len(self._enabled_steps):
+            self._block_ready = False
+            return None
+        self._current_idx = next_idx
+        self._block_ready = True
+        return self._enabled_steps[self._current_idx].spec
+    def execute_current(
+        self,
+        params_override: dict[str, Any] | None = None,
+    ) -> BlockResult:
+        """Execute the current block, optionally with transient param overrides.
+
+        Parameters
+        ----------
+        params_override:
+            Dict of param field names to override values. Applied
+            transiently --- the original block's ``params`` attribute is
+            **not** mutated.
+
+        Raises
+        ------
+        RuntimeError
+            If ``next_block()`` was not called or the pipeline is complete.
+        ValidationError
+            If ``params_override`` contains unknown field names.
+        """
+        if not self._block_ready:
+            raise RuntimeError(
+                "PipelineRunner.execute_current() called without a "
+                "preceding next_block() call, or the pipeline is complete."
+            )
+
+        block = self._enabled_steps[self._current_idx]
+        total = len(self._enabled_steps)
+
+        # Build inputs dict (same logic as old run_pipeline_sync)
+        if self._prev_result is None:
+            inputs: dict[str, Any] = {}
+        else:
+            inputs = {self._prev_result.block_id: self._prev_result.data}
+
+        # Apply transient params override if provided
+        if params_override and hasattr(block, "params"):
+            block = self._apply_params_override(block, params_override)
+
+        try:
+            result = block.run(self._context, inputs)
+        except Exception as exc:  # noqa: BLE001
+            raise ExecutionError(
+                f"Block '{block.spec.block_id}' failed at step "
+                f"{self._current_idx + 1}/{total}: {exc}"
+            ) from exc
+
+        # Propagate metadata to context.extra for downstream blocks (ADR-014)
+        self._context.extra["prev_metadata"] = result.metadata
+        for key, value in result.metadata.items():
+            self._context.extra[key] = value
+
+        self._context.progress(
+            block.spec.block_id, self._current_idx + 1, total,
+        )
+        self._results.append(result)
+        self._prev_result = result
+        self._block_ready = False
+
+        return result
+    @property
+    def is_complete(self) -> bool:
+        """Whether all enabled blocks have been executed."""
+        if not self._started:
+            return False
+        return (
+            self._current_idx >= len(self._enabled_steps) - 1
+            and not self._block_ready
+        )
+
+    @property
+    def current_idx(self) -> int:
+        """Index of the current block (0-based among enabled steps)."""
+        return self._current_idx
+
+    @property
+    def results(self) -> list[BlockResult]:
+        """List of results from executed blocks so far."""
+        return list(self._results)
+
+    @property
+    def total_steps(self) -> int:
+        """Total number of enabled steps."""
+        return len(self._enabled_steps)
+
+    @property
+    def current_block(self) -> Block | None:
+        """The current block instance, or None if not started/complete."""
+        if not self._started or self._current_idx < 0:
+            return None
+        if self._current_idx >= len(self._enabled_steps):
+            return None
+        return self._enabled_steps[self._current_idx]
+
+    @staticmethod
+    def _apply_params_override(
+        block: Block,
+        overrides: dict[str, Any],
+    ) -> Block:
+        """Create a copy of block with overridden params (transient).
+
+        The original block is never mutated. A new block instance is
+        created with the merged params dataclass.
+
+        Raises
+        ------
+        ValidationError
+            If any key in overrides is not a valid field of the params
+            dataclass.
+        """
+        params = getattr(block, "params", None)
+        if params is None or not dataclasses.is_dataclass(params):
+            raise ValidationError(
+                f"Block '{block.spec.block_id}' has no dataclass params "
+                f"--- cannot apply params_override."
+            )
+
+        # Validate override keys
+        valid_fields = {f.name for f in dataclasses.fields(params)}
+        unknown = set(overrides) - valid_fields
+        if unknown:
+            raise ValidationError(
+                f"params_override contains unknown field(s) for "
+                f"'{block.spec.block_id}': {sorted(unknown)}. "
+                f"Valid fields: {sorted(valid_fields)}."
+            )
+
+        # Merge: original params + overrides
+        # cast needed because is_dataclass() does not narrow for mypy
+        params_dict: dict[str, Any] = dataclasses.asdict(params)  # type: ignore[arg-type]
+        merged = {**params_dict, **overrides}
+        params_cls: type[Any] = type(params)
+        new_params = params_cls(**merged)
+
+        # Create new block instance with merged params
+        block_cls = type(block)
+        return block_cls(params=new_params)  # type: ignore[call-arg]
+
+
+def run_pipeline_sync(
+    pipeline: Pipeline,
+    context: ExecutionContext | None = None,
+) -> list[BlockResult]:
+    """Execute pipeline synchronously --- backward-compatible wrapper.
+
+    This is a thin wrapper around :class:`PipelineRunner` that calls
+    ``next_block()`` + ``execute_current()`` in a loop until complete.
+    Behavior is identical to the pre-T-023 implementation.
+
+    Parameters
+    ----------
+    pipeline:
+        The :class:`~nirspy.domain.pipeline.Pipeline` to execute.
+    context:
+        Optional :class:`ExecutionContext`. A default (no cache, no-op progress)
+        is created when omitted.
+
+    Returns
+    -------
+    list[BlockResult]
+        One result per enabled block, in execution order.
+
+    Raises
+    ------
+    ExecutionError
+        Wraps any exception raised by a block's ``run`` method.
+    """
+    runner = PipelineRunner(pipeline, context)
+    runner.start()
+    while not runner.is_complete:
+        spec = runner.next_block()
+        if spec is None:
+            break
+        runner.execute_current()
+    return runner.results