fibphot 0.1.0__py3-none-any.whl

fibphot/stages/filters.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+import numpy as np
+import scipy.ndimage as ndi
+import scipy.signal
+
+from ..state import PhotometryState
+from ..types import FloatArray
+from .base import StageOutput, UpdateStage, _resolve_channels
+
+
+def _hampel_1d(
+    x: FloatArray,
+    window_size: int,
+    n_sigmas: float,
+    *,
+    mad_scale: float = 1.4826,
+    mode: str = "reflect",
+    match_edges: bool = True,
+) -> FloatArray:
+    """
+    Fast Hampel filter using rolling medians.
+
+    Parameters
+    ----------
+    mad_scale:
+        Scale factor so MAD estimates standard deviation under Normal noise.
+    mode:
+        Padding strategy for the rolling median ('reflect', 'nearest', ...).
+    match_edges:
+        If True, applies "shrinking window" behaviour at first/last k samples.
+    """
+
+    if window_size < 3:
+        raise ValueError("window_size must be >= 3.")
+    if window_size % 2 == 0:
+        window_size += 1
+
+    x = np.asarray(x, dtype=float)
+    n = int(x.shape[0])
+    k = window_size // 2
+
+    # Rolling median
+    med = ndi.median_filter(x, size=window_size, mode=mode)
+
+    # Rolling MAD = median(|x - med|)
+    abs_dev = np.abs(x - med)
+    mad = mad_scale * ndi.median_filter(abs_dev, size=window_size, mode=mode)
+
+    out = x.copy()
+    mask = (mad > 1e-12) & (abs_dev > (n_sigmas * mad))
+    out[mask] = med[mask]
+
+    if match_edges and k > 0 and n > 0:
+        left = min(k, n)
+        for i in range(left):
+            lo = 0
+            hi = min(n, i + k + 1)
+            w = x[lo:hi]
+            m = float(np.median(w))
+            s = mad_scale * float(np.median(np.abs(w - m)))
+            if s > 1e-12 and abs(x[i] - m) > n_sigmas * s:
+                out[i] = m
+
+        right_start = max(0, n - k)
+        for i in range(right_start, n):
+            lo = max(0, i - k)
+            hi = n
+            w = x[lo:hi]
+            m = float(np.median(w))
+            s = mad_scale * float(np.median(np.abs(w - m)))
+            if s > 1e-12 and abs(x[i] - m) > n_sigmas * s:
+                out[i] = m
+
+    return out
+
+
+@dataclass(frozen=True, slots=True)
+class HampelFilter(UpdateStage):
+    """
+    Applies a Hampel filter to specified channels.
+
+    This implementation is fast: it uses rolling medians (SciPy) rather than
+    a Python loop over all samples.
+
+    Parameters
+    ----------
+    window_size:
+        Size of the moving window (forced odd and >= 3).
+    n_sigmas:
+        Threshold in units of (scaled) MAD.
+    channels:
+        "all", a channel name, a list of names, or None for all.
+    mad_scale:
+        Scale factor converting MAD to sigma under Normal noise.
+    mode:
+        Padding mode used by the rolling median.
+    match_edges:
+        If True, uses shrinking-window behaviour at the edges.
+
+    Context
+    -------
+    The Hampel filter is a robust method for outlier detection and correction
+    in time series data. It replaces outliers with the median of neighbouring
+    values within a specified window, making it effective for removing transient
+    spikes or noise without significantly distorting the underlying signal.
+
+    Compared to the `MedianFilter`, which replaces each point with the median of
+    its neighbours, the Hampel filter specifically targets outliers based on
+    their deviation from the local median. Hence, it does not alter the signal
+    unless an outlier is detected.
+    """
+
+    name: str = field(default="hampel_filter", init=False)
+
+    window_size: int = 11
+    n_sigmas: float = 3.0
+    channels: str | list[str] | None = None
+
+    mad_scale: float = 1.4826
+    mode: str = "reflect"
+    match_edges: bool = True
+
+    def _params_for_summary(self) -> dict[str, object]:
+        return {
+            "window_size": self.window_size,
+            "n_sigmas": self.n_sigmas,
+            "channels": self.channels if self.channels is not None else "all",
+            "mad_scale": self.mad_scale,
+            "mode": self.mode,
+            "match_edges": self.match_edges,
+        }
+
+    def apply(self, state: PhotometryState) -> StageOutput:
+        idxs = _resolve_channels(state, self.channels)
+        new = state.signals.copy()
+        for i in idxs:
+            new[i] = _hampel_1d(
+                new[i],
+                self.window_size,
+                self.n_sigmas,
+                mad_scale=self.mad_scale,
+                mode=self.mode,
+                match_edges=self.match_edges,
+            )
+        return StageOutput(signals=new)
+
+
+@dataclass(frozen=True, slots=True)
+class MedianFilter(UpdateStage):
+    name: str = field(default="median_filter", init=False)
+    kernel_size: int = 5
+    channels: str | list[str] | None = None
+
+    def _params_for_summary(self) -> dict[str, object]:
+        return {
+            "kernel_size": self.kernel_size,
+            "channels": self.channels if self.channels is not None else "all",
+        }
+
+    def apply(self, state: PhotometryState) -> StageOutput:
+        k = self.kernel_size + (self.kernel_size % 2 == 0)
+        idxs = _resolve_channels(state, self.channels)
+
+        new = state.signals.copy()
+        for i in idxs:
+            new[i] = scipy.signal.medfilt(new[i], kernel_size=k)
+
+        return StageOutput(signals=new)
+
+
+@dataclass(frozen=True, slots=True)
+class LowPassFilter(UpdateStage):
+    """
+    Applies a zero-phase low-pass Butterworth filter to specified channels.
+
+    Parameters
+    ----------
+    critical_frequency : float
+        The critical frequency (in Hz) for the low-pass filter. This is where
+        the filter begins to attenuate higher frequencies.
+    order : int
+        The order of the Butterworth filter. Higher order filters have a
+        steeper roll-off.
+    sampling_rate : float | None
+        The sampling rate (in Hz) of the input signals. If None, uses the
+        sampling rate from the PhotometryState.
+    channels : str | list[str] | None
+        The channels to which the filter should be applied. Can be "all", a
+        single channel name, or a list of channel names. If None, defaults to
+        "all".
+    representation : Literal["sos", "ba"]
+        The filter representation to use. "sos" for second-order sections
+        (numerically stable), or "ba" for (b, a) coefficients.
+
+    Context
+    -------
+    Biosensor kinetics typically operate on slower (e.g., sub-second) timescales
+    relative to higher-frequency electrical noise. A low-pass filter keeps low
+    frequencies and attenuates high frequencies.
+    """
+
+    name: str = field(default="low_pass_filter", init=False)
+    critical_frequency: float = 10.0
+    order: int = 2
+    sampling_rate: float | None = None
+    channels: str | list[str] | None = None
+    representation: Literal["sos", "ba"] = "sos"
+
+    def _params_for_summary(self) -> dict[str, object]:
+        return {
+            "critical_frequency": self.critical_frequency,
+            "order": self.order,
+            "sampling_rate": self.sampling_rate,
+            "channels": self.channels if self.channels is not None else "all",
+            "representation": self.representation,
+        }
+
+    def apply(self, state: PhotometryState) -> StageOutput:
+        fs = (
+            state.sampling_rate
+            if self.sampling_rate is None
+            else float(self.sampling_rate)
+        )
+        if not (0.0 < self.critical_frequency < 0.5 * fs):
+            raise ValueError(
+                "critical_frequency must be > 0 and < Nyquist (fs/2). "
+                f"Got critical_frequency={self.critical_frequency}, fs={fs}."
+            )
+
+        idxs = _resolve_channels(state, self.channels)
+        new = state.signals.copy()
+
+        if self.representation == "sos":
+            sos = scipy.signal.butter(
+                N=self.order,
+                Wn=self.critical_frequency,
+                btype="low",
+                fs=fs,
+                output="sos",
+            )
+            for i in idxs:
+                new[i] = scipy.signal.sosfiltfilt(sos, new[i])
+            return StageOutput(signals=new)
+
+        if self.representation == "ba":
+            res = scipy.signal.butter(
+                N=self.order,
+                Wn=self.critical_frequency,
+                btype="low",
+                fs=fs,
+                output="ba",
+            )
+
+            if res is None:
+                raise RuntimeError(
+                    "scipy.signal.butter returned None; check filter params."
+                )
+
+            assert len(res) == 2, (
+                "Expected (b,a) tuple from scipy.signal.butter."
+            )
+            b, a = res
+
+            for i in idxs:
+                new[i] = scipy.signal.filtfilt(b, a, new[i])
+
+            return StageOutput(signals=new)
+
+        raise ValueError(f"Unknown representation: {self.representation!r}")

fibphot/stages/normalisation.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import numpy as np
+
+from ..state import PhotometryState
+from .base import StageOutput, UpdateStage, _resolve_channels
+
+NormaliseMethod = Literal["baseline", "z_score", "null_z"]
+BaselineMode = Literal["dff", "percent"]
+NullZScale = Literal["rms", "mad"]
+
+
+def _window_mask(
+    state: PhotometryState,
+    time_window: tuple[float, float] | None,
+) -> np.ndarray:
+    if time_window is None:
+        return np.ones(state.n_samples, dtype=bool)
+
+    t0, t1 = time_window
+    if t1 < t0:
+        raise ValueError("time_window must satisfy t0 <= t1.")
+
+    mask = (state.time_seconds >= t0) & (state.time_seconds <= t1)
+    if not np.any(mask):
+        raise ValueError(
+            f"time_window={time_window} selects no samples; check your time range."
+        )
+    return mask
+
+
+@dataclass(frozen=True, slots=True)
+class Normalise(UpdateStage):
+    """
+    Normalise photometry signals using one of several common schemes.
+
+    Use the class constructors for clarity:
+
+        Normalise.baseline(...)
+        Normalise.z_score(...)
+        Normalise.null_z(...)
+
+    Notes
+    -----
+    This stage always operates on `state.signals` as they currently stand.
+    For baseline normalisation, this typically means you should run motion
+    correction first so your signals represent dF.
+    """
+
+    name: str = field(default="normalise", init=False)
+
+    method: NormaliseMethod = "baseline"
+    channels: str | list[str] | None = None
+
+    # baseline normalisation
+    baseline_key: str | None = "double_exp_baseline"
+    baseline_mode: BaselineMode = "percent"
+
+    # z-score / null-z window
+    time_window: tuple[float, float] | None = None
+    ddof: int = 0
+
+    # null-z options
+    null_z_scale: NullZScale = "rms"
+    mad_scale: float = 1.4826
+
+    # numerical safety
+    eps: float = 1e-12
+
+    def __post_init__(self) -> None:
+        if self.method == "baseline":
+            if not self.baseline_key:
+                raise ValueError(
+                    "baseline_key must be set when method='baseline'."
+                )
+        else:
+            # baseline parameters should not be used for non-baseline methods
+            if self.baseline_key not in (None, "double_exp_baseline"):
+                raise ValueError(
+                    "baseline_key is only valid when method='baseline'. "
+                    "Use Normalise.baseline(...)."
+                )
+
+        if self.ddof < 0:
+            raise ValueError("ddof must be >= 0.")
+        if self.eps <= 0:
+            raise ValueError("eps must be > 0.")
+        if self.mad_scale <= 0:
+            raise ValueError("mad_scale must be > 0.")
+        if self.time_window is not None:
+            t0, t1 = self.time_window
+            if t1 < t0:
+                raise ValueError("time_window must satisfy t0 <= t1.")
+
+    @classmethod
+    def baseline(
+        cls,
+        *,
+        baseline_key: str = "double_exp_baseline",
+        mode: BaselineMode = "percent",
+        channels: str | list[str] | None = None,
+        eps: float = 1e-12,
+    ) -> Normalise:
+        return cls(
+            method="baseline",
+            channels=channels,
+            baseline_key=baseline_key,
+            baseline_mode=mode,
+            eps=eps,
+        )
+
+    @classmethod
+    def z_score(
+        cls,
+        *,
+        channels: str | list[str] | None = None,
+        time_window: tuple[float, float] | None = None,
+        ddof: int = 0,
+        eps: float = 1e-12,
+    ) -> Normalise:
+        return cls(
+            method="z_score",
+            channels=channels,
+            time_window=time_window,
+            ddof=ddof,
+            eps=eps,
+            baseline_key=None,
+        )
+
+    @classmethod
+    def null_z(
+        cls,
+        *,
+        channels: str | list[str] | None = None,
+        time_window: tuple[float, float] | None = None,
+        scale: NullZScale = "rms",
+        mad_scale: float = 1.4826,
+        eps: float = 1e-12,
+    ) -> Normalise:
+        return cls(
+            method="null_z",
+            channels=channels,
+            time_window=time_window,
+            null_z_scale=scale,
+            mad_scale=mad_scale,
+            eps=eps,
+            baseline_key=None,
+        )
+
+    def _params_for_summary(self) -> dict[str, Any]:
+        return {
+            "method": self.method,
+            "channels": self.channels if self.channels is not None else "all",
+            "baseline_key": self.baseline_key,
+            "baseline_mode": self.baseline_mode,
+            "time_window": self.time_window,
+            "ddof": self.ddof,
+            "null_z_scale": self.null_z_scale,
+            "mad_scale": self.mad_scale,
+            "eps": self.eps,
+        }
+
+    def apply(self, state: PhotometryState) -> StageOutput:
+        idxs = _resolve_channels(state, self.channels)
+        new = state.signals.copy()
+
+        if self.method == "baseline":
+            assert self.baseline_key is not None  # for type-checkers
+
+            if self.baseline_key not in state.derived:
+                raise KeyError(
+                    f"Baseline '{self.baseline_key}' not found in state.derived. "
+                    "Run the stage that produces this baseline first."
+                )
+
+            baseline = np.asarray(state.derived[self.baseline_key], dtype=float)
+            if baseline.shape != state.signals.shape:
+                raise ValueError(
+                    f"Baseline shape {baseline.shape} does not match signals shape "
+                    f"{state.signals.shape}."
+                )
+
+            scale = 100.0 if self.baseline_mode == "percent" else 1.0
+            for i in idxs:
+                denom = baseline[i]
+                denom = np.where(np.abs(denom) < self.eps, np.nan, denom)
+                new[i] = scale * (new[i] / denom)
+
+            return StageOutput(
+                signals=new,
+                results={
+                    "method": "baseline",
+                    "baseline_key": self.baseline_key,
+                    "baseline_mode": self.baseline_mode,
+                    "channels_normalised": idxs,
+                },
+            )
+
+        mask = _window_mask(state, self.time_window)
+
+        if self.method == "z_score":
+            means: dict[str, float] = {}
+            stds: dict[str, float] = {}
+
+            for i in idxs:
+                x = new[i]
+                mu = float(np.nanmean(x[mask]))
+                sd = float(np.nanstd(x[mask], ddof=self.ddof))
+                if not np.isfinite(sd) or sd < self.eps:
+                    raise ValueError(
+                        f"Standard deviation too small/invalid for channel "
+                        f"'{state.channel_names[i]}': {sd}."
+                    )
+                new[i] = (x - mu) / sd
+                means[state.channel_names[i]] = mu
+                stds[state.channel_names[i]] = sd
+
+            return StageOutput(
+                signals=new,
+                results={
+                    "method": "z_score",
+                    "means": means,
+                    "stds": stds,
+                    "time_window": self.time_window,
+                    "ddof": self.ddof,
+                },
+            )
+
+        # null_z
+        scales: dict[str, float] = {}
+        for i in idxs:
+            x = new[i]
+            xm = x[mask]
+
+            if self.null_z_scale == "rms":
+                s0 = float(np.sqrt(np.nanmean(xm * xm)))
+            else:
+                s0 = float(self.mad_scale * np.nanmedian(np.abs(xm)))
+
+            if not np.isfinite(s0) or s0 < self.eps:
+                raise ValueError(
+                    f"Null-Z scale too small/invalid for channel "
+                    f"'{state.channel_names[i]}': {s0}."
+                )
+
+            new[i] = x / s0
+            scales[state.channel_names[i]] = s0
+
+        return StageOutput(
+            signals=new,
+            results={
+                "method": "null_z",
+                "null_z_scale": self.null_z_scale,
+                "scales": scales,
+                "time_window": self.time_window,
+            },
+        )

fibphot/stages/regression.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import numpy as np
+
+from ..fit.regression import fit_irls, fit_ols
+from ..state import PhotometryState
+from .base import StageOutput, UpdateStage, _resolve_channels
+
+RegressionMethod = Literal["ols", "irls_tukey", "irls_huber"]
+
+
+@dataclass(frozen=True, slots=True)
+class IsosbesticRegression(UpdateStage):
+    """
+    Regress a control channel (typically isosbestic) onto one or more channels.
+
+    For each target channel y and control x, fit:
+
+        y ≈ intercept + slope * x
+
+    Output:
+        dF = y - y_hat
+
+    Also stores:
+        derived["motion_fit"] = y_hat (per channel; shape matches signals)
+
+    Notes
+    -----
+    `motion_fit` is a nuisance estimate used for subtraction/diagnostics. It is
+    not necessarily suitable as a denominator for dF/F, especially if signals
+    have been detrended (e.g. double exponential subtraction).
+    """
+
+    name: str = field(default="isosbestic_regression", init=False)
+
+    control: str = "iso"
+    channels: str | list[str] | None = None
+
+    method: RegressionMethod = "irls_tukey"
+    include_intercept: bool = True
+
+    # IRLS settings
+    tuning_constant: float = 4.685
+    max_iter: int = 100
+    tol: float = 1e-10
+    store_weights: bool = False
+
+    def _params_for_summary(self) -> dict[str, Any]:
+        return {
+            "control": self.control,
+            "channels": self.channels if self.channels is not None else "all",
+            "method": self.method,
+            "include_intercept": self.include_intercept,
+            "tuning_constant": self.tuning_constant,
+            "max_iter": self.max_iter,
+            "tol": self.tol,
+            "store_weights": self.store_weights,
+        }
+
+    def apply(self, state: PhotometryState) -> StageOutput:
+        control_idx = state.idx(self.control)
+        x = state.signals[control_idx]
+
+        idxs = _resolve_channels(state, self.channels)
+        idxs = [i for i in idxs if i != control_idx]
+        if not idxs:
+            raise ValueError(
+                "No target channels remain after excluding the control channel."
+            )
+
+        new = state.signals.copy()
+        motion_fit = np.full_like(state.signals, np.nan, dtype=float)
+
+        per_channel: dict[str, dict[str, Any]] = {}
+        r2s: list[float] = []
+
+        for i in idxs:
+            name = state.channel_names[i]
+            y = state.signals[i]
+
+            if self.method == "ols":
+                fit = fit_ols(x, y, include_intercept=self.include_intercept)
+                max_iter: int | None = None
+            else:
+                loss = "tukey" if self.method == "irls_tukey" else "huber"
+                fit = fit_irls(
+                    x,
+                    y,
+                    include_intercept=self.include_intercept,
+                    loss=loss,
+                    tuning_constant=self.tuning_constant,
+                    max_iter=self.max_iter,
+                    tol=self.tol,
+                    store_weights=self.store_weights,
+                )
+                max_iter = self.max_iter
+
+            y_hat = fit.fitted
+            motion_fit[i] = y_hat
+            new[i] = y - y_hat
+
+            per_channel[name] = {
+                "control": self.control,
+                "intercept": fit.intercept,
+                "slope": fit.slope,
+                "r2": fit.r2,
+                "method": fit.method,
+                "n_iter": fit.n_iter,
+                "max_iter": max_iter,
+                "tuning_constant": fit.tuning_constant,
+                "scale": fit.scale,
+                "weights": fit.weights,
+            }
+            if np.isfinite(fit.r2):
+                r2s.append(float(fit.r2))
+
+        metrics: dict[str, float] = {}
+        if r2s:
+            metrics["mean_r2"] = float(np.mean(r2s))
+            metrics["median_r2"] = float(np.median(r2s))
+
+        return StageOutput(
+            signals=new,
+            derived={
+                "motion_fit": motion_fit,
+            },
+            results={
+                "control": self.control,
+                "control_idx": control_idx,
+                "channels_fitted": idxs,
+                "method": self.method,
+                "include_intercept": self.include_intercept,
+                "channels": per_channel,
+            },
+            metrics=metrics,
+        )