Source code for photon_mosaic.core.generators

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

from typing import Literal, NamedTuple

import numpy as np

from photon_mosaic.core import BaseRois
from photon_mosaic.core.numpyimaging import NumpyImaging, NumpyRois


[docs] class FluorescenceData(NamedTuple): """Return type of :func:`generate_fluorescence`. Attributes ---------- 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 :func:`generate_imaging_with_rois` (:func:`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: np.ndarray spikes: np.ndarray clean_traces: np.ndarray neuropil: np.ndarray | None = None
[docs] def generate_random_imaging( num_frames: int | tuple[int, ...] = 1000, height: int = 256, width: int = 256, num_planes: int = 1, sampling_frequency: float = 30.0, dtype: type = np.float32, seed: int | None = None, ) -> NumpyImaging: """Generate a random NumpyImaging object for testing. Parameters ---------- num_frames : int | tuple[int, ...], default: 1000 Number of frames for each epoch in the imaging data. height : int, default: 256 Height of each frame in pixels. width : int, default: 256 Width of each frame in pixels. sampling_frequency : float, default: 30.0 Sampling frequency in Hz. dtype : type, default: np.float32 Dtype of the generated video (``np.float32``/``np.float64``). Float32 halves memory with no precision cost -- nothing downstream reads above float32 precision anyway. Returns ------- NumpyImaging A NumpyImaging object containing the generated random imaging data. """ if isinstance(num_frames, int): num_frames = (num_frames,) rng = np.random.default_rng(seed) videos = [] for n_frames in num_frames: video = rng.random((n_frames, height, width, num_planes), dtype=dtype) videos.append(video) return NumpyImaging(imaging_series=videos, sampling_frequency=sampling_frequency)
[docs] def generate_rois( num_rois: int = 20, height: int = 256, width: int = 256, radius_range: tuple[int, int] | tuple[int, int, int] = (5, 15), sampling_frequency: float = 30.0, roi_ids: np.ndarray | None = None, weighted: bool = False, num_planes: int = 1, seed: int | None = None, sparse: bool = False, ) -> BaseRois: """Generate circular ROIs for testing. Parameters ---------- num_rois : int, default: 20 Number of ROIs to generate, by default 20 height : int, default: 256 Height of the imaging field, by default 256 width : int, default: 256 Width of the imaging field, by default 256 radius_range : tuple[int, int] | tuple[int, int, int], default: (5, 15) 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, default: 30. Sampling frequency, by default 30.0 roi_ids : np.ndarray | None, default: None Array of ROI IDs. If None, defaults to np.arange(num_rois) weighted : bool, default: False Whether to create weighted masks (values between 0 and 1) or binary masks (0 or 1), by default False num_planes : int, default: 1 Number of planes for the ROIs, by default 1 (2D masks). If >1, creates 3D masks. sparse : bool, default: False If True, return the masks as a sparse.GCXS array instead of a dense np.ndarray. """ if num_planes == 1: roi_masks = np.zeros((num_rois, height, width)) rng = np.random.default_rng(seed) else: roi_masks = np.zeros((num_rois, height, width, num_planes)) rng = np.random.default_rng(seed) if len(radius_range) == 2: depth_radius = max(1, num_planes // 2) else: depth_radius = radius_range[2] assert radius_range[0] < radius_range[1], "Invalid radius range" assert radius_range[1] < width - radius_range[1], "ROIs may not fit in the image with the given radius range" assert radius_range[1] < height - radius_range[1], "ROIs may not fit in the image with the given radius range" for roi_idx in range(num_rois): center_x = rng.integers(radius_range[1], width - radius_range[1]) center_y = rng.integers(radius_range[1], height - radius_range[1]) radius = rng.integers(radius_range[0], radius_range[1]) if num_planes == 1: y, x = np.ogrid[:height, :width] mask = (x - center_x) ** 2 + (y - center_y) ** 2 <= radius**2 if not weighted: roi_masks[roi_idx] = mask else: # Create a weighted mask with values decreasing from center to edge distance_from_center = np.sqrt((x - center_x) ** 2 + (y - center_y) ** 2) weighted_mask = np.clip(1 - (distance_from_center / radius), 0, 1) * mask roi_masks[roi_idx] = weighted_mask else: # Choose z-center so the ROI fits in depth; fall back to middle plane if too shallow if num_planes > 2 * depth_radius: center_z = rng.integers(depth_radius, num_planes - depth_radius) else: center_z = num_planes // 2 y, x, z = np.ogrid[:height, :width, :num_planes] # Ellipsoidal ROI: (dx^2+dy^2)/r^2 + dz^2/drz^2 <= 1 dx2_dy2 = (x - center_x) ** 2 + (y - center_y) ** 2 dz2 = (z - center_z) ** 2 ellipsoid_distance = np.sqrt((dx2_dy2 / (radius**2)) + (dz2 / (depth_radius**2))) mask = ellipsoid_distance <= 1 if not weighted: roi_masks[roi_idx] = mask else: weighted_mask = np.clip(1 - ellipsoid_distance, 0, 1) * mask roi_masks[roi_idx] = weighted_mask roi_ids = np.arange(num_rois) if roi_ids is None else roi_ids if sparse: import sparse as sparse_module # Compress along the ROI axis so per-ROI indexing (e.g. select_rois) stays fast -- # the default heuristic often picks a different axis, making it ~40x slower. roi_masks = sparse_module.GCXS.from_numpy(roi_masks, compressed_axes=(0,)) return NumpyRois(roi_image_masks=roi_masks, roi_ids=roi_ids, sampling_frequency=sampling_frequency)
# Internal constants for the "vignette" neuropil model (see `generate_imaging_with_rois`). _VIGNETTE_FALLOFF = 0.25 # fraction of center brightness lost at the frame corners _NEUROPIL_TAU_SECONDS = 5.0 # OU mean-reversion timescale -- slow drift, not frame-to-frame noise def _generate_vignette_profile(height: int, width: int, num_planes: int = 1) -> np.ndarray: """Static radial illumination falloff, brighter at the frame center than the edges. Simple linear falloff from the frame center -- real 2P vignetting (Gaussian beam, finite-NA lens falloff) isn't modeled exactly. Renormalized to spatial mean 1, so multiplying it into `background` preserves that parameter's "mean photon count per pixel per frame" semantics regardless of `neuropil_model`. Parameters ---------- height, width : int Frame dimensions in pixels. num_planes : int, default: 1 Number of imaging planes; the same 2D profile is broadcast across all planes. Returns ------- np.ndarray ``(height, width)`` or ``(height, width, num_planes)``, float32, spatial mean 1. """ y, x = np.ogrid[:height, :width] center_y, center_x = (height - 1) / 2.0, (width - 1) / 2.0 distance = np.sqrt((y - center_y) ** 2 + (x - center_x) ** 2) max_distance = np.sqrt(center_y**2 + center_x**2) profile = 1.0 - _VIGNETTE_FALLOFF * (distance / max_distance) profile = profile / profile.mean() if num_planes > 1: profile = np.broadcast_to(profile[:, :, np.newaxis], (height, width, num_planes)) return profile.astype(np.float32) def _generate_ou_process( num_frames: int, sampling_frequency: float, rng: np.random.Generator, num_traces: int = 1, ) -> np.ndarray: """Ornstein-Uhlenbeck-like fluctuation(s): exactly zero-mean per trace, asymptotically unit variance. Discrete-time AR(1), ``x[t] = phi * x[t-1] + sqrt(1 - phi**2) * white[t]`` with ``phi = exp(-1 / (_NEUROPIL_TAU_SECONDS * sampling_frequency))``, run through `lfilter`. It starts at 0 and reaches unit variance within a few `_NEUROPIL_TAU_SECONDS`; the brief initial transient is ignored. Each trace is then centered to exactly zero mean. Parameters ---------- num_frames : int Number of time points to generate. sampling_frequency : float Sampling frequency in Hz. rng : np.random.Generator Source of randomness. num_traces : int, default: 1 Number of independent traces to generate at once. Returns ------- np.ndarray ``(num_frames, num_traces)``, float32, each column exactly zero-mean. """ from scipy.signal import lfilter phi = np.exp(-1.0 / (_NEUROPIL_TAU_SECONDS * sampling_frequency)) white = rng.normal(0, 1, size=(num_frames, num_traces)).astype(np.float32) ou = lfilter([np.sqrt(1 - phi**2)], [1.0, -phi], white, axis=0) ou = ou - ou.mean(axis=0, keepdims=True) return ou.astype(np.float32)
[docs] def generate_imaging_with_rois( num_frames: int = 1000, height: int = 256, width: int = 256, num_planes: int = 1, num_rois: int = 20, radius_range: tuple[int, int] | tuple[int, int, int] = (5, 15), sampling_frequency: float = 30.0, decay_time: float = 0.5, event_rate: float = 0.3, weighted_rois: bool = False, background: float = 0.2, baseline_range: tuple[float, float] = (0.5, 1.0), noise_std: float | Literal["poisson"] = 1.3, bleaching_time: float = np.inf, seed: int | None = None, neuropil_model: Literal["constant", "vignette"] = "constant", neuropil_fluctuation_std: float = 0.5, neuropil_roi_coefficient: float | None = None, ) -> tuple[BaseRois, NumpyImaging, FluorescenceData]: """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, default: 1000 Number of frames in the imaging data. height : int, default: 256 Height of each frame in pixels. width : int, default: 256 Width of each frame in pixels. num_planes : int, default: 1 Number of imaging planes. num_rois : int, default: 20 Number of ROIs to generate. radius_range : tuple[int, int] | tuple[int, int, int], default: (5, 15) Range of radii for circular ROIs. sampling_frequency : float, default: 30.0 Sampling frequency in Hz. decay_time : float, default: 0.5 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, default: 0.3 Mean spike-event rate in Hz, passed through to :func:`generate_fluorescence`. Each ROI's number of events scales with the recording's duration (`num_frames` / `sampling_frequency`). weighted_rois : bool, default: False Whether to create weighted masks. background : float, default: 0.2 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], default: (0.5, 1.0) 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 : float or "poisson", default: 1.3 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, default: inf Time constant of multiplicative photobleaching in seconds, passed through to :func:`generate_fluorescence`. The default of ``inf`` means no photobleaching. seed : int | None, default: None Random seed for reproducibility. neuropil_model : {"constant", "vignette"}, default: "constant" 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, default: 0.5 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 or None, default: 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. 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 :func:`generate_fluorescence`, which leaves it ``None``) -- e.g. for comparison against values recovered from `imaging` via an :class:`~photon_mosaic.core.roianalyzer.RoiAnalyzer`. """ if neuropil_model not in ("constant", "vignette"): raise ValueError(f"Unknown neuropil_model: {neuropil_model!r}. Supported: 'constant', 'vignette'.") if neuropil_roi_coefficient is None: neuropil_roi_coefficient = 1.0 if neuropil_model == "constant" else 0.7 if neuropil_roi_coefficient < 0: raise ValueError(f"neuropil_roi_coefficient must be non-negative, got {neuropil_roi_coefficient}.") rng = np.random.default_rng(seed) imaging_seed = int(rng.integers(0, 2**31)) rois_seed = int(rng.integers(0, 2**31)) fluorescence_seed = int(rng.integers(0, 2**31)) noise_seed = int(rng.integers(0, 2**31)) roi_baseline = rng.uniform(baseline_range[0], baseline_range[1], size=num_rois) neuropil_seed = int(rng.integers(0, 2**31)) imaging = generate_random_imaging( num_frames=num_frames, height=height, width=width, num_planes=num_planes, sampling_frequency=sampling_frequency, seed=imaging_seed, ) rois = generate_rois( num_rois=num_rois, height=height, width=width, radius_range=radius_range, sampling_frequency=sampling_frequency, weighted=weighted_rois, num_planes=num_planes, seed=rois_seed, ) fluorescence = generate_fluorescence( num_frames=num_frames, num_rois=num_rois, sampling_frequency=sampling_frequency, decay_time=decay_time, event_rate=event_rate, bleaching_time=bleaching_time, seed=fluorescence_seed, ) # background bleaches too, so bleaching cancels out of the dF/F ratio instead of drifting. # (T, N) @ (N, H*W*P) -> (T, H*W*P) -> (T, H, W, P). video = imaging.epochs[0]._video masks = rois.get_roi_image_masks() # (N, H, W) or (N, H, W, P) masks_flat = masks.reshape((num_rois, -1)).astype(video.dtype) # roi_baseline is float64 by default; cast to video.dtype, or the matmul below (out=flat) # silently allocates a full movie-sized float64 temporary for the mixed-precision multiply. signal = (roi_baseline[np.newaxis, :] * fluorescence.traces).astype(video.dtype) # (T, N) bleach = np.exp(-np.arange(num_frames) / (bleaching_time * sampling_frequency), dtype=np.float32) # `video` is reused as scratch (about to be overwritten); background+noise are added slab by # slab to avoid a full (num_frames, height*width*num_planes) temporary for either. flat = video.reshape(num_frames, -1) np.matmul(signal, masks_flat, out=flat) neuropil_rng = np.random.default_rng(neuropil_seed) # Static spatial profile of the background; None means spatially uniform. profile_flat = None fluctuation = np.ones(num_frames) if neuropil_model == "vignette": profile_flat = _generate_vignette_profile(height, width, num_planes).reshape(-1).astype(video.dtype) fluctuation = 1.0 + neuropil_fluctuation_std * _generate_ou_process( num_frames, sampling_frequency, neuropil_rng ).reshape(-1) if neuropil_roi_coefficient != 1.0: if profile_flat is None: profile_flat = np.ones(masks_flat.shape[1], dtype=video.dtype) profile_flat[masks_flat.any(axis=0)] *= neuropil_roi_coefficient # Both backgrounds are a per-frame scalar times a nonnegative spatial profile, so Poisson's # clip to nonnegative acts on the scalar alone and the true background under each ROI's mask # (mask-weighted mean, before noise) stays closed-form -- it only needs the ROI masks, not the # full pixel grid. mask_sums = masks_flat.sum(axis=1) background_scale = background * bleach * fluctuation if noise_std == "poisson": background_scale = np.clip(background_scale, 0, None) if profile_flat is None: neuropil = np.broadcast_to(background_scale[:, np.newaxis], (num_frames, num_rois)).copy() else: roi_profile_avg = (masks_flat * profile_flat[np.newaxis, :]).sum(axis=1) / mask_sums neuropil = background_scale[:, np.newaxis] * roi_profile_avg[np.newaxis, :] noise_rng = np.random.default_rng(noise_seed) slab_size = 256 for t0 in range(0, num_frames, slab_size): sl = flat[t0 : t0 + slab_size] scale_sl = background_scale[t0 : t0 + slab_size, np.newaxis].astype(sl.dtype) sl += scale_sl if profile_flat is None else scale_sl * profile_flat[np.newaxis, :] if noise_std == "poisson": sl[:] = noise_rng.poisson(np.clip(sl, 0, None)) else: sl += noise_rng.normal(0, noise_std, sl.shape) fluorescence = fluorescence._replace(neuropil=neuropil.astype(np.float32)) rois.register_imaging(imaging) # Link the ROIs to the imaging data return rois, imaging, fluorescence
[docs] def generate_fluorescence( num_frames: int, num_rois: int = 1, sampling_frequency: float = 30.0, decay_time: float = 0.5, event_rate: float = 0.3, noise_std: float = 0.0, bleaching_time: float = np.inf, seed: int | None = None, ) -> FluorescenceData: """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, default: 1 Number of independent fluorescence traces to generate. sampling_frequency : float, default: 30.0 Sampling frequency in Hz. decay_time : float, default: 0.5 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, default: 0.3 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, default: 0.0 Standard deviation of additive Gaussian noise. 0 means no noise. bleaching_time : float, default: inf Time constant of multiplicative photobleaching in seconds. The default of ``inf`` means no photobleaching. seed : int | None, default: None Random seed for reproducibility. Returns ------- FluorescenceData See :class:`FluorescenceData` for field descriptions. """ from scipy.signal import lfilter rng = np.random.default_rng(seed) # Generate binary spike trains. Each event has unit amplitude, i.e. a single, isolated # spike produces a dF/F peak of 1 (100%); this is close to single-AP responses reported # for newer, high-sensitivity indicators like jGCaMP8m/8s (Zhang et al. 2023, Nature). spikes = np.zeros((num_frames, num_rois), dtype=np.float32) for roi_idx in range(num_rois): num_events = round(rng.uniform(0.5, 1.5) * event_rate * num_frames / sampling_frequency) num_events = min(max(num_events, 0), num_frames) event_times = rng.choice(num_frames, size=num_events, replace=False) spikes[event_times, roi_idx] = 1.0 # Convolve spikes with exponential kernel via exact IIR recurrence: traces[t] = spikes[t] + g * traces[t-1] g = np.exp(-1.0 / (decay_time * sampling_frequency)) clean_traces = lfilter([1.0], [1.0, -g], spikes, axis=0).astype(np.float32) # traces acts as F = (1 + dF/F) * F0(t), with F0 normalised to 1 at t=0; bleaching_time=inf # is exactly the no-bleaching limit, since bleach(t) = exp(-t / (inf * sf)) == 1 for all t. bleach = np.exp(-np.arange(num_frames) / (bleaching_time * sampling_frequency), dtype=np.float32) traces = (1.0 + clean_traces) * bleach[:, np.newaxis] if noise_std > 0: traces = traces + rng.normal(0, noise_std, (num_frames, num_rois)).astype(np.float32) return FluorescenceData(traces=traces, spikes=spikes, clean_traces=clean_traces)