Source code for photon_mosaic.core.roianalyzer_core_extensions

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)