nirspy 0.0.1__py3-none-any.whl

nirspy/__init__.py

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

nirspy/blocks/__init__.py

@@ -0,0 +1,70 @@
+"""nirspy.blocks -- concrete pipeline blocks.
+
+The module-level :data:`registry` is pre-populated with all built-in block
+**classes** so callers only need to import this package to gain access to the
+full set.  Instantiation happens at pipeline-assembly time (ADR-009).
+
+    >>> from nirspy.blocks import registry
+    >>> sorted(registry.list_blocks())
+    ['bandpass_filter', 'beer_lambert', 'block_average', 'load_snirf',
+     'optical_density', 'prune_channels', 'scalp_coupling_index']
+"""
+
+from nirspy.blocks.analysis import (
+    BlockAverageBlock,
+    BlockAverageParams,
+    ConditionWindow,
+)
+from nirspy.blocks.load import LoadSnirfBlock, LoadSnirfParams
+from nirspy.blocks.manual_exclude import (
+    ManualChannelExcludeBlock,
+    ManualChannelExcludeParams,
+)
+from nirspy.blocks.preprocessing import (
+    BandpassFilterBlock,
+    BandpassFilterParams,
+    BeerLambertBlock,
+    BeerLambertParams,
+    OpticalDensityBlock,
+    OpticalDensityParams,
+)
+from nirspy.blocks.quality import (
+    PruneChannelsBlock,
+    PruneChannelsParams,
+    ScalpCouplingIndexBlock,
+    ScalpCouplingIndexParams,
+)
+from nirspy.blocks.registry import BlockRegistry, register, registry
+
+# Register built-in block classes (not instances -- ADR-009)
+registry.register("load_snirf", LoadSnirfBlock)
+registry.register("optical_density", OpticalDensityBlock)
+registry.register("beer_lambert", BeerLambertBlock)
+registry.register("bandpass_filter", BandpassFilterBlock)
+registry.register("scalp_coupling_index", ScalpCouplingIndexBlock)
+registry.register("prune_channels", PruneChannelsBlock)
+registry.register("block_average", BlockAverageBlock)
+registry.register("manual_channel_exclude", ManualChannelExcludeBlock)
+
+__all__ = [
+    "BandpassFilterBlock",
+    "BandpassFilterParams",
+    "BeerLambertBlock",
+    "BeerLambertParams",
+    "BlockAverageBlock",
+    "BlockAverageParams",
+    "ConditionWindow",
+    "BlockRegistry",
+    "ManualChannelExcludeBlock",
+    "ManualChannelExcludeParams",
+    "LoadSnirfBlock",
+    "LoadSnirfParams",
+    "OpticalDensityBlock",
+    "OpticalDensityParams",
+    "PruneChannelsBlock",
+    "PruneChannelsParams",
+    "ScalpCouplingIndexBlock",
+    "ScalpCouplingIndexParams",
+    "register",
+    "registry",
+]

nirspy/blocks/analysis.py

@@ -0,0 +1,339 @@
+"""Analysis blocks -- Etapa 3 (T-004).
+
+BlockAverageBlock: computes epoch-averaged HRF per stimulus condition.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+import mne
+import mne.io
+
+from nirspy.domain.block import BlockResult, BlockSpec
+from nirspy.domain.data_types import DataType
+from nirspy.domain.exceptions import ValidationError
+from nirspy.engine.mne_adapter import MNEAdapter
+
+# ---------------------------------------------------------------------------
+# BlockAverage
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ConditionWindow:
+    """Temporal window override for a single condition.
+
+    Each field mirrors the corresponding global parameter in
+    :class:`BlockAverageParams`.  When a condition has an entry in
+    ``per_condition_windows`` these values take precedence over the
+    globals for that condition only.
+    """
+
+    tmin: float
+    tmax: float
+    baseline_tmin: float
+    baseline_tmax: float
+
+
+def _validate_condition_window(name: str, window: ConditionWindow) -> None:
+    """Raise :class:`ValidationError` if *window* has invalid ranges."""
+    if window.tmin >= window.tmax:
+        raise ValidationError(
+            f"ConditionWindow {name!r}: tmin ({window.tmin}) "
+            f"must be < tmax ({window.tmax})."
+        )
+    if window.baseline_tmin > window.baseline_tmax:
+        raise ValidationError(
+            f"ConditionWindow {name!r}: baseline_tmin "
+            f"({window.baseline_tmin}) must be <= baseline_tmax "
+            f"({window.baseline_tmax})."
+        )
+
+
+@dataclass(frozen=True)
+class BlockAverageParams:
+    """Parameters for block averaging (HRF computation).
+
+    Attributes
+    ----------
+    tmin:
+        Epoch start relative to event onset (seconds). Default -2.0.
+    tmax:
+        Epoch end relative to event onset (seconds). Default 18.0.
+    baseline_tmin:
+        Baseline correction start. Default -2.0.
+    baseline_tmax:
+        Baseline correction end. Default 0.0.
+    reject_by_amplitude:
+        Whether to reject epochs exceeding amplitude threshold.
+    amplitude_threshold:
+        Rejection threshold in mol/L (default 80e-6 = 80 uM).
+    pick_conditions:
+        List of condition names to include. None = all conditions.
+    per_condition_windows:
+        Per-condition temporal window overrides.  Empty dict (default)
+        uses the global window for every condition.
+    """
+
+    tmin: float = -2.0
+    tmax: float = 18.0
+    baseline_tmin: float = -2.0
+    baseline_tmax: float = 0.0
+    reject_by_amplitude: bool = True
+    amplitude_threshold: float = 80e-6
+    pick_conditions: list[str] | None = field(default=None)
+    per_condition_windows: dict[str, ConditionWindow] = field(
+        default_factory=dict,
+    )
+
+    def __post_init__(self) -> None:
+        """Coerce raw dicts to ConditionWindow for YAML round-trip."""
+        if self.per_condition_windows:
+            coerced: dict[str, ConditionWindow] = {}
+            for key, val in self.per_condition_windows.items():
+                if isinstance(val, dict):
+                    coerced[key] = ConditionWindow(**val)
+                else:
+                    coerced[key] = val
+            object.__setattr__(self, "per_condition_windows", coerced)
+
+
+_BA_SPEC = BlockSpec(
+    block_id="block_average",
+    display_name="Block Average (HRF)",
+    input_type=DataType.RAW_HAEMO,
+    output_type=DataType.EVOKED,
+    params_class=BlockAverageParams,
+    description="Computes epoch-averaged HRF per stimulus condition.",
+)
+
+
+class BlockAverageBlock:
+    """Compute epoch-averaged HRF per stimulus condition.
+
+    Pipeline:
+    1. Extract events from raw annotations
+    2. Create epochs (tmin/tmax window, baseline correction)
+    3. Optionally reject epochs by amplitude threshold
+    4. Average per condition -> dict[str, Evoked]
+
+    When ``per_condition_windows`` is non-empty the block creates one
+    :class:`mne.Epochs` per condition (each with its own window) via
+    :meth:`MNEAdapter.create_epochs_per_condition`.
+
+    Invariant: input Raw must have hbo/hbr channels (RAW_HAEMO).
+    Raw must have annotations/events; raises ValidationError if none found.
+    """
+
+    SPEC: ClassVar[BlockSpec] = _BA_SPEC
+
+    def __init__(
+        self,
+        params: BlockAverageParams | None = None,
+        adapter: MNEAdapter | None = None,
+    ) -> None:
+        self.params: BlockAverageParams = params or BlockAverageParams()
+        self._adapter: MNEAdapter = adapter or MNEAdapter()
+
+    @property
+    def spec(self) -> BlockSpec:
+        """Return the static block descriptor."""
+        return _BA_SPEC
+
+    def run(self, context: Any, inputs: dict[str, Any]) -> BlockResult:
+        """Execute block averaging."""
+        if not inputs:
+            raise ValidationError(
+                "BlockAverageBlock requires input data. "
+                "It cannot be the first block in a pipeline."
+            )
+
+        # Validate params
+        required = {
+            "tmin": self.params.tmin,
+            "tmax": self.params.tmax,
+            "baseline_tmin": self.params.baseline_tmin,
+            "baseline_tmax": self.params.baseline_tmax,
+        }
+        missing = [name for name, val in required.items() if val is None]
+        if missing:
+            raise ValidationError(
+                f"BlockAverageBlock: required parameter(s) "
+                f"{missing} must not be empty."
+            )
+
+        if self.params.baseline_tmin > self.params.baseline_tmax:
+            raise ValidationError(
+                f"BlockAverageBlock: baseline_tmin ({self.params.baseline_tmin}) "
+                f"must be <= baseline_tmax ({self.params.baseline_tmax})."
+            )
+
+        if self.params.tmin >= self.params.tmax:
+            raise ValidationError(
+                f"BlockAverageBlock: tmin ({self.params.tmin}) "
+                f"must be < tmax ({self.params.tmax})."
+            )
+
+
+        # Validate each per-condition window
+        for cond_name, window in self.params.per_condition_windows.items():
+            _validate_condition_window(cond_name, window)
+
+        raw: mne.io.BaseRaw = next(iter(inputs.values()))
+
+        # Validate channel type
+        ch_types = set(raw.get_channel_types())
+        if "hbo" not in ch_types and "hbr" not in ch_types:
+            raise ValidationError(
+                f"BlockAverageBlock expects hbo/hbr channels (RAW_HAEMO), "
+                f"got: {sorted(ch_types)}. "
+                f"Ensure a BeerLambert block precedes this one."
+            )
+
+        # Check for annotations/events
+        events_from_annot, event_id = mne.events_from_annotations(
+            raw, verbose=False
+        )
+        if len(events_from_annot) == 0:
+            raise ValidationError(
+                "BlockAverageBlock: no events found in raw annotations. "
+                "Ensure the SNIRF file contains stimulus annotations."
+            )
+
+        # Filter conditions if pick_conditions is set
+        used_event_id: dict[str, int] | None = None
+        if self.params.pick_conditions is not None:
+            used_event_id = {
+                k: v for k, v in event_id.items()
+                if k in self.params.pick_conditions
+            }
+            if not used_event_id:
+                raise ValidationError(
+                    f"BlockAverageBlock: none of pick_conditions "
+                    f"{self.params.pick_conditions} found in event_id "
+                    f"{list(event_id.keys())}."
+                )
+        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)
+            )
+            if unknown:
+                raise ValidationError(
+                    f"BlockAverageBlock: per_condition_windows contains "
+                    f"condition(s) {sorted(unknown)} not found in "
+                    f"event_id {sorted(used_event_id.keys())}."
+                )
+
+        # Build rejection dict
+        reject: dict[str, float] | None = None
+        if self.params.reject_by_amplitude:
+            reject = {
+                "hbo": self.params.amplitude_threshold,
+                "hbr": self.params.amplitude_threshold,
+            }
+
+        # ---- Per-condition path vs legacy single-Epochs path ----
+        if self.params.per_condition_windows:
+            default_window = (
+                self.params.tmin,
+                self.params.tmax,
+                self.params.baseline_tmin,
+                self.params.baseline_tmax,
+            )
+            epochs_dict = self._adapter.create_epochs_per_condition(
+                raw,
+                used_event_id,
+                default_window=default_window,
+                per_condition_windows=self.params.per_condition_windows,
+                reject=reject,
+            )
+            evoked_dict = self._adapter.average_epochs(epochs_dict)
+
+            # Metadata for per-condition path
+            windows_used: dict[str, dict[str, float]] = {}
+            n_epochs_total = 0
+            skipped_conditions: list[str] = []
+            metadata: dict[str, Any] = {}
+
+            for cond in used_event_id:
+                if cond in self.params.per_condition_windows:
+                    w = self.params.per_condition_windows[cond]
+                    windows_used[cond] = {
+                        "tmin": w.tmin,
+                        "tmax": w.tmax,
+                        "baseline_tmin": w.baseline_tmin,
+                        "baseline_tmax": w.baseline_tmax,
+                    }
+                else:
+                    windows_used[cond] = {
+                        "tmin": self.params.tmin,
+                        "tmax": self.params.tmax,
+                        "baseline_tmin": self.params.baseline_tmin,
+                        "baseline_tmax": self.params.baseline_tmax,
+                    }
+                if cond in epochs_dict:
+                    n_ep = len(epochs_dict[cond].events)
+                    n_epochs_total += n_ep
+                    metadata[f"n_epochs_{cond}"] = n_ep
+                if cond not in evoked_dict:
+                    skipped_conditions.append(cond)
+
+            metadata.update({
+                "conditions": list(evoked_dict.keys()),
+                "n_conditions": len(evoked_dict),
+                "n_epochs_total": n_epochs_total,
+                "skipped_conditions": skipped_conditions,
+                "tmin": self.params.tmin,
+                "tmax": self.params.tmax,
+                "per_condition_used": True,
+                "windows_used": windows_used,
+            })
+
+        else:
+            # Legacy single-Epochs path
+            epochs = self._adapter.create_epochs(
+                raw,
+                tmin=self.params.tmin,
+                tmax=self.params.tmax,
+                baseline_tmin=self.params.baseline_tmin,
+                baseline_tmax=self.params.baseline_tmax,
+                reject=reject,
+                event_id=used_event_id,
+            )
+            evoked_dict = self._adapter.average_epochs(epochs)
+
+            skipped_conditions = [
+                cond for cond in epochs.event_id
+                if cond not in evoked_dict
+            ]
+            metadata = {
+                "conditions": list(evoked_dict.keys()),
+                "n_conditions": len(evoked_dict),
+                "n_epochs_total": len(epochs.events),
+                "skipped_conditions": skipped_conditions,
+                "tmin": self.params.tmin,
+                "tmax": self.params.tmax,
+            }
+
+            for condition in evoked_dict:
+                metadata[f"n_epochs_{condition}"] = len(
+                    epochs[condition]
+                )
+
+            if epochs.drop_log is not None:
+                n_dropped = sum(
+                    1 for log in epochs.drop_log if len(log) > 0
+                )
+                metadata["n_epochs_dropped"] = n_dropped
+
+        return BlockResult(
+            data=evoked_dict,
+            block_id=_BA_SPEC.block_id,
+            metadata=metadata,
+        )

nirspy/blocks/load.py

@@ -0,0 +1,232 @@
+"""LoadSnirfBlock — loads a SNIRF file and returns a Raw MNE object.
+
+Entry block for any fNIRS pipeline. Wraps :class:`~nirspy.engine.mne_adapter.MNEAdapter`
+and produces a :class:`~nirspy.domain.data_types.DataType.RAW` result.
+
+Security (S-02): Path is canonicalized via ``resolve()`` and validated against
+an allowlist of directories. Paths containing ``..`` components are rejected.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+import mne.io
+
+from nirspy.domain.block import BlockResult, BlockSpec
+from nirspy.domain.data_types import DataType
+from nirspy.domain.exceptions import ExecutionError, ValidationError
+from nirspy.engine.exceptions import MNEOperationError, SnirfLoadError
+from nirspy.engine.mne_adapter import MNEAdapter
+
+# ---------------------------------------------------------------------------
+# Security: default allowed directories for file loading (S-02)
+# ---------------------------------------------------------------------------
+
+_DEFAULT_ALLOWED_DIRS: list[Path] = [
+    Path.home(),
+    Path.cwd(),
+]
+
+
+def get_allowed_dirs() -> list[Path]:
+    """Return the list of allowed base directories for file loading.
+
+    Directories are resolved (absolute, no symlinks). Defaults to user home
+    and current working directory. Can be extended via ``NIRSPY_ALLOWED_DIRS``
+    environment variable (``os.pathsep``-separated paths).
+    """
+    dirs = [p.resolve() for p in _DEFAULT_ALLOWED_DIRS]
+    env_dirs = os.environ.get("NIRSPY_ALLOWED_DIRS", "")
+    if env_dirs:
+        for d in env_dirs.split(os.pathsep):
+            p = Path(d).resolve()
+            if p.is_dir():
+                dirs.append(p)
+    return dirs
+
+
+def validate_snirf_path(path: Path, allowed_dirs: list[Path] | None = None) -> Path:
+    """Validate and canonicalize a SNIRF file path (S-02).
+
+    Parameters
+    ----------
+    path:
+        User-provided path to validate.
+    allowed_dirs:
+        Optional override for testing. Defaults to :func:`get_allowed_dirs`.
+
+    Returns
+    -------
+    Path
+        Resolved (canonical) path guaranteed to be within allowed directories.
+
+    Raises
+    ------
+    ValidationError
+        When the path contains ``..`` traversal, is outside allowed directories,
+        or does not have a ``.snirf`` extension.
+    """
+    # Reject raw path containing ".." before resolution
+    path_str = str(path)
+    if ".." in path_str.replace("\\", "/").split("/"):
+        raise ValidationError(
+            f"Path traversal detected: '{path}'. "
+            "Paths containing '..' components are not allowed."
+        )
+
+    resolved = path.resolve()
+
+    # Validate extension
+    if resolved.suffix.lower() != ".snirf":
+        raise ValidationError(
+            f"Expected a .snirf file, got '{resolved.suffix}': {resolved}"
+        )
+
+    # Validate against allowlist
+    dirs = allowed_dirs if allowed_dirs is not None else get_allowed_dirs()
+    for allowed in dirs:
+        try:
+            resolved.relative_to(allowed)
+            return resolved
+        except ValueError:
+            continue
+
+    raise ValidationError(
+        f"Path '{resolved}' is outside allowed directories. "
+        f"Allowed: {[str(d) for d in dirs]}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Block definition
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class LoadSnirfParams:
+    """Parameters for :class:`LoadSnirfBlock`.
+
+    Attributes
+    ----------
+    path:
+        Absolute or relative path to the ``.snirf`` file to load.
+    """
+
+    path: str
+
+
+_SPEC = BlockSpec(
+    block_id="load_snirf",
+    display_name="Load SNIRF",
+    description="Load a SNIRF file and emit a MNE Raw object.",
+    input_type=DataType.NONE,
+    output_type=DataType.RAW,
+    params_class=LoadSnirfParams,
+)
+
+
+class LoadSnirfBlock:
+    """Block that loads a SNIRF file via MNE-NIRS and emits ``DataType.RAW``.
+
+    Parameters
+    ----------
+    params:
+        :class:`LoadSnirfParams` instance holding the file path. Stored as
+        ``self.params`` and accessed in :meth:`run` (ADR-009).
+    adapter:
+        Optional :class:`~nirspy.engine.mne_adapter.MNEAdapter` override.
+        Defaults to a freshly constructed :class:`MNEAdapter` so that tests
+        can inject a fake adapter without modifying production code.
+    allowed_dirs:
+        Optional override for path validation allowlist.  When *None*
+        (default), uses :func:`get_allowed_dirs`.
+
+    Class attributes
+    ----------------
+    SPEC:
+        Class-level reference to the static :class:`~nirspy.domain.block.BlockSpec`
+        descriptor. Exposed here so the serialiser can read ``params_class``
+        from the class without instantiating it.
+    """
+
+    SPEC: ClassVar[BlockSpec] = _SPEC
+
+    def __init__(
+        self,
+        params: LoadSnirfParams,
+        adapter: MNEAdapter | None = None,
+        allowed_dirs: list[Path] | None = None,
+    ) -> None:
+        self.params: LoadSnirfParams = params
+        self._adapter: MNEAdapter = adapter or MNEAdapter()
+        self._allowed_dirs = allowed_dirs
+
+    @property
+    def spec(self) -> BlockSpec:
+        """Return the static block descriptor."""
+        return _SPEC
+
+    def run(self, context: Any, inputs: dict[str, Any]) -> BlockResult:
+        """Load the SNIRF file referenced in ``self.params`` and return a :class:`BlockResult`.
+
+        Security (S-02): The path is validated and canonicalized before loading.
+
+        Parameters
+        ----------
+        context:
+            :class:`~nirspy.domain.execution.ExecutionContext` injected by the
+            runner — unused here but required by the :class:`~nirspy.domain.block.Block`
+            Protocol.
+        inputs:
+            Must be an empty dict (``{}``).  The load block is always the first
+            step in a linear pipeline and has no upstream dependency.
+
+        Returns
+        -------
+        BlockResult
+            ``data`` is the :class:`mne.io.BaseRaw` object.
+            ``metadata`` contains ``n_channels`` and ``sfreq``.
+
+        Raises
+        ------
+        ExecutionError
+            When *inputs* is non-empty (contract violation: load block must be first).
+        ValidationError
+            When the path fails security validation (traversal, outside allowlist).
+        ~nirspy.engine.exceptions.SnirfLoadError
+            When the file is missing or cannot be parsed (propagated from adapter).
+        ~nirspy.engine.exceptions.MNEOperationError
+            When MNE raises an unexpected error during loading.
+        """
+        if inputs:
+            raise ExecutionError(
+                "LoadSnirfBlock received non-empty inputs. "
+                "The load block must be the first block in the pipeline (inputs must be {})."
+            )
+
+        # S-02: Validate path before loading
+        validated_path = validate_snirf_path(
+            Path(self.params.path), self._allowed_dirs
+        )
+
+        try:
+            raw: mne.io.BaseRaw = self._adapter.load_snirf(validated_path)
+        except (SnirfLoadError, MNEOperationError):
+            raise
+        except Exception as exc:  # noqa: BLE001
+            raise ExecutionError(
+                f"LoadSnirfBlock failed to load '{self.params.path}': {exc}"
+            ) from exc
+
+        return BlockResult(
+            data=raw,
+            block_id=_SPEC.block_id,
+            metadata={
+                "n_channels": len(raw.ch_names),
+                "sfreq": raw.info["sfreq"],
+            },
+        )