fibphot 0.1.0__tar.gz

fibphot-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,16 @@
+# 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/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fibphot"
+version = "0.1.0"
+description = "Analysis pipeline for fibre photometry data"
+readme = "README.md"
+authors = [{ name = "Thomas Nicholas", email = "tcnicholas@me.com" }]
+license = { file = "LICENSE" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "h5py>=3.15.1",
+    "matplotlib>=3.10.8",
+    "numpy>=2.4.1",
+    "openpyxl>=3.1.5",
+    "pandas>=2.3.3",
+    "pybaselines>=1.2.1",
+    "scipy>=1.17.0",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+topo_metrics = ["RingStatistics/**/*"]
+
+[project.urls]
+Homepage = "https://github.com/tcnicholas/fibphot"
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.14.13",
+    "pytest>=8.0",
+    "matplotlib>=3.10.8",
+]
+publish = ["build", "twine"]
+docs = [
+    "sphinx",
+    "pip",
+    "furo",
+    "nbsphinx",
+    "ipython",
+    "pyzmq",
+    "sphinx-autoapi",
+    "sphinx-autobuild",
+    "pydata_sphinx_theme",
+    "sphinxext-opengraph",
+    "sphinx-copybutton",
+    "sphinx-design",
+    "jupyter_sphinx",
+    "sphinx-togglebutton",
+    "sphinx_favicon",
+    "sphinx_sitemap",
+]
+
+[tool.bumpver]
+current_version = "0.1.0"
+version_pattern = "MAJOR.MINOR.PATCH"
+commit_message = "bump {old_version} -> {new_version}"
+commit = true
+tag = true
+push = false
+
+[tool.bumpver.file_patterns]
+"pyproject.toml" = ['current_version = "{version}"', 'version = "{version}"']
+"src/fibphot/__init__.py" = ["{version}"]
+
+[tool.ruff]
+line-length = 80
+indent-width = 4
+target-version = "py38"
+extend-include = ["*.ipynb", "*.pyi", "*.toml"]
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I"]
+ignore = ["SIM300", "E402", "E703", "F722", "UP037", "F821", "B018", "E741"]
+fixable = ["ALL"]
+unfixable = []
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"

fibphot-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fibphot-0.1.0/src/fibphot/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .state import PhotometryState, StageRecord
+
+__all__ = ["PhotometryState", "StageRecord"]
+__version__ = "0.1.0"

fibphot-0.1.0/src/fibphot/analysis/aggregate.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+
+from ..state import PhotometryState
+from ..types import FloatArray
+
+AlignMode = Literal["intersection", "union"]
+TimeRef = Literal["absolute", "start"]
+InterpKind = Literal["linear", "nearest"]
+
+
+@dataclass(frozen=True, slots=True)
+class AlignedSignals:
+    """
+    Container for a time-aligned stack of signals.
+
+    aligned has shape (n_states, n_channels, n_time).
+    """
+
+    time_seconds: FloatArray
+    aligned: FloatArray
+    channel_names: tuple[str, ...]
+    subjects: tuple[str | None, ...]
+    align_mode: AlignMode
+    time_ref: TimeRef
+    dt: float
+
+
+def _as_relative_time(t: FloatArray) -> FloatArray:
+    t = np.asarray(t, dtype=float)
+    return t - float(t[0])
+
+
+def _infer_dt(states: Sequence[PhotometryState]) -> float:
+    dts: list[float] = []
+    for s in states:
+        dt = np.diff(np.asarray(s.time_seconds, dtype=float))
+        if dt.size == 0:
+            continue
+        dts.append(float(np.nanmedian(dt)))
+    if not dts:
+        raise ValueError(
+            "Cannot infer dt from empty or degenerate time arrays."
+        )
+    return float(np.nanmedian(np.asarray(dts, dtype=float)))
+
+
+def _time_window(
+    times: list[FloatArray],
+    mode: AlignMode,
+) -> tuple[float, float]:
+    starts = [float(t[0]) for t in times]
+    ends = [float(t[-1]) for t in times]
+
+    if mode == "intersection":
+        t0 = max(starts)
+        t1 = min(ends)
+    elif mode == "union":
+        t0 = min(starts)
+        t1 = max(ends)
+    else:
+        raise ValueError(f"Unknown align mode: {mode!r}")
+
+    if not np.isfinite(t0) or not np.isfinite(t1) or t1 <= t0:
+        raise ValueError(
+            f"Invalid common window from mode={mode!r}: ({t0}, {t1})."
+        )
+    return t0, t1
+
+
+def _make_grid(t0: float, t1: float, dt: float) -> FloatArray:
+    n = int(np.floor((t1 - t0) / dt)) + 1
+    if n < 2:
+        raise ValueError("Common time grid would have <2 points.")
+    return t0 + dt * np.arange(n, dtype=float)
+
+
+def _interp_1d(
+    x: FloatArray,
+    y: FloatArray,
+    x_new: FloatArray,
+    *,
+    kind: InterpKind,
+    fill: float,
+) -> FloatArray:
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    x_new = np.asarray(x_new, dtype=float)
+
+    mask = np.isfinite(x) & np.isfinite(y)
+    x0 = x[mask]
+    y0 = y[mask]
+    if x0.size < 2:
+        return np.full_like(x_new, fill, dtype=float)
+
+    order = np.argsort(x0)
+    x0 = x0[order]
+    y0 = y0[order]
+
+    if kind == "linear":
+        return np.interp(x_new, x0, y0, left=fill, right=fill).astype(float)
+
+    if kind == "nearest":
+        idx = np.searchsorted(x0, x_new, side="left")
+        idx = np.clip(idx, 0, x0.size - 1)
+        left = np.clip(idx - 1, 0, x0.size - 1)
+
+        choose_left = np.abs(x_new - x0[left]) <= np.abs(x_new - x0[idx])
+        out = np.where(choose_left, y0[left], y0[idx]).astype(float)
+
+        out[(x_new < x0[0]) | (x_new > x0[-1])] = fill
+        return out
+
+    raise ValueError(f"Unknown interpolation kind: {kind!r}")
+
+
+def align_collection_signals(
+    states: Sequence[PhotometryState],
+    *,
+    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:
+    """
+    Align a set of states to a common time axis via interpolation.
+
+    align="intersection":
+        Uses only the time interval present in all states (truncate behaviour).
+    align="union":
+        Uses the full time span across states and fills missing regions (pad behaviour).
+
+    time_ref="start":
+        Treats each state's time as relative to its own start time.
+    time_ref="absolute":
+        Uses each state's original time_seconds values.
+    """
+    if not states:
+        raise ValueError("No states provided.")
+
+    if channels is None:
+        channel_names = states[0].channel_names
+        idxs = list(range(states[0].n_signals))
+    else:
+        channel_names = tuple(c.lower() for c in channels)
+        idxs = [states[0].idx(c) for c in channel_names]
+
+    for s in states[1:]:
+        for c in channel_names:
+            _ = s.idx(c)
+
+    if target_fs is not None:
+        if target_fs <= 0:
+            raise ValueError("target_fs must be > 0.")
+        dt_use = 1.0 / float(target_fs)
+    else:
+        dt_use = float(dt) if dt is not None else _infer_dt(states)
+
+    times: list[FloatArray] = []
+    for s in states:
+        t = np.asarray(s.time_seconds, dtype=float)
+        if time_ref == "start":
+            t = _as_relative_time(t)
+        times.append(t)
+
+    t0, t1 = _time_window(times, align)
+    grid = _make_grid(t0, t1, dt_use)
+
+    aligned = np.full(
+        (len(states), len(idxs), grid.size),
+        fill,
+        dtype=float,
+    )
+
+    for si, s in enumerate(states):
+        t = times[si]
+        for cj, idx in enumerate(idxs):
+            y = np.asarray(s.signals[idx], dtype=float)
+            aligned[si, cj] = _interp_1d(
+                t,
+                y,
+                grid,
+                kind=interpolation,
+                fill=fill,
+            )
+
+    subjects: tuple[str | None, ...] = tuple(
+        getattr(s, "subject", None) for s in states
+    )
+
+    return AlignedSignals(
+        time_seconds=grid,
+        aligned=aligned,
+        channel_names=tuple(channel_names),
+        subjects=subjects,
+        align_mode=align,
+        time_ref=time_ref,
+        dt=dt_use,
+    )
+
+
+def mean_aligned(
+    aligned: AlignedSignals,
+) -> tuple[FloatArray, FloatArray, FloatArray, FloatArray]:
+    """
+    Compute mean, std, sem, and n (per channel/time) from an aligned stack.
+    """
+    x = np.asarray(aligned.aligned, dtype=float)
+
+    n = np.sum(np.isfinite(x), axis=0).astype(float)
+    mean = np.nanmean(x, axis=0)
+    std = np.nanstd(x, axis=0)
+
+    sem = std / np.sqrt(np.where(n <= 0, np.nan, n))
+    return mean, std, sem, n
+
+
+def mean_state_from_aligned(
+    aligned: AlignedSignals,
+    *,
+    name: str = "group_mean",
+) -> PhotometryState:
+    """
+    Return a PhotometryState whose signals are the group mean.
+
+    Additional statistics are stored in derived:
+        - derived["group_std"]
+        - derived["group_sem"]
+        - derived["group_n"]
+    """
+    mean, std, sem, n = mean_aligned(aligned)
+
+    return PhotometryState(
+        time_seconds=aligned.time_seconds,
+        signals=mean,
+        channel_names=aligned.channel_names,
+        derived={
+            "group_std": std,
+            "group_sem": sem,
+            "group_n": n,
+        },
+        metadata={
+            "kind": name,
+            "align_mode": aligned.align_mode,
+            "time_ref": aligned.time_ref,
+            "dt": aligned.dt,
+            "subjects": list(aligned.subjects),
+        },
+    )