photon_mosaic.core.roianalyzer_core_extensions#
Classes
|
Extension to estimate a low-rank background over the whole field of view. |
|
Extension to deconvolve neural activity from dF/F traces using OASIS. |
|
Extension to compute dF/F (relative fluorescence change) from fluorescence traces. |
|
Extension to extract fluorescence traces from ROIs. |
|
|
|
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,
Astands for the flattened ROI masks,(n_rois, n_pixels)– ROI-first, asget_roi_image_masks()returns them (CaImAn stores the transpose) – andCfor 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 ofmovie ~= C A (+ f b)for all ROIs at once, so overlapping ROIs are separated. The sparseA A.Tis factorized once and reused for every chunk, withbhandled by a smallgnb x gnbSchur-complement correction on top.'nnls': the same solve withC >= 0enforced (fluorescence is a photon count). Solved frame by frame withscipy.optimize.nnls(), so it costs more per chunk than'regression'.
When a
BackgroundExtensionexists, its spatial backgroundbis appended to the design matrix and its timecoursefis solved for together with the tracesC. That requires'regression'or'nnls'. With both aNeuropilExtensionand aBackgroundExtensioncomputed,neuropil_sourcepicks which one to use.neuropil_weightw(default0.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 areC + (1 - w) B, i.e.(C + B) - w B, the same correction withBas the neuropil: the joint fit’s own split corresponds tow = 1, andw < 1returns(1 - w) Bto 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 (seeNeuropilExtension).Computed data keys:
Key
Shape
Contents
fluorescence(n_frames, n_rois)the extracted traces:
C + (1 - neuropil_weight) Bfor a CNMF background (Cforneuropil_weight=1),F - neuropil_weight * Fneufor surroundbackground(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 ofC), beforeneuropil_weight. Surround: the ring meanFneubeforeneuropil_weight, on the same L2 scale asfluorescence(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#
- 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
- 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 whencircular=True, viasuite2p.extraction.masks.create_cell_pix()/create_neuropil_masks(). Ring pixels are weighted1 / n_ring_pixelsso that the weighted-sum matmul inFluorescenceNodereproduces suite2p’s own unweighted-meanFneuconvention. Works with anyBaseRois– per-ROI pixel coordinates are derived fromrois.get_roi_image_masks()(not suite2p-specific stat data), sinceRoiAnalyzeralways stores its own in-memory/on-disk snapshot of the ROIs rather than the original object passed tocreate_roi_analyzer(e.g.format="memory"always copies into a plainNumpyRois, so a Suite2pRois-specific accessor would not be reachable viaroi_analyzer.roisin 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 itsuse_neuropilparam) – just callroi_analyzer.compute("neuropil")beforeroi_analyzer.compute("fluorescence").'surround'feeds anF - neuropil_weight * Fneusubtraction, with the ring mask applied to the movie insideFluorescenceNode; 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 backgroundbofgnbspatial components, fitted from the movie and the ROI masks.get_data()returnsb, of shape(gnb, Ly, Lx, n_planes). It is not per ROI.Once computed, this extension is picked up automatically by
FluorescenceExtension(see itsuse_neuropilandneuropil_sourceparams) – just callroi_analyzer.compute("background")beforeroi_analyzer.compute("fluorescence").The fluorescence extension gets
bas extra columns of its design matrix, which needsFluorescenceExtension(method='regression')ormethod='nnls'. The resulting per-ROI backgroundBis persisted asget_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, whereF0is 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 fromCintob, f(or back) fits the movie equally well, soC’s own baseline is not reliable on its own. Withuse_background=True(the default) the background per ROIB(FluorescenceExtension.get_data(key='background'), scaled by that extension’sneuropil_weightlike the share of it removed from the traces) is then used as a second input, as in CaImAn’sdetrend_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
Cand the background shiftsC_baselineandB_baselineby 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-varyingf alphaterm 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 fromC. 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), matchingself.data["df_over_f"]). With a CNMF background it is the denominatorB_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#