RS-FISH documentation

1. Abstract & Availability

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.

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

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.

3. Calculating Anisotropy Coefficient

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

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.

5. Show 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

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

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

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.

License: GPLv2