Wiki
Clone wikiSMolPhot Software / User manual
Table of Contents
Getting started
The following instructions guide you throught the installation of SMolPhot software on a Windows computer. Step by step instructions are also given for calculating the molecule positions and saving the result.
Download and install
Download and run the SMolPhot installer.
Get the example files
Download and unpack the example files.
These contain example datasets and configurations.
Run
Run the SMolPhot software from Start menu.
Load dataset
Click the "Open" icon or select "File > Open" to load a dataset. Locate a dataset from the example directory. For example you can use "\example\datasets\MT0.N2.LD\3D-AS\3D-AS.yml".
Load configuration
Click the "Load configuration" icon or select "Config > Load" config to load a corresponding configuration file. For example you can use "\example\configs\MT0.N2.LD-3D-AS.yaml".
Axial calibration
Select the "Axial calibration" tab.
Click on the "Calibrate" button to do the axial calibration.
View frames
You can view individual frames by selecting the "Frames" tab. Use left and right arrow keys to cycle through frames.
Calculate molecule positions
Select the "Hi-res image" tab.
Click on the "Process frames" button to calculate molecule positions and view the result.
Save result
Click on the "Save" button in the "Hi-res image" tab to save the results to a csv file.
Description of Graphical User Interface
The software has two main frames: the left one is organized into four tabs (Info, Axial calibration, Frames, Hi-res image) and right (Parameter) displays the actual parameter settings used for localizations.
Info tab
Info tab shows all the information about the image sequence loaded into application. The program requires two parameters: pixelSize and totalGain to be present.
Axial calibration
Axial molecular position is estimated from astigmatism introduced by a cylindrical lens or by using natural astigmatism of objective. In order to do the calibration the dataset consisting of fluorescence images from fluorobead as a function of known axial depth (represented as z in um) is used.
The main windows in tab:
- Original frame: Shows the original image with frame number and z-distance. Left and right scroll keys allow to browse through the frames, respectively (or up and down or page up and page down buttons for faster scrolling).
- Pre-processed: Displays image after pre-processing. The blue crosses represent ground-truth locations.
- Calibration: Shows the z-calibration if the calibration dataset is available. In order to get the calibration curve first click on the button Calibrate. This display shows two sets (red and blue) calibration data corresponding to sigma values of Gaussian fit along the x and y axis fitted from the spread point functions (PSF) of the calibration dataset (shown on display Pre-processed frame). The calibration curves marked as 4 px, 5px, correspond to the results by using fitting area of 4 or 5 pixels, respectively. Lines sow the respective spline trough the data points.
- Wobble: Systematic error of the z-calibration.
Frames
Displays actual frame and localization info. The scrolling is similar to the axial calibration tab.
The main windows in tab:
- Original frame: Shows the original image with frame number and z-distance. Left and right scroll keys allow to browse through the frames, respectively (or up and down or page up and page down buttons for faster scrolling).
- Pre-processed frame: Shows image after pre-processing. The red and blue crosses represent fitted and ground-truth locations, respectively. The red circles denote the initial fitting locations.
- Subtracted frame: the previous frame is subtracted from the current one.
- Residual: The remaining image if the found molecules are subtracted from the image.
- Iterations: Show the iteration info if the localizer supports it.
- Histogram: Noise distribution of the signal.
Hi-Res image
This tab displays the resulting constructed super-resolution image and localization statistics.
The main windows in tab:
- Hi-Res image: In order to calculate the image, first click the “Process frames” button. Now the Hi-res image display shows super resolved image constructed from all found molecules. Save results saves the coordinates for all the localized molecules in file in CSV format.
- Processed image: Displays the super resolved image after post-processing.
-
Runtime stats: Shows an overview of statistics of matched localizations respect to ground-truth data by using the characteristics such as jaccard (JAC); recall (fraction of detected molecules respect to total number in ground-truth data); rmsXY, rmsZ root-mean-square displacements along xy- and z-axis, respectively (more specific description of these paramaters see ref.
-
Goodness panel: Displays the validation characteristics. It shows dependencies between JAC and rmsXY, rmsZ.
Description of parameters
Pre-processors
The aim of pre-processor is to prepare images for localization (e.g filtering and reducing background).
Background subtractor
The aim of this pre-processor is to subtract background from the image. Divides image into bins X times bins Y blocks, then calculates specified percentile for every bin (also takes into account frames before and after, up to span T frames). Finally fits a 2D spline through the points found for every pin and then subtracts the interpolated plane form image.
| Parameter | Description |
|---|---|
Enabled |
Enables or disables the pre-processor |
Bins X |
Number of bins to divide the image in x-direction |
Bins Y |
Number of bins to divide the image in y-direction |
Span T |
In percentile calculation also includes up to Span T frames (preferably before and after equally) |
Percentile |
Percentile value (0..100) |
Smoothing |
Fitting smoothing parameter |
Gaussian filter
Applys standard Gaussian filtering to the image in order to reduce noise.
| Parameter | Description |
|---|---|
Enabled |
Enables or disables the pre-processor |
Sigma |
The width of Gaussian filter |
PSFs
| Parameter | Description |
|---|---|
Current PSF |
Enables the selection of PSF |
Gaussian
2D gaussian function with two different widths and angle phi.
| Parameter | Description |
|---|---|
Symmetric (2D/3D) |
Forces Gaussian to be symmetric or not |
Smooth sigmaX |
Smoothing factor for axial calibration of sigmaX (x-axis width of Gaussian function) |
Smooth sigmaY |
Smoothing factor for axial calibration of sigmaY (y-axis width of Gaussian function) |
Wobble correction |
Enables or disables wobble correction |
Smooth wobble x |
Smoothing factor for axial calibration of x-axis wobble |
Smooth wobble y |
Smoothing factor for axial calibration of y-axis wobble |
Fitting library |
Different options for least-square fitting libraries |
Fitting method |
Some libraries support multiple methods for fitting |
Fit x-tol |
Fitting termination tolerance in parameters (see manual of fitting library) |
Fit f-tol |
Fitting termination tolerance in least squares (see manual of fitting library) |
Fit g-tol |
Fitting termination criteria (see manual of fitting library) |
Fit scale |
Extra option for fitting (rescales different parameters to be in the same order of magnitude) |
Initial sigma |
Initial Gaussian width for fitting |
Initial offset |
Initial Gaussian offset from zero for fitting |
Initial z |
Initial z-axis position for 3D fitting |
Phi |
Angle of Gaussian function (in radians) |
Max shift iterations |
Maximum number of fitting-area recenterings |
Goodness func |
Function used to calculate the goodness of the fit |
Error func |
Function used to calculate the error probability of the fitting result |
Axial calibrator
The aim of axial calibrator is to analyse beads sequence and determine how the different parameters of PSFs depend on the z-axis. This calibration is used to determine the z-coordinate.
| Parameter | Description |
|---|---|
Current calibrator |
Different options for the z-axis calibration |
Manual calibrator
User has to manually select the beads used for the calibration.As the calibration slightly depend on the fitting area size, then different calibrations could be made for different fitting area sizes. The calibration is done form min fit half-width (correspond to 2 * min fit half-width + 1 pixels) to max fit half-width (correspond to 2 * max fit half-width + 1 pixels).
| Parameter | Description |
|---|---|
Min fit half-width |
Minimum fit half-width in pixels |
Max fit half-width |
Maximum fit half-width in pixels |
Initial max dist |
If the coordinate of the fitted PSF is farther than Initial max dist from initial fitting position, the fitting result is considered as error |
Calib from z |
The beginning coordinate of z-axis calibration |
Calib to z |
The end coordinate of z-axis calibration |
Ground-truth calibrator
If the position of the beads is known, then manual selection of the beads is not necessary (see Manual Calibrator).
| Parameter | Description |
|---|---|
Min fit half-width |
Minimum fit half-width in pixels |
Max fit half-width |
Maximum fit half-width in pixels |
Initial max dist |
If the coordinate of the fitted PSF is farther than Initial max dist from initial fitting position, the fitting result is considered as error |
Calib from z |
The beginning coordinate of z-axis calibration |
Calib to z |
The end coordinate of z-axis calibration |
Localizer
Localizers are responsible for localizing the single molecules form images after pre-processing. Localizer itself uses PSF for fitting, so the main function of the localizer is to find the good fitting starting positions and possibly subtract already found molecules and do the next iteration of localization (i.e iterative localization).
Local maxima localizer
Simple local maximum localizer with enhancements. It is recommended to use more advanced iterative localizer instead. This localizer will find all the pixels above maxima threshold that are local maximums. Then with PSF module all the local maximums are fitted (also taking into account all the limiting criteria described bellow). If no molecules are found, then the fitting area will be reduced, i.e dynamic fitting-area, (down to min region half-width) and the procedure is repeated.
| Parameter | Description |
|---|---|
Maxima threshold |
Minimum intensity of pixel in order to be considered |
Region half-width |
Initial fitting-area half-width in pixels (fitting area size 2 * region half-width + 1) |
Min region half-width |
Minimum region half-width (half-width is reduced down to this value, if no molecule is found with higher region half-width) |
Initial max dist |
Maximum distance of the fitted location of the PSF form the initial fitting location in order to be considered |
Border region |
Defines border region where fitting results will be discarded |
Duplicate min dist |
Minimum distance of found molecules at the same frame |
Simultaneous fit min dist |
Minimal distance between PSF fitting at the same iteration (in order to avoid double subtraction of PSFs) |
Min goodness |
Minimal goodness defined by PSF's goodness func |
Initial fit location |
Whether fitting inital coordinate will be the center of the local maximum or the coordinate of the local weighted centroid |
Min offset |
If the fitting offset is bellow this value, then the fitting result is considered as error and is discarded |
Noise level |
Approximate level of noise, used by min area |
Min area |
Filters found local maximums, if near the local maximum there is less than min area pixels with value greater then noise level, then this local maximum is not considered |
Blob detection localizer
Uses blob detection algorithm (method blob_log from scikit-image library skimage.feature.blob_log) to find the potential starting locations for the fitting. Does up to maximum # of iterations iterations (subtracts found molecules and does localization again).
| Parameter | Description |
|---|---|
Maximum # of iterations |
Maximum number of iterations to make |
Maxima threshold |
Minimum intensity of pixel in order to be considered |
Min sigma |
Minimum std for Gaussian kernel in pixels |
Max sigma |
Maximum std for Gaussian kernel in pixels |
# of sigmas |
number of stds to try |
Region half-width |
Fitting-area half-width in pixels (fitting area size 2 * region half-width + 1) |
Initial max dist |
Maximum distance of the fitted location of the PSF form the initial fitting location in order to be considered |
Border region |
Defines border region where fitting results will be discarded |
Duplicate min dist |
Minimum distance of found molecules at the same frame |
Region detection localizer
Divides image into connected regions (method label from scikit-image library skimage.measure.label) to find the potential starting locations for the fitting. Does up to maximum # of iterations iterations (subtracts found molecules and does localization again).
| Parameter | Description |
|---|---|
Peak detection mode |
Single peak mode increases the labeling treshold until only one peak that matches the criterions are found. Multipeak mode will giv its best effort to localize all the peaks at once |
Maximum # of iterations |
Maximum number of iterations to make |
Maxima threshold |
Minimum intensity of pixel in order to be considered |
Labeling threshold |
Initial background signal level for label detection |
Minimum area |
Minimum area of region |
Maximum area |
Maximum area of region, if the area size id greather, then the area will be divide further |
Region half-width |
Initial fitting-area half-width in pixels (fitting area size 2 * region half-width + 1) |
Min region half-width |
Minimum region half-width (half-width is reduced down to this value, if no molecule is found with higher region half-width) |
Initial max dist |
Maximum distance of the fitted location of the PSF form the initial fitting location in order to be considered |
Border region |
Defines border region where fitting results will be discarded |
Duplicate min dist |
Minimum distance of found molecules at the same frame |
Simultaneous fit min dist |
Minimal distance between PSF fitting at the same iteration (in order to avoid double subtraction of PSFs) |
Min goodness |
Minimal goodness defined by PSF's goodness func |
Iterative localizer
Iterative localizer is more advanced version of local maxima localizer. The functionality is almost the same, however at every iteration only up to one molecule is subtracted (the best one). Also performance is enhanced by avoiding refitting if the same area was already fitted in previous iteration and nothing has changed.
| Parameter | Description |
|---|---|
Iteration info |
Turns ON/OFF the iteration info in Frames -> Iterations tab |
Max iterations |
Maximum number of iterations to make |
Potential loc mode |
Local maxima mode will only consider points that are local maximums, above threshold hasn't this criterion |
Detection threshold |
Minimum intensity of pixel in order to be considered |
Noise level |
Approximate level of noise, used by min area |
Min area |
Filters found local maximums, if near the local maximum there is less than min area pixels with value greater then noise level, then this local maximum is not considered |
Min region half-width |
Minimum region half-width (half-width is reduced down to this value, if no molecule is found with higher region half-width) |
Max region half-width |
Initial fitting-area half-width in pixels |
Region half-with mode |
Reduce min max mode reduces both min and max fitting-area size, reduce min only decreases min fitting-area size if no molecule is found and all mode makes all the fitting-area sizes available from the first iteration |
Initial max dist |
Maximum distance of the fitted location of the PSF form the initial fitting location in order to be considered |
Border region |
Defines border region where fitting results will be discarded |
Initial fit location |
Whether fitting inital coordinate will be the center of the local maximum or the coordinate of the local weighted centroid |
Min offset |
If the fitting offset is bellow this value, then the fitting result is considered as error and is discarded |
Duplicate min dist |
Minimum distance of found molecules at the same frame |
Min goodness |
Minimal goodness defined by PSF's goodness func |
Ground-Truth
If competition data is loaded where ground-truth information is available, then the parameters of matching the found and ground-truth molecules are specified here.
| Parameter | Description |
|---|---|
Tolerance XY |
Tolerance for matching in XY-plane |
Tolerance Z |
Tolerance for matching in Z-direction |
Post-processors
Post-processors are considering all the found locations together and do error removal and averaging for example.
Nearest molecule post-processor
This post-processor removes locations, that has no other locations nearby (error with high probability).
| Parameter | Description |
|---|---|
Enabled |
Enables or disables post-processor |
Max iterations |
Maximum number of iterations to make |
Nearest max dist XY |
For every found molecule the nearby molecules are counted in radius nearest max dist XY (in xy-plane), for 2D localization |
Min % of melecules (XY) |
If there is less than such percent of molecules nearby (defined by nearest max dist XY) then the molecule is considered as error, for 2D |
Nearest max dist XYZ |
For every found molecule the nearby molecules are counted in radius nearest max dist XYZ, for 3D localization |
Min % of melecules (XZY) |
If there is less than such percent of molecules nearby (defined by nearest max dist XYZ) then the molecule is considered as error, for 3D |
Temporal correlation
Used to detect the same molecule at the different frames.
| Parameter | Description |
|---|---|
Enabled |
Enables or disables post-processor |
xyTol |
Maximum distance in xy-plane in order to be considered as the same molecule |
Dark frames |
Number of dark frames allowed |
Weights |
Weight function for weighted average of the new location |
Error removal post-processor
Used to remove errors on the basis of the fitting results (the aim is to increase precision).
| Parameter | Description |
|---|---|
Enabled |
Enables or disables post-processor |
Error func |
Selects error function to use |
To remove |
The percent of total locations to remove |
Bad molecule post-processor
Used to remove less good molecules on the basis of the fitting results (the aim is to decrease rms).
| Parameter | Description |
|---|---|
Enabled |
Enables or disables post-processor |
Error func |
Selects badness function to use |
To remove |
The percent of total locations to remove |
Molecule sorter post-processor
Used to sort found locations in the order of goodness. Usually used only if the ground-truth is available.
Shift
Used to eliminate systematic offsets.
| Parameter | Description |
|---|---|
Enabled |
Enables or disables post-processor |
x |
Shift in x-direction |
y |
Shift in y-direction |
z |
Shift in z-direction |
I |
Shift the output intensity of photons |
Multiply I |
Scales the output intensity of photons |
Updated