fibphot 0.1.0__py3-none-any.whl

fibphot/analysis/photobleaching.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+from ..state import PhotometryState
+from ..types import FloatArray
+
+ParamOrder = Literal["const", "amp_fast", "amp_slow", "tau_fast", "tau_slow"]
+
+
+@dataclass(frozen=True, slots=True)
+class DoubleExpParams:
+    const: float
+    amp_fast: float
+    amp_slow: float
+    tau_fast: float
+    tau_slow: float
+
+    @classmethod
+    def from_row(cls, row: FloatArray) -> DoubleExpParams:
+        r = np.asarray(row, dtype=float).ravel()
+        if r.shape[0] != 5:
+            raise ValueError(f"Expected 5 params, got shape {r.shape}.")
+        return cls(
+            const=float(r[0]),
+            amp_fast=float(r[1]),
+            amp_slow=float(r[2]),
+            tau_fast=float(r[3]),
+            tau_slow=float(r[4]),
+        )
+
+    def f0(self, t: FloatArray) -> FloatArray:
+        t = np.asarray(t, dtype=float)
+        return (
+            self.const
+            + self.amp_fast * np.exp(-t / self.tau_fast)
+            + self.amp_slow * np.exp(-t / self.tau_slow)
+        )
+
+
+def _last_stage_id(state: PhotometryState, stage_name: str) -> str:
+    target = stage_name.lower()
+    for rec in reversed(state.summary):
+        if rec.name.lower() == target:
+            return rec.stage_id
+    raise KeyError(f"Stage not found in summary: {stage_name!r}")
+
+
+def _half_drop_time(t: FloatArray, y: FloatArray) -> float:
+    """
+    Time at which y has completed half of its total drop from y[0] to y[-1].
+
+    If there is no net drop (y[-1] >= y[0]) returns NaN.
+    Uses linear interpolation between samples.
+    """
+    t = np.asarray(t, dtype=float)
+    y = np.asarray(y, dtype=float)
+
+    if t.ndim != 1 or y.ndim != 1 or t.shape[0] != y.shape[0]:
+        raise ValueError("t and y must be 1D arrays of the same length.")
+
+    y0 = float(y[0])
+    y1 = float(y[-1])
+    drop = y0 - y1
+    if not np.isfinite(drop) or drop <= 0.0:
+        return float("nan")
+
+    target = y0 - 0.5 * drop
+
+    # Find the first index where we are at/below target (assuming decay).
+    idx = np.where(y <= target)[0]
+    if idx.size == 0:
+        return float("nan")
+
+    j = int(idx[0])
+    if j == 0:
+        return float(t[0])
+
+    # Linear interpolation between (j-1) and j
+    t_lo, t_hi = float(t[j - 1]), float(t[j])
+    y_lo, y_hi = float(y[j - 1]), float(y[j])
+
+    denom = y_hi - y_lo
+    if not np.isfinite(denom) or abs(denom) < 1e-20:
+        return float(t_hi)
+
+    frac = (target - y_lo) / denom
+    frac = float(np.clip(frac, 0.0, 1.0))
+    return t_lo + frac * (t_hi - t_lo)
+
+
+def _norm_shape_rmse(a: FloatArray, b: FloatArray, eps: float = 1e-12) -> float:
+    """
+    RMSE between two traces after normalising each by its first sample.
+    """
+    a = np.asarray(a, dtype=float)
+    b = np.asarray(b, dtype=float)
+
+    if a.shape != b.shape:
+        raise ValueError(f"Shape mismatch: {a.shape} vs {b.shape}.")
+
+    a0 = float(a[0])
+    b0 = float(b[0])
+    if not (
+        np.isfinite(a0) or not np.isfinite(b0) or abs(a0) < eps or abs(b0) < eps
+    ):
+        return float("nan")
+
+    an = a / a0
+    bn = b / b0
+    d = an - bn
+    return float(np.sqrt(np.nanmean(d * d)))
+
+
+def photobleaching_summary(
+    state: PhotometryState,
+    *,
+    stage_id: str | None = None,
+    stage_name: str = "double_exp_baseline",
+    fast_component_threshold: float = 0.05,
+    control: str | None = None,
+) -> pd.DataFrame:
+    """
+    Per-channel summary of a fitted double exponential baseline.
+
+    Adds:
+      - has_fast_component: whether amp_fast / (amp_fast + amp_slow) exceeds
+        `fast_component_threshold`
+      - half_drop_time_s: time to complete half of the session-long drop
+      - optional control comparisons if `control` is provided:
+          * control_percent_drop
+          * percent_drop_minus_control
+          * tau_slow_ratio_to_control
+          * norm_shape_rmse_to_control
+    """
+    sid = stage_id or _last_stage_id(state, stage_name)
+    res = state.results.get(sid)
+    if res is None:
+        raise KeyError(f"No results found for stage_id={sid!r}.")
+
+    params = np.asarray(res.get("params"), dtype=float)
+    r2 = np.asarray(res.get("r2"), dtype=float) if "r2" in res else None
+    rmse = np.asarray(res.get("rmse"), dtype=float) if "rmse" in res else None
+
+    if params.ndim != 2 or params.shape[1] != 5:
+        raise ValueError(f"Expected params shape (n, 5), got {params.shape}.")
+
+    t = np.asarray(state.time_seconds, dtype=float)
+
+    baseline_curves: dict[str, FloatArray] = {}
+    rows: list[dict[str, float | str | bool]] = []
+
+    for i, name in enumerate(state.channel_names):
+        p = DoubleExpParams.from_row(params[i])
+
+        f = p.f0(t)
+        baseline_curves[name] = f
+
+        f_start = float(f[0])
+        f_end = float(f[-1])
+
+        amp_total = p.amp_fast + p.amp_slow
+        if amp_total != 0.0:
+            fast_frac = float(p.amp_fast / amp_total)
+            slow_frac = float(p.amp_slow / amp_total)
+        else:
+            fast_frac = float("nan")
+            slow_frac = float("nan")
+
+        has_fast = bool(
+            np.isfinite(fast_frac) and fast_frac > fast_component_threshold
+        )
+
+        if f_start != 0.0 and np.isfinite(f_start) and np.isfinite(f_end):
+            drop_frac = float((f_start - f_end) / f_start)
+            percent_drop = 100.0 * drop_frac
+        else:
+            percent_drop = float("nan")
+
+        row: dict[str, float | str | bool] = {
+            "channel": name,
+            "tau_fast_s": p.tau_fast,
+            "tau_slow_s": p.tau_slow,
+            "fast_amp_frac": fast_frac,
+            "slow_amp_frac": slow_frac,
+            "has_fast_component": has_fast,
+            "half_drop_time_s": _half_drop_time(t, f),
+            "percent_drop": percent_drop,
+            "const": p.const,
+            "amp_fast": p.amp_fast,
+            "amp_slow": p.amp_slow,
+            "f0_start": f_start,
+            "f0_end": f_end,
+        }
+        if r2 is not None and i < r2.shape[0]:
+            row["r2"] = float(r2[i])
+        if rmse is not None and i < rmse.shape[0]:
+            row["rmse"] = float(rmse[i])
+
+        rows.append(row)
+
+    df = pd.DataFrame(rows)
+
+    if control is not None:
+        ctl = control.lower()
+        if ctl not in baseline_curves:
+            raise KeyError(
+                f"Control channel {control!r} not found. "
+                f"Available: {state.channel_names}"
+            )
+
+        ctl_row = df.loc[df["channel"] == ctl]
+        if ctl_row.empty:
+            raise KeyError(f"Control channel {control!r} not found in summary.")
+        ctl_percent_drop = float(ctl_row["percent_drop"].iloc[0])
+        ctl_tau_slow = float(ctl_row["tau_slow_s"].iloc[0])
+        ctl_curve = baseline_curves[ctl]
+
+        df["control_percent_drop"] = ctl_percent_drop
+        df["percent_drop_minus_control"] = df["percent_drop"] - ctl_percent_drop
+        df["tau_slow_ratio_to_control"] = df["tau_slow_s"] / ctl_tau_slow
+
+        rmses: list[float] = []
+        for ch in df["channel"].tolist():
+            rmses.append(_norm_shape_rmse(baseline_curves[ch], ctl_curve))
+        df["norm_shape_rmse_to_control"] = rmses
+
+    preferred = [
+        "channel",
+        "tau_fast_s",
+        "tau_slow_s",
+        "fast_amp_frac",
+        "slow_amp_frac",
+        "has_fast_component",
+        "half_drop_time_s",
+        "percent_drop",
+        "r2",
+        "rmse",
+    ]
+    if control is not None:
+        preferred += [
+            "control_percent_drop",
+            "percent_drop_minus_control",
+            "tau_slow_ratio_to_control",
+            "norm_shape_rmse_to_control",
+        ]
+    preferred += ["const", "amp_fast", "amp_slow", "f0_start", "f0_end"]
+
+    cols = [c for c in preferred if c in df.columns]
+    return df[cols].sort_values("channel")
+
+
+def get_baseline_trace(
+    state: PhotometryState,
+    *,
+    baseline_key: str = "double_exp_baseline",
+    channel: str,
+    normalise_to_start: bool = False,
+    eps: float = 1e-12,
+) -> FloatArray:
+    """
+    Fetch a baseline trace from state.derived and optionally normalise to start.
+    """
+    if baseline_key not in state.derived:
+        raise KeyError(
+            f"derived['{baseline_key}'] not found. "
+            "Run the baseline stage first."
+        )
+    base = np.asarray(state.derived[baseline_key], dtype=float)
+    if base.shape != state.signals.shape:
+        raise ValueError(
+            f"derived['{baseline_key}'] has shape {base.shape}, "
+            f"expected {state.signals.shape}."
+        )
+
+    i = state.idx(channel)
+    y = base[i].copy()
+
+    if normalise_to_start:
+        d0 = float(y[0])
+        if not np.isfinite(d0) or abs(d0) < eps:
+            y[:] = np.nan
+        else:
+            y = y / d0
+
+    return y

fibphot/analysis/plotting.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from ..state import PhotometryState
+from .report import AnalysisResult
+
+
+def plot_auc_result(
+    state: PhotometryState,
+    result: AnalysisResult,
+    *,
+    ax=None,
+    label: str | None = None,
+    signal_alpha: float = 0.9,
+    window_alpha: float = 0.08,
+    fill_alpha: float = 0.30,
+    linewidth: float = 1.2,
+    fontsize: int = 8,
+    show_metrics: bool = True,
+    colour_signal: str = "#1f77b4",  # vivid blue
+    colour_baseline: str = "#444444",  # dark grey
+    colour_fill: str = "#ff7f0e",  # vivid orange
+):
+    """
+    Visualise an AUC AnalysisResult:
+      - plots full trace
+      - shows baseline reference line
+      - shades the analysis window
+      - fills the integrated area (using stored window contrib)
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 3), dpi=150)
+    else:
+        fig = ax.figure
+
+    chan = result.channel
+    t = np.asarray(state.time_seconds, float)
+    y = np.asarray(state.channel(chan), float)
+
+    lab = label or chan
+    ax.plot(
+        t,
+        y,
+        linewidth=linewidth,
+        alpha=signal_alpha,
+        label=lab,
+        color=colour_signal,
+    )
+
+    b = float(result.metrics.get("baseline", np.nan))
+    if np.isfinite(b):
+        ax.axhline(
+            b, linewidth=1.0, alpha=0.85, linestyle="--", color=colour_baseline
+        )
+
+    # Window display
+    t0 = result.metrics.get("t0", None)
+    t1 = result.metrics.get("t1", None)
+    if (
+        t0 is not None
+        and t1 is not None
+        and np.isfinite(t0)
+        and np.isfinite(t1)
+    ):
+        ax.axvspan(float(t0), float(t1), alpha=window_alpha, color="grey")
+
+    # Fill based on stored arrays
+    tt = np.asarray(result.arrays.get("t_window", np.array([])), float)
+    contrib = np.asarray(result.arrays.get("contrib", np.array([])), float)
+
+    if tt.size >= 2 and contrib.size == tt.size and np.isfinite(b):
+        ax.fill_between(
+            tt,
+            b,
+            b + contrib,
+            alpha=fill_alpha,
+            color=colour_fill,
+            label="AUC area",
+        )
+
+    ax.set_xlabel("time (s)", fontsize=fontsize)
+    ax.set_ylabel(chan, fontsize=fontsize)
+
+    ax.tick_params(axis="both", which="major", labelsize=fontsize)
+
+    if show_metrics:
+        auc = result.metrics.get("auc", np.nan)
+        baseline = result.metrics.get("baseline", np.nan)
+        txt = f"AUC: {auc:.3g}\nBaseline: {baseline:.3g}"
+        ax.text(
+            0.02,
+            0.98,
+            txt,
+            transform=ax.transAxes,
+            va="top",
+            ha="left",
+            fontsize=fontsize,
+            color="#222222",
+        )
+
+    ax.legend(frameon=False, fontsize=fontsize)
+
+    return fig, ax

fibphot/analysis/report.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import numpy.typing as npt
+
+from ..state import PhotometryState
+
+WindowRef = Literal["seconds", "samples"]
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisWindow:
+    """
+    A window over which an analysis is evaluated.
+
+    - ref="seconds": start/end are in seconds (state.time_seconds space)
+    - ref="samples": start/end are integer sample indices [start, end)
+    """
+
+    start: float | int
+    end: float | int
+    ref: WindowRef = "seconds"
+    label: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisResult:
+    name: str  # e.g. "auc"
+    channel: str  # e.g. "gcamp"
+    window: AnalysisWindow | None  # None means “whole trace”
+    params: dict[str, Any] = field(default_factory=dict)
+
+    metrics: dict[str, float] = field(default_factory=dict)
+    arrays: dict[str, npt.NDArray[Any]] = field(default_factory=dict)
+
+    notes: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PhotometryReport:
+    state: PhotometryState
+    results: tuple[AnalysisResult, ...] = ()
+
+    def add(self, result: AnalysisResult) -> PhotometryReport:
+        return PhotometryReport(self.state, results=(*self.results, result))
+
+    def extend(self, results: Iterable[AnalysisResult]) -> PhotometryReport:
+        return PhotometryReport(
+            self.state, results=(*self.results, *tuple(results))
+        )
+
+    def find(self, name: str) -> tuple[AnalysisResult, ...]:
+        return tuple(r for r in self.results if r.name == name)

fibphot/collection.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from .analysis.aggregate import (
+    AlignedSignals,
+    align_collection_signals,
+    mean_state_from_aligned,
+)
+from .state import PhotometryState
+from .tags import TagTable, apply_tags, default_subject_getter, read_tag_table
+
+SubjectGetter = Callable[[PhotometryState], str | None]
+AlignMode = Literal["intersection", "union"]
+InterpKind = Literal["linear", "nearest"]
+TimeRef = Literal["absolute", "start"]
+
+
+@dataclass(frozen=True, slots=True)
+class PhotometryCollection:
+    """
+    A thin immutable wrapper around multiple PhotometryState objects.
+
+    Provides tag-aware filtering, grouping, sorting, and bulk serialisation.
+    """
+
+    states: Sequence[PhotometryState]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "states", tuple(self.states))
+
+    @classmethod
+    def from_iterable(
+        cls, states: Iterable[PhotometryState]
+    ) -> PhotometryCollection:
+        return cls(states=tuple(states))
+
+    @classmethod
+    def from_glob(
+        cls,
+        base_path: Path | str,
+        pattern: str = "*.doric",
+        *,
+        reader: Callable[[Path], PhotometryState],
+        metadata_fn: Callable[[Path], dict[str, Any]] | None = None,
+        sort: bool = True,
+    ) -> PhotometryCollection:
+        base = Path(base_path)
+        paths = list(base.glob(pattern))
+        if sort:
+            paths.sort()
+
+        def _iter() -> Iterable[PhotometryState]:
+            for p in paths:
+                st = reader(p)
+                if metadata_fn is not None:
+                    st = st.with_metadata(**metadata_fn(p))
+                yield st
+
+        return cls(states=tuple(_iter()))
+
+    def __len__(self) -> int:
+        return len(self.states)
+
+    def __iter__(self):
+        return iter(self.states)
+
+    @property
+    def subjects(self) -> tuple[str | None, ...]:
+        return tuple(s.subject for s in self.states)
+
+    def pipe(self, *stages: object) -> PhotometryCollection:
+        return PhotometryCollection(
+            states=tuple(s.pipe(*stages) for s in self.states)
+        )
+
+    def with_tags_from_table(
+        self,
+        path: Path | str,
+        *,
+        subject_getter: SubjectGetter = default_subject_getter,
+        overwrite: bool = False,
+    ) -> PhotometryCollection:
+        table = read_tag_table(path)
+        return self.with_tags(
+            table, subject_getter=subject_getter, overwrite=overwrite
+        )
+
+    def with_tags(
+        self,
+        table: TagTable,
+        *,
+        subject_getter: SubjectGetter = default_subject_getter,
+        overwrite: bool = False,
+    ) -> PhotometryCollection:
+        tagged = tuple(
+            apply_tags(
+                s, table, subject_getter=subject_getter, overwrite=overwrite
+            )
+            for s in self.states
+        )
+        return PhotometryCollection(states=tagged)
+
+    def filter(self, **criteria: str) -> PhotometryCollection:
+        """
+        Filter by tags: e.g. .filter(genotype="KO", context="A")
+        """
+
+        def ok(s: PhotometryState) -> bool:
+            tags = s.tags
+            return all(tags.get(k) == v for k, v in criteria.items())
+
+        return PhotometryCollection(
+            states=tuple(s for s in self.states if ok(s))
+        )
+
+    def groupby(self, key: str) -> dict[str, PhotometryCollection]:
+        """
+        Group by a tag key: returns {tag_value: PhotometryCollection}.
+        Missing values go under "".
+        """
+        groups: dict[str, list[PhotometryState]] = {}
+        for s in self.states:
+            v = s.tags.get(key, "")
+            groups.setdefault(v, []).append(s)
+
+        return {
+            k: PhotometryCollection(states=tuple(v)) for k, v in groups.items()
+        }
+
+    def sort_by(self, *keys: str) -> PhotometryCollection:
+        """
+        Sort by one or more tag keys (lexicographic).
+        Missing values sort as "".
+        """
+
+        def sort_key(s: PhotometryState) -> tuple[str, ...]:
+            tags = s.tags
+            return tuple(tags.get(k, "") for k in keys)
+
+        return PhotometryCollection(
+            states=tuple(sorted(self.states, key=sort_key))
+        )
+
+    def map(
+        self, fn: Callable[[PhotometryState], PhotometryState]
+    ) -> PhotometryCollection:
+        return PhotometryCollection(states=tuple(fn(s) for s in self.states))
+
+    def align(
+        self,
+        *,
+        channels: Sequence[str] | None = None,
+        align: AlignMode = "intersection",
+        time_ref: TimeRef = "start",
+        dt: float | None = None,
+        target_fs: float | None = None,
+        interpolation: InterpKind = "linear",
+        fill: float = float("nan"),
+    ) -> AlignedSignals:
+        return align_collection_signals(
+            self.states,
+            channels=channels,
+            align=align,
+            time_ref=time_ref,
+            dt=dt,
+            target_fs=target_fs,
+            interpolation=interpolation,
+            fill=fill,
+        )
+
+    def mean(
+        self,
+        *,
+        channels: Sequence[str] | None = None,
+        align: AlignMode = "intersection",
+        time_ref: TimeRef = "start",
+        dt: float | None = None,
+        target_fs: float | None = None,
+        interpolation: InterpKind = "linear",
+        fill: float = float("nan"),
+        name: str = "group_mean",
+    ) -> PhotometryState:
+        aligned = self.align(
+            channels=channels,
+            align=align,
+            time_ref=time_ref,
+            dt=dt,
+            target_fs=target_fs,
+            interpolation=interpolation,
+            fill=fill,
+        )
+        return mean_state_from_aligned(aligned, name=name)
+
+    def to_h5(self, path: Path | str) -> None:
+        from .io.h5 import save_collection_h5
+
+        save_collection_h5(self, path)
+
+    @classmethod
+    def from_h5(cls, path: Path | str) -> PhotometryCollection:
+        from .io.h5 import load_collection_h5
+
+        return load_collection_h5(path)