photon_mosaic.core.roianalyzer_core_extensions#

Classes

BackgroundExtension(roi_analyzer)

Extension to estimate a low-rank background over the whole field of view.

DeconvolutionExtension(roi_analyzer)

Extension to deconvolve neural activity from dF/F traces using OASIS.

DfOverFExtension(roi_analyzer)

Extension to compute dF/F (relative fluorescence change) from fluorescence traces.

FluorescenceExtension(roi_analyzer)

Extension to extract fluorescence traces from ROIs.

FluorescenceNode(imaging, rois[, neuropil, ...])

NeuropilExtension(roi_analyzer)

Extension to model the neuropil / background contaminating each ROI's fluorescence.

class photon_mosaic.core.roianalyzer_core_extensions.FluorescenceExtension(roi_analyzer)[source]#

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 scipy.optimize.nnls(), so it costs more per chunk than 'regression'.

When a 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 NeuropilExtension and a 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 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 _persisted_neuropil()). (n_frames, 0) without a neuropil.

Methods

get_optional_dependencies

extension_name: str | None = 'fluorescence'#
depend_on: list[str] = []#
need_imaging = True#
use_nodepipeline = True#
nodepipeline_variables: list[str] | None = ['fluorescence', 'background']#
need_job_kwargs = True#
classmethod get_optional_dependencies(use_neuropil=True, neuropil_source=None, **params)[source]#
class photon_mosaic.core.roianalyzer_core_extensions.FluorescenceNode(imaging, rois, neuropil=None, neuropil_weight=0.7, background_spatial=None, method='projection', ridge=1e-06)[source]#

Methods

compute

get_dtype

get_dtype()[source]#
compute(chunk, *args)[source]#
class photon_mosaic.core.roianalyzer_core_extensions.NeuropilExtension(roi_analyzer)[source]#

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 suite2p.extraction.masks.create_cell_pix()/create_neuropil_masks(). Ring pixels are weighted 1 / n_ring_pixels so that the weighted-sum matmul in FluorescenceNode reproduces suite2p’s own unweighted-mean Fneu convention. Works with any 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 (code), rather than this per-plane approach).

Once computed, this extension is picked up automatically by 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 FluorescenceNode; it needs no change to the design matrix, since the ring is spatially disjoint from its ROI.

extension_name: str | None = 'neuropil'#
depend_on: list[str] = []#
need_imaging = False#
use_nodepipeline = False#
need_job_kwargs = True#
class photon_mosaic.core.roianalyzer_core_extensions.BackgroundExtension(roi_analyzer)[source]#

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 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: str | None = 'background'#
depend_on: list[str] = []#
need_imaging = True#
use_nodepipeline = False#
need_job_kwargs = True#
class photon_mosaic.core.roianalyzer_core_extensions.DfOverFExtension(roi_analyzer)[source]#

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 (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: str | None = 'df_over_f'#
depend_on: list[str] = ['fluorescence']#
need_imaging = False#
need_job_kwargs = True#
class photon_mosaic.core.roianalyzer_core_extensions.DeconvolutionExtension(roi_analyzer)[source]#

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: str | None = 'deconvolution'#
depend_on: list[str] = ['df_over_f']#
need_imaging = False#
need_job_kwargs = True#