fibphot 0.1.0__py3-none-any.whl

fibphot/state.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from .types import FloatArray
+
+
+@dataclass(frozen=True, slots=True)
+class StageRecord:
+    """Concise record of an applied preprocessing stage."""
+
+    stage_id: str
+    name: str
+    params: dict[str, Any] = field(default_factory=dict)
+    metrics: dict[str, float] = field(default_factory=dict)
+    notes: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PhotometryState:
+    """
+    Immutable photometry data state.
+
+    signals: stacked 2D array with shape (n_signals, n_samples).
+    history: stacked 3D array with shape (h, n_signals, n_samples),
+             storing previous *signals* snapshots only.
+    """
+
+    time_seconds: FloatArray
+    signals: FloatArray
+    channel_names: tuple[str, ...]
+    history: FloatArray = field(
+        default_factory=lambda: np.empty((0, 0, 0), dtype=float)
+    )
+    summary: tuple[StageRecord, ...] = ()
+    derived: dict[str, FloatArray] = field(default_factory=dict)
+    results: dict[str, dict[str, Any]] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    _name_to_index: dict[str, int] = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        t = np.asarray(self.time_seconds, dtype=float)
+        s = np.asarray(self.signals, dtype=float)
+
+        if t.ndim != 1:
+            raise ValueError("time_seconds must be 1D.")
+        if s.ndim != 2:
+            raise ValueError(
+                "signals must be 2D with shape (n_signals, n_samples)."
+            )
+        if s.shape[1] != t.shape[0]:
+            raise ValueError(
+                "signals second dimension must match time length: "
+                f"{s.shape[1]} != {t.shape[0]}"
+            )
+        if len(self.channel_names) != s.shape[0]:
+            raise ValueError(
+                "channel_names length must match signals first dimension: "
+                f"{len(self.channel_names)} != {s.shape[0]}"
+            )
+
+        # normalise channel names to lower case
+        names = tuple(str(n).lower() for n in self.channel_names)
+        name_to_idx = {n: i for i, n in enumerate(names)}
+
+        # history normalisation
+        h = np.asarray(self.history, dtype=float)
+        if h.size == 0:
+            h = np.empty((0, s.shape[0], s.shape[1]), dtype=float)
+        elif h.ndim != 3 or h.shape[1:] != s.shape:
+            raise ValueError(
+                "history must be 3D with shape (h, n_signals, n_samples) "
+                f"matching signals; got {h.shape}, expected "
+                f"(*, {s.shape[0]}, {s.shape[1]})."
+            )
+
+        object.__setattr__(self, "time_seconds", t)
+        object.__setattr__(self, "signals", s)
+        object.__setattr__(self, "channel_names", names)
+        object.__setattr__(self, "history", h)
+        object.__setattr__(self, "_name_to_index", name_to_idx)
+
+    @property
+    def n_samples(self) -> int:
+        return int(self.time_seconds.shape[0])
+
+    @property
+    def n_signals(self) -> int:
+        return int(self.signals.shape[0])
+
+    @property
+    def sampling_rate(self) -> float:
+        dt = np.diff(self.time_seconds)
+        return float(1.0 / np.median(dt))
+
+    @property
+    def tags(self) -> dict[str, str]:
+        raw = self.metadata.get("tags", {})
+        if isinstance(raw, dict):
+            return {str(k): str(v) for k, v in raw.items()}
+        return {}
+
+    @property
+    def subject(self) -> str | None:
+        subj = self.metadata.get("subject")
+        if subj is not None:
+            return str(subj)
+
+        src = self.metadata.get("source_path")
+        if not src:
+            return None
+
+        stem = Path(str(src)).stem
+
+        return stem.split("_", maxsplit=1)[0].lower() if stem else None
+
+    def idx(self, channel: str) -> int:
+        key = channel.lower()
+        if key not in self._name_to_index:
+            raise KeyError(
+                f"Unknown channel '{channel}'. Available: {self.channel_names}"
+            )
+        return self._name_to_index[key]
+
+    def channel(self, channel: str) -> FloatArray:
+        return self.signals[self.idx(channel)]
+
+    def tag(self, key: str, default: str | None = None) -> str | None:
+        return self.tags.get(key, default)
+
+    def with_channel(self, channel: str, values: FloatArray) -> PhotometryState:
+        v = np.asarray(values, dtype=float)
+        if v.shape != (self.n_samples,):
+            raise ValueError(
+                f"Channel replacement must have shape ({self.n_samples},), "
+                f"got {v.shape}."
+            )
+        i = self.idx(channel)
+        new_signals = self.signals.copy()
+        new_signals[i] = v
+        return replace(self, signals=new_signals)
+
+    def with_metadata(
+        self, updates: dict[str, Any] | None = None, **kwargs: Any
+    ) -> PhotometryState:
+        patch: dict[str, Any] = {}
+        if updates:
+            patch.update(updates)
+        patch.update(kwargs)
+
+        new_meta = dict(self.metadata)
+        new_meta.update(patch)
+        return replace(self, metadata=new_meta)
+
+    def with_tags(
+        self,
+        tags: dict[str, str],
+        *,
+        overwrite: bool = False,
+    ) -> PhotometryState:
+        existing = dict(self.tags)
+        incoming = {str(k): str(v) for k, v in tags.items()}
+
+        if overwrite:
+            existing.update(incoming)
+        else:
+            for k, v in incoming.items():
+                existing.setdefault(k, v)
+
+        return self.with_metadata(tags=existing)
+
+    def push_history(self) -> PhotometryState:
+        """Return a new state with the current signals appended to history."""
+        new_hist = np.concatenate(
+            [self.history, self.signals[None, :, :]], axis=0
+        )
+        return replace(self, history=new_hist)
+
+    def raw(self) -> PhotometryState:
+        """
+        Return a new state representing the raw signals (after 0 stages).
+
+        - signals restored to the raw snapshot
+        - history cleared (you are back at the start)
+        - summary/results/derived cleared
+        - metadata preserved
+        """
+        if self.history.shape[0] == 0:
+            # No stages applied, already raw.
+            return self
+
+        raw_signals = self.history[0]
+
+        return PhotometryState(
+            time_seconds=self.time_seconds,
+            signals=raw_signals,
+            channel_names=self.channel_names,
+            history=np.empty((0, self.n_signals, self.n_samples), dtype=float),
+            summary=(),
+            derived={},
+            results={},
+            metadata=self.metadata,
+        )
+
+    def revert(self, n_steps: int | None = 1) -> PhotometryState:
+        """
+        Revert to a previous signals snapshot and drops corresponding summary
+        entries and stage results.
+
+        n_steps=1: before most recent stage
+        n_steps=None: restore raw (after 0 stages)
+        """
+        if n_steps is None:
+            return self.raw()
+
+        if n_steps < 1:
+            raise ValueError("n_steps must be >= 1.")
+        if self.history.shape[0] < n_steps:
+            raise ValueError(
+                f"Cannot revert {n_steps} step(s); history has "
+                f"{self.history.shape[0]}."
+            )
+
+        restored_signals = self.history[-n_steps]
+        new_history = self.history[:-n_steps]
+        new_summary = self.summary[:-n_steps]
+
+        valid_ids = {r.stage_id for r in new_summary}
+        new_results = {k: v for k, v in self.results.items() if k in valid_ids}
+
+        return PhotometryState(
+            time_seconds=self.time_seconds,
+            signals=restored_signals,
+            channel_names=self.channel_names,
+            history=new_history,
+            summary=new_summary,
+            derived={},
+            results=new_results,
+            metadata=self.metadata,
+        )
+
+    def revert_to(self, stage_name: str) -> PhotometryState:
+        """
+        Revert to the state immediately after the last occurrence of stage_name.
+
+        If stage_name does not exist in the summary, raises KeyError.
+        """
+        target = stage_name.lower()
+        names = [r.name.lower() for r in self.summary]
+        if target not in names:
+            raise KeyError(f"Stage '{stage_name}' not found in summary.")
+
+        last_idx = max(i for i, n in enumerate(names) if n == target)
+        steps_to_drop = len(self.summary) - (last_idx + 1)
+        return self if steps_to_drop == 0 else self.revert(steps_to_drop)
+
+    def pipe(self, *stages: Any) -> PhotometryState:
+        """Apply stages in order (functional pipeline)."""
+        state: PhotometryState = self
+        for st in stages:
+            state = st(state)
+        return state
+
+    def plot(
+        self,
+        *,
+        signal: str,
+        control: str | None = None,
+        **kwargs: Any,
+    ):
+        """Plot the current state."""
+        from .plotting import plot_current
+
+        return plot_current(self, signal=signal, control=control, **kwargs)
+
+    def plot_history(self, channel: str, **kwargs):
+        """Plot a channel across the saved history (and optionally current)."""
+        from .plotting import plot_history
+
+        return plot_history(self, channel, **kwargs)
+
+    def to_h5(
+        self,
+        path: Path | str,
+        *,
+        compression: str | None = "gzip",
+        compression_opts: int = 4,
+    ) -> None:
+        """Save this state to an HDF5 file."""
+        from .io.h5 import save_state_h5
+
+        save_state_h5(
+            self,
+            path,
+            compression=compression,
+            compression_opts=compression_opts,
+        )
+
+    @classmethod
+    def from_h5(cls, path: Path | str) -> PhotometryState:
+        """Load a state from an HDF5 file."""
+        from .io.h5 import load_state_h5
+
+        return load_state_h5(path)

fibphot/tags.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import csv
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from .state import PhotometryState
+
+SubjectGetter = Callable[[PhotometryState], str | None]
+
+
+@dataclass(frozen=True, slots=True)
+class TagTable:
+    """
+    Mapping from subject -> tags.
+
+    The first column is assumed to be the subject identifier. Remaining columns
+    are treated as tag keys.
+    """
+
+    by_subject: dict[str, dict[str, str]]
+
+    def tags_for(self, subject: str) -> dict[str, str]:
+        return dict(self.by_subject.get(subject.lower(), {}))
+
+
+def read_tag_table(path: Path | str) -> TagTable:
+    """
+    Read a delimited text table where the first column is subject.
+
+    Supports CSV/TSV/space-delimited. Header row is required.
+    """
+    path = Path(path)
+
+    text = path.read_text(encoding="utf-8").strip()
+    if not text:
+        raise ValueError(f"Tag file is empty: {path}")
+
+    # sniff delimiter (fallback to whitespace splitting)
+    sample = "\n".join(text.splitlines()[:5])
+    try:
+        dialect = csv.Sniffer().sniff(sample, delimiters=",\t;")
+        delim: str | None = dialect.delimiter
+    except csv.Error:
+        delim = None
+
+    rows: list[list[str]] = []
+    if delim is None:
+        for line in text.splitlines():
+            rows.append(re.split(r"\s+", line.strip()))
+    else:
+        reader = csv.reader(text.splitlines(), delimiter=delim)
+        rows = [list(r) for r in reader]
+
+    if len(rows) < 2:
+        raise ValueError(
+            "Tag table must include a header and at least one row."
+        )
+
+    header = [h.strip().lower() for h in rows[0]]
+    if len(header) < 2:
+        raise ValueError("Tag table must have >=2 columns (subject + tags).")
+
+    subj_key = header[0]
+    tag_keys = header[1:]
+
+    mapping: dict[str, dict[str, str]] = {}
+    for r in rows[1:]:
+        if not r or all(not c.strip() for c in r):
+            continue
+        subject = str(r[0]).strip().lower()
+        if not subject:
+            continue
+        tags: dict[str, str] = {}
+        for j, k in enumerate(tag_keys, start=1):
+            if j >= len(r):
+                tags[k] = ""
+            else:
+                tags[k] = str(r[j]).strip()
+        mapping[subject] = tags
+
+    if subj_key != "subject":
+        pass
+
+    return TagTable(by_subject=mapping)
+
+
+def subject_from_filename(path: Path | str) -> str:
+    """
+    Default subject extraction:
+      - take the stem
+      - split on '_' and use the first token
+
+    Example:
+      '74R_10122025_A61603_0001.doric' -> '74r'
+    """
+    p = Path(path)
+    stem = p.stem
+    token = stem.split("_", maxsplit=1)[0]
+    return token.lower()
+
+
+def default_subject_getter(state: PhotometryState) -> str | None:
+    """
+    Prefer explicit metadata subject, else derive from metadata['source_path'].
+    """
+    if state.subject is not None:
+        return state.subject
+    src = state.metadata.get("source_path")
+    if not src:
+        return None
+    return subject_from_filename(str(src))
+
+
+def apply_tags(
+    state: PhotometryState,
+    table: TagTable,
+    *,
+    subject_getter: SubjectGetter = default_subject_getter,
+    overwrite: bool = False,
+) -> PhotometryState:
+    subject = subject_getter(state)
+    if subject is None:
+        return state
+    tags = table.tags_for(subject)
+    if not tags:
+        return state
+    return state.with_tags(tags, overwrite=overwrite)

fibphot/types.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+FloatArray = npt.NDArray[np.floating]

fibphot-0.1.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: fibphot
+Version: 0.1.0
+Summary: Analysis pipeline for fibre photometry data
+Author-email: Thomas Nicholas <tcnicholas@me.com>
+Project-URL: Homepage, https://github.com/tcnicholas/fibphot
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: h5py>=3.15.1
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: numpy>=2.4.1
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pybaselines>=1.2.1
+Requires-Dist: scipy>=1.17.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.14.13; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: matplotlib>=3.10.8; extra == "dev"
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: pip; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: ipython; extra == "docs"
+Requires-Dist: pyzmq; extra == "docs"
+Requires-Dist: sphinx-autoapi; extra == "docs"
+Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: pydata_sphinx_theme; extra == "docs"
+Requires-Dist: sphinxext-opengraph; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Requires-Dist: jupyter_sphinx; extra == "docs"
+Requires-Dist: sphinx-togglebutton; extra == "docs"
+Requires-Dist: sphinx_favicon; extra == "docs"
+Requires-Dist: sphinx_sitemap; extra == "docs"
+Dynamic: license-file
+
+# FibPhot
+
+<div align="center">
+
+![PyPI - Version](https://img.shields.io/pypi/v/fibphot)
+[![GitHub License](https://img.shields.io/github/license/tcnicholas/fibphot)](LICENSE.md)
+</div>
+
+
+## Install
+
+
+## Relevant sources and related packages/code
+
+
+### References

fibphot-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+fibphot/__init__.py,sha256=J1DLAhU3rMvbc2cCU0KdvmKvj12LO6eDD1_34_TOplc,152
+fibphot/collection.py,sha256=cht9iam6Twa7xkHhf_RLNJFLwHIpDWcOc0RkJz1f0bA,6127
+fibphot/misc.py,sha256=7ubXg8-V_nNRRDcBCDYkqkrRhUd8e82qaLZyEkS2dWw,238
+fibphot/peaks.py,sha256=oSNQk1fHgLprH-_HU9lomyq9i_bsj9dMcsUHOl72440,18943
+fibphot/pipeline.py,sha256=LpCwFCt-mW69agjQrCqotRGWGa_y5w5A1EtaGLnZhbI,365
+fibphot/plotting.py,sha256=AUDGfN2T96RzuUb-7yj_3Tzsa_law0gMIxPn5EDfHWM,17081
+fibphot/state.py,sha256=X1IvSrWl8867EU7Lz10mcpSokpbWPDL7GQvYPcnVR9w,9927
+fibphot/tags.py,sha256=hpdN3yNQr4mSZ8IzXPBjPxdOSkRP_xIkJwbtmZiBRlk,3458
+fibphot/types.py,sha256=6z3Y6diDFRwafQcyJURJ4ILSk1GNx0zw4LeReFSNCHY,121
+fibphot/analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fibphot/analysis/aggregate.py,sha256=ETUxRYRPcBM_C0MTm6bcfNWIJ8DsjEXofYXk2AnmMCA,6958
+fibphot/analysis/auc.py,sha256=hIKxt4IY2EQLByONG3UD4rSi3rC79ZDVgVAVYCu8bGI,10109
+fibphot/analysis/irls.py,sha256=XNBkDnDDUPxIE2VmzTk9zIA_o35cT-nbALe2aNkcylQ,9846
+fibphot/analysis/peaks.py,sha256=YfByY7Ai_8aERxf3ae2lOxrhwcUgjHL6iD9GEk2XJVc,37014
+fibphot/analysis/photobleaching.py,sha256=2LZnZWLGoVRzCwBRoTdY3ec0i5-brSNT6hnzngajPMA,8806
+fibphot/analysis/plotting.py,sha256=2voBGXrDhE8SzU2Co_8hZWfycielY_8ye1NV0p84l1Q,2790
+fibphot/analysis/report.py,sha256=CgGKwjoo4wCTXSC5lTYsdUCcSmLfY7tCdm31ekfj11k,1622
+fibphot/fit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fibphot/fit/regression.py,sha256=6bgObLY26lk8bsk5j7s-HlUSTwW3gZ3YKEgIw6GLWd0,6969
+fibphot/io/__init__.py,sha256=punBqN99w6VCX_E2ZDWyvfxL6zQyP9TJW0Xr0uBNsFQ,136
+fibphot/io/doric.py,sha256=eGJjizkaKjapxqaOPNzLPk-OmEc0t13ydaql4yWQIEM,13702
+fibphot/io/excel.py,sha256=aGU-h8nWmP4H2_0XZ_MqWaPCpEbUgwu5ddQM3v-Y7EI,2241
+fibphot/io/h5.py,sha256=ev44eE_gXm3pZ9AlcjyfsPw_H8E9t9VgBHcLphNAjh8,10851
+fibphot/stages/__init__.py,sha256=SEDH1Gd8Jv7B-KfmKLXLbKuiFsBhUjxk1T0EPvXr5cM,551
+fibphot/stages/base.py,sha256=-C4gDU7EIgQc9cpq-bN6ttQp7DO4kzpYLx0JCgsJun0,2856
+fibphot/stages/baseline.py,sha256=mC-spEiCsuLMYKUqt3t2GPlJrPGQqkNbvpa8KRdlz7k,10989
+fibphot/stages/control_dff.py,sha256=5o-JSuSTnTEkJVcDl5uAN7tpk-KOVmkeg7HDPsFvdfU,7249
+fibphot/stages/filters.py,sha256=ciA92JZzCCwdc6Tpzyivfa5giawSq_Pp6qtUoFTFhRM,8817
+fibphot/stages/normalisation.py,sha256=aRxRsNSZ7Y4-CerJe-txy-APq8tcNh6NuSn7pEifNF8,8151
+fibphot/stages/regression.py,sha256=qAwDnNxFAtRiD_tfmiLAV9SUgLnNrmnLZ8rgDy2B-do,4409
+fibphot/stages/smooth.py,sha256=sqkNE7D9P6rfzjKJiu-Jr_ExSkFFQNseq44doBtOZjM,13193
+fibphot/stages/trim.py,sha256=zcnb-M4Wi7KdBVRN0m9PyPogsgp_rJ0Y4mFuoqEAS_w,3790
+fibphot-0.1.0.dist-info/licenses/LICENSE.md,sha256=W47AITyI1Om7cxTi5AKJYNe-rVEbsZPF4a5DOtFXMek,1071
+fibphot-0.1.0.dist-info/METADATA,sha256=_KJR5CFPd8amhlKxqwtdI5gqQvr7ZpWK8K5NrxIrr1Y,2057
+fibphot-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+fibphot-0.1.0.dist-info/top_level.txt,sha256=exLJNDNxfOY-ufk5CNv1B3bF-1mkVqyCZLKP77YeggM,8
+fibphot-0.1.0.dist-info/RECORD,,

fibphot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fibphot-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Nicholas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fibphot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fibphot