RS-FISH: Precise, interactive, fast, and scalable FISH spot detection
Ella Bahry*, Laura Breimann*, Marwan Zouinkhi*, Leo Epstein, Klim Kolyvanov, Xi Long, 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
- 8. Filtering detections using a binary mask
Fluorescent in-situ hybridization (FISH)-based methods are powerful tools to study molecular processes with subcellular resolution, relying on accurate identification and localization of diffraction-limited spots in microscopy images. We developed the Radial Symmetry-FISH (RS-FISH) software that accurately, robustly, and quickly detects single-molecule spots in two and three dimensions, making it applicable to several key assays, including single-molecule FISH (smFISH), spatial transcriptomics, and spatial genomics. RS-FISH allows interactive parameter tuning and scales to large sets of images and tera-byte sized image volumes such as entire brain scans using straight-forward distributed processing on workstations, clusters, and in the cloud.
Availability and implementation:
RS-FISH is implemented as open-source in Java/ImgLib2 and provided as a macro-scriptable Fiji plugin and stand-alone command-line application capable of cluster and cloud execution.
Code source, tutorial, documentation, and example images are available at: https://github.com/PreibischLab/RS-FISH and https://github.com/PreibischLab/RS-FISH-Spark
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 maven
On 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/bin
All 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.
![RS_FISH screenshot one spot](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/one_spot.png?raw=true)
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:
![RS_FISH screenshot anisotropy menu](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/calculate_anisotropy_coefficient.png?raw=true)
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.
![RS_FISH screenshot DoG menu](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/adjust_DoG.png?raw=true)
In the Adjust difference-of-gaussian values window, you can choose Sigma and Threshold values to detect the majority of subpixel resolution spots.
![RS_FISH screenshot one spot detection](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/one_spot_detected.png?raw=true)
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.
![Embryo with smFISH spots](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/smFISH_embryo.png?raw=true)
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.
![RS_FISH interactive menu](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/RS_interactive.png?raw=true)
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.
![RS_FISH RANSAC dropdown menu](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/select_RANSAC.png?raw=true)
- 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.
![RS_FISH screenshot DoG vals slide bars](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/adjust_DoG_values.png?raw=true)
![RS_FISH detection preview](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/detection_preview.png?raw=true)
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.
![RS_FISH screenshot RANSAC vals menu](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/adjust_RANSAC_values.png?raw=true)
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).
![RS_FISH RANSAC preview](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/RANSAC_preview.png?raw=true)
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.
![RS_FISH screenshot background menu](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/background.png?raw=true)
Once the parameters are adjusted, hit any of the Done buttons and wait a bit while the computations are performed.
![RS_FISH screenshot intensity distribution histogram](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/intensity_distribution.png?raw=true)
![RS_FISH display spots](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/display_spots.png?raw=true)
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.
![RS_FISH log](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/final_log.png?raw=true)
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.
![RS_FISH result table](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/results_csv.png?raw=true)
Advanced mode
![RS_FISH advance mode menu](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/RS_advanced.png?raw=true)
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.
![RS_FISH advance mode set parameters menu](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/Advanced_options.png?raw=true)
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.
![Fiji ROI Manager with detected spot coordinates](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/ROI_Manager.png?raw=true)
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.
![Show detections in Fiji tool](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/detections_tool_fiji.png?raw=true)
![Embryo with smFISH spots detection overlay](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/show_detections.png?raw=true)
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.
![Show detection in the Big data viewer](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/detection_tool_bdv.png?raw=true)
![Options for the display in the Big data viewer](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/options_bdv.png?raw=true)
![Overlay of detected points using the Big Data Viewer](https://github.com/PreibischLab/RadialSymmetryLocalization/raw/master/documents/Tutorial_screenshots/bdv.png?raw=true)
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
To filter RS-FISH detections, a binary mask (with values of 0 and 1) can be used to identify parts that are inside a cell or selection and outside the structure.
![Image of smFISH spot detection in neuron, filtered with a binary mask](https://github.com/PreibischLab/RS-FISH/raw/master/documents/Tutorial_screenshots/filter_neurons.png?raw=true)
After creating a binary mask with the same dimensions as the original image using Fiji or a different software, the Mask filtering
tool can be used. The tool is located under Plugins > RS-FISH > Tools > Mask filtering
. In the interface, one can specify the input file or folder with csv files and the mask file or folder as well as the output folder. The output is a new csv file with detections only in the specified areas of the image.
![Screenshot of the mask filtering tool](https://github.com/PreibischLab/RS-FISH/raw/master/documents/Tutorial_screenshots/mask_filter.png?raw=true)
License: GPLv2