"""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)