SpotMAX AI parameters

Here you can find the description of the paramters required to configure and run the neural network models provided with SpotMAX.

You can set this paramaters from the GUI (see the Spots segmentation method parameter) or manually set them in the SpotMAX INI configuration file. At the end of this page, you can find an example of the INI configuration file with the AI parameters.

Model type

Model type to use for the prediction. The available models are: 2D and 3D. The default value is 2D. If you choose the 2D model and the input data is 3D z-stacks, then the prediction will be done slice by slice.

Type:: string 2D or 3D
Default:: 2D

Preprocess across experiment

This paramater has two different behaviours depending on how you are running the model. More details about preprocessing below.

If you are running the model as part of the entire SpotMAX workflow (from GUI or from the command line with the spotmax -p command) and you set this parameter to True, the model will run preprocessing across all Positions in each experiment folder. Setting this paramater to True will result in using the global minimum and maximum intensity values across all Positions in the experiment to normalize the images to the range [0, 1].

If you are running the model from the Python APIs and you set this parameter to True, the model will run preprocessing on all input images. If you set it to False, no preprocessing will be applied only if also Preprocess across timepoints is False.

Note

Preprocessing pipeline includes the following steps:

Morphological opening to remove hot pixels (isolated bright pixels). This step is applied only if Remove hot pixels is True.

Gaussian filter (smooth) using the sigma value defined in the Gaussian filter sigma parameter. This step is applied only if Gaussian filter sigma is greater than 0.0.

Normalization of the input images to the range [0, 1] using the minimum and maximum intensity values across the timepoints of each video (if Preprocess across timepoints is True) or using the global minimum and maximum intensity values across all Positions in the experiment (if Preprocess across experiment is True).

Type:: boolean
Default:: False

Preprocess across timepoints

This paramater has two different behaviours depending on how you are running the model. More details about preprocessing below.

If you are running the model as part of the entire SpotMAX workflow (from GUI or from the command line with the spotmax -p command) and you set this parameter to True, the model will run preprocessing across all timepoints of each loaded Position. Setting this paramater to True will result in using the minimum and maximum intensity values across the timepoints of each video to normalize the images to the range [0, 1].

If you are running the model from the Python APIs (using the Model class from spotmax.nnet.model) and you set this parameter to True, the model will run preprocessing on all input images (no matter if they are timepoints or not). If you set it to False, no preprocessing will be applied only if also Preprocess across experiment is False.

Note

See Preprocess across experiment parameter for more details about preprocessing.

Type:: boolean
Default:: True

Gaussian filter sigma

Sigma of the Gaussian filter (smoothing fitler) to apply to the input images. This can be a single float value or a sequence of three floats (z, y, x) to apply different sigmas in each direction.

If the input images are 2D, the sigma value in the z-direction will be ignored.

Default value is 0.0, which means no smoothing will be applied.

Type:: float or (z, y, x) sequence of floats
Default:: 0.0

Remove hot pixels (AI input)

If True, the model will apply a morphological opening filter to remove hot pixels (isolated bright pixels) from the input images.

Type:: boolean
Default:: False

Config YAML filepath

Path to the configuration file with the model parameters. This is created during training. The default value is spotmax/nnet/config.yaml, which are the pretrained models provided with SpotMAX.

View config file.

Type:: PathLike
Default:: spotmax/nnet/config.yaml

Threshold value

Threshold value to apply to the prediction map. The default value is 0.0, meaning that the value will be retrieved from the configuration file.

The value for the pre-trained 2D model is 0.9, and for the 3D model is 0.7.

Type:: float
Default:: 0.0

PhysicalSizeX

Physical size of a pixel in the x-direction in micrometers. This value is used in conjuction with the Resolution multiplier YX to calculate the scaling factor for the input images.

The scaling factor is used to resize the input images to the same pixel size of the training images.

The default value is 0.073, meaning that if Resolution multiplier YX is 1.0, and you are using the pretrained models, the input images will not be resized.

The scaling factor \(S_f\) is calculated as follows:

\[S_f = p_{input} \cdot \frac{1}{p_{training}} \cdot \frac{1}{r_{yx}}\]

where \(p_{input}\) is defined in the PhysicalSizeX parameter, \(p_{training}\) is the physical size of a pixel in the training images (defined in the configuration file at the base_pixel_size_nm), and \(r_{yx}\) is defined in the Resolution multiplier YX parameter.

Note that the same scaling factor is then used to rescale the model output to the original size of the input images.

Type:: float
Default:: 0.073

Resolution multiplier YX

Additional factor to reduce the scaling factor (see PhysicalSizeX for more information) when resizing the input images. Pass a value greater than 1.0 when you need to detect spots that are larger than the diffraction limit.

Default is 1.0

Type:: float
Default:: 1.0

Use GPU

If True, the model will use the GPU to run the prediction. Make sure you have a compatible GPU and the required libraries installed (e.g., NVIDIA GPU with PyTorch and CUDA drivers).

Type:: boolean
Default:: False

Save prediction map

If True, the model will either return the prediction map or save it as a NPZ file in the same directory as the input images.

The prediction map is returned when you are running the model from the Python APIs (using the Model.segment method from spotmax.nnet.model), while it is saved as a NPZ file when you are running the model as part of the entire SpotMAX workflow (from GUI or from the command line with the spotmax -p command).

Type:: boolean
Default:: False

Label components

If True, the output boolean masks will be converted to connected components using the skimage.measure.label function.

More information here.

Type:: boolean
Default:: False

Example of the INI configuration file with the AI parameters

[Spots channel]
Spots segmentation method = spotMAX AI

[neural_network.init.spots]
model_type = 3D
preprocess_across_experiment = False
preprocess_across_timepoints = True
gaussian_filter_sigma = 0.0
remove_hot_pixels = False
config_yaml_filepath = spotmax/nnet/config.yaml
threshold_value = 0.7
PhysicalSizeX = 0.073
resolution_multiplier_yx = 1.0
use_gpu = False
save_prediction_map = False
verbose = True

[neural_network.segment.spots]
label_components = False