RS-FISH: Precise, interactive and scalable smFISH spot detection using Radial Symmetry
Ella Bahry*, Laura Breimann*, Leo Epstein*, Klim Kolyvanov, Kyle I S Harrington, Timothée Lionnet, Stephan Preibisch
bioRxiv 2021, doi: https://doi.org/10.1101/2021.03.09.434205
* equal contribution
- 1. Abstract & Availability
- 2.Download & Installation
- 3. Calculating Anisotropy Coefficient
- 4. RS-FISH tutorial
- 5. Show detections
- 6. Batch processing using RS-FISH
- 7. Running RS-FISH on large volumes
Availability and implementation: RS-FISH is implemented as open-source in Java/ImgLib2 and provided as a macro-scriptable Fiji plugin. Code source, tutorial, documentation, and example images are available at: https://github.com/PreibischLab/RadialSymmetryLocalization
Implementation of Radial Symmetry Localization for Java using ImgLib2 (http://imglib2.net)
After the Nature Methods paper "Rapid, accurate particle tracking by calculation of radial symmetry centers" by Raghuveer Parthasarathy (http://www.nature.com/nmeth/journal/v9/n7/abs/nmeth.2071.html)
Including derivation for 3D + integration with RANSAC
The RS-FISH plugin can be downloaded via the Fiji Updater. Go to Help > Update …, click Manage update sites and select Radial Symmetry in the list. Then click “Apply changes” and restart Fiji. You will now find the RS-FISH plugin under Plugins.
The source code is available on GitHub. If you encounter bugs or want to report a feature request, please report everything there.
The simulation data that was generated to benchmark the method can be downloaded here. The smFISH image of the C. elegans embryo can be found here
Command-line installation requires maven (>=3.8.1) and OpenJDK8 (or newer) on Ubuntu:
sudo apt-get install openjdk-8-jdk mavenOn other platforms, please find your way and report back if interested.
Next, please check out this repository and go into the folder
git clone https://github.com/PreibischLab/RS-FISH.git
cd RS-FISH
Install into your favorite local binary $PATH (or leave empty for using the checked out directory):
./install $HOME/binAll dependencies will be downloaded and managed by maven automatically.
This currently installs three tools, rs-fish, rs-fish-anisotropy, csv-overlay. Please execute them in order to get detailed execution instructions.
Since the effective size of objects along the z-axis is usually different than in the x- and y-axis of your images, you should correct this to achieve a more accurate smFISH detection. To estimate your anisotropy coefficient, you can acquire a fluorescent bead image on the same microscope, using the same settings and equipment or you can use the smFISH image directly.
Open the image with the beads or the smFISH detections and navigate to the Plugins > RS-FISH > Tools > Calculate Anisotropy Coefficient.
You will see the dialog window:
Make sure your bead image is selected in the Image drop-down menu. Next, you can choose between two Detection methods: Gauss fit or Radial Symmetry. If you have fewer detections Gaussian fit might be the better choice, however, both methods usually provide reasonable results. It can even be useful to simply average the results of both methods. The resulting number can be visually confirmed by turning the input image around its x or y-axis (Image > Stacks > Reslice > Top) as it simply describes the ratio of the size in z versus xy.
After you choose a detection method, two windows will open once you press OK.
In the Adjust difference-of-gaussian values window, you can choose Sigma and Threshold values to detect the majority of subpixel resolution spots.
Once you are done – press the Done button.
Depending on the number of spots, the calculations might take some time as the Gaussian fit is slower and the RS-RANSAC needs to iterate over a range of potential anisotropy coefficients. The program will calculate the corresponding anisotropy coefficient, which shows how we should squeeze the objects in the z-axis to make them look radially symmetric.
The Log window will show the corresponding anisotropy value, and it should be transferred to the next step automatically.
Important: It is OK to skip this step if the objects are more or less round in 3D. The plugin will be able to do a decent job even with the default value of the anisotropy coefficient. However, we advise performing this prior to actual RS detection.
Localizing Spots
The main RS-FISH plugin can be found under: Plugins > RS-FISH > RS-FISH. There are two different modes of processing images: interactive and advanced. The Interactive method is used to adjust the parameters for further dataset processing or is the right choice if single images need to be processed. The interactive mode provides the visual feedback necessary to adjust the advanced automated processing parameters on large datasets.
Interactive mode
Open a 2D or 3D single-channel image for analysis and navigate to the Plugins menu under RS-FISH > RS-FISH.
A window will pop up.
Ensure that the correct image is chosen in the Image drop-down menu. Next, you choose the Mode that you want to run RS-FISH in. For finding the best parameters or analyzing a small set of images, choose the Interactive Mode.
Anisotropy coefficient defines how much the z-resolution differs from the x/y-resolution. The parameter would be set automatically if you ran the Calculate Anisotropy Coefficient plugin before-hand (Plugins > RS-FISH > Calculate Anisotropy Coefficient). In general, 1.0 gives a good result if the spots are somewhat round in 3D. You can choose to use the same anisotropy coefficient for computing the Difference of Gaussian (DoG), which will lead to a more robust DoG detection for anisotropic spots.
There are various options for Robust fitting Computation.
- RANSAC defines if you want to use radial symmetry with robust outlier removal, it will identify all gradients within every local patch that supports the same center point (Fig. 1)
- No RANSAC for the use of radial symmetry without robust outlier removal, simply all gradients of a local spot will be used to compute the center point (classic RS)
- Multiconsensus RANSAC will iteratively run robust outlier removal on each local patch until all sets of gradients are identified that support a center point. This allows RS-FISH to potentially find multiple points within each local patch that was identified using DoG detections.
The last option in the Visualization section is whether you want to add the detected spots directly to the ROI Manager at the end of the detection.
Once you are done with the settings, press the OK button.
In the second step, and based on your selection, multiple windows will open.
In the Difference of Gaussian window, you can adjust the parameters for the initial detection of the spots. The goal of this step is to minimize false detections. Adjust the Sigma and Threshold slider so that the red circles in the image detect as many single spots as possible. Try to slightly find more spots if you chose RANSAC; the RANSAC window allows additional restrictive settings. If you are working with a 3D stack, it helps to constantly move through z while adjusting the parameters as the red circle appears only in the z-slices where the signal is the strongest. It can help to adjust the yellow preview box during this step. If the image is very large, it can help to choose a smaller box to speed up the visualization (the detection will be performed in the whole image).
Important: If you choose to run RANSAC robust fitting, don’t click the Done button on the Difference of Gaussian window at this step; simply continue setting the parameters in the Adjust RANSAC values window.
The Adjust RANSAC values dialog allows you to find the right setting for the robust outlier removal. The Support Region Radius defines the radius for each spot in which gradients are extracted for RS. You might want to play with this parameter. Sometimes it is helpful to increase the radius and decrease the Inlier Ratio at the same time. The Inlier ratio defines the ratio of the gradients (i.e. pixels) that have to support the RS center point (Simply speaking, the ratio of pixels should 'belong' to the current spot), given the Max error that defines maximally allowed error for RS fitting (see Fig. 1).
While moving the sliders, you will see the updates in both image windows. Firstly the RANSAC preview window displays the pixels used by RANSAC and the error values at each of the used pixels. The second window is the initial image window with the preview of the detections. Additionally to the red circles, the blue crosses indicate spots that were detected using RANSAC outlier removal. So the goal of this part is to find all spots with a red circle and a blue cross inside while not detecting noise or background.
The background removal step allows you to remove a non-planar background prior to computing the RS. It will try to estimate a plane using the intensity values of the edges of each local patch using any of the outlined methods. Note: constant backgrounds do not need to be removed, only if strong gradients are present.
Once the parameters are adjusted, hit any of the Done buttons and wait a bit while the computations are performed.
In the next window, you have the option of thresholding the detected spots based on their intensity. The Intensity distribution window displays all detected spots and their corresponding intensity value as a histogram. By clicking at an intensity value in the histogram, the blue thresholding bar can be adjusted. All spots that currently pass the thresholding are displayed in the image window and marked by a red circle. If you are satisfied with the selected spots, press the OK button and continue to the final results table.
The Log window gives you a summary of all spots found at every step and the final number of detections. The Results table contains the spot coordinates, time, channel, and intensity values in the corresponding columns. You can save the results and use them in the Show Detections part of the plugin to visualize all found spots’ locations.
Advanced mode
In the Advanced mode, you can skip the interactive setting of parameters and only use already known parameters for the computation. After choosing Advanced in the first window, you will reach the second window to set the parameters for spot detection. If you previously used the interactive mode to find the best parameters, they will be saved and set as default for the advanced mode.
After you press OK, the computation is done in all RS-FISH steps automatically, and the same Results table as above is either saved or displayed.
Scripting / headless
When using the advanced mode you can simply record the parameters you used for running RS-FISH (Plugins > Macro > Record). You are then able to apply it to a set of images using the Fiji/ImageJ macro language.
After RS-FISH computed all spots, the results table can be saved as CSV or directly be used to visualize the detected spots. There are three ways to visulaize the RS-FISH detected spots:
- ROI Manager
- Fiji/ImageJ overlay
- Big Data Viewer
If the option to transfer spots directly to ROI manager was chosen in the begining, the ROI manager will pop up with the results table in the last step.
The Show Detections (ImageJ/Fiji) plugin (Plugins > RS-FISH > Tools > Show Detections (ImageJ/Fiji)) can be used to overlay all spots stored in a CSV onto the current image for visual inspection of the final result using Fiji. The detected spots will be highlighted by red circles that are largest in the z position where the center of the spot is.
The Show Detections (BigDataViewer) plugin (Plugins > RS-FISH > Tools > Show Detections (BigDataViewer)) can be used to visualize the spots using the Big Data Viewer. In the first window are four options whether to open a saved image or CSV or use the currently active image and table. The intensity of the overlay points can be changed with the sigma slider.
For batch processing instructions and running on computing cluster please see the README in the example_scripts folder.
There is a dedicated repository for Spark-based execution of RS-FISH on large (and also smaller) volumes: https://github.com/PreibischLab/RS-FISH-Spark
License: GPLv2