All classes here are importable from the microsim.schema module.
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 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
+
+
+#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 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 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
+
+
+#CosemLabel
+
+
+#
+ Bases: _BaseDistribution
Renders ground truth based on a specific layer from a COSEM dataset.
+Go to https://openorganelle.janelia.org/datasets/ to find a dataset, and then +chose a label from the dataset to render.
+ + + + +Fluorophore
+
+
+#
+ Bases: SimBaseModel
FluorophoreDistribution
+
+
+#
+ Bases: SimBaseModel
__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 | +Description | +Default | +
|---|---|---|---|
type |
+
+ Literal[str]
+ |
+
+
+
+
+ |
+
+ 'matslines'
+ |
+
density |
+
+ float
+ |
+
+
+
+
+ |
+
+ 1
+ |
+
length |
+
+ int
+ |
+
+
+
+
+ |
+
+ 10
+ |
+
azimuth |
+
+ int
+ |
+
+
+
+
+ |
+
+ 10
+ |
+
max_r |
+
+ float
+ |
+
+
+
+
+ |
+
+ 0.9
+ |
+
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.
+ +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
+ |
+
Types used in the schema that may be used across categories.
+ + +microsim.schema.spectrum
+
+
+#Spectrum
+
+
+#
+ Bases: SimBaseModel
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
wavelength |
+
+ ndarray
+ |
+
+
+
+
+ |
+ + required + | +
intensity |
+
+ ndarray
+ |
+
+
+
+
+ |
+ + required + | +
scalar |
+
+ float
+ |
+
+
+
+
+ |
+
+ 1
+ |
+
get_overlapping_indices(ary1, ary2)
+
+#Return slices of overlapping subset of arrays.
+This assumes that the arrays are sorted 1d arrays.
+ +