Awesome

RS-FISH documentation

RS-FISH: Precise, interactive, fast, and scalable FISH spot detection

Ella Bahry*, Laura Breimann*, Marwan Zouinkhi*, Leo Epstein, Klim Kolyvanov, Nicholas Mamrak, Benjamin King, Xi Long, Kyle I S Harrington, Timothée Lionnet & Stephan Preibisch
Nature Methods 2022, doi: https://doi.org/10.1038/s41592-022-01669-y

* equal contribution

Content

• 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
• 9. Choosing the right parameters for RS-FISH

1. Abstract & Availability<a name="abstract">

Fluorescent in-situ hybridization (FISH)-based methods extract spatially resolved genetic and epigenetic information from biological samples by detecting fluorescent spots in microscopy images, an often challenging task. We present Radial Symmetry-FISH (RS-FISH), an accurate, fast, and user-friendly software for spot detection in two- and three-dimensional images. RS-FISH offers interactive parameter tuning and readily scales to large datasets and image volumes of cleared or expanded samples using distributed processing on workstations, clusters, or the cloud. RS-FISH maintains high detection accuracy and low localization error across a wide range of signal-to-noise ratios, a key feature for single-molecule FISH, spatial transcriptomics, or spatial genomics applications.

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

2. Download & Installation <a name="download">

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

2.1. Installation as command-line tools

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. <br /> <br />

2.2. Installation using Docker container

Alternatively to installing RS-FISH as a command line tool on your operating system, you can also use it directly from our Docker container.

To build the docker container, git pull the repository and then execute the following command:

docker build -t rs_fish:2.3.1 .

To pull the docker container directly from Dockerhub, run the following command:

docker pull wuennemannflorian/rs_fish:2.3.1

You can then run RS-FISH from the container using the following command:

docker run -v [your_local_input_folder]:/input -v [your_local_output_folder]:/output rs-fish:2.3.1 /RS-FISH/rs-fish [rs_fish_parameter] --image=/input/[your_file.tif] --output=/output/[your_file.csv]

3. Calculating Anisotropy Coefficient<a name="anisotropy">

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.

4. Running RS-FISH<a name="tutorial">

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 next option you can choose is to compute the min and max intensity from image. If you deselect the option, in the next step you can choose range of intensity of the image, which might be a good option if you are processing a set of images with the same accquisition parameters.

There are two options in RS-FISH to calculate the spot intensity value. Each spot’s associated intensity values are by default computed using linear interpolation at the spot’s sub-pixel location. By selecting the option Refine spot intensity with Gaussian fit on inliers the spot intensity can be refined by fitting a Gaussian to the subset of pixels that support the spot as identified by RS-RANSAC.

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.

5. Show Detections<a name="detections">

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.

6. Batch processing using RS-FISH<a name="batch">

For batch processing instructions and running on computing cluster please see the README in the example_scripts folder.

7. Running RS-FISH on large volumes<a name="spark">

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

8. Filtering detections using a binary mask<a name="mask">

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.

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.

9. Choosing the right parameters for RS-FISH<a name="parameters">

RS-FISH allows the user to choose between different detection methods to localize spots in the image. The tool offers three localization methods that build on each other:

1. radial symmetry (‘No RANSAC’)
2. radial symmetry + RANSAC (the default option)
3. radial symmetry + multi-consensus RANSAC

The default option is radial symmetry detection of spots with additional RANSAC outlier removal. In cases where the noise level is good, and an even higher computation speed is preferred, the RANSAC outlier removal step can be skipped by choosing “no RANSAC”. In cases where many spots potentially overlap, we recommend choosing multi-consensus RANSAC spot detection, which will try to separate close points by detecting gradients in several rounds.

The next step is to choose the parameters for detection, which is simplified by the plugin’s visual feedback. Using the default spot detection method, there are two windows with parameters to set and two different visual feedback cues (see the Tutorial RS-FISH section). The red circle marks spots detected using the radial symmetry parameters, and the blue cross confirms those spots that pass the RANSAC outlier removal. The detection of the red circle can be adjusted in size (sigma) and the threshold of the signal intensity of the DoG pre-detected spots.

The RANSAC parameters determine which and how the gradients are used to localize each spot. The support region radius determines the number of gradients computed in a local patch around each DoG pre-detected spot. We propose a default radius of 3 pixels which means a 7x7[x7] pixel patch resulting in 216 gradients for the 3D case. Decreasing this number might allow more spots to be found but will decrease localization precision as fewer gradients are used to define the center. The inlier ratio describes the number of gradients that support the detection's center point. Increasing the inlier ratio increases the robustness of the detected spot but can decrease the total number of detected spots, especially for lower SNR spots. The max error threshold defines the maximally allowed error for the intersection point defined by the gradients; i.e., how far away from the intersection point can each gradient be (only in a perfect scenario, all gradients intersect perfectly in the same point, see Supp. Fig 1d). Decreasing the number restricts the error, thus decreasing the number of false detections but potentially also the number of real detections, especially if the noise level is higher.

For the multi-consensus selection, a window pops up where parameters for additional rounds of spot detection can be defined. It is important to realize that for multi-consensus to work well, the max error in the RANSAC settings should be set relatively low since otherwise, the gradients of multiple points are allowed to intersect in a single spot. A typical setting could be 0.5 - 0.75 pixels. It is important to first run RS-FISH in RANSAC mode before setting the multi-consensus parameters. The log record will output two critical parameters: the average #inliers and stdev #inliers. The average #inliers defines how many inliers intersect in each spot on average, while the stdev #inliers describes its variability. The parameters for multi-consensus RANSAC must be defined relative to those two values. The “Initial #inlier threshold for new spot (avg - n*stdev) n=” asks the user how many inliers are required for it to be considered a new spot next to an already found one. For example, let us assume a 7x7x7 local neighborhood with 216 total candidate gradients. If average #inliers was 80 and stdev #inliers was 6, then defining n=8 would require at least 80-48=32 inliers for a new spot to be defined. Keep in mind that only around 136 gradients (=216-80) are left to be evaluated per local patch. Once a new spot was identified, we re-center the local patch around its location and re-compute it. Thus the second parameter, “Final #inlier threshold for new spot (avg - n*stdev) n=”, is usually chosen higher, e.g., n=6, thus requiring 80-32=48 inliers for a final confirmation of a new spot.

Additionally, the min number of inliers describes the number of inlier gradients minimally required to localize a point. This value is supposed to prevent the fitting of noise spots that are expected to have a low number of gradients that agree on a specific spot. Typically a value of 30 inliers is a good starting point. Note that if you set “Initial #inlier threshold for new spot (avg - n*stdev) n=” and “Final #inlier threshold for new spot (avg - n*stdev) n=” very high, only the ”min number of inliers” will be relevant, which somewhat simplifies the process.

License: GPLv2