photon_mosaic.core.generators#
Module to generate synthetic imaging and ROI objects for testing and example purposes.
Functions
|
Generate synthetic fluorescence traces by convolving random spike events with an exponential kernel. |
|
Generate a random NumpyImaging object and corresponding ROIs with fluorescence activity. |
|
Generate a random NumpyImaging object for testing. |
|
Generate circular ROIs for testing. |
Classes
|
Return type of |
- class photon_mosaic.core.generators.FluorescenceData(traces, spikes, clean_traces, neuropil=None)[source]#
Return type of
generate_fluorescence().- Variables:
traces (np.ndarray) – Final fluorescence traces
(num_frames, num_rois), float32. Always(1 + clean_traces) * bleach(t)(plus additive noise if noise_std > 0), i.e. absolute fluorescence normalised soF0(0) == 1;bleach(t) == 1for all frames when there is no photobleaching (bleaching_time isinf).spikes (np.ndarray) – Binary spike trains
(num_frames, num_rois), float32.clean_traces (np.ndarray) – Convolved traces before bleaching and noise
(num_frames, num_rois), float32.neuropil (np.ndarray | None) – True background/neuropil level at each ROI’s own mask (mask-weighted mean over the ROI’s own pixels, before noise),
(num_frames, num_rois), float32. Only populated bygenerate_imaging_with_rois()(generate_fluorescence()alone has no background to report);Noneotherwise. Lets a NeuropilExtension surround-based estimate be checked against the true local contamination, rather than only the end effect on recovered dF/F.
- traces: ndarray#
Alias for field number 0
- spikes: ndarray#
Alias for field number 1
- clean_traces: ndarray#
Alias for field number 2
- neuropil: ndarray | None#
Alias for field number 3
- photon_mosaic.core.generators.generate_random_imaging(num_frames=1000, height=256, width=256, num_planes=1, sampling_frequency=30.0, dtype=<class 'numpy.float32'>, seed=None)[source]#
Generate a random NumpyImaging object for testing.
- Parameters:
num_frames (
int|tuple[int,...]) – Number of frames for each epoch in the imaging data.height (
int) – Height of each frame in pixels.width (
int) – Width of each frame in pixels.sampling_frequency (
float) – Sampling frequency in Hz.dtype (
type) – Dtype of the generated video (np.float32/np.float64). Float32 halves memory with no precision cost – nothing downstream reads above float32 precision anyway.
- Returns:
A NumpyImaging object containing the generated random imaging data.
- Return type:
- photon_mosaic.core.generators.generate_rois(num_rois=20, height=256, width=256, radius_range=(5, 15), sampling_frequency=30.0, roi_ids=None, weighted=False, num_planes=1, seed=None, sparse=False)[source]#
Generate circular ROIs for testing.
- Parameters:
num_rois (
int) – Number of ROIs to generate, by default 20height (
int) – Height of the imaging field, by default 256width (
int) – Width of the imaging field, by default 256radius_range (
tuple[int,int] |tuple[int,int,int]) – Range of radii for the circular ROIs, by default (5, 15) (for 2D). If num_planes > 1 and a tuple of three ints is provided, the third int is used as the radius for the z-dimension. If a tuple of two ints is provided, the depth radius will be half of the num_planes.sampling_frequency (
float) – Sampling frequency, by default 30.0roi_ids (
ndarray|None) – Array of ROI IDs. If None, defaults to np.arange(num_rois)weighted (
bool) – Whether to create weighted masks (values between 0 and 1) or binary masks (0 or 1), by default Falsenum_planes (
int) – Number of planes for the ROIs, by default 1 (2D masks). If >1, creates 3D masks.sparse (
bool) – If True, return the masks as a sparse.GCXS array instead of a dense np.ndarray.
- Return type:
- photon_mosaic.core.generators.generate_imaging_with_rois(num_frames=1000, height=256, width=256, num_planes=1, num_rois=20, radius_range=(5, 15), sampling_frequency=30.0, decay_time=0.5, event_rate=0.3, weighted_rois=False, background=0.2, baseline_range=(0.5, 1.0), noise_std=1.3, bleaching_time=inf, seed=None, neuropil_model='constant', neuropil_fluctuation_std=0.5, neuropil_roi_coefficient=None)[source]#
Generate a random NumpyImaging object and corresponding ROIs with fluorescence activity.
Creates synthetic imaging data with exponentially decaying fluorescence bumps injected at random times for each ROI, on top of a background with Gaussian or Poisson (shot) noise.
- Parameters:
num_frames (
int) – Number of frames in the imaging data.height (
int) – Height of each frame in pixels.width (
int) – Width of each frame in pixels.num_planes (
int) – Number of imaging planes.num_rois (
int) – Number of ROIs to generate.radius_range (
tuple[int,int] |tuple[int,int,int]) – Range of radii for circular ROIs.sampling_frequency (
float) – Sampling frequency in Hz.decay_time (
float) – Duration of exponential decay for fluorescence events in seconds. Since this generative model (sharp rise, single-exponential decay) matches OASIS’s own deconvolution model, the relevant reference is OASIS’s optimal single-exponential fit to real GCaMP8 recordings – 0.2/0.45/0.5 s for GCaMP8f/8m/8s (Rupprecht et al. 2026, Nat. Methods) – not the sensor’s true, more complex kinetics. Default follows GCaMP8s, the variant most often recommended for reliably detecting isolated action potentials.event_rate (
float) – Mean spike-event rate in Hz, passed through togenerate_fluorescence(). Each ROI’s number of events scales with the recording’s duration (num_frames / sampling_frequency).weighted_rois (
bool) – Whether to create weighted masks.background (
float) – Mean photon count per pixel per frame, exact only undernoise_std="poisson"(otherwise just an intensity scale) – present everywhere in the frame, including under the ROIs (e.g. neuropil, out-of- focus light). 0 means a dark background with only noise. Subject to the same bleaching_time decay as the ROI signal, since it mostly represents genuine fluorescence rather than non-bleaching dark counts. This is the true frame-and-time-averaged mean regardless of neuropil_model: each model’s spatial profile and/or temporal fluctuation is normalized to mean 1, so background always means the same thing. (The one exception is a neuropil_roi_coefficient other than 1, which scales the background on ROI pixels only, as"vignette"does by default.)baseline_range (
tuple[float,float]) – Range from which each ROI’s baseline fluorescence (F0) is drawn uniformly at random, modeling cell-to-cell brightness variability – same photon-count semantics as background (exact only undernoise_std="poisson"). Recovered dF/F matches clean_traces when background is 0; a nonzero background attenuates it (see FluorescenceNode’s neuropil argument to correct for this).noise_std (
Union[float,Literal['poisson']]) – Standard deviation of additive Gaussian noise on the video, per pixel and frame. 0 means no noise. Pass"poisson"instead to draw physically realistic shot noise (variance equals the local mean signal) rather than fixed-variance Gaussian noise. The default of 1.3 gives roughly the same recovered dF/F noise level (measured viaaind_ophys_utils.signal_utils.noise_std(method="welch")) asnoise_std="poisson"at the default background/baseline_range.bleaching_time (
float) – Time constant of multiplicative photobleaching in seconds, passed through togenerate_fluorescence(). The default ofinfmeans no photobleaching.seed (
int|None) – Random seed for reproducibility.neuropil_model (
Literal['constant','vignette']) –How background varies over space and time:
"constant": spatially uniform, no fluctuation beyond bleaching_time decay."vignette": one shared Ornstein-Uhlenbeck-like fluctuation (slow, ~5s timescale) modulated by a static radial illumination falloff (brighter center, dimmer edges – real 2P vignetting). Every background pixel shares the same fluctuation, just scaled by its own position.
"vignette"is normalized to preserve background’s mean-photon-count semantics (see background above); only its spatial and temporal structure differs from"constant". Kept intentionally simple – just enough realism to make neuropil subtraction demonstrably matter, not an optically/biologically precise model. A"diffuse"model (many independently-fluctuating sources) is not implemented.neuropil_fluctuation_std (
float) – How strongly the background fluctuates relative to background, forneuropil_model="vignette"(ignored for"constant"). The fluctuation is additive around a mean level, so large values can push the instantaneous background negative (unphysical); 0.5 balances a clearly demonstrable effect against that risk.neuropil_roi_coefficient (
float|None) – Background level on ROI pixels relative to the background around them, applied to every pixel covered by any ROI mask.1.0: the same background everywhere, so a ring around an ROI estimates the neuropil under it exactly. Below 1, ROI pixels are dimmer than their surroundings (e.g. cell bodies displacing neuropil), the situation Suite2p’s default neuropil weight of 0.7 corrects for; the optimalneuropil_weightof a"surround"correction is then about this value.None(the default) is1.0forneuropil_model="constant", which stays spatially uniform, and0.7for"vignette". Must be non-negative.
- Return type:
tuple[BaseRois,NumpyImaging,FluorescenceData]- Returns:
rois (BaseRois) – The generated ROIs.
imaging (NumpyImaging) – The imaging data with injected fluorescence activity.
fluorescence (FluorescenceData) – The ground-truth fluorescence (traces, spikes, clean_traces) injected into the video, plus neuropil (unlike bare
generate_fluorescence(), which leaves itNone) – e.g. for comparison against values recovered from imaging via anRoiAnalyzer.
- photon_mosaic.core.generators.generate_fluorescence(num_frames, num_rois=1, sampling_frequency=30.0, decay_time=0.5, event_rate=0.3, noise_std=0.0, bleaching_time=inf, seed=None)[source]#
Generate synthetic fluorescence traces by convolving random spike events with an exponential kernel.
- Parameters:
num_frames (
int) – Number of frames (time points) to generate.num_rois (
int) – Number of independent fluorescence traces to generate.sampling_frequency (
float) – Sampling frequency in Hz.decay_time (
float) – Time constant of the exponential decay kernel in seconds. This sharp-rise, single-exponential kernel is the same simplified model OASIS itself fits during deconvolution, so the default follows the single-exponential time constant OASIS finds optimal when fit to real GCaMP8s ground-truth recordings under that same model (0.5 s; Rupprecht et al. 2026, Nat. Methods) rather than the sensor’s true single-spike kinetics.event_rate (
float) – Mean spike-event rate in Hz. Each ROI’s number of events is drawn asround(uniform(0.5, 1.5) * event_rate * num_frames / sampling_frequency), scaling with the recording’s duration. Clamped to[0, num_frames].noise_std (
float) – Standard deviation of additive Gaussian noise. 0 means no noise.bleaching_time (
float) – Time constant of multiplicative photobleaching in seconds. The default ofinfmeans no photobleaching.seed (
int|None) – Random seed for reproducibility.
- Returns:
See
FluorescenceDatafor field descriptions.- Return type: