photon_mosaic.core.generators#

Module to generate synthetic imaging and ROI objects for testing and example purposes.

Functions

generate_fluorescence(num_frames[, ...])

Generate synthetic fluorescence traces by convolving random spike events with an exponential kernel.

generate_imaging_with_rois([num_frames, ...])

Generate a random NumpyImaging object and corresponding ROIs with fluorescence activity.

generate_random_imaging([num_frames, ...])

Generate a random NumpyImaging object for testing.

generate_rois([num_rois, height, width, ...])

Generate circular ROIs for testing.

Classes

FluorescenceData(traces, spikes, clean_traces)

Return type of generate_fluorescence().

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 so F0(0) == 1; bleach(t) == 1 for all frames when there is no photobleaching (bleaching_time is inf).

  • 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 by generate_imaging_with_rois() (generate_fluorescence() alone has no background to report); None otherwise. 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:

NumpyImaging

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 20

  • height (int) – Height of the imaging field, by default 256

  • width (int) – Width of the imaging field, by default 256

  • radius_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.0

  • roi_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 False

  • num_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:

BaseRois

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 to generate_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 under noise_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 under noise_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 via aind_ophys_utils.signal_utils.noise_std(method="welch")) as noise_std="poisson" at the default background/baseline_range.

  • bleaching_time (float) – Time constant of multiplicative photobleaching in seconds, passed through to generate_fluorescence(). The default of inf means 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, for neuropil_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 optimal neuropil_weight of a "surround" correction is then about this value. None (the default) is 1.0 for neuropil_model="constant", which stays spatially uniform, and 0.7 for "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 it None) – e.g. for comparison against values recovered from imaging via an RoiAnalyzer.

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 as round(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 of inf means no photobleaching.

  • seed (int | None) – Random seed for reproducibility.

Returns:

See FluorescenceData for field descriptions.

Return type:

FluorescenceData