import warnings
from typing import Any
import numpy as np
import sparse
from spikeinterface.core.job_tools import fix_job_kwargs
from spikeinterface.core.node_pipeline import PipelineNode, run_node_pipeline
from .baseimaging import BaseImaging
from .baserois import BaseRois
from .roianalyzer import AnalyzerExtension, register_result_extension
_FLUORESCENCE_METHODS = ("projection", "regression", "nnls")
_NEUROPIL_SOURCES = ("neuropil", "background")
_NEUROPIL_METHODS = ("surround",)
[docs]
class FluorescenceExtension(AnalyzerExtension):
"""Extension to extract fluorescence traces from ROIs.
In the formulas below, ``A`` stands for the flattened ROI masks, ``(n_rois, n_pixels)`` -- ROI-first,
as ``get_roi_image_masks()`` returns them (CaImAn stores the transpose) -- and ``C`` for the traces,
``(n_frames, n_rois)``.
Three extraction methods are supported:
- ``'projection'`` (default): each ROI's trace is the movie projected onto its own mask,
``movie @ mask.T / sum(mask**2)``, each ROI independently -- a plain average over the mask
only when the mask is binary. Overlapping ROIs therefore pick up each other's signal.
- ``'regression'``: the least-squares solve of ``movie ~= C A (+ f b)`` for all ROIs at once, so
overlapping ROIs are separated. The sparse ``A A.T`` is factorized once and reused for every
chunk, with ``b`` handled by a small ``gnb x gnb`` Schur-complement correction on top.
- ``'nnls'``: the same solve with ``C >= 0`` enforced (fluorescence is a photon count). Solved
frame by frame with :func:`scipy.optimize.nnls`, so it costs more per chunk than
``'regression'``.
When a :class:`BackgroundExtension` exists, its spatial background ``b`` is appended to the
design matrix and its timecourse ``f`` is solved for together with the traces ``C``. That
requires ``'regression'`` or ``'nnls'``. With both a :class:`NeuropilExtension` and a
:class:`BackgroundExtension` computed, ``neuropil_source`` picks which one to use.
``neuropil_weight`` ``w`` (default ``0.7``, as in Suite2p) is how much of the estimated neuropil is
assumed to contaminate the ROI. For surround it is the weight of the subtracted ring mean
(``F - w Fneu``). For a CNMF background the traces are ``C + (1 - w) B``, i.e. ``(C + B) - w B``,
the same correction with ``B`` as the neuropil: the joint fit's own split corresponds to ``w = 1``,
and ``w < 1`` returns ``(1 - w) B`` to the trace, which is right when the background under the
ROIs is weaker than around them (cell bodies displacing neuropil). The fit cannot tell this from
the data: it only fixes the split up to a gauge freedom (see :class:`NeuropilExtension`).
Computed data keys:
================ ====================== ======================================================
Key Shape Contents
================ ====================== ======================================================
``fluorescence`` ``(n_frames, n_rois)`` the extracted traces: ``C + (1 - neuropil_weight) B``
for a CNMF background (``C`` for ``neuropil_weight=1``),
``F - neuropil_weight * Fneu`` for surround
``background`` ``(n_frames, n_rois)`` CNMF: ``B = f b A.T``, the background projected onto
each ROI's own footprint (divided by ``||a_i||^2``,
i.e. in the units of ``C``), before ``neuropil_weight``.
Surround: the ring mean
``Fneu`` before ``neuropil_weight``, on the same L2
scale as ``fluorescence`` (see
:meth:`_persisted_neuropil`). ``(n_frames, 0)``
without a neuropil.
================ ====================== ======================================================
"""
extension_name = "fluorescence"
depend_on: list[str] = []
need_imaging = True
use_nodepipeline = True
nodepipeline_variables = ["fluorescence", "background"]
need_job_kwargs = True
[docs]
@classmethod
def get_optional_dependencies(cls, use_neuropil=True, neuropil_source=None, **params):
if not use_neuropil:
return []
return ["|".join(_NEUROPIL_SOURCES)] if neuropil_source is None else [neuropil_source]
def _set_params(
self, use_neuropil=True, neuropil_weight=0.7, method="projection", ridge=1e-6, neuropil_source=None
):
"""Set parameters for fluorescence extraction.
Parameters
----------
use_neuropil : bool, optional
Use the ``neuropil`` or ``background`` extension if one has been computed. Default is
``True``.
neuropil_weight : float, optional
How much of the neuropil estimate is assumed to contaminate each ROI: the weight of the
subtracted surround trace, or, for a CNMF background, the share of ``B`` kept out of the
trace (see the class docstring); ``1`` keeps the joint fit's own split. Default is ``0.7``.
method : str, optional
``'projection'``, ``'regression'`` or ``'nnls'``; see the class docstring. Default is
``'projection'``.
ridge : float, optional
Regularization added to each diagonal entry of the Gram matrix, relative to that entry,
for ``'regression'`` and ``'nnls'``. Must be finite and non-negative: a negative ridge
shrinks the diagonal instead of padding it, which rescales the traces rather than
stabilizing them. Default is ``1e-6``.
neuropil_source : str or None, optional
``'neuropil'`` (surround masks) or ``'background'`` (CNMF ``b``). ``None`` (the default)
uses whichever of the two has been computed, and raises if both have.
"""
if method not in _FLUORESCENCE_METHODS:
raise ValueError(f"Unknown method: '{method}'. Supported: {_FLUORESCENCE_METHODS}.")
if neuropil_source is not None and neuropil_source not in _NEUROPIL_SOURCES:
raise ValueError(f"Unknown neuropil_source: '{neuropil_source}'. Supported: {_NEUROPIL_SOURCES}.")
_check_finite_non_negative("ridge", ridge)
return dict(
use_neuropil=use_neuropil,
neuropil_weight=neuropil_weight,
method=method,
ridge=ridge,
neuropil_source=neuropil_source,
)
def _neuropil_source(self):
"""The extension the traces are corrected with: ``'neuropil'``, ``'background'`` or ``None``."""
if not self.params["use_neuropil"]:
return None
available = [name for name in _NEUROPIL_SOURCES if self.roi_analyzer.has_extension(name)]
# .get() rather than [] so analyzers saved before 'neuropil_source' existed still load.
source = self.params.get("neuropil_source")
if source is None:
if len(available) > 1:
raise ValueError(
"Both 'neuropil' and 'background' are computed; pass "
"neuropil_source='neuropil' or neuropil_source='background' to choose one."
)
return available[0] if available else None
if source not in available:
raise ValueError(f"neuropil_source='{source}', but the '{source}' extension has not been computed.")
return source
def _run(self, verbose=False, **job_kwargs):
gather_mode = "memory"
gather_kwargs = {}
job_kwargs = fix_job_kwargs(job_kwargs)
nodes = self.get_pipeline_nodes()
fluorescence, background = run_node_pipeline(
self.roi_analyzer.imaging,
nodes,
job_kwargs=job_kwargs,
job_name=self.extension_name,
gather_mode=gather_mode,
gather_kwargs=gather_kwargs,
verbose=verbose,
)
self.data["fluorescence"] = fluorescence
self.data["background"] = background
def _neuropil_and_background(self):
"""``(neuropil, background_spatial)`` for the node; at most one of the two is not ``None``."""
source = self._neuropil_source()
neuropil = self.roi_analyzer.get_extension("neuropil").get_data() if source == "neuropil" else None
background_spatial = (
self.roi_analyzer.get_extension("background").get_data() if source == "background" else None
)
return neuropil, background_spatial
def _get_pipeline_nodes(self):
neuropil, background_spatial = self._neuropil_and_background()
return [
FluorescenceNode(
self.roi_analyzer.imaging,
self.roi_analyzer.rois,
neuropil=neuropil,
neuropil_weight=self.params["neuropil_weight"],
background_spatial=background_spatial,
method=self.params.get("method", "projection"),
ridge=self.params.get("ridge", 1e-6),
)
]
def _get_data(self, outputs="numpy", key="fluorescence"):
"""Return the extracted traces.
Parameters
----------
outputs : str, optional
``'numpy'`` or ``'recording'`` (a SpikeInterface ``NumpyRecording``). Default is
``'numpy'``.
key : str, optional
``'fluorescence'`` (the traces) or ``'background'`` (``B`` for a CNMF background, ``Fneu``
for surround; see the class docstring). Default is ``'fluorescence'``.
Raises
------
ValueError
For ``key='background'`` when the fluorescence was extracted without a neuropil. A
zero-ROI analyzer returns an empty ``(n_frames, 0)`` background instead of raising.
"""
if key not in ("fluorescence", "background"):
raise KeyError(f"Unknown key: '{key}'. Supported: 'fluorescence', 'background'.")
if key == "background":
if "background" not in self.data:
raise ValueError("No background: fluorescence was extracted without a neuropil.")
# A zero-ROI analyzer (select_rois([]), remove_rois(all)) also has a width-0
# background, but that is an empty result rather than a missing one. The traces
# carry the same width, so use them to tell the two apart.
if self.data["background"].shape[1] == 0 and self.data["fluorescence"].shape[1] > 0:
raise ValueError("No background: fluorescence was extracted without a neuropil.")
traces = self.data[key]
if outputs == "numpy":
return traces
elif outputs == "recording":
from spikeinterface.core import NumpyRecording
return NumpyRecording(
traces,
sampling_frequency=self.roi_analyzer.imaging.sampling_frequency,
channel_ids=self.roi_analyzer.rois.roi_ids,
)
else:
raise ValueError(f"Unsupported output type: {outputs}. Supported types are 'numpy' and 'recording'.")
def _select_extension_data(self, roi_ids):
roi_indices = self.roi_analyzer.rois.ids_to_indices(roi_ids)
selected = {"fluorescence": self.data["fluorescence"][:, roi_indices]}
if "background" in self.data:
background = self.data["background"]
# (n_frames, 0) when there was no neuropil: nothing to slice. Selecting no ROIs
# yields a width-0 background too; _get_data tells the two cases apart.
selected["background"] = background[:, roi_indices] if background.shape[1] else background
return selected
[docs]
class FluorescenceNode(PipelineNode):
def __init__(
self,
imaging: BaseImaging,
rois: BaseRois,
neuropil: np.ndarray | None = None,
neuropil_weight: float = 0.7,
background_spatial: np.ndarray | None = None,
method: str = "projection",
ridge: float = 1e-6,
):
"""
Pipeline node to extract fluorescence traces from ROIs, with optional neuropil subtraction.
Each ROI's own mask (whatever ``rois.get_roi_image_masks()`` returns) is renormalized
internally so the returned trace correctly reconstructs the movie via ``traces @
masks`` (using the original, unnormalized masks) and, for non-overlapping ROIs,
matches the least-squares solution of ``movie ~ traces @ masks``. For binary masks
(Suite2pRois and generate_rois's default) this exactly recovers each ROI's own
per-pixel value; masks themselves are untouched (`rois` isn't mutated).
Parameters
----------
imaging : BaseImaging
The imaging data to analyze.
rois : BaseRois
The ROIs to extract fluorescence from.
neuropil : np.ndarray, optional
Optional neuropil mask(s) to subtract from the fluorescence traces.
Should have shape (num_rois, height, width) or (height, width).
neuropil_weight : float, optional
Weight to apply to the neuropil signal before subtraction (default is 0.7). With
``background_spatial`` it is the share of the modelled background kept out of the traces:
they become ``C + (1 - neuropil_weight) B``.
background_spatial : np.ndarray, optional
Spatial background components ``b`` of shape ``(gnb, height, width[, planes])``, e.g.
from :class:`BackgroundExtension`'s ``method='cnmf'``. Appended to the design matrix and
solved for jointly with the traces; requires ``method='regression'`` or ``'nnls'``.
Mutually exclusive with ``neuropil``.
method : str, optional
``'projection'``, ``'regression'`` or ``'nnls'``; see :class:`FluorescenceExtension`.
ridge : float, optional
Relative diagonal regularization for ``'regression'`` and ``'nnls'`` (default ``1e-6``).
"""
PipelineNode.__init__(
self,
imaging,
parents=[],
return_output=True,
)
if method not in _FLUORESCENCE_METHODS:
raise ValueError(f"Unknown method: '{method}'. Supported: {_FLUORESCENCE_METHODS}.")
if neuropil is not None and background_spatial is not None:
raise ValueError("Pass either `neuropil` (surround masks) or `background_spatial` (CNMF), not both.")
if background_spatial is not None and method == "projection":
raise ValueError(
"A CNMF background is solved jointly with the traces, which needs "
"FluorescenceExtension(method='regression') or method='nnls', not 'projection'."
)
_check_finite_non_negative("ridge", ridge)
self.rois = rois
self.neuropil = neuropil
self.neuropil_weight = neuropil_weight
self.method = method
# Precompute flattened masks for efficient matrix multiplication. masks may be a
# dense ndarray or a sparse array (see BaseRois.get_roi_image_masks) -- reshape must
# be called with a single shape tuple for sparse arrays to accept it (unlike ndarray,
# which also accepts unpacked dimensions); a tuple works for both.
masks = rois.get_roi_image_masks() # (N, H, W) or (N, H, W, P)
num_rois = masks.shape[0]
masks_flat = masks.reshape((num_rois, -1)).astype(np.float32) # (N, spatial)
def _row_norm(x):
x = x.todense() if isinstance(x, sparse.SparseArray) else x
x = np.asarray(x).reshape(-1, 1)
x[x == 0] = 1.0 # an all-zero mask ROI stays all-zero, not NaN, downstream
return x
# Extraction uses each ROI's mask normalized to sum to 1 (L1, "mean" convention) --
# matching Suite2p's own F/Fneu convention (stat['lam'] weights sum to ~1;
# NeuropilExtension's ring masks are likewise L1-normalized, see
# _build_surround_neuropil_masks) so that F and the neuropil trace are on the same scale
# and F - neuropil_weight * neuropil_trace is dimensionally meaningful.
l1_norm = _row_norm(masks_flat.sum(axis=1))
self._masks_flat = masks_flat / l1_norm
# But L1 isn't the scale that correctly reconstructs the movie (or generalizes to
# regression-based extraction of overlapping ROIs): movie ~ traces @ masks has the
# least-squares solution traces = movie @ masks.T @ pinv(masks @ masks.T), which for
# non-overlapping ROIs is diagonal with each entry ||mask_n||^2 (L2 norm squared, not
# L1) -- so the correctly-scaled trace divides by L2 squared, not L1. This L1->L2
# rescale step is itself a no-op for binary masks (mask**2 == mask, so L1 == L2^2 --
# true for every current mask source: Suite2pRois, generate_rois's default). The
# L1-normalization above is not a no-op for binary masks, though: it changes F from a
# raw per-ROI pixel sum to a per-pixel mean, for every mask, binary included --
# deliberate (matching Suite2p's F/Fneu mean convention so neuropil subtraction is
# dimensionally meaningful), not specific to weighted masks. Harmless for dF/F (a
# per-ROI constant scale factor cancels in (F - F0) / F0), but does change raw
# `fluorescence` values for every binary mask. Extracting via L1 first (for
# neuropil-subtraction consistency, above) and rescaling the result by L1/L2^2
# afterwards is algebraically identical to extracting via L2^2 directly and rescaling
# the neuropil term by the same factor -- scalar multiplication distributes over the
# subtraction -- so this order also keeps the neuropil subtraction itself correctly in
# Suite2p's mean-scale convention.
l2sq_norm = _row_norm((masks_flat**2).sum(axis=1))
self._rescale_to_l2 = (l1_norm / l2sq_norm).reshape(1, -1) # (1, N), for compute()
# Precompute flattened neuropil masks
if neuropil is not None:
if neuropil.ndim == 2:
# Global neuropil (H, W) -> (1, spatial)
self._neuropil_flat = neuropil.reshape((1, -1)).astype(np.float32)
else:
# Per-ROI neuropil (N, H, W) -> (N, spatial)
self._neuropil_flat = neuropil.reshape((neuropil.shape[0], -1)).astype(np.float32)
else:
self._neuropil_flat = None
self._gnb = 0 if background_spatial is None else int(background_spatial.shape[0])
if method != "projection":
self._setup_joint_solve(masks, background_spatial, ridge)
def _setup_joint_solve(self, masks, background_spatial, ridge):
"""Precompute everything the per-chunk solve of ``movie ~= C A + f b`` reuses.
The design is ``D = [A.T, b.T]`` (``n_pixels x (n_rois + gnb)``); each chunk forms
``chunk @ D`` and solves against ``D.T D``. That Gram is an arrowhead matrix: the ``A A.T``
block (ROI-ROI overlaps) is exactly as sparse as without ``b``, while the ``A b.T`` border is
dense (``b`` is broad, so every ROI overlaps it). ``'regression'`` therefore factorizes the
sparse ``A A.T`` once and handles ``b`` through the ``gnb x gnb`` Schur complement
``S = b b.T - (A b.T).T inv(A A.T) (A b.T)`` (block elimination / Sherman-Morrison-Woodbury).
"""
import scipy.sparse as sp
from scipy.linalg import pinvh
from scipy.sparse.linalg import splu
# float64: the traces come out of a difference of large, strongly correlated terms (A and b
# are both positive and overlap), so float32 right-hand sides lose too many digits.
self._masks_csr = _masks_to_sparse_matrix(masks).astype(np.float64) # (N, n_pixels)
num_rois = self._masks_csr.shape[0]
gram_aa = (self._masks_csr @ self._masks_csr.T).tocsc() # (N, N), sparse
if self._gnb:
b = np.asarray(background_spatial, dtype=np.float64).reshape(self._gnb, -1) # (gnb, n_pixels)
if b.shape[1] != self._masks_csr.shape[1]:
raise ValueError(
f"background_spatial has {b.shape[1]} pixels per component, "
f"the ROI masks {self._masks_csr.shape[1]}"
)
gram_ab = np.asarray(self._masks_csr @ b.T, dtype=np.float64) # (N, gnb)
gram_bb = b @ b.T
else:
b = np.zeros((0, self._masks_csr.shape[1]))
gram_ab = np.zeros((num_rois, 0))
gram_bb = np.zeros((0, 0))
self._background_spatial = b
self._gram_ab = gram_ab
# B = f b A.T, the background projected onto each cell's own footprint (as CaImAn's
# detrend_df_f does), divided by ||a_i||^2 to put it in the units of C: C is on the L2 scale
# (movie ~= C A), where CaImAn gets the same by unit-L2-normalizing A instead.
own_norm = np.asarray(gram_aa.diagonal(), dtype=np.float64)
empty = own_norm <= 0
own_norm[empty] = 1.0 # an all-zero mask has A b.T == 0, so its B stays 0
self._background_to_rois = gram_ab.T / own_norm # (gnb, N)
if self.method == "regression":
# Same per-diagonal-entry ridge as _ridge_regularize, applied to each block. An all-zero
# mask contributes a zero row, so it needs a floor on the diagonal for the factorization
# to exist at all -- and that floor cannot be scaled by `ridge`, or `ridge=0` (documented
# and accepted) would reinstate the singularity.
fallback = float(own_norm[~empty].mean()) if (~empty).any() else 1.0
shift = np.where(empty, fallback, ridge * own_norm)
self._gram_aa_regularized = (gram_aa + sp.diags(shift)).tocsc()
self._gram_aa_lu = splu(self._gram_aa_regularized)
self._aa_inv_ab = self._gram_aa_lu.solve(gram_ab) if self._gnb else gram_ab # (N, gnb)
schur = _ridge_regularize(gram_bb, ridge) - gram_ab.T @ self._aa_inv_ab # (gnb, gnb)
self._schur_inv = pinvh(schur) if self._gnb else schur
return
# nnls: only C is constrained, so f is eliminated first. Given C, the best f is
# f = (Y b.T - C A b.T) inv(b b.T),
# which leaves an NNLS problem in C alone with Gram S (the Schur complement of b b.T) and
# right-hand side r = Y A.T - Y b.T inv(b b.T) (A b.T).T.
gram_aa = gram_aa.toarray()
gram_bb_inv = _ridge_inverse(gram_bb, ridge)
self._gram_bb_inv = gram_bb_inv
self._rhs_correction = gram_bb_inv @ gram_ab.T # (gnb, N): r = rhs_a - rhs_b @ this
# Ridge on the *reduced* system: after eliminating f, ROI i's scale is ||a_i orthogonal to b||^2,
# not ||a_i||^2, so regularizing gram_aa first would over-penalize an ROI close to span(b).
# 'regression' and 'nnls' thus solve slightly different regularized problems, which only matters
# where the trace/background split is unidentifiable anyway (the gauge freedom).
schur = _ridge_regularize(gram_aa - gram_ab @ gram_bb_inv @ gram_ab.T, ridge)
# scipy's nnls takes min ||M x - y||, not a Gram: write S = M.T M with M = sqrt(w) V.T, and
# then M.T y = r gives y = (V.T r) / sqrt(w).
eigvals, eigvecs = np.linalg.eigh(schur)
# Relative to the spectrum, so masks with small weights are not attenuated; only an underflow guard
# stays absolute. `_ridge_regularize` leaves every eigenvalue positive, so max(eigvals) > 0 here.
floor = max(float(eigvals.max(initial=0.0)) * np.finfo(np.float64).eps, np.finfo(np.float64).tiny)
sqrt_w = np.sqrt(np.maximum(eigvals, floor))
self._nnls_matrix = (eigvecs * sqrt_w).T
self._nnls_rhs_map = eigvecs / sqrt_w # r @ this == y
def __getstate__(self):
# scipy.sparse.linalg.SuperLU (method='regression') isn't picklable, which breaks
# n_jobs>1 (spikeinterface's run_node_pipeline sends nodes to worker processes via
# ProcessPoolExecutor). Drop it here and rebuild it from the already-picklable
# `_gram_aa_regularized` in __setstate__, once per worker process.
state = self.__dict__.copy()
state.pop("_gram_aa_lu", None)
return state
def __setstate__(self, state):
self.__dict__.update(state)
if "_gram_aa_regularized" in self.__dict__:
from scipy.sparse.linalg import splu
self._gram_aa_lu = splu(self._gram_aa_regularized)
[docs]
def get_dtype(self):
return np.float32
[docs]
def compute(self, chunk, *args):
# chunk shape: (num_frames, H, W, P)
num_frames = chunk.shape[0]
chunk_flat = chunk.reshape(num_frames, -1).astype(np.float32) # (T, spatial)
if self.method == "projection":
# Weighted fluorescence per ROI: (T, N)
fluorescence = chunk_flat @ self._masks_flat.T
neuropil_trace = None
# Neuropil subtraction, in the same L1/mean scale as self._masks_flat
if self._neuropil_flat is not None:
# (T, 1) for global or (T, N) for per-ROI
neuropil_trace = chunk_flat @ self._neuropil_flat.T
fluorescence -= self.neuropil_weight * neuropil_trace
# Rescale from L1 to the L2-normalized scale (see __init__) -- a no-op (factor 1) for
# binary masks (Suite2pRois and generate_rois's default).
fluorescence *= self._rescale_to_l2
return fluorescence, self._persisted_neuropil(neuropil_trace, num_frames)
rhs_a = np.asarray(self._masks_csr @ chunk_flat.T.astype(np.float64)).T # (T, N)
if self._gnb:
rhs_b = _project_float64(chunk_flat, self._background_spatial.T) # (T, gnb)
else:
rhs_b = np.zeros((num_frames, 0))
if self.method == "regression":
# Block elimination of [C, f] [[A A.T, A b.T], [(A b.T).T, b b.T]] = [rhs_a, rhs_b]: f from
# the small Schur system, then C from the reused sparse A A.T factorization.
aa_inv_rhs = self._gram_aa_lu.solve(rhs_a.T).T # rhs_a inv(A A.T)
temporal = (rhs_b - aa_inv_rhs @ self._gram_ab) @ self._schur_inv
traces = aa_inv_rhs - temporal @ self._aa_inv_ab.T
else:
from scipy.optimize import nnls
targets = (rhs_a - rhs_b @ self._rhs_correction) @ self._nnls_rhs_map
traces = np.empty((num_frames, rhs_a.shape[1]), dtype=np.float64)
for t in range(num_frames):
traces[t], _ = nnls(self._nnls_matrix, targets[t])
temporal = (rhs_b - traces @ self._gram_ab) @ self._gram_bb_inv
if self._gnb:
background = temporal @ self._background_to_rois
if self.neuropil_weight != 1.0:
traces = traces + (1.0 - self.neuropil_weight) * background
return traces.astype(np.float32), background.astype(np.float32)
neuropil_trace = None
if self._neuropil_flat is not None:
# Surround stays a two-step correction on the traces. They are already on the L2 scale
# and the ring trace on the L1 (mean) scale, hence the same rescale as the projection path.
neuropil_trace = chunk_flat @ self._neuropil_flat.T
traces = traces - self.neuropil_weight * neuropil_trace * self._rescale_to_l2
return traces.astype(np.float32), self._persisted_neuropil(neuropil_trace, num_frames)
def _persisted_neuropil(self, neuropil_trace, num_frames):
"""The surround ring mean ``Fneu`` as ``(T, N)``, persisted rather than discarded.
Rescaled by the same L1 -> L2 factor as the traces, so that
``fluorescence + neuropil_weight * background`` is the uncorrected trace. That makes it the raw
``Fneu`` for binary masks (where the factor is exactly 1) and ``Fneu * L1 / L2**2`` for weighted
ones. ``(T, 0)`` when there is no surround neuropil.
"""
num_rois = self._rescale_to_l2.shape[1]
if neuropil_trace is None:
return np.zeros((num_frames, 0), dtype=np.float32)
# A global (H, W) neuropil gives (T, 1): the same ring mean for every ROI.
neuropil_trace = np.broadcast_to(neuropil_trace, (num_frames, num_rois))
return (neuropil_trace * self._rescale_to_l2).astype(np.float32)
[docs]
class NeuropilExtension(AnalyzerExtension):
"""Extension to model the neuropil / background contaminating each ROI's fluorescence.
Only ``method='surround'`` is currently supported:
- ``'surround'``: Suite2p-style neuropil mask -- the region surrounding each ROI (excluding
pixels belonging to any ROI), rectangular by default or circular when ``circular=True``,
via :func:`suite2p.extraction.masks.create_cell_pix`/:func:`~suite2p.extraction.masks.create_neuropil_masks`.
Ring pixels are weighted ``1 / n_ring_pixels`` so that the weighted-sum matmul in
:class:`FluorescenceNode` reproduces suite2p's own unweighted-mean ``Fneu`` convention.
Works with *any* :class:`~photon_mosaic.core.baserois.BaseRois` -- per-ROI pixel
coordinates are derived from ``rois.get_roi_image_masks()`` (not suite2p-specific stat
data), since ``RoiAnalyzer`` always stores its own in-memory/on-disk snapshot of the ROIs
rather than the original object passed to ``create_roi_analyzer`` (e.g. ``format="memory"``
always copies into a plain ``NumpyRois``, so a `Suite2pRois`-specific accessor would not be
reachable via ``roi_analyzer.rois`` in the common case). Multi-plane ROIs are supported as
long as each ROI's own mask is confined to a single plane (e.g. well-separated mesoscope
planes) -- each plane's ROIs are then treated as an independent 2D problem. A genuinely
volumetric ROI spanning multiple planes is not yet supported (would need a true 3D
"shell" neuropil mask, e.g. as in `Suite3D <https://www.biorxiv.org/content/10.1101/2025.03.26.645628v2.full>`_
(`code <https://github.com/alihaydaroglu/suite3d>`_), rather than this per-plane approach).
Once computed, this extension is picked up automatically by :class:`FluorescenceExtension`
(see its ``use_neuropil`` param) -- just call ``roi_analyzer.compute("neuropil")`` before
``roi_analyzer.compute("fluorescence")``. ``'surround'`` feeds an
``F - neuropil_weight * Fneu`` subtraction, with the ring mask applied to the movie inside
:class:`FluorescenceNode`; it needs no change to the design matrix, since the ring is spatially
disjoint from its ROI.
"""
extension_name = "neuropil"
depend_on: list[str] = []
need_imaging = False
use_nodepipeline = False
need_job_kwargs = True
def _set_params(
self,
method: str = "surround",
inner_neuropil_radius: int = 2,
min_neuropil_pixels: int = 350,
circular: bool = False,
lam_percentile: float = 50.0,
**params: Any,
) -> dict[str, Any]:
"""Set parameters for neuropil mask computation.
Parameters
----------
method : str, optional
Neuropil mask construction method. Only ``'surround'`` (Suite2p-style neighborhood mask,
rectangular or circular) is currently supported. Default is ``'surround'``.
inner_neuropil_radius : int, optional
Pixels around each ROI to exclude before the ring starts. Only used with
``method='surround'``. Default is ``2``.
min_neuropil_pixels : int, optional
Minimum ring pixel count; the ring grows outward until this many pixels are found.
Only used with ``method='surround'``. Default is ``350``.
circular : bool, optional
Restrict the ring to a circular region instead of a rectangular bounding-box grow.
Only used with ``method='surround'``. Default is ``False``.
lam_percentile : float, optional
Percentile threshold used to decide which weighted pixels count as "ROI" pixels,
excluded from every ROI's ring. Only used with ``method='surround'``. Default is
``50.0``.
"""
if params:
raise TypeError(f"_set_params() got unexpected keyword argument(s): {sorted(params)}")
if method not in _NEUROPIL_METHODS:
raise ValueError(f"Unknown method: '{method}'. Supported: {_NEUROPIL_METHODS}.")
return dict(
method=method,
inner_neuropil_radius=inner_neuropil_radius,
min_neuropil_pixels=min_neuropil_pixels,
circular=circular,
lam_percentile=lam_percentile,
)
def _run(self, verbose: bool = False, **job_kwargs: Any) -> None:
method = self.params["method"]
rois = self.roi_analyzer.rois
if method == "surround":
masks = rois.get_roi_image_masks()
self.data["neuropil_masks"] = _build_surround_neuropil_masks(
masks,
inner_neuropil_radius=self.params["inner_neuropil_radius"],
min_neuropil_pixels=self.params["min_neuropil_pixels"],
circular=self.params["circular"],
lam_percentile=self.params["lam_percentile"],
)
def _get_data(self):
"""Return a computed neuropil result.
Returns
-------
sparse.GCXS or np.ndarray or dict
For ``method='surround'``, a ``sparse.GCXS`` of shape ``(n_rois, Ly, Lx)`` -- or
``(n_rois, Ly, Lx, n_planes)`` for multi-plane ROIs. Each ROI's ring pixels sum to 1.0
(an unweighted mean over the ring, matching suite2p's own ``Fneu`` convention), except
ROIs whose ring ended up empty (e.g. fully surrounded by other ROIs), which get an
all-zero row.
"""
return self.data["neuropil_masks"]
def _select_extension_data(self, roi_ids):
roi_indices = self.roi_analyzer.rois.ids_to_indices(roi_ids)
return {"neuropil_masks": self.data["neuropil_masks"][roi_indices]}
[docs]
class BackgroundExtension(AnalyzerExtension):
"""Extension to estimate a low-rank background over the whole field of view.
Only ``method='cnmf'`` is currently supported: a CNMF-style background ``b`` of ``gnb`` spatial
components, fitted from the movie and the ROI masks. ``get_data()`` returns ``b``, of shape
``(gnb, Ly, Lx, n_planes)``. It is not per ROI.
Once computed, this extension is picked up automatically by :class:`FluorescenceExtension`
(see its ``use_neuropil`` and ``neuropil_source`` params) -- just call
``roi_analyzer.compute("background")`` before ``roi_analyzer.compute("fluorescence")``.
The fluorescence extension gets ``b`` as extra columns of its design matrix, which needs
``FluorescenceExtension(method='regression')`` or ``method='nnls'``. The resulting per-ROI
background ``B`` is persisted as ``get_data(key='background')`` on the fluorescence extension.
"""
extension_name = "background"
depend_on: list[str] = []
need_imaging = True
use_nodepipeline = False
need_job_kwargs = True
def _set_params(
self,
method: str = "cnmf",
gnb: int = 1,
max_iter: int = 20,
tol: float = 1e-4,
highpass_sigma: float | None = 20.0,
lowpass_sigma: float | None = 1.0,
init_method: str = "ramp",
nonneg_background: bool = True,
nonneg_traces: bool = False,
ridge: float = 1e-6,
subsample_frames: int | None = 1000,
**params: Any,
) -> dict[str, Any]:
"""Set parameters for background estimation.
Parameters
----------
method : str, optional
Background estimation method. Only ``'cnmf'`` (Constrained Non-negative Matrix Factorization)
is currently supported. Default is ``'cnmf'``.
gnb : int, optional
Number of low-rank background components to fit. Only used with ``method='cnmf'``.
Default is ``1``, which also makes the fit deterministic and the non-negativity
projection exact (the Gram is then 1x1); ``2``-``3`` suits spatially structured
background.
max_iter : int, optional
Maximum alternating iterations for the background factors. Only used with
``method='cnmf'``. Default is ``20``.
tol : float, optional
Relative change in the fit objective below which the alternation stops. Only used with
``method='cnmf'``. Default is ``1e-4``.
highpass_sigma : float or None, optional
Standard deviation **in pixels** of the Gaussian subtracted from each frame to remove
broad background before the initial trace estimate. ``None`` or ``0`` disables it. Only
used with ``method='cnmf'``. Default is ``20.0`` (roughly 2-3 soma radii).
lowpass_sigma : float or None, optional
Standard deviation in pixels of a mild Gaussian smoothing applied before the high-pass,
to suppress shot noise. ``None`` or ``0`` disables it. Only used with
``method='cnmf'``. Default is ``1.0``.
init_method : str, optional
How the background factors are initialised: ``'ramp'`` (spatial bumps over the mean
residual image; dependency-free, the default) or ``'svd'`` (truncated SVD of the
residual). Only used with ``method='cnmf'``.
nonneg_background : bool, optional
Constrain both background factors to be non-negative, as CaImAn does. Only used with
``method='cnmf'``. Default is ``True``.
nonneg_traces : bool, optional
Also constrain the demixed traces to be non-negative. Only used with
``method='cnmf'``. Default is ``False``, since a band-passed seed legitimately goes
negative. The traces are clipped at zero, which is the exact non-negative solution only
for non-overlapping ROIs.
ridge : float, optional
Tikhonov regularisation applied to the least-squares solves, relative to *each diagonal
entry* of the Gram matrix rather than to its mean diagonal (see
:func:`_ridge_inverse`). Must be finite and non-negative. Only used with
``method='cnmf'``. Default is ``1e-6``.
subsample_frames : int or None, optional
Number of evenly-spaced frames used for the alternating background fit (the final
traces and background timecourses are always solved over *all* frames). ``None`` uses
every frame. Only used with ``method='cnmf'``. Default is ``1000``.
"""
if params:
raise TypeError(f"_set_params() got unexpected keyword argument(s): {sorted(params)}")
if method != "cnmf":
raise ValueError(f"Unknown method: '{method}'. Supported: 'cnmf'.")
if gnb < 1:
raise ValueError(f"gnb must be >= 1, got {gnb}")
if init_method not in _CNMF_INIT_METHODS:
raise ValueError(f"Unknown init_method: '{init_method}'. Supported: {_CNMF_INIT_METHODS}.")
if subsample_frames is not None and subsample_frames < 2:
raise ValueError(f"subsample_frames must be None or >= 2, got {subsample_frames}")
if max_iter < 1:
raise ValueError(f"max_iter must be >= 1, got {max_iter}")
# Same finite/non-negative contract as FluorescenceExtension's ridge; see
# _check_finite_non_negative for why a negative ridge is the dangerous one.
_check_finite_non_negative("tol", tol)
_check_finite_non_negative("ridge", ridge)
for _name, _sigma in (("highpass_sigma", highpass_sigma), ("lowpass_sigma", lowpass_sigma)):
if _sigma is not None:
_check_finite_non_negative(_name, _sigma)
# The background initialiser can build at most subsample_frames - 1 independent
# components; beyond that it duplicates the last one, and identical columns receive
# identical updates forever, so the extra components can never separate.
if subsample_frames is not None and gnb >= subsample_frames:
raise ValueError(f"gnb must be < subsample_frames ({subsample_frames}), got {gnb}")
return dict(
method=method,
gnb=gnb,
max_iter=max_iter,
tol=tol,
highpass_sigma=highpass_sigma,
lowpass_sigma=lowpass_sigma,
init_method=init_method,
nonneg_background=nonneg_background,
nonneg_traces=nonneg_traces,
ridge=ridge,
subsample_frames=subsample_frames,
)
def _run(self, verbose: bool = False, **job_kwargs: Any) -> None:
rois = self.roi_analyzer.rois
from spikeinterface.core.job_tools import ensure_chunk_size
imaging = self.roi_analyzer.imaging
job_kwargs = fix_job_kwargs(job_kwargs)
chunk_size = ensure_chunk_size(imaging, **job_kwargs)
self.data["background_spatial"] = _fit_cnmf_background(
imaging,
rois.get_roi_image_masks(),
gnb=self.params["gnb"],
max_iter=self.params["max_iter"],
tol=self.params["tol"],
highpass_sigma=self.params["highpass_sigma"],
lowpass_sigma=self.params["lowpass_sigma"],
init_method=self.params["init_method"],
nonneg_background=self.params["nonneg_background"],
nonneg_traces=self.params["nonneg_traces"],
ridge=self.params["ridge"],
subsample_frames=self.params["subsample_frames"],
chunk_size=chunk_size,
n_jobs=job_kwargs["n_jobs"],
verbose=verbose,
)
def _get_data(self):
"""Return the spatial background.
Returns
-------
np.ndarray
``b``, of shape ``(gnb, Ly, Lx, n_planes)``.
"""
return self.data["background_spatial"]
def _select_extension_data(self, roi_ids):
# Every key must be returned: copy() assigns the result straight over `data`, so an
# omitted key would be silently dropped. The spatial background is a property of the
# whole field of view, so it passes through unsliced.
return {"background_spatial": self.data["background_spatial"]}
[docs]
class DfOverFExtension(AnalyzerExtension):
"""Extension to compute dF/F (relative fluorescence change) from fluorescence traces.
dF/F is defined as ``(F - F0) / F0``, where ``F0`` is an estimate of the
baseline fluorescence. Two baseline estimation methods are supported:
- ``'maximin'``: Gaussian smoothing followed by a rolling minimum and
maximum filter, as used in Suite2p. Robust to slow drift and does not
require setting a percentile level.
- ``'percentile'`` (alias ``'running_percentile'``): Rolling percentile
filter, as used in CaImAn. The percentile level can be fixed
(``prctile_baseline=<float>``) or estimated automatically per ROI via a
DCT-based KDE of the fluorescence distribution (``prctile_baseline=None``).
When the fluorescence was extracted against a CNMF background (:class:`BackgroundExtension`),
the fit can't fully separate a cell's baseline from the background: moving part of the baseline
from ``C`` into ``b, f`` (or back) fits the movie equally well, so ``C``'s own baseline is not
reliable on its own. With ``use_background=True`` (the default) the background per ROI ``B``
(``FluorescenceExtension.get_data(key='background')``, scaled by that extension's
``neuropil_weight`` like the share of it removed from the traces) is then used as a second input,
as in CaImAn's ``detrend_df_f``::
dF/F = (C - C_baseline) / (B_baseline + C_baseline)
This reduces the gauge ambiguity rather than removing it. A constant offset moved between ``C``
and the background shifts ``C_baseline`` and ``B_baseline`` by exactly opposite amounts, since
percentile and maximin both commute with a constant shift, so their sum is unchanged. A general
CNMF reparameterisation moves a time-varying ``f alpha`` term instead, and those baselines are
non-linear, so the compensation is only approximate there. Both baselines use the same method,
window and (per ROI) percentile, the percentile being chosen from ``C``. Surround and no-neuropil
fluorescence are unaffected.
The fitted baseline itself is kept alongside the dF/F traces, accessible via
``self.data["f0"]`` (shape ``(n_frames, n_rois)``, matching ``self.data["df_over_f"]``). With a
CNMF background it is the denominator ``B_baseline + C_baseline``.
"""
extension_name = "df_over_f"
depend_on: list[str] = ["fluorescence"]
need_imaging = False
need_job_kwargs = True
def _set_params(
self,
method: str = "percentile",
win_baseline: float = 60.0,
sig_baseline: float = 10.0,
prctile_baseline: float | None = None,
use_background: bool = True,
**params: Any,
) -> dict[str, Any]:
"""Set parameters for dF/F computation.
Parameters
----------
method : str, optional
Baseline estimation method. One of ``'maximin'`` (Suite2p-style) or
``'percentile'`` / ``'running_percentile'`` (CaImAn-style).
Default is ``'percentile'``.
win_baseline : float, optional
Duration of the sliding window in seconds used to estimate the
baseline. Default is ``60.0``.
sig_baseline : float, optional
Standard deviation of the Gaussian filter (in frames) applied
before the min/max filters. Only used with ``method='maximin'``.
Default is ``10.0``.
prctile_baseline : float or None, optional
Percentile level (0–100) used for the rolling percentile baseline.
Only used with ``method='percentile'``. If ``None``, the percentile
is estimated automatically per ROI using a DCT-based KDE of the
fluorescence distribution (CaImAn-style), falling back to the 50th
percentile if estimation fails. If a float, that value is used
directly for all ROIs. Default is ``None``.
use_background : bool, optional
If the fluorescence was extracted against a CNMF background, add its
background baseline to the denominator (see the class docstring). Ignored otherwise.
Default is ``True``.
"""
return dict(
method=method,
win_baseline=win_baseline,
sig_baseline=sig_baseline,
prctile_baseline=prctile_baseline,
use_background=use_background,
)
def _cnmf_background(self) -> np.ndarray | None:
"""The fluorescence extension's CNMF background per ROI ``B``, or ``None`` if there is none.
Only a CNMF ``B`` qualifies: for surround, ``background`` holds the ring mean ``Fneu``, which
was already subtracted from the traces and is not a share of their baseline.
"""
if not self.params.get("use_background", True):
return None
fluorescence = self.roi_analyzer.get_extension("fluorescence")
background = fluorescence.data.get("background")
if background is None or background.shape[1] == 0:
return None
if fluorescence._neuropil_source() != "background":
return None
# The traces keep (1 - w) B, so only w B is left as background (see FluorescenceExtension).
return fluorescence.params.get("neuropil_weight", 0.7) * background
def _run(self, verbose: bool = False, **job_kwargs) -> None:
F = self.roi_analyzer.get_extension("fluorescence").get_data()
B = self._cnmf_background()
method = self.params["method"]
if method == "maximin": # maximin baseline estimation as in Suite2p
from scipy.ndimage import gaussian_filter1d, maximum_filter1d, minimum_filter1d
fs = self.roi_analyzer.sampling_frequency
win = int(self.params["win_baseline"] * fs)
win += 1 if win % 2 == 0 else 0 # ensure odd window
def _maximin(x):
x = gaussian_filter1d(x, sigma=self.params["sig_baseline"], axis=0)
x = minimum_filter1d(x, size=win, axis=0)
return maximum_filter1d(x, size=win, axis=0)
F0 = _maximin(F)
B0 = None if B is None else _maximin(B)
elif method in ("percentile", "running_percentile"): # running percentile baseline as in CaImAn
from concurrent.futures import ProcessPoolExecutor
win = int(self.params["win_baseline"] * self.roi_analyzer.sampling_frequency)
n_jobs = fix_job_kwargs(job_kwargs).get("n_jobs", 1)
prctile_baseline = self.params["prctile_baseline"]
if B is None:
func: Any = _percentile_filter_roi
args: list[tuple] = [(F[:, i].copy(), win, prctile_baseline) for i in range(F.shape[1])]
else:
func = _percentile_filter_roi_and_background
args = [(F[:, i].copy(), B[:, i].copy(), win, prctile_baseline) for i in range(F.shape[1])]
if n_jobs == 1:
cols = [func(a) for a in args]
else:
with ProcessPoolExecutor(max_workers=n_jobs) as ex:
cols = list(ex.map(func, args))
if B is None:
F0, B0 = np.stack(cols, axis=1), None
else:
F0 = np.stack([c for c, _ in cols], axis=1)
B0 = np.stack([b for _, b in cols], axis=1)
else:
raise ValueError(f"Unknown method: '{method}'. Supported: 'maximin', 'percentile'.")
# CaImAn's detrend_df_f: the numerator uses C's own baseline, the denominator adds B's.
denominator = F0 if B0 is None else F0 + B0
self.data["df_over_f"] = ((F - F0) / (denominator + np.finfo(np.float32).eps)).astype(np.float32)
self.data["f0"] = denominator.astype(np.float32)
def _get_data(self, outputs="numpy"):
"""Return the computed dF/F traces.
Parameters
----------
outputs : str, optional
Output format. ``'numpy'`` returns an ``ndarray`` of shape ``(n_frames, n_rois)``.
``'recording'`` wraps the traces in a :class:`~spikeinterface.core.NumpyRecording`.
Default is ``'numpy'``.
Returns
-------
np.ndarray or NumpyRecording
dF/F traces in the requested format.
"""
df_over_f_traces = self.data["df_over_f"]
if outputs == "numpy":
return df_over_f_traces
elif outputs == "recording":
from spikeinterface.core import NumpyRecording
return NumpyRecording(
df_over_f_traces,
sampling_frequency=self.roi_analyzer.sampling_frequency,
channel_ids=self.roi_analyzer.rois.roi_ids,
)
else:
raise ValueError(f"Unsupported output type: {outputs}. Supported types are 'numpy' and 'recording'.")
def _select_extension_data(self, roi_ids):
roi_indices = self.roi_analyzer.rois.ids_to_indices(roi_ids)
return {
"df_over_f": self.data["df_over_f"][:, roi_indices],
"f0": self.data["f0"][:, roi_indices],
}
[docs]
class DeconvolutionExtension(AnalyzerExtension):
"""Extension to deconvolve neural activity from dF/F traces using OASIS.
Solves the noise-constrained sparse non-negative deconvolution problem
(Friedrich, Zhou & Paninski, PLOS Comput Biol 2017) to infer, for each
ROI, the most likely deconvolved activity trace and denoised calcium
trace underlying its dF/F signal.
"""
extension_name = "deconvolution"
depend_on: list[str] = ["df_over_f"]
need_imaging = False
need_job_kwargs = True
def _set_params(
self,
decay_time: float | None = None,
rise_time: float | None = 0,
baseline: float | None = None,
baseline_nonneg: bool = False,
penalty: int | None = 1,
**params: Any,
) -> dict[str, Any]:
"""Set parameters for OASIS deconvolution.
Parameters
----------
decay_time : float or None, optional
Decay time constant in seconds. If provided, sets the decay kinetics
directly instead of estimating it per ROI. Default is None.
rise_time : float or None, optional
Rise time constant in seconds, modeling the calcium kinetics as a
rise-and-decay (double exponential) process instead of
decay-only. Default is 0 (no rise, decay-only). Set both
`decay_time` and `rise_time` to None to auto-estimate a
rise-and-decay model instead of a decay-only one.
baseline : float or None, optional
Fixed baseline value. Optimized per ROI if not given. Unused
when `penalty` is None (treated as a fixed offset, default 0).
Default is None.
baseline_nonneg : bool, optional
Enforce a strictly non-negative estimated baseline. Default is
False, since the input is dF/F (already baseline-subtracted and
free to fluctuate below zero), unlike raw fluorescence. Unused
when `penalty` is None.
penalty : int or None, optional
Sparsity penalty: 1 for L1 (convex), 0 for L0. If None, skips
the noise-constrained optimization entirely and deconvolves
without imposing sparsity by default (`noise_std` and
`baseline_nonneg` are unused in this mode). Default is 1.
Advanced, undocumented keyword arguments are also accepted and
passed through to :func:`oasis.functions.deconvolve` for power
users: ``noise_std`` (overrides the per-ROI noise estimate that
otherwise controls the sparsity weight), ``refine_kinetics``
(number of large, isolated events used to refine the time
constant(s) per ROI — can make estimates worse on noisy or
low-event-count traces), and, only when `penalty` is None,
``lam`` (fixed sparsity weight, default 0) and ``s_min`` (minimal
non-zero activity per bin, default 0).
"""
lam = params.pop("lam", 0.0)
s_min = params.pop("s_min", 0.0)
noise_std = params.pop("noise_std", None)
refine_kinetics = params.pop("refine_kinetics", 0)
if params:
raise TypeError(f"_set_params() got unexpected keyword argument(s): {sorted(params)}")
return dict(
decay_time=decay_time,
rise_time=rise_time,
baseline=baseline,
baseline_nonneg=baseline_nonneg,
penalty=penalty,
lam=lam,
s_min=s_min,
noise_std=noise_std,
refine_kinetics=refine_kinetics,
)
def _run(self, verbose: bool = False, **job_kwargs) -> None:
from concurrent.futures import ProcessPoolExecutor
dff = self.roi_analyzer.get_extension("df_over_f").get_data()
fs = self.roi_analyzer.sampling_frequency
n_jobs = fix_job_kwargs(job_kwargs).get("n_jobs", 1)
# deconvolve() never mutates its input, and pickling a column slice (for the parallel
# path below) serializes just that slice's own data, not the whole dff matrix.
args = [(dff[:, i], fs, self.params) for i in range(dff.shape[1])]
if n_jobs == 1:
results = [_deconvolve_roi(a) for a in args]
else:
with ProcessPoolExecutor(max_workers=n_jobs) as ex:
results = list(ex.map(_deconvolve_roi, args))
self.data["denoised"] = np.stack([r[0] for r in results], axis=1).astype(np.float32)
self.data["deconvolved"] = np.stack([r[1] for r in results], axis=1).astype(np.float32)
def _get_data(self, outputs="numpy"):
"""Return the deconvolved activity trace.
Parameters
----------
outputs : str, optional
Output format. ``'numpy'`` returns an ``ndarray`` of shape ``(n_frames, n_rois)``.
``'recording'`` wraps the traces in a :class:`~spikeinterface.core.NumpyRecording`.
Default is ``'numpy'``.
Returns
-------
np.ndarray or NumpyRecording
Deconvolved activity trace in the requested format. The
denoised calcium traces are available via
``self.data["denoised"]``.
"""
deconvolved = self.data["deconvolved"]
if outputs == "numpy":
return deconvolved
elif outputs == "recording":
from spikeinterface.core import NumpyRecording
return NumpyRecording(
deconvolved,
sampling_frequency=self.roi_analyzer.sampling_frequency,
channel_ids=self.roi_analyzer.rois.roi_ids,
)
else:
raise ValueError(f"Unsupported output type: {outputs}. Supported types are 'numpy' and 'recording'.")
def _select_extension_data(self, roi_ids):
roi_indices = self.roi_analyzer.rois.ids_to_indices(roi_ids)
return {
"denoised": self.data["denoised"][:, roi_indices],
"deconvolved": self.data["deconvolved"][:, roi_indices],
}
def _deconvolve_roi(args: tuple) -> tuple[np.ndarray, np.ndarray]:
"""Run OASIS deconvolution on a single ROI's dF/F trace.
Unpacks ``(y, framerate, params)`` — required as a module-level function
so it can be pickled by :class:`~concurrent.futures.ProcessPoolExecutor`.
Parameters
----------
args : tuple
``(y, framerate, params)`` where:
- ``y`` : dF/F trace for one ROI, shape ``(n_frames,)``.
- ``framerate`` : imaging sampling frequency in Hz.
- ``params`` : dict with keys ``decay_time``, ``rise_time``,
``noise_std``, ``baseline``, ``baseline_nonneg``, ``penalty``,
``refine_kinetics``, ``lam``, ``s_min``
(see :meth:`DeconvolutionExtension._set_params`).
Returns
-------
c : np.ndarray
Denoised calcium trace, shape ``(n_frames,)``.
s : np.ndarray
Deconvolved activity trace, shape ``(n_frames,)``.
"""
from oasis.functions import deconvolve
y, framerate, params = args
kwargs = dict(
framerate=framerate,
sn=params["noise_std"],
b=params["baseline"],
b_nonneg=params["baseline_nonneg"],
optimize_g=params["refine_kinetics"],
penalty=params["penalty"],
)
if params["penalty"] is None:
# lam/s_min are only accepted by oasisAR1/oasisAR2 (via deconvolve's penalty=None
# path), not by constrained_oasisAR1/constrained_onnlsAR2 used for the default penalty.
kwargs["lam"] = params["lam"]
kwargs["s_min"] = params["s_min"]
c, s, _b, _g, _lam = deconvolve(y, tau_d=params["decay_time"], tau_r=params["rise_time"], **kwargs)
return c, s
def _percentile_filter_roi(args: tuple) -> np.ndarray:
"""Estimate baseline percentile (if needed) and apply a rolling percentile filter to one ROI.
Unpacks ``(col, size, prctile_baseline)`` — required as a module-level
function so it can be pickled by
:class:`~concurrent.futures.ProcessPoolExecutor`.
Parameters
----------
args : tuple
``(col, size, prctile_baseline)`` where:
- ``col`` : full fluorescence trace (float32 or float64).
- ``size`` : rolling window length in frames.
- ``prctile_baseline`` : fixed percentile (float) or ``None`` to trigger
automatic KDE estimation from the first ``size`` frames of ``col``.
"""
col, size, prctile_baseline = args
return _rolling_percentile(col, size, _resolve_percentile(col, size, prctile_baseline))
def _percentile_filter_roi_and_background(args: tuple) -> tuple[np.ndarray, np.ndarray]:
"""Rolling percentile baselines of one ROI's trace and of its CNMF background, at one percentile.
Unpacks ``(col, background_col, size, prctile_baseline)``. As in CaImAn's ``detrend_df_f``, the
percentile is chosen from the trace alone (by KDE when ``prctile_baseline`` is ``None``) and
then applied to both, so the two baselines are directly comparable.
"""
col, background_col, size, prctile_baseline = args
prct = _resolve_percentile(col, size, prctile_baseline)
return _rolling_percentile(col, size, prct), _rolling_percentile(background_col, size, prct)
def _resolve_percentile(col: np.ndarray, size: int, prctile_baseline: float | None) -> float:
"""The fixed ``prctile_baseline``, or (if ``None``) the KDE estimate from the first ``size`` frames."""
if prctile_baseline is not None:
return float(prctile_baseline)
window = col if size >= len(col) else col[:size]
try:
return _kde_mode_percentile(window.astype(np.float64))
except Exception:
return 50.0
def _rolling_percentile(col: np.ndarray, size: int, prct: float) -> np.ndarray:
"""Rolling ``prct`` percentile of ``col`` over a ``size``-frame window."""
if size >= len(col):
# Window covers the whole trace: skip scipy.ndimage's boundary-reflection
# padding, whose behavior here isn't reliably reproducible across environments.
baseline = np.percentile(col, prct)
return np.full_like(col, baseline)
from scipy.ndimage import percentile_filter
return percentile_filter(col, prct, size=size)
def _kde_mode_percentile(data: np.ndarray, N: int = 2**12) -> float:
"""Return the percentile rank of the mode of `data` using a DCT-based KDE.
Implements the bandwidth-selection method of Botev et al. (2010),
mirroring CaImAn's ``caiman.utils.stats.kde`` / ``df_percentile``.
Parameters
----------
data : np.ndarray
1-D array of fluorescence values (float64 recommended).
N : int, optional
Number of histogram bins and DCT coefficients. Must be a power of 2
for efficiency. Default is ``4096`` (``2**12``).
Returns
-------
float
Percentile rank (0–100) of the KDE mode within ``data``.
Raises
------
ValueError
If the estimated percentile is NaN, negative, or ≥ 100.
"""
from scipy import fftpack, optimize
M = len(data)
minimum, maximum = data.min(), data.max()
R = maximum - minimum
if R == 0:
return 50.0
MIN = minimum - R / 10
MAX = maximum + R / 10
R = MAX - MIN
# Histogram → DCT
hist, bins = np.histogram(data, bins=N, range=(MIN, MAX))
hist = hist / M
dct_data = fftpack.dct(hist, norm=None)
i_sq = np.arange(1, N, dtype=np.float64) ** 2
sq = (dct_data[1:] / 2) ** 2
def fixed_point(t):
ell = 7
f = 2 * np.pi ** (2 * ell) * np.sum(i_sq**ell * sq * np.exp(-i_sq * np.pi**2 * t))
for s in range(ell, 1, -1):
K0 = np.prod(np.arange(1, 2 * s, 2, dtype=np.float64)) / np.sqrt(2 * np.pi)
const = (1 + (0.5) ** (s + 0.5)) / 3
time = (2 * const * K0 / M / f) ** (2 / (3 + 2 * s))
f = 2 * np.pi ** (2 * s) * np.sum(i_sq**s * sq * np.exp(-i_sq * np.pi**2 * time))
return t - (2 * M * np.sqrt(np.pi) * f) ** (-2 / 5)
t_star = optimize.brentq(fixed_point, 0, 0.1)
# Smooth DCT coefficients and invert
smooth = dct_data * np.exp(-(np.arange(N, dtype=np.float64) ** 2) * np.pi**2 * t_star / 2)
density = fftpack.idct(smooth, norm=None) * N / R
mesh = (bins[:-1] + bins[1:]) / 2
density = density / np.trapezoid(density, mesh)
cdf = np.cumsum(density) * (mesh[1] - mesh[0])
return float(cdf[np.argmax(density)] * 100)
def _build_surround_neuropil_masks(
masks,
inner_neuropil_radius: int = 2,
min_neuropil_pixels: int = 350,
circular: bool = False,
lam_percentile: float = 50.0,
):
"""Build Suite2p-style ("surround") neuropil masks from ROI image masks.
For each ROI, builds the ring of pixels surrounding it (excluding pixels belonging to any
ROI) via :mod:`suite2p.extraction.masks`, then converts the flattened-index ring into a
mask where each ring pixel has weight ``1 / n_ring_pixels``. This weighting is required (not
optional): :meth:`FluorescenceNode.compute` consumes this mask via
``chunk_flat @ neuropil_flat.T``, a *weighted sum*. A binary ring mask would instead compute
a sum scaled by ring pixel count (typically >=350), which does not match suite2p's own
``Fneu = mean(movie[neuropil_ipix], axis=0)`` convention and would make ``neuropil_weight``
uninterpretable.
Per-ROI pixel coordinates and weights are derived directly from ``masks`` (each ROI's own
nonzero entries), rather than requiring suite2p's raw stat dicts -- this makes ``'surround'``
usable with any :class:`~photon_mosaic.core.baserois.BaseRois`, not only
:class:`~photon_mosaic.extractors.Suite2pRois`. Each ROI's ``radius`` (needed by
``create_cell_pix``'s internal smoothing) is estimated from its pixel count assuming a
roughly circular shape (``sqrt(n_pixels / pi)``); ``lam`` is taken from the mask's own
values, falling back to uniform weights for all-zero/binary masks.
Multi-plane input (``masks.ndim == 4``, shape ``(n_rois, Ly, Lx, n_planes)``) is supported
as long as every ROI's own mask is confined to a single plane -- each plane's ROIs are then
treated as an independent 2D problem via suite2p's (inherently 2D) mask functions, so a
ring only ever excludes/competes with same-plane neighbors. This is correct for
well-separated planes (e.g. mesoscope acquisitions where each ROI shows up in exactly one
plane) but not for genuinely volumetric ROIs spanning multiple planes -- that would need a
true 3D "shell" neuropil mask (e.g. as in
`Suite3D <https://www.biorxiv.org/content/10.1101/2025.03.26.645628v2.full>`_, code at
https://github.com/alihaydaroglu/suite3d) and raises ``NotImplementedError``.
Parameters
----------
masks : np.ndarray | sparse.SparseArray
ROI image masks, shape ``(n_rois, Ly, Lx)`` or ``(n_rois, Ly, Lx, n_planes)`` (e.g.
from ``BaseRois.get_roi_image_masks()``).
inner_neuropil_radius, min_neuropil_pixels, circular, lam_percentile
Passed through to suite2p's ``create_cell_pix``/``create_neuropil_masks``.
Returns
-------
sparse.GCXS
Same shape as ``masks``, dtype float32. Ring pixels sum to 1.0 per ROI; ROIs whose
ring ended up empty get an all-zero row (no neuropil subtraction for that ROI).
"""
import sparse
try:
from suite2p.extraction.masks import create_cell_pix, create_neuropil_masks
except ImportError as e:
raise ImportError(
"NeuropilExtension(method='surround') requires suite2p. Install it with "
"'pip install \"photon-mosaic[suite2p]\"'."
) from e
if masks.ndim == 3:
n_rois, Ly, Lx = masks.shape
n_planes = 1
elif masks.ndim == 4:
n_rois, Ly, Lx, n_planes = masks.shape
else:
raise ValueError(f"Expected masks with 3 or 4 dimensions (n_rois, Ly, Lx[, n_planes]), got {masks.shape}")
out_shape = (0, Ly, Lx) if masks.ndim == 3 else (0, Ly, Lx, n_planes)
if n_rois == 0:
return sparse.GCXS.from_numpy(np.zeros(out_shape, dtype=np.float32), compressed_axes=(0,))
# roi_planes[i] is only meaningful (and only used) when masks.ndim == 4.
roi_planes = np.zeros(n_rois, dtype=int)
stats = []
for i in range(n_rois):
roi_mask = masks[i]
if isinstance(roi_mask, sparse.SparseArray):
coo = roi_mask.tocoo()
coords, data = coo.coords, np.asarray(coo.data, dtype=np.float64)
else:
nz = np.nonzero(roi_mask)
coords, data = np.stack(nz), np.asarray(roi_mask[nz], dtype=np.float64)
if masks.ndim == 4:
ypix, xpix, plane_idx = coords[0], coords[1], coords[2]
planes_present = np.unique(plane_idx)
if len(planes_present) > 1:
raise NotImplementedError(
f"ROI {i} spans multiple planes ({planes_present.tolist()}). "
"NeuropilExtension(method='surround') only supports ROIs confined to a "
"single plane each (e.g. well-separated mesoscope planes); a genuinely "
"volumetric neuropil mask (Suite3D-style 3D shell) is not yet implemented."
)
if len(planes_present):
roi_planes[i] = int(planes_present[0])
else:
ypix, xpix = coords[0], coords[1]
lam = data
if len(ypix) == 0 or lam.sum() <= 0:
lam = np.ones(len(ypix))
radius = np.sqrt(len(ypix) / np.pi) if len(ypix) > 0 else 1.0
stats.append({"ypix": ypix, "xpix": xpix, "lam": lam, "radius": radius})
def _cell_pix_and_neuropil_ipix(stats_subset):
cell_pix = create_cell_pix(stats_subset, Ly, Lx, lam_percentile=lam_percentile)
return create_neuropil_masks(
ypixs=[s["ypix"] for s in stats_subset],
xpixs=[s["xpix"] for s in stats_subset],
cell_pix=cell_pix,
inner_neuropil_radius=inner_neuropil_radius,
min_neuropil_pixels=min_neuropil_pixels,
circular=circular,
)
# An all-zero ROI (no pixels) gets an all-zero ring directly: suite2p's rectangular (the
# default, non-circular) growth path calls .min()/.max() on a ROI's own pixel coordinates
# while extending it, which raises on an empty array. Such a ROI can never contribute any
# cell pixels either, so simply excluding it from the suite2p calls below changes nothing
# for the other ROIs.
neuropil_ipix: list = [np.zeros(0, dtype=np.intp)] * n_rois
if n_planes == 1:
non_empty = [i for i in range(n_rois) if len(stats[i]["ypix"])]
if non_empty:
ipix = _cell_pix_and_neuropil_ipix([stats[i] for i in non_empty])
for local_i, global_i in enumerate(non_empty):
neuropil_ipix[global_i] = ipix[local_i]
else:
# Each plane's ROIs are solved as an independent 2D problem (see docstring): a ring
# only excludes/competes with pixels from the same plane's other ROIs.
for p in range(n_planes):
roi_indices_p = [i for i in np.flatnonzero(roi_planes == p) if len(stats[i]["ypix"])]
if len(roi_indices_p) == 0:
continue
ipix_p = _cell_pix_and_neuropil_ipix([stats[i] for i in roi_indices_p])
for local_i, global_i in enumerate(roi_indices_p):
neuropil_ipix[global_i] = ipix_p[local_i]
ring_masks = []
for i, ipix in enumerate(neuropil_ipix):
ipix = np.asarray(ipix)
n_pixels = len(ipix)
shape = (Ly, Lx) if masks.ndim == 3 else (Ly, Lx, n_planes)
if n_pixels == 0:
ring_masks.append(
sparse.COO(np.zeros((len(shape), 0), dtype=np.intp), np.zeros(0, dtype=np.float32), shape=shape)
)
continue
ring_y, ring_x = np.unravel_index(ipix, (Ly, Lx))
weights = np.full(n_pixels, 1.0 / n_pixels, dtype=np.float32)
if masks.ndim == 3:
coords = np.stack([ring_y, ring_x])
else:
plane_coord = np.full(n_pixels, roi_planes[i], dtype=np.intp)
coords = np.stack([ring_y, ring_x, plane_coord])
ring_masks.append(sparse.COO(coords, weights, shape=shape))
return sparse.GCXS.from_coo(sparse.stack(ring_masks, axis=0), compressed_axes=(0,))
_CNMF_INIT_METHODS = ("ramp", "svd")
def _masks_to_sparse_matrix(masks):
"""Flatten ROI image masks into a ``scipy.sparse`` CSR matrix of shape ``(n_rois, n_pixels)``.
Returns a ``scipy.sparse.csr_matrix``; scipy is imported lazily, hence the untyped signature.
Accepts whatever ``BaseRois.get_roi_image_masks()`` returns (dense ndarray or
:class:`sparse.SparseArray`) and keeps the mask *values* -- CNMF footprints are weighted, so
binarizing here would change the model being fit.
"""
import scipy.sparse as sp
num_rois = masks.shape[0]
flat = masks.reshape((num_rois, -1))
if isinstance(flat, sparse.SparseArray):
coo = flat.tocoo()
rows, cols = coo.coords
return sp.csr_matrix(
(np.asarray(coo.data, dtype=np.float32), (rows, cols)),
shape=(num_rois, flat.shape[1]),
)
return sp.csr_matrix(np.asarray(flat, dtype=np.float32))
def _check_finite_non_negative(name: str, value: float) -> None:
"""Reject a solver parameter that must be finite and non-negative.
Chiefly about ``ridge``, which is relative to each Gram diagonal entry and so scales that entry
by ``1 + ridge``: a negative value shrinks the diagonal rather than padding it. ``ridge=-0.5``
doubles every recovered trace and ``ridge=-1`` makes the factorization exactly singular --
neither fails loudly on its own.
"""
if not np.isfinite(value) or value < 0:
raise ValueError(f"{name} must be finite and >= 0, got {value}")
def _spatial_bandpass(chunk, highpass_sigma, lowpass_sigma):
"""Difference-of-Gaussians spatial band-pass, applied per frame and per plane.
``chunk`` has shape ``(n_frames, Ly, Lx, n_planes)``; each frame is filtered in 2D with the planes as
channels. The border is replicated, not reflected or constant (a constant border darkens the field-of-view
edge and so manufactures a spurious high-pass ring).
"""
import cv2
x = np.asarray(chunk, dtype=np.float32)
def blur(frame, sigma):
out = cv2.GaussianBlur(frame, (0, 0), sigmaX=sigma, sigmaY=sigma, borderType=cv2.BORDER_REPLICATE)
return out.reshape(frame.shape) # cv2 drops a trailing axis of size 1
out = np.empty_like(x)
for k, frame in enumerate(x):
low = blur(frame, lowpass_sigma) if lowpass_sigma else frame
out[k] = low - blur(frame, highpass_sigma) if highpass_sigma else low
return out
def _spatial_bandpass_blocks(frames, highpass_sigma, lowpass_sigma, n_jobs=1, block=64):
""":func:`_spatial_bandpass` of ``frames`` ``(n_frames, Ly, Lx, n_planes)``, in blocks of ``block`` frames.
Frames are independent, so the blocks run in a thread pool (cv2 releases the GIL) without changing the result.
"""
out = np.empty(frames.shape, dtype=np.float32)
def filter_block(start):
out[start : start + block] = _spatial_bandpass(frames[start : start + block], highpass_sigma, lowpass_sigma)
starts = range(0, len(frames), block)
if n_jobs <= 1:
for start in starts:
filter_block(start)
else:
from concurrent.futures import ThreadPoolExecutor
with ThreadPoolExecutor(max_workers=n_jobs) as pool:
list(pool.map(filter_block, starts))
return out
def _ridge_regularize(gram, ridge: float):
"""``gram`` with ``ridge`` times each diagonal entry added to that entry.
The ridge is scaled by each *diagonal entry* rather than by the mean diagonal, so that entries
of very different magnitudes each get a comparable relative penalty.
A non-positive or non-finite diagonal entry (e.g. an all-zero mask) gets the mean of the valid
ones instead, so the result stays positive definite. That floor is *not* scaled by ``ridge``:
it is what makes the matrix invertible at all, and ``ridge=0`` is an accepted value. Applying it
whole rather than as ``ridge * fallback`` also keeps an empty row from dominating the condition
number -- it leaves valid ROIs bit-identical, since an all-zero mask decouples from them.
"""
gram = np.asarray(gram, dtype=np.float64)
diagonal = np.diag(gram).astype(np.float64).copy()
invalid = ~np.isfinite(diagonal) | (diagonal <= 0)
fallback = float(np.mean(diagonal[~invalid])) if (~invalid).any() else 1.0
if not np.isfinite(fallback) or fallback <= 0:
fallback = 1.0
return gram + np.diag(np.where(invalid, fallback, ridge * diagonal))
def _ridge_inverse(gram, ridge: float):
"""Symmetric (pseudo-)inverse of a Gram matrix with a per-entry-relative ridge.
The ridge is scaled by each *diagonal entry* rather than by the mean diagonal. That distinction
is load-bearing for the joint ``[A, b]`` Gram: a background component's diagonal is orders of
magnitude larger than an ROI's, so a mean-scaled ridge would apply a huge relative penalty to
the ROI block and visibly shrink the recovered traces.
"""
from scipy.linalg import pinvh
if np.shape(gram)[0] == 0:
return np.zeros((0, 0))
regularized = _ridge_regularize(gram, ridge)
try:
return pinvh(regularized)
except Exception: # pragma: no cover - pinvh is very hard to make fail
return np.linalg.pinv(regularized)
def _nnls_block(gram, rhs, x0, n_iter: int = 50):
"""``argmin_{X >= 0} 0.5*||X||^2_gram - <X, rhs>`` by projected gradient descent.
Simply clipping the unconstrained minimiser ``rhs @ inv(gram)`` at zero is *not* the constrained
minimiser unless ``gram`` is diagonal (i.e. exact only for ``gnb == 1``, where it is 1x1).
Projected gradient with step ``1/||gram||_2`` is monotone, which is what keeps the reported
objective non-increasing.
"""
gram = np.asarray(gram, dtype=np.float64)
rhs = np.asarray(rhs, dtype=np.float64)
x = np.maximum(np.asarray(x0, dtype=np.float64), 0.0)
norm = np.linalg.norm(gram, 2) if gram.size else 0.0
if not np.isfinite(norm) or norm <= 0:
return x
step = 1.0 / norm
for _ in range(n_iter):
x = np.maximum(x - step * (x @ gram - rhs), 0.0)
return x
def _project_float64(data, factor, block: int = 512):
"""``data @ factor`` accumulated in float64, in bounded-memory row blocks.
The movie is float32, but the fit objective is a difference of terms of order ``||Y||^2`` that
cancel down to something ~1e7 times smaller. float32 projections leave absolute noise big
enough to make the objective visibly non-monotone, so every reduction against the movie is done
in float64 -- blocked, so the float64 upcast never materialises the whole array at once.
"""
out = np.empty((data.shape[0], factor.shape[1]), dtype=np.float64)
for i in range(0, data.shape[0], block):
out[i : i + block] = data[i : i + block].astype(np.float64) @ factor
return out
def _project_float64_left(factor, data, block: int = 512):
"""``factor.T @ data`` accumulated in float64, in bounded-memory row blocks of ``data``."""
out = np.zeros((factor.shape[1], data.shape[1]), dtype=np.float64)
for i in range(0, data.shape[0], block):
out += factor[i : i + block].T @ data[i : i + block].astype(np.float64)
return out
def _partition_of_unity(spatial_shape, gnb: int):
"""``(gnb, n_pixels)`` non-negative spatial weights summing to 1 at every pixel.
Used to split a single broad background estimate into ``gnb`` spatially distinct, deterministic
starting components (triangular bumps along the x axis). Deterministic matters: extension data is
cached on disk and compared across runs, so an RNG-based init would make results irreproducible.
"""
n_pixels = int(np.prod(spatial_shape))
if gnb == 1:
return np.ones((1, n_pixels), dtype=np.float64)
height, width, num_planes = spatial_shape
centers = np.linspace(0.0, width - 1, gnb)
coords = np.arange(width, dtype=np.float64)
bump_width = max((width - 1) / max(gnb - 1, 1), 1.0)
bumps = np.maximum(1.0 - np.abs(coords[None, :] - centers[:, None]) / bump_width, 0.0)
totals = bumps.sum(axis=0)
totals[totals == 0] = 1.0
bumps = bumps / totals
weights = np.broadcast_to(bumps[:, None, :, None], (gnb, height, width, num_planes))
return np.ascontiguousarray(weights.reshape(gnb, -1))
def _inpaint_roi_support(image, roi_support, spatial_shape, sigma):
"""Replace ``image`` on ROI pixels by a smooth interpolation of its off-ROI neighbourhood.
This is what picks the initial point along the model's gauge freedom (``b -> b + alpha A``,
``C -> C - f alpha``, see :class:`NeuropilExtension`). The objective is *exactly* flat along
that direction, so which member of the family the fit lands on is decided by the
initialisation, not by the data -- and the seeded traces come from a band-passed movie, so they
carry no baseline and the raw residual image hands every ROI's baseline to ``b``.
Assuming instead that the background is spatially smooth *through* each footprint -- which is
what "neuropil" physically means -- starts the fit at the sensible member of the family, where
each ROI's baseline stays in its own trace.
"""
from scipy.ndimage import gaussian_filter
if not roi_support.any() or not sigma:
return image
shaped = image.reshape(spatial_shape)
keep = (~roi_support).reshape(spatial_shape).astype(np.float64)
blur = (0 if spatial_shape[0] == 1 else sigma, sigma, 0)
numerator = gaussian_filter(shaped * keep, sigma=blur, mode="nearest")
denominator = gaussian_filter(keep, sigma=blur, mode="nearest")
filled = np.where(denominator > 1e-8, numerator / np.maximum(denominator, 1e-8), shaped)
out = image.copy()
out[roi_support] = filled.reshape(-1)[roi_support]
return out
def _init_cnmf_background(y_sub, masks_csr, traces_sub, gnb, spatial_shape, init_method, nonneg, ridge, inpaint_sigma):
"""Deterministic non-negative initialisation of the background factors ``b`` ``(gnb, n_pixels)`` and ``f``.
Both methods start from the *mean residual image* ``mean(Y) - A mean(C)``, smoothed across the
ROI footprints (see :func:`_inpaint_roi_support`, which is what fixes the gauge), since that is
the broad structure left over once the seeded ROI traces are accounted for.
- ``'ramp'``: split that image into ``gnb`` spatial bumps (see :func:`_partition_of_unity`).
Dependency-free and the default.
- ``'svd'``: rank-``gnb`` truncated SVD of the residual with an NNDSVD-style sign fix.
"""
residual_mean = y_sub.mean(axis=0).astype(np.float64) - np.asarray(
traces_sub.mean(axis=0) @ masks_csr, dtype=np.float64
)
roi_support = np.asarray(abs(masks_csr).sum(axis=0), dtype=np.float64).ravel() > 0
residual_mean = _inpaint_roi_support(residual_mean, roi_support, spatial_shape, inpaint_sigma)
if init_method == "ramp":
background_spatial = np.maximum(residual_mean, 0.0)[None, :] * _partition_of_unity(spatial_shape, gnb)
elif init_method == "svd":
from scipy.sparse.linalg import svds
residual = y_sub.astype(np.float64) - np.asarray(traces_sub @ masks_csr, dtype=np.float64)
residual[:, roi_support] = 0.0 # same gauge choice as 'ramp': ignore ROI pixels
k = min(gnb, min(residual.shape) - 1)
if k < 1:
background_spatial = np.maximum(residual_mean, 0.0)[None, :] * np.ones((gnb, 1))
else:
_, _, vt = svds(residual, k=k)
components = np.abs(vt[::-1]) # svds returns ascending singular values
background_spatial = np.zeros((gnb, residual.shape[1]), dtype=np.float64)
for i in range(gnb):
background_spatial[i] = components[min(i, k - 1)]
else: # pragma: no cover - validated in _set_params
raise ValueError(f"Unknown init_method: '{init_method}'. Supported: {_CNMF_INIT_METHODS}.")
background_spatial = np.asarray(background_spatial, dtype=np.float64).reshape(gnb, -1)
# A background component that initialises to all-zero can never move (every update is
# multiplicative in b's own support), so fall back to a flat component.
for k in range(gnb):
if not np.any(background_spatial[k] > 0):
background_spatial[k] = 1.0
gram_bb = background_spatial @ background_spatial.T
rhs = _project_float64(y_sub, background_spatial.T) - traces_sub @ np.asarray(
masks_csr @ background_spatial.T, dtype=np.float64
)
f = rhs @ _ridge_inverse(gram_bb, ridge)
if nonneg:
f = _nnls_block(_ridge_regularize(gram_bb, ridge), rhs, f)
return background_spatial, f
def _cnmf_objective(ynorm_sq, traces, temporal, proj_masks, proj_background, gram_aa, gram_ab, gram_bb):
"""``||Y - C A - f b||_F^2``, computed entirely from cached Gram matrices.
Needs no access to the movie, so convergence can be monitored for free every iteration. This is
also the cheapest possible check on the update algebra: any sign or transpose slip shows up as a
non-monotone objective.
"""
return float(
ynorm_sq
+ np.sum((traces.T @ traces) * gram_aa)
+ np.sum((temporal.T @ temporal) * gram_bb)
- 2.0 * np.sum(proj_masks * traces)
- 2.0 * np.sum(proj_background * temporal)
+ 2.0 * np.sum((traces.T @ temporal) * gram_ab)
)
def _iter_movie_chunks(imaging, chunk_size, epoch_offsets):
"""Yield ``(global_start, flat_chunk, shaped_chunk)`` over the whole movie, in gather order.
Uses SpikeInterface's own :func:`divide_time_series_into_chunks` -- the *same* slice list
``run_node_pipeline`` consumes -- so the frame ordering of everything computed here matches
``FluorescenceExtension``'s output by construction rather than by coincidence.
"""
from spikeinterface.core.job_tools import divide_time_series_into_chunks
for epoch_index, start, stop in divide_time_series_into_chunks(imaging, chunk_size):
chunk = np.asarray(
imaging.get_series(start_frame=start, end_frame=stop, epoch_index=epoch_index),
dtype=np.float32,
)
if chunk.ndim == 3: # (frames, Ly, Lx) -> (frames, Ly, Lx, 1)
chunk = chunk[..., np.newaxis]
yield int(epoch_offsets[epoch_index]) + start, chunk.reshape(chunk.shape[0], -1), chunk
def _fit_cnmf_background(
imaging,
masks,
*,
gnb: int,
max_iter: int,
tol: float,
highpass_sigma: float | None,
lowpass_sigma: float | None,
init_method: str,
nonneg_background: bool,
nonneg_traces: bool,
ridge: float,
subsample_frames: int | None,
chunk_size: int | None,
n_jobs: int = 1,
verbose: bool = False,
) -> np.ndarray:
"""Fit the spatial part ``b`` of a low-rank CNMF background ``f b`` against *fixed* footprints.
Model: ``Y ~= C A + f b`` for ``Y`` ``(n_frames, n_pixels)``, ``A`` ``(n_rois, n_pixels)``
taken as given from the ROI masks (``masks_csr``), ``C`` ``(n_frames, n_rois)``, ``b``
``(gnb, n_pixels)`` and ``f`` ``(n_frames, gnb)``. In the code ``A`` is ``masks_csr``, ``C`` is
``traces_sub``, ``b`` is ``background_spatial`` and ``f`` is ``temporal_sub``.
``b`` is fitted by alternating ``C``, ``b`` and ``f`` updates on a deterministic frame subsample,
which is gathered in **one streaming pass** over the movie. ``C`` and ``f`` over all frames are
not computed here: once ``A`` and ``b`` are fixed that is exactly the joint solve
:class:`FluorescenceExtension` does per chunk anyway (``method='regression'`` or ``'nnls'``).
Returns ``b`` as ``(gnb, Ly, Lx, n_planes)`` float32, each component unit-L2 and ordered by
descending energy of its timecourse on the subsample.
"""
num_rois = int(masks.shape[0])
spatial_shape = tuple(int(s) for s in masks.shape[1:])
if len(spatial_shape) == 2:
spatial_shape = spatial_shape + (1,)
n_pixels = int(np.prod(spatial_shape))
num_epochs = imaging.get_num_epochs()
frames_per_epoch = [imaging.get_num_frames(epoch_index=i) for i in range(num_epochs)]
epoch_offsets = np.concatenate(([0], np.cumsum(frames_per_epoch))).astype(np.int64)
num_frames = int(epoch_offsets[-1])
if num_rois == 0:
return np.zeros((gnb,) + spatial_shape, dtype=np.float32)
# float64 throughout: see _project_float64 on why float32 reductions are not good enough here.
masks_csr = _masks_to_sparse_matrix(masks).astype(np.float64) # (n_rois, n_pixels)
gram_aa = np.asarray((masks_csr @ masks_csr.T).todense(), dtype=np.float64)
gram_aa_inv = _ridge_inverse(gram_aa, ridge)
if chunk_size is None:
chunk_size = max(num_frames, 1)
# ---- The one pass: the frame subsample, its P_A = Y A.T, and the band-passed P_A for the seed -
if subsample_frames is None or subsample_frames >= num_frames:
sub_rows = np.arange(num_frames)
else:
# Deterministic and evenly spread over the whole recording (never an RNG: extension data is
# cached on disk and compared across runs, so the fit has to be reproducible).
sub_rows = np.unique(np.round(np.linspace(0, num_frames - 1, subsample_frames)).astype(int))
y_sub = np.zeros((len(sub_rows), n_pixels), dtype=np.float32)
for global_start, flat, _ in _iter_movie_chunks(imaging, chunk_size, epoch_offsets):
n = flat.shape[0]
in_chunk = np.flatnonzero((sub_rows >= global_start) & (sub_rows < global_start + n))
if len(in_chunk) == 0:
continue
y_sub[in_chunk] = flat[sub_rows[in_chunk] - global_start]
# Band-pass the gathered frames once, in threads.
y_sub_hp = _spatial_bandpass_blocks(
y_sub.reshape((len(sub_rows),) + spatial_shape), highpass_sigma, lowpass_sigma, n_jobs
).reshape(len(sub_rows), -1)
proj_masks_sub = _project_float64(y_sub, masks_csr.T) # (n_sub, n_rois)
proj_masks_hp = _project_float64(y_sub_hp, masks_csr.T)
del y_sub_hp
# ---- Alternating fit for b, on the subsample only (no further movie access) -----------------
# The band-passed seed removes the broad background before the first trace estimate so it does
# not leak into C.
traces_sub = proj_masks_hp @ gram_aa_inv
if nonneg_traces:
traces_sub = np.maximum(traces_sub, 0.0)
# A footprint-sized smoothing scale: wide enough to bridge a soma, narrow enough to keep real
# background structure. Falls back to the high-pass scale when the masks are degenerate.
inpaint_sigma = float(np.sqrt(max(gram_aa.diagonal().max(), 1.0) / np.pi)) + 1.0
if highpass_sigma:
inpaint_sigma = min(inpaint_sigma, float(highpass_sigma))
background_spatial, temporal_sub = _init_cnmf_background(
y_sub,
masks_csr,
traces_sub,
gnb,
spatial_shape,
init_method,
nonneg_background,
ridge,
inpaint_sigma,
)
ysub_norm_sq = sum(float(np.square(y_sub[i : i + 512], dtype=np.float64).sum()) for i in range(0, len(y_sub), 512))
objective: list[float] = []
for n_iter in range(1, max_iter + 1):
gram_ab = np.asarray(masks_csr @ background_spatial.T, dtype=np.float64)
traces_sub = (proj_masks_sub - temporal_sub @ gram_ab.T) @ gram_aa_inv
if nonneg_traces:
traces_sub = np.maximum(traces_sub, 0.0)
gram_ff = temporal_sub.T @ temporal_sub
rhs_b = _project_float64_left(temporal_sub, y_sub) - np.asarray(
(temporal_sub.T @ traces_sub) @ masks_csr, dtype=np.float64
)
if nonneg_background:
# _nnls_block takes one sample per row, here a pixel.
background_spatial = _nnls_block(_ridge_regularize(gram_ff, ridge), rhs_b.T, background_spatial.T).T
else:
background_spatial = _ridge_inverse(gram_ff, ridge) @ rhs_b
gram_ab = np.asarray(masks_csr @ background_spatial.T, dtype=np.float64)
gram_bb = background_spatial @ background_spatial.T
proj_background_sub = _project_float64(y_sub, background_spatial.T)
rhs_f = proj_background_sub - traces_sub @ gram_ab
if nonneg_background:
temporal_sub = _nnls_block(_ridge_regularize(gram_bb, ridge), rhs_f, temporal_sub)
else:
temporal_sub = rhs_f @ _ridge_inverse(gram_bb, ridge)
objective.append(
_cnmf_objective(
ysub_norm_sq,
traces_sub,
temporal_sub,
proj_masks_sub,
proj_background_sub,
gram_aa,
gram_ab,
gram_bb,
)
)
if verbose:
print(f"neuropil(cnmf) iteration {n_iter}: objective={objective[-1]:.6g}")
if len(objective) > 1:
previous = objective[-2]
denom = abs(previous) if previous else 1.0
if abs(previous - objective[-1]) / denom < tol:
break
# ---- Pin the scale/permutation ambiguity so results are comparable across runs -------------
# b f is invariant under b_k -> alpha_k b_k, f_k -> f_k / alpha_k for any alpha_k > 0, and under
# permutation of k. Fix it: unit-L2 spatial components, ordered by descending temporal energy.
for k in range(gnb):
scale = float(np.linalg.norm(background_spatial[k]))
if scale > 0:
background_spatial[k] /= scale
temporal_sub[:, k] *= scale
background_spatial = background_spatial[np.argsort(-np.linalg.norm(temporal_sub, axis=0))]
gram_ab = np.asarray(masks_csr @ background_spatial.T, dtype=np.float64)
gram_joint = np.block([[gram_aa, gram_ab], [gram_ab.T, background_spatial @ background_spatial.T]])
cond_aa = float(np.linalg.cond(gram_aa))
cond_joint = float(np.linalg.cond(gram_joint))
if max(cond_aa, cond_joint) > 1e6:
warnings.warn(
f"Ill-conditioned CNMF design (cond(A A.T)={cond_aa:.3g}, cond(D D.T)={cond_joint:.3g}); "
"heavily overlapping ROIs make the trace/background split poorly determined. Consider "
"raising `ridge` or reducing `gnb`.",
stacklevel=2,
)
return np.ascontiguousarray(background_spatial.reshape((gnb,) + spatial_shape), dtype=np.float32)
register_result_extension(FluorescenceExtension)
register_result_extension(NeuropilExtension)
register_result_extension(BackgroundExtension)
register_result_extension(DfOverFExtension)
register_result_extension(DeconvolutionExtension)