API Reference#

All classes here are importable from the microsim.schema module.

Simulation#

The top level object is the Simulation object. This object contains all the information needed to run a simulation.

`microsim.schema.simulation` #

`Simulation` #

Bases: SimBaseModel

Top level Simulation object.

Parameters:

Name	Type	Default
`truth_space`	`ExtentScaleSpace \| ShapeExtentSpace \| ShapeScaleSpace \| DownscaledSpace \| UpscaledSpace`	required
`output_space`	`ExtentScaleSpace \| ShapeExtentSpace \| ShapeScaleSpace \| DownscaledSpace \| UpscaledSpace \| None`	`None`
`sample`	`Sample`	required
`modality`	`Confocal \| Widefield \| Identity`	`Widefield(type='widefield')`
`objective_lens`	`ObjectiveLens`	`ObjectiveLens(numerical_aperture=1.4, coverslip_ri=1.515, coverslip_ri_spec=1.515, immersion_medium_ri=1.515, immersion_medium_ri_spec=1.515, specimen_ri=1.47, working_distance_um=150.0, coverslip_thickness_um=170.0, coverslip_thickness_spec_um=170.0, magnification=1.0)`
`channels`	`list[OpticalConfig]`	[OpticalConfig(name='FITC', filters=[Bandpass(type='bandpass', name='', placement=<Placement.EX_PATH: 'EX'>, bandcenter=470.0, bandwidth=40.0, transmission=1.0, spectrum=Spectrum(wavelength=ndarray<shape=(500,) dtype=int64>, intensity=ndarray<shape=(500,) dtype=float64>, scalar=1.0)), Longpass(type='longpass', name='', placement=<Placement.BS: 'BS'>, cuton=495.0, slope=None, transmission=1.0, spectrum=Spectrum(wavelength=ndarray<shape=(500,) dtype=int64>, intensity=ndarray<shape=(500,) dtype=float64>, scalar=1.0)), Bandpass(type='bandpass', name='', placement=<Placement.EM_PATH: 'EM'>, bandcenter=525.0, bandwidth=50.0, transmission=1.0, spectrum=Spectrum(wavelength=ndarray<shape=(500,) dtype=int64>, intensity=ndarray<shape=(500,) dtype=float64>, scalar=1.0))], lights=[], detector=None, exposure_ms=None, power=None)]
`detector`	`CameraEMCCD \| CameraCMOS \| CameraCCD \| PMT \| HyD \| None`	`None`
`exposure_ms`	`float`	`100`
`settings`	`Settings`	`Settings(np_backend='auto', device='auto', float_dtype=dtype('float32'), random_seed=1701481050, max_psf_radius_aus='auto', cache=CacheSettings(read=True, write=True, in_mem_size=InMemoryCacheSizes(psf=64, otf_mb=1000.0)), spectral_bins_per_emission_channel=1, excitation_bin_width_nm=10.0, spectral_bin_threshold_percentage=1.0)`
`output_path`	`Annotated[Path, AfterValidator] \| None`	`None`

`digital_image(optical_image=None, *, exposure_ms=None, with_detector_noise=True)` #

Return the digital image as captured by the detector.

This down-scales the optical image to the output space, and simulates the detector response. The return array has dimensions (C, Z, Y, X). The units are gray values, based on the bit-depth of the detector. If there is no detector or with_detector_noise is False, the units are simply photons.

`emission_flux(*, saturate=True)` #

Return the spatial emission in photons per second (after emission filters).

This is the ground truth data multiplied by the filtered emission rates, prior to convolution with the PSF.

This multiplies the per-fluorophore emission rates by the ground truth data to get the total emission flux for each voxel in the ground truth. The return array has dimensions (C, F, Z, Y, X). The units are photons/s.

Note, this integrates over all wavelengths. For finer control over the emission spectrum, you may wish to directly combine filtered_emission_rates with the ground truth data as needed.

This function is NOT used by run(). It is provided as a convenience for debugging and analysis. See also optical_image_per_fluor, which is similar to this function, but returns the image after convolution with the PSF. That function may return a different result than simply convolving this function's output with a single PSF, as it more accurately models multi-wavelength emission spectra (as superposition of multiple PSFs).

`filtered_emission_rates(*, saturate=True)` #

Return the emission rates for each fluorophore in each channel.

Returns a (C, F, W) array of detected emission rates for each fluorophore in each channel, as a function of wavelength. The units are photons/s. The range of wavelengths will encompass the union of all the fluorophores' emission spectra, and the rates will be zero where the fluorophore does not emit.

These are the rates for a fluorophore at the reference illumination intensity (OpticalConfig.power): anywhere in a widefield field of view, or at the center of the excitation spot for point-scanning modalities (e.g. Confocal). If saturate is True (the default), excitation saturation at that intensity is applied.

Examples:

>>> sim = Simulation(...)
>>> rates = sim.filtered_emission_rates()
>>> rates.isel(c=0).plot.line(x='w') # plot emission of all fluors in channel 0
>>> plt.show()

`from_ground_truth(ground_truth, scale, **kwargs)` `classmethod` #

Shortcut to create a simulation directly from a ground truth array.

In this case, we bypass derive the truth_space and sample objects directly from a pre-calculated ground truth array. scale must also be provided as a tuple of floats, one for each dimension of the ground truth array.

`ground_truth()` #

Return the ground truth data.

Returns position and quantity of fluorophores in the sample. The return array has dimensions (F, Z, Y, X). The units are fluorophores counts.

Examples:

>>> sim = Simulation(...)
>>> truth = sim.ground_truth()
>>> truth.isel(f=0).max('z').plot()  # plot max projection of first fluorophore
>>> plt.show()

`model_copy(*, update=None, deep=False)` #

Copy the simulation, applying (and validating) any update fields.

Unlike pydantic's default, the updated simulation is validated as a whole (so relative spaces are re-resolved), and the cached ground truth is dropped.

`optical_image()` #

Return the optical image as delivered to the detector.

This is the same as optical_image_per_fluor, but sums the contributions of all fluorophores in each channel (which a detector would not know). The return array has dimensions (C, Z, Y, X). The units are photons/s.

`optical_image_per_fluor()` #

Return the optical image for each channel/fluorophore combination.

This is the emission from each fluorophore in each channel, after filtering by the optical configuration and convolution with the PSF.

The return array has dimensions (C, F, Z, Y, X). The units are photons/s.

`plot(transpose=False, legend=True)` #

Plot a summary of fluorophores and filters/configs used in the simulation.

Requires matplotlib.

As the number of channels increases, the plot may become crowded. In this case, consider setting transpose=True to plot channels on the x-axis and fluorophores on the y-axis.

`run()` #

Run the complete simulation and return the result.

This will also write a file to disk if output_path is set.

`run_batch(samples)` #

Run this simulation once per sample, yielding each result.

Everything but the sample is shared, so PSFs and emission rates are computed once and reused (see Settings.cache.in_mem_size). Each sample gets its own random seed (derived from settings.random_seed, so batches are reproducible), and if output_path is set, result i is written to <stem>_<i>.<suffix>.

Examples:

>>> images = list(sim.run_batch(samples))
>>> stacked = xr.concat(images, dim="s")  # if all samples share a shape

Spaces#

Spaces define the shape and scale of various spaces in the simulation. They can be defined in many different ways, but they all either directly declare or calculate the shape, scale, extent and axes names of the space in which the simulation is run.

For example, you might define the ground truth fluorophore distribution in a highly sampled space, and then downscale the resulting simulation to a realistic microscope image sampling.

from microsim import Simulation
import microsim.schema as ms

Simulation(
    # ground truth with z-step 20nm and XY pixel size 10nm
    truth_space=ms.ShapeScaleSpace(shape=(256, 1024, 1024), scale=(0.02, 0.01, 0.01)),
    # downscale output to 160nm x 80nm x 80nm pixels with shape (32, 128, 128)
    output_space=ms.DownscaledSpace(downscale=8),
    sample=ms.Sample(labels=[]),  # ...
)

If one of the spaces is defined using a relative space such as DownscaledSpace, the other must be an absolute space such as ShapeScaleSpace.

`microsim.schema.space` #

`DownscaledSpace` #

Bases: _RelativeSpace

Parameters:

Name	Type	Description	Default
`downscale`	`tuple[int, ...] \| int`		required

`ExtentScaleSpace` #

Bases: _AxesSpace

Parameters:

Name	Type	Description	Default
`extent`	`tuple[float, ...]`		required
`scale`	`tuple[float, ...]`		required

`ShapeExtentSpace` #

Bases: _AxesSpace

Parameters:

Name	Type	Description	Default
`shape`	`tuple[int, ...]`		required
`extent`	`tuple[float, ...]`		required

`ShapeScaleSpace` #

Bases: _AxesSpace

Parameters:

Name	Type	Description	Default
`shape`	`tuple[int, ...]`		required
`scale`	`tuple[float, ...]`		`()`

`UpscaledSpace` #

Bases: _RelativeSpace

Parameters:

Name	Type	Description	Default
`upscale`	`tuple[float, ...] \| int`		required

Objective Lens#

Properties of the objective lens used in the simulation. Will help to determine the PSF and other optical properties of the simulation.

`microsim.schema.lens` #

`ObjectiveKwargs` #

Bases: TypedDict

Parameters:

Name	Type	Default
`numerical_aperture`	`float`	required
`coverslip_ri`	`float`	required
`coverslip_ri_spec`	`float`	required
`immersion_medium_ri`	`float`	required
`immersion_medium_ri_spec`	`float`	required
`specimen_ri`	`float`	required
`working_distance_um`	`float`	required
`coverslip_thickness_um`	`float`	required
`coverslip_thickness_spec_um`	`float`	required
`magnification`	`float`	required

`ObjectiveLens` #

Bases: SimBaseModel

Parameters:

Name	Type	Description	Default
`numerical_aperture`	`float`		`1.4`
`coverslip_ri`	`float`		`1.515`
`coverslip_ri_spec`	`float`		`1.515`
`immersion_medium_ri`	`float`		`1.515`
`immersion_medium_ri_spec`	`float`		`1.515`
`specimen_ri`	`float`		`1.47`
`working_distance_um`	`float`		`150.0`
`coverslip_thickness_um`	`float`		`170.0`
`coverslip_thickness_spec_um`	`float`		`170.0`
`magnification`	`float`	magnification of objective lens.	`1`

`collection_efficiency: float` `property` #

Fraction of isotropic emission collected by the objective (solid angle).

`cache_key()` #

Persistent identifier for the model.

Optical Configs#

Optical configurations define the filters and wavelengths used in the simulation.

`microsim.schema.optical_config` #

`Bandpass` #

Bases: _FilterBase

Parameters:

Name	Type	Default
`type`	`Literal['bandpass']`	`'bandpass'`
`bandcenter`	`float`	required
`bandwidth`	`float`	required
`transmission`	`float`	`1.0`

`ChannelFluorescence` `dataclass` #

How bright one fluorophore is in one channel, and at which wavelengths.

This has no spatial information: it describes a single fluorophore at the reference illumination intensity (OpticalConfig.power), which is the intensity everywhere in a widefield field of view, or at the center of a focused spot. The rates are given with or without saturation at that intensity: modalities that don't illuminate evenly (e.g. confocal) apply saturation locally instead.

Modalities receive one of these for each channel and fluorophore in render().

Parameters:

Name	Type	Default
`channel`	`str`	required
`fluorophore`	`str`	required
`absorption_rate`	`str`	required
`detected_fraction`	`str`	required

Attributes:

Name	Type	Description
`channel`	`OpticalConfig`	The channel (light sources, filters).
`fluorophore`	`Fluorophore`	The fluorophore.
`absorption_rate`	`DataArray`	Photons absorbed per second by one fluorophore, at each excitation wavelength.
`detected_fraction`	`DataArray`	Photons detected per photon absorbed, at each emission wavelength: quantum yield x emission spectrum x emission filters x detector QE x the fraction of emitted light collected by the objective.

`saturation: float` `property` #

How strongly the fluorophore is saturated at the reference intensity.

This is the (unsaturated) absorption rate times the excited-state lifetime (0 if the lifetime is unknown): I / I_sat for a two-level system. Emission is reduced by a factor of 1 + saturation relative to a linear response: at 1, a fluorophore emits half as much as it would without saturation.

`create(channel, fluorophore, objective, detector=None)` `classmethod` #

Describe fluorophore in channel.

`detected_rate(*, saturate=True)` #

Photons detected per second from one fluorophore (all wavelengths).

If saturate is True, saturation at the reference intensity is applied.

`detected_spectrum(*, saturate=True)` #

Photons detected per second from one fluorophore, at each wavelength.

If saturate is True, saturation at the reference intensity is applied.

`from_channel(channel, fluorophore, detector_qe=None)` `classmethod` #

Describe fluorophore in channel, ignoring the objective.

Unlike create, the detected fraction doesn't include the fraction of emitted light collected by the objective.

`total_absorption_rate(*, saturate=True)` #

Photons absorbed per second by one fluorophore (all wavelengths).

If saturate is True, saturation at the reference intensity is applied: a saturated fluorophore spends more time in the excited state, where it can't absorb.

`LightSource` #

Bases: SimBaseModel

Parameters:

Name	Type	Default
`name`	`str`	`''`
`spectrum`	`Spectrum`	required
`power`	`float \| None`	`None`

`scaled_spectrum()` #

Return light source spectrum scaled to power, if present.

`Longpass` #

Bases: _FilterBase

Parameters:

Name	Type	Default
`type`	`Literal['longpass']`	`'longpass'`
`placement`	`Placement`	`<Placement.EM_PATH: 'EM'>`
`cuton`	`float`	required
`slope`	`float \| None`	`None`
`transmission`	`float`	`1.0`

`OpticalConfig` #

Bases: SimBaseModel

Parameters:

Name	Type	Default
`name`	`str`	`''`
`filters`	`list[Union[Bandpass, Shortpass, Longpass, SpectrumFilter]]`	`[]`
`lights`	`list[LightSource]`	`[]`
`detector`	`CameraEMCCD \| CameraCMOS \| CameraCCD \| PMT \| HyD \| None`	`None`
`exposure_ms`	`float \| None`	`None`
`power`	`float \| None`	`None`

`emission: Filter | None` `property` #

Combine all emission filters into a single spectrum.

`excitation: Filter | None` `property` #

Combine all excitation filters into a single spectrum.

`illumination: Spectrum | None` `property` #

Return the combined illumination spectrum.

This represents the spectrum of light source and all of the filters in the excitation path. If there are multiple light sources, they are combined. Different light sources can have different powers. In that case light sources are scaled by the respective light powers.

`illumination_flux_density: xr.DataArray` `property` #

Return the illumination flux density in photons/cm^2/s.

This is a measure of the number of photons per unit area per second in the excitation path of this optical configuration. It converts irradiance (W/cm^2) to photons/cm^2/s using the energy of a photon.

`irradiance: xr.DataArray` `property` #

Return the illumination irradiance in W/cm^2.

This scales the illumination spectrum to power. It is a measure of the power per unit area of the excitation path of this optical configuration, in W/cm^2, as a function of wavelength.

`absorption_rate(fluorophore)` #

Return the absorption rate of a fluorophore with this configuration.

The absorption rate is the number of photons absorbed per second per fluorophore, as a function of wavelength. It's a vector with a single axis W, and singleton dimensions F and C.

`all_spectra()` #

Return a DataArray with all spectra in this configuration.

`detected_fraction(fluorophore, detector_qe=None)` #

Return the fraction of absorbed photons that are detected in this channel.

This is the number of photons detected per photon absorbed by fluorophore, as a function of emission wavelength: the quantum yield, times the emission spectrum (normalized to an area of 1), times the transmission of the emission filters and the detector QE. It does not include the fraction of emitted light collected by the objective (see ObjectiveLens.collection_efficiency).

`emission_band_center()` #

Center wavelength of the emission filter passband.

This is the midpoint of the band where transmission is above half its peak (as in filter names, e.g. 525/50), combining all filters in the emission path. If they pass several bands, the one transmitting the most light is used, and transmission beyond 900 nm (e.g. near-infrared leaks) is ignored. Returns None if there are no emission filters, or if the band is open-ended: e.g. a longpass filter, still transmitting at the end of its spectrum. (A spectrum that only covers a narrow passband is fine: beyond its data, transmission is 0.)

`filtered_emission_rate(fluorophore, detector_qe=None, *, saturate=True)` #

Return the emission rate of a fluorophore with this config, after filters.

The emission rate is the number of photons emitted per second per fluorophore, as a function of wavelength, after being excited by this optical config, then passing through the emission path of this config. It's a vector with a single axis W, and singleton dimensions F and C.

This is the complete picture of the treatment of a specific fluorophore with this optical configuration. It takes into account:

- the excitation spectrum and extinction coefficient of the fluorophore
- the excitation filter/beamsplitter and light source spectra
- the quantum yield and emission spectrum of the fluorophore
- excitation saturation (unless `saturate` is False)
- the emission filter/beamsplitter spectra
- detector QE: `detector_qe`, or else this config's detector's QE

It does not include the fraction of emitted light collected by the objective (see Simulation.filtered_emission_rates, which does).

`plot_emission(ax=None, detector_qe=None)` #

Plot all components of the emission path.

`plot_excitation(ax=None)` #

Plot all components of the excitation path.

`saturation_parameter(fluorophore)` #

Return k * tau: absorption rate relative to the excited-state decay rate.

This is I / I_sat for a two-level system. Returns 0 if the fluorophore lifetime is unknown. See ChannelFluorescence.saturation.

`total_emission_rate(fluorophore, *, saturate=True)` #

Return the emission rate of a fluorophore with this configuration.

The emission rate is the total number of photons emitted per second per fluorophore, as a function of wavelength, prior to any filtering in the emission path. It's a vector with a single axis W, and singleton dimensions F and C. If saturate is True, excitation saturation is applied.

`Shortpass` #

Bases: _FilterBase

Parameters:

Name	Type	Default
`type`	`Literal['shortpass']`	`'shortpass'`
`placement`	`Placement`	`<Placement.EX_PATH: 'EX'>`
`cutoff`	`float`	required
`slope`	`float \| None`	`None`
`transmission`	`float`	`1.0`

`SpectrumFilter` #

Bases: _FilterBase

Parameters:

Name	Type	Description	Default
`type`	`Literal['spectrum']`		`'spectrum'`
`transmission`	`Spectrum`		required

Samples#

Samples define the distribution and properties of fluorophores in the simulation. A Sample is a set of labels, each of which is a combination of a Fluorophore and a FluorophoreDistribution.

The FluorophoreDistribution is the primary object that determines what the sample will look like.

`microsim.schema.sample` #

`BaseDistribution` #

Bases: BaseModel, ABC

`cache_path()` #

Return a tuple of strings that uniquely identify this distribution.

This may be used to determine a cache location for ground truths generated by this distribution. If None is returned, no caching will be performed.

`is_random()` `classmethod` #

Return True if this distribution generates randomized results.

`render(space, xp=None)` `abstractmethod` #

Render the distribution into the given space.

`Fluorophore` #

Bases: SimBaseModel

Parameters:

Name	Type	Default
`name`	`str`	required
`excitation_spectrum`	`Spectrum`	required
`emission_spectrum`	`Spectrum`	required
`bleaching_half_life_s`	`float \| None`	`None`
`extinction_coefficient`	`float \| None`	`None`
`quantum_yield`	`float \| None`	`None`
`lifetime_ns`	`float \| None`	`None`

`absorption_cross_section: xr.DataArray` `property` #

Return the absorption cross section in cm^2.

`emission_per_absorbed_photon: xr.DataArray` `property` #

Photons emitted per absorbed photon, at each wavelength.

The emission spectrum (normalized to an area of 1) times the quantum yield.

`all_spectra()` #

Return a DataArray with both excitation and emission spectra.

`FluorophoreDistribution` #

Bases: SimBaseModel

Parameters:

Name	Type	Default
`distribution`	`MatsLines \| CosemLabel \| FixedArrayTruth \| Annotated[Renderable, _IsInstanceAnySer]`	required
`fluorophore`	`Fluorophore`	`Fluorophore(name='mockFluorophore', excitation_spectrum=Spectrum(wavelength=ndarray<shape=(500,) dtype=int64>, intensity=ndarray<shape=(500,) dtype=int64>, scalar=1.0), emission_spectrum=Spectrum(wavelength=ndarray<shape=(500,) dtype=int64>, intensity=ndarray<shape=(500,) dtype=int64>, scalar=1.0), bleaching_half_life_s=None, extinction_coefficient=50000.0, quantum_yield=1.0, lifetime_ns=1.0)`
`concentration`	`float \| Callable[list, DataArray] \| None`	`None`

`str()` #

Return a string representation of the fluorophore distribution.

`from_array(array)` `classmethod` #

Create a FluorophoreDistribution from a fixed array.

`render(space, xp=None)` #

Render the fluorophore distribution into the given space.

`MatsLines` #

Bases: BaseDistribution

Parameters:

Name	Type	Default
`type`	`Literal['matslines']`	`'matslines'`
`density`	`float`	`1`
`length`	`int`	`10`
`azimuth`	`int`	`10`
`max_r`	`float`	`0.9`

`Sample` #

Bases: SimBaseModel

Parameters:

Name	Type	Description	Default
`labels`	`list[FluorophoreDistribution]`		required

Modality#

Modalities define the imaging modality used in the simulation, such as "widefield", "confocal", "3D-SIM", etc. This object has a lot of control over how other parts of the simulation are combined to render the final image.

`microsim.schema.modality` #

`Confocal` #

Bases: _PSFModality

Point-scanning confocal.

The PSF is the probability that a photon emitted by a fluorophore at a given position (relative to the scan spot) passes the pinhole, times the relative excitation intensity there. The channel's power (OpticalConfig.power, in W/cm^2) is therefore interpreted as the peak irradiance at the focus, and exposure_ms as the per-pixel integration (dwell) time (it is not divided by the number of pixels). The excitation spot is computed at the excitation wavelengths, and excitation saturation is applied locally (it is strongest at the center of the spot).

Parameters:

Name	Type	Description	Default
`type`	`Literal['confocal']`		`'confocal'`
`pinhole_au`	`float`		`1`
`airy_unit_wavelength_nm`	`float \| None`	Wavelength (nm) at which `pinhole_au` is defined. By default, 1 AU is matched to the center of each channel's emission filter band.	`None`

`Identity` #

Bases: _PSFModality

Optical modality in which PSF is not applied.

The idea is to use this modality when the ground truth flurophore distribution is generated from a light micorscope image, i.e., the PSF convolution is already applied on the image. This is useful primarily when you are more interested in the spectral properties (fluorophores, filters, bleedthrough, etc.) than the spatial properties (PSF, modality, etc.) in the simulation.

`render(truth, fluorescence, objective_lens, settings, xp)` #

Render a 3D image of the truth for F fluorophores, in C channels.

In this case we don't apply the PSF convolution, as the truth is assumed to be already convolved with the PSF. Therefore, we simply compute the emission flux for each fluorophore and each channel.

`Widefield` #

Bases: _PSFModality

Parameters:

Name	Type	Description	Default
`type`	`Literal['widefield']`		`'widefield'`

Settings#

Various global settings for the simulation, such as the calculation backend (numpy, cupy, jax, etc...) and an optional random seed, which can be used to reproduce the same simulation multiple times.

Note that all of these settings can also be defined using environment variables prefixed with MICROSIM_. For example, to globally disallow caching, you can set MICROSIM_CACHE=0. Nested settings can be defined using __ as a separator, such as MICROSIM_CACHE__WRITE=0, which would disable writing to the cache (but still allow reading).

`microsim.schema.settings` #

`CacheSettings` #

Bases: SimBaseModel

Parameters:

Name	Type	Default
`read`	`bool`	`True`
`write`	`bool`	`True`
`in_mem_size`	`InMemoryCacheSizes`	`InMemoryCacheSizes(psf=64, otf_mb=1000.0)`

`InMemoryCacheSizes` #

Bases: SimBaseModel

Parameters that control the in-memory cache size of various cached functions.

Parameters:

Name	Type	Description	Default
`psf`	`int`	The maximum number of PSFs that will be stored in the in-memory cache, which follows the LRU caching strategy. Note, this setting will only take effect by modifying the equivalent environment variable prior to importing microsim.	`64`
`otf_mb`	`float`	The maximum total size (in MB) of Fourier-transformed PSFs that will be kept in memory (LRU) for reuse across simulations with the same optics. Set to 0 to disable. Unaffected by `cache.read`/`cache.write`, which control on-disk caching. For GPU backends, this is GPU memory.	`1000`

`Settings` #

Bases: SimBaseModel, BaseSettings

Parameters:

Name	Type	Description	Default
`np_backend`	`Literal['numpy', 'torch', 'jax', 'cupy', 'auto']`		`'auto'`
`device`	`Literal['cpu', 'gpu', 'auto']`		`'auto'`
`float_dtype`	`dtype[floating]`	Floating-point precision to use for simulations.	`'float32'`
`random_seed`	`int \| None`		`1886584170`
`max_psf_radius_aus`	`float \| Literal['auto'] \| None`	Restrict the lateral radius of simulated PSFs to this many Airy units. `'auto'` (default) is our opinionated balance between speed and accuracy, aiming for ~1% RMSE (and <2% max error) relative to an untruncated PSF, which is below shot noise unless pixels collect well over ~10^4 photons. For widefield, the radius grows with the depth of the simulated volume, since out-of-focus light spreads in a cone of half-angle asin(NA/n): it is ~14 AU (for the tails of the in-focus Airy pattern) plus half the radius of that cone at half the volume depth (e.g. ~17 AU for a 1 um deep volume, ~27 AU for 5 um, at NA 1.4). For confocal, where the pinhole rejects out-of-focus light, it is 8 AU. A number sets the radius directly; a too-small radius loses out-of-focus light (in a 5 um deep widefield volume, 8 AU loses ~20% of it). `None` uses the full extent of the simulated space (most accurate, but much slower for large volumes: ~2-4x slower per sample than 'auto' at 2048x2048 pixels). The PSF is never larger than the simulated space.	`'auto'`
`cache`	`CacheSettings`		`CacheSettings(read=True, write=True, in_mem_size=InMemoryCacheSizes(psf=64, otf_mb=1000.0))`
`spectral_bins_per_emission_channel`	`int`	Number of wavelengths to use (per channel) when simulating the optical image. By default, a single centroid wavelength is used to approximatethe emission wavelength. Increasing this will make the simulation more realistic, by superposing multiple different PSFs, but will also increase memory usage and time.	`1`
`excitation_bin_width_nm`	`float`	Maximum width (nm) of the wavelength bins used to represent the excitation light absorbed by each fluorophore, for modalities that focus the excitation (e.g. confocal). Each bin uses a separate excitation spot, so laser lines further apart than this are always simulated separately.	`10`
`spectral_bin_threshold_percentage`	`float`	Percentage of the peak intensity to use as a threshold when binning the emission (and excitation) spectra. This is used to determine the range of wavelengths to consider when simulating the optical image. First, the spectrum is trimmed to include only relevant wavelengths (those with intensity above this threshold). Then, the spectrum is discretized into spectral_bins_per_emission_channel bins (or, for excitation, bins of at most excitation_bin_width_nm).	`1`

Other Types#

Types used in the schema that may be used across categories.

`microsim.schema.spectrum` #

`Spectrum` #

Bases: SimBaseModel

Parameters:

Name	Type	Default
`wavelength`	`ndarray`	required
`intensity`	`ndarray`	required
`scalar`	`float`	`1`

`max_intensity: float` `property` #

Maximum intensity.

`peak_wavelength: float` `property` #

Wavelength corresponding to maximum intensity.

`at(wavelength)` #

Return the intensity at wavelength (nm).

Values between samples are linearly interpolated; outside the range of this spectrum, the intensity is 0.

`transmitted(transmission)` #

Return this (light) spectrum after passing through transmission.

Unlike self * transmission, the result keeps this spectrum's wavelengths (e.g. a laser line stays a laser line), and transmission is interpolated.

`get_overlapping_indices(ary1, ary2)` #

Return slices of overlapping subset of arrays.

This assumes that the arrays are sorted 1d arrays.

API Reference#

Simulation#

microsim.schema.simulation #

Simulation #

digital_image(optical_image=None, *, exposure_ms=None, with_detector_noise=True) #

emission_flux(*, saturate=True) #

filtered_emission_rates(*, saturate=True) #

from_ground_truth(ground_truth, scale, **kwargs) classmethod #

ground_truth() #

model_copy(*, update=None, deep=False) #

optical_image() #

optical_image_per_fluor() #

plot(transpose=False, legend=True) #

run() #

run_batch(samples) #

Spaces#

microsim.schema.space #

DownscaledSpace #

ExtentScaleSpace #

ShapeExtentSpace #

ShapeScaleSpace #

UpscaledSpace #

Objective Lens#

microsim.schema.lens #

ObjectiveKwargs #

ObjectiveLens #

collection_efficiency: float property #

cache_key() #

Optical Configs#

microsim.schema.optical_config #

Bandpass #

ChannelFluorescence dataclass #

saturation: float property #

create(channel, fluorophore, objective, detector=None) classmethod #

detected_rate(*, saturate=True) #

detected_spectrum(*, saturate=True) #

from_channel(channel, fluorophore, detector_qe=None) classmethod #

total_absorption_rate(*, saturate=True) #

LightSource #

scaled_spectrum() #

Longpass #

OpticalConfig #

emission: Filter | None property #

excitation: Filter | None property #

illumination: Spectrum | None property #

illumination_flux_density: xr.DataArray property #

irradiance: xr.DataArray property #

absorption_rate(fluorophore) #

all_spectra() #

detected_fraction(fluorophore, detector_qe=None) #

emission_band_center() #

filtered_emission_rate(fluorophore, detector_qe=None, *, saturate=True) #

plot_emission(ax=None, detector_qe=None) #

plot_excitation(ax=None) #

saturation_parameter(fluorophore) #

total_emission_rate(fluorophore, *, saturate=True) #

Shortpass #

SpectrumFilter #

Samples#

microsim.schema.sample #

BaseDistribution #

cache_path() #

is_random() classmethod #

render(space, xp=None) abstractmethod #

Fluorophore #

absorption_cross_section: xr.DataArray property #

emission_per_absorbed_photon: xr.DataArray property #

all_spectra() #

FluorophoreDistribution #

__str__() #

from_array(array) classmethod #

render(space, xp=None) #

MatsLines #

Sample #

Modality#

microsim.schema.modality #

Confocal #

Identity #

render(truth, fluorescence, objective_lens, settings, xp) #

Widefield #

`microsim.schema.simulation` #

`Simulation` #

`digital_image(optical_image=None, *, exposure_ms=None, with_detector_noise=True)` #

`emission_flux(*, saturate=True)` #

`filtered_emission_rates(*, saturate=True)` #

`from_ground_truth(ground_truth, scale, **kwargs)` `classmethod` #

`ground_truth()` #

`model_copy(*, update=None, deep=False)` #

`optical_image()` #

`optical_image_per_fluor()` #

`plot(transpose=False, legend=True)` #

`run()` #

`run_batch(samples)` #

`microsim.schema.space` #

`DownscaledSpace` #

`ExtentScaleSpace` #

`ShapeExtentSpace` #

`ShapeScaleSpace` #

`UpscaledSpace` #

`microsim.schema.lens` #

`ObjectiveKwargs` #

`ObjectiveLens` #

`collection_efficiency: float` `property` #

`cache_key()` #

`microsim.schema.optical_config` #

`Bandpass` #

`ChannelFluorescence` `dataclass` #

`saturation: float` `property` #

`create(channel, fluorophore, objective, detector=None)` `classmethod` #

`detected_rate(*, saturate=True)` #

`detected_spectrum(*, saturate=True)` #

`from_channel(channel, fluorophore, detector_qe=None)` `classmethod` #

`total_absorption_rate(*, saturate=True)` #

`LightSource` #

`scaled_spectrum()` #

`Longpass` #

`OpticalConfig` #

`emission: Filter | None` `property` #

`excitation: Filter | None` `property` #

`illumination: Spectrum | None` `property` #

`illumination_flux_density: xr.DataArray` `property` #

`irradiance: xr.DataArray` `property` #

`absorption_rate(fluorophore)` #

`all_spectra()` #

`detected_fraction(fluorophore, detector_qe=None)` #

`emission_band_center()` #

`filtered_emission_rate(fluorophore, detector_qe=None, *, saturate=True)` #

`plot_emission(ax=None, detector_qe=None)` #

`plot_excitation(ax=None)` #

`saturation_parameter(fluorophore)` #

`total_emission_rate(fluorophore, *, saturate=True)` #

`Shortpass` #

`SpectrumFilter` #

`microsim.schema.sample` #

`BaseDistribution` #

`cache_path()` #

`is_random()` `classmethod` #

`render(space, xp=None)` `abstractmethod` #

`Fluorophore` #

`absorption_cross_section: xr.DataArray` `property` #

`emission_per_absorbed_photon: xr.DataArray` `property` #

`all_spectra()` #

`FluorophoreDistribution` #

`str()` #

`from_array(array)` `classmethod` #

`render(space, xp=None)` #

`MatsLines` #

`Sample` #

`microsim.schema.modality` #

`Confocal` #

`Identity` #

`render(truth, fluorescence, objective_lens, settings, xp)` #

`Widefield` #

`microsim.schema.settings` #

`CacheSettings` #

`InMemoryCacheSizes` #

`Settings` #

`microsim.schema.spectrum` #

`Spectrum` #

`max_intensity: float` `property` #