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.
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()
#
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()
#
Return the emission rates for each fluorophore in each channel.
Returns a (C, F, W) array of 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.
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()
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 is set.
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.
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 | Description | 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 |
float
|
|
required |
coverslip_thickness |
float
|
|
required |
coverslip_thickness_spec |
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
|
cache_key()
#
Persistent identifier for the model.
Optical Configs#
Optical configurations define the filters and wavelengths used in the simulation.
microsim.schema.optical_config
#
LightSource
#
Bases: SimBaseModel
scaled_spectrum()
#
Return light source spectrum scaled to power, if present.
OpticalConfig
#
Bases: SimBaseModel
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.
filtered_emission_rate(fluorophore, detector_qe=None)
#
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
- the emission filter/beamsplitter spectra
- camera QE, if passed
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.
total_emission_rate(fluorophore)
#
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
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
#
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
#
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, em_rates, *args, **kwargs)
#
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.
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
#
Settings
#
Bases: SimBaseModel, BaseSettings
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
np_backend |
Literal[str, str, str, str, str]
|
|
'auto'
|
device |
Literal[str, str, str]
|
|
'auto'
|
float_dtype |
dtype[floating]
|
Floating-point precision to use for simulations. |
'float32'
|
random_seed |
int | None
|
|
2247253096
|
max_psf_radius_aus |
float | None
|
When simulating, restrict generated lateral PSF size to no more than this many Airy units. Decreasing this can dramatically speed up simulations, but will decrease accuracy. If |
8
|
cache |
CacheSettings
|
|
CacheSettings(read=True, write=True)
|
binning_strategy |
Literal[str, str]
|
The strategy to use for binning data. |
'equal_space'
|
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. |
4
|
spectral_bin_threshold_percentage |
float
|
Percentage of the total intensity to use as a threshold when binning the emission spectrum. 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. |
1
|
num_wavelength_bins |
int
|
Number of bins to use when discretizing the wavelength spectrum.It regards the wavelength range for illumination and excitation spectra.Increasing this will increase accuracy but also increase memory usage. |
32
|
min_wavelength |
int
|
Minimum wavelength to consider in the simulation.It is used to define the range of the wavelength spectrum when fluorophores are not defined. |
300
|
max_wavelength |
int
|
Maximum wavelength to consider in the simulation.It is used to define the range of the wavelength spectrum when fluorophores are not defined. |
800
|
Other Types#
Types used in the schema that may be used across categories.