Image simulation

Functions used to simulate spot images, in 2D and 3D.

Simulation is performed in three steps:

1. We simulate ground truth coordinates.

   • simfish.simulate_ground_truth()

2. From an empty frame we simulate a gaussian signal in every spot location.

   • simfish.add_spots()

3. We add an additive background noise in image if needed.

   • simfish.add_white_noise()

The full process can be run with:

• simfish.simulate_images()

• simfish.simulate_image()

simfish.simulate_ground_truth(ndim, n_spots, random_n_spots=False, n_clusters=0, random_n_clusters=False, n_spots_cluster=0, random_n_spots_cluster=False, centered_cluster=False, frame_shape=(128, 128), voxel_size=(100, 100), sigma=(150, 150), random_sigma=0.05, amplitude=5000, random_amplitude=0.05, probability_map=None)

Simulate ground truth information about the simulated spots like their coordinates, standard deviations and amplitude.

Parameters

ndim{2, 3}

Number of dimension to consider for the simulation.

n_spotsint

Expected number of spots to simulate.

random_n_spotsbool, default=False

Make the number of spots follow a Poisson distribution with expectation n_spots, instead of a constant predefined value.

n_clustersint

Expected number of clusters to simulate.

random_n_clustersbool, default=False

Make the number of clusters follow a Poisson distribution with expectation n_clusters, instead of a constant predefined value.

n_spots_clusterint

Expected number of spots to simulate per cluster.

random_n_spots_clusterbool, default=False

Make the number of spots follow a Poisson distribution with expectation n_spots_cluster, instead of a constant predefined value.

centered_clusterbool, default=False

Center the simulated cluster. Only used if one cluster is simulated.

frame_shapetuple or list, default=(128, 128)

Shape (z, y, x) or (y, x) of the image to simulate.

voxel_sizeint or float or tuple or list, default=(100, 100)

Size of a voxel, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions.

sigmaint or float or tuple or list, default=(150, 150)

Standard deviation of the spot, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions.

random_sigmaint or float, default=0.05

Sigmas follow a normal distribution around the provided sigma values. The scale used is:

\[\mbox{scale} = \mbox{sigma} * \mbox{random_sigma}\]

amplitudeint or float, default=5000

Intensity of the spot.

random_amplitudeint or float, default=0.05

Margin allowed around the amplitude value. The formula used is:

\[\mbox{margin} = \mbox{amplitude} * \mbox{random_amplitude}\]

probability_mapnp.ndarray, np.float32, optional

Probability map to sample spots coordinates with shape (z, y, x).

Returns

ground_truthnp.ndarray, np.float64

Ground truth array with shape (nb_spots, 6) or (nb_spots, 4). Columns are:

• Coordinate along the z axis (optional).

• Coordinate along the y axis.

• Coordinate along the x axis.

• Standard deviation of the spot along the z axis (optional).

• Standard deviation of the spot in the yx plan.

• Intensity of the spot.

simfish.add_spots(image, ground_truth, voxel_size, precomputed_gaussian=None)

Simulate gaussian spots based on the ground truth coordinates.

Parameters

imagenp.ndarray

Image with shape (z, y, x) or (y, x).

ground_truthnp.ndarray, np.float64

Ground truth array with shape (nb_spots, 6) or (nb_spots, 4). Columns are:

• Coordinate along the z axis (optional).

• Coordinate along the y axis.

• Coordinate along the x axis.

• Standard deviation of the spot along the z axis (optional).

• Standard deviation of the spot in the yx plan.

• Intensity of the spot.

voxel_sizeint or float or tuple or list

Size of a voxel, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions.

precomputed_gaussiansequence of array_like, optional

Sequence with tables of precomputed values for the erf, with shape (nb_value, 2). One table per dimension.

Returns

image_with_spotsnp.ndarray

A 3-d or 2-d image with simulated spots and shape (z, y, x) or (y, x).

simfish.add_white_noise(image, noise_level, random_noise=0.05)

Generate and add white noise to an image.

Parameters

imagenp.ndarray

Image with shape (z, y, x) or (y, x).

noise_levelint or float

Reference level of noise background to add in the image.

random_noiseint or float, default=0.05

Background noise follows a normal distribution around the provided noise values. The scale used is:

\[\mbox{scale} = \mbox{noise_level} * \mbox{random_noise}\]

Returns

noised_imagenp.ndarray

Noised image with shape (z, y, x) or (y, x).

simfish.simulate_images(n_images, ndim, n_spots, random_n_spots=False, n_clusters=0, random_n_clusters=False, n_spots_cluster=0, random_n_spots_cluster=False, centered_cluster=False, image_shape=(128, 128), image_dtype=<class 'numpy.uint16'>, subpixel_factors=None, voxel_size=(100, 100), sigma=(150, 150), random_sigma=0.05, amplitude=5000, random_amplitude=0.05, noise_level=300, random_noise=0.05)

Return a generator to simulate multiple ground truth coordinates and images of spots.

Parameters

n_imagesint

Number of images to simulate.

ndim{2, 3}

Number of dimension to consider for the simulation.

n_spotsint or tuple

Expected number of spots to simulate per image. If tuple, provide the minimum and maximum number of spots to simulate. Multiple images are simulated with a growing number of spots.

random_n_spotsbool, default=False

Make the number of spots follow a Poisson distribution with expectation n_spots, instead of a constant predefined value.

n_clustersint

Expected number of clusters to simulate.

random_n_clustersbool, default=False

Make the number of spots follow a Poisson distribution with expectation n_clusters, instead of a constant predefined value.

n_spots_clusterint

Expected number of spots per cluster to simulate.

random_n_spots_clusterbool, default=False

Make the number of spots follow a Poisson distribution with expectation n_spots_cluster, instead of a constant predefined value.

centered_clusterbool, default=False

Center the simulated cluster. Only used one cluster is simulated.

image_shapetuple or list, default=(128, 128)

Shape (z, y, x) or (y, x) of the images to simulate.

image_dtypedtype, default=np.uint16

Type of the image to simulate (np.uint8, np.uint16, np.float32 or np.float64).

subpixel_factorstuple or list, optional

Scaling factors to simulate images with subpixel accuracy. First a larger image is simulated, with larger spots, then we downscale it. One element per dimension. Can make the simulation much longer. If None, spots are localized at pixel level.

voxel_sizeint or float or tuple or list, default=(100, 100)

Size of a voxel, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions.

sigmaint or float or tuple or list, default=(150, 150)

Standard deviation of the spot, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions.

random_sigmaint or float, default=0.05

Sigmas follow a normal distribution around the provided sigma values. The scale used is:

\[\mbox{scale} = \mbox{sigma} * \mbox{random_sigma}\]

amplitudeint or float, default=5000

Intensity of the spot.

random_amplitudeint or float, default=0.05

Margin allowed around the amplitude value. The formula used is:

\[\mbox{margin} = \mbox{amplitude} * \mbox{random_amplitude}\]

noise_levelint or float, default=300

Reference level of noise background to add in the image.

random_noiseint or float

Background noise follows a normal distribution around the provided noise values. The scale used is:

\[\mbox{scale} = \mbox{noise_level} * \mbox{random_noise}\]

Returns

_Tuple generator

imagenp.ndarray

Simulated image with spots and shape (z, y, x) or (y, x).

ground_truthnp.ndarray, np.float64

Ground truth array with shape (nb_spots, 6) or (nb_spots, 4). Columns are:

• Coordinate along the z axis (optional).

• Coordinate along the y axis.

• Coordinate along the x axis.

• Standard deviation of the spot along the z axis (optional).

• Standard deviation of the spot in the yx plan.

• Intensity of the spot.

simfish.simulate_image(ndim, n_spots, random_n_spots=False, n_clusters=0, random_n_clusters=False, n_spots_cluster=0, random_n_spots_cluster=False, centered_cluster=False, image_shape=(128, 128), image_dtype=<class 'numpy.uint16'>, subpixel_factors=None, voxel_size=(100, 100), sigma=(150, 150), random_sigma=0.05, amplitude=5000, random_amplitude=0.05, noise_level=300, random_noise=0.05)

Simulate ground truth coordinates and image of spots.

Parameters

ndim{2, 3}

Number of dimension to consider for the simulation.

n_spotsint

Expected number of spots to simulate.

random_n_spotsbool, default=False

Make the number of spots follow a Poisson distribution with expectation n_spots, instead of a constant predefined value.

n_clustersint

Expected number of clusters to simulate.

random_n_clustersbool, default=False

Make the number of spots follow a Poisson distribution with expectation n_clusters, instead of a constant predefined value.

n_spots_clusterint

Expected number of spots per cluster to simulate.

random_n_spots_clusterbool, default=False

Make the number of spots follow a Poisson distribution with expectation n_spots_cluster, instead of a constant predefined value.

centered_clusterbool, default=False

Center the simulated cluster. Only used one cluster is simulated.

image_shapetuple or list, default=(128, 128)

Shape (z, y, x) or (y, x) of the image to simulate.

image_dtypedtype, default=np.uint16

Type of the image to simulate (np.uint8, np.uint16, np.float32 or np.float64).

subpixel_factorstuple or list, optional

Scaling factors to simulate an image with subpixel accuracy. First a larger image is simulated, with larger spots, then we downscale it. One element per dimension. Can make the simulation much longer. If None, spots are localized at pixel level.

voxel_sizeint or float or tuple or list, default=(100, 100)

Size of a voxel, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions.

sigmaint or float or tuple or list, default=(150, 150)

Standard deviation of the spot, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions.

random_sigmaint or float, default=0.05

Sigmas follow a normal distribution around the provided sigma values. The scale used is:

\[\mbox{scale} = \mbox{sigma} * \mbox{random_sigma}\]

amplitudeint or float, default=5000

Intensity of the spot.

random_amplitudeint or float, default=0.05

Margin allowed around the amplitude value. The formula used is:

\[\mbox{margin} = \mbox{amplitude} * \mbox{random_amplitude}\]

noise_levelint or float, default=300

Reference level of noise background to add in the image.

random_noiseint or float

Background noise follows a normal distribution around the provided noise values. The scale used is:

\[\mbox{scale} = \mbox{noise_level} * \mbox{random_noise}\]

Returns

imagenp.ndarray, np.uint

Simulated image with spots and shape (z, y, x) or (y, x).

ground_truthnp.ndarray

Ground truth array with shape (nb_spots, 6) or (nb_spots, 4):

• coordinate_z (optional)

• coordinate_y

• coordinate_x

• sigma_z (optional)

• sigma_yx

• amplitude