Foci-analyzer

ImageJ macro for the analysis of foci (e.g. DNA damage) in nuclei (or cells). Works on 2D/3D fluorescence images, including multiseries files, as long as all series have the same dimensions. The macro doesn't work on timelapse images (yet). A (slightly tedious) workaround is splitting your timepoints first. This option may be included in a future version.

Author: Bram van den Broek, The Netherlands Cancer Institute (b.vd.broek@nki.nl or bioimaging@nki.nl)

Workflow summary

1. Nuclei are segmented (in a 2D projection) using the pre-trained deep learning network StarDist. Alternatively, classic thresholding + watershedding can be used (though no parameters can be changed). As a third option, the deep learning network Cellpose can be used to segment whole cells, thanks to the Cellpose wrapper for Fiji by BIOP.¹

2. Foci are detected in each nucleus in 2D or 3D. After Difference of Gaussians background subtraction, local maxima are detected and used as seeds for MorpholibJ's marker-controlled watershed (executed on the GPU using CLIJ2/CLIJx). Additionally, AreaMaxima local maxima detection can be used as detection method. Thresholds are automatically calculated per image as 3 times the median of the standard deviations of the (outlier-removed) foci signal in the nuclei, and can be adapted using the threshold bias sliders.

3. Foci are quantified in a single channel A, or in two channels A and B. For each nucleus a number of metrics are reported in a table: foci count, as well as mean/median values for foci intensity, area/volume, and whole nucleus intensity. If two channels are selected, foci colocalization between channels is automatically calculated. The table is saved as a .tsv file, which can be easily opened in other programs (e.g. Excel).

4. Segmented nuclei and foci are visualized as overlays on the original images for easy inspection. If desired, foci detection settings (threshold bias, min/max size) can be adapted before processing all input images. A colocalization map is also created when two channels are measured.

Installation / Requirements

Download the latest release of Foci_Analyzer.ijm (in Assets) into a sensible folder.

► Activate the following Fiji update sites (in the menu bar, via Help > Update...):

• 3D ImageJ Suite
• CLIJ
• CLIJ2
• CLIJx-assistent
• CLIJx-assistent-extensions
• CSBDeep
• IJPB-plugins
• SCF MPI CBG
• StarDist

► To run the script, you have two options:

1. Drag&drop the .ijm file onto the Fiji window. This will open the file in the editor. Click 'Run' in the bottom left.
2. Copy the .ijm file to <myPath>\Fiji.app\Plugins\Macros and restart Fiji. It will now appear in the menu bar under Plugins > Macros.

In case you also want to use Cellpose segmentation you additionally need:

• A working Cellpose 2.0 environment in Python (conda or venv)
• Activated PTBIOP update site, with proper settings. See https://github.com/BIOP/ijl-utilities-wrappers/blob/master/README.md#cellpose

The macro Merge_result_files_1.1.ijm can be used to pool output .tsv files into a single file.

Usage manual

The macro starts with a large dialog containing all options and parameters (click to enlarge): The dialog has several sections that are discussed below. All settings in this dialog will be remembered after you click OK.

File handling and image settings

• Input files : Here you can specify which files to analyze, by adding them to the list, or drag&drop from a file explorer window

• Output folder : the folder where all the analyzed images and results will be written.

• Nuclei channel : The image channel on which nuclei segmentation will be performed. This segmentation always happens in 2D; for 3D images on a maximum intensity projection. (default: 1)

• Foci channel A : the first foci channel (default: 2)

• Foci channel B : the second foci channel (default: 3)

• Also detect foci in Channel B and perform colocalization? : If checked, foci in both channels A and B will be analyzed, followed by a simple colocalization analysis. (default: checked)

• 3D image handling : This parameter determines how foci in 3D images should be analyzed. For 2D input images this setting is ignored. There are four options:

  • Analyze foci in 3D (default) performs foci analysis using 3D filters and 3D marker-controlled watershed functions. Connected foci in consecutive slices are counted once.
  • Detect foci on a Extended Depth of Focus Projection performs 2D foci analysis on an EDF projection.
  • Detect foci on the Maximum Intensity Projection performs 2D foci analysis on the MIP projection.
  • Use quasi-2D foci detection (detect foci separately in every Z-slice) analyzes every z-slice in a 3D image as a separate 2D image. This setting is useful in cases where the z-spacing is very large and each focus is visible in only one z-slice. Hence, connected foci in consecutive slices will be counted multiple times.
  • Process a single z-slice only (specify below which slice) allows the user to analyze foci only in a particular z-slice.

  Often analysis on 2D projections provides satisfactory results that are easier visualized/inspected compared to true 3D analysis, and much faster processing, with minimal sacrifices (e.g. foci intensities).

• [single z-slice foci detection only] Slice nr : the single z-slice used for the option above. For any other choice this parameter is ignored.

• Remove image borders (pixels) : Possibility to remove edges from the image. This can in particular be useful when the image edges have very different intensities, causing incorrect automatic nuclei segmentation. (default: 0)

• Image XY binning before analysis : Optional pixel binning in case the resolution is very high and the foci consist of many pixels. A value of 2 means: 2x2 pixels will be binned into 1 pixel. This reduces noise in the image and speeds up analysis. (default: 1)

Nuclei/cell segmentation settings

• Nuclei/cell segmentation method :

  • Stardist nuclei segmentation (default) uses the pretrained convolutional neural network StarDist to recognize cell nuclei in fluoresence microscopy images. In general this method works very well on a large variety of samples.
  • Cellpose cytoplasm segmentation uses the deep learning network Cellpose (model: cyto) to recognize whole cells. Use this option if you want to measure foci in entire cells and/or you do not have a nuclear staining (but it can also work well for nuclei). Cellpose requires a few additional installations (see Installation / Requirements).
  • Classic nuclei segmentation allows the user to segment nuclei using manual/automatic thresholding is provided for legacy reasons. The method is almost always outperformed by the two other methods.

• Stardist nuclei rescaling factor [1-n], 0 for automatic rescaling : Stardist is trained on medium resolution images, and generally performs well on images with pixel sizes around 0.5 µm. For images with much smaller pixel size StarDist tends to 'oversegment' nuclei. Set to 0 for automatic rescaling the nuclei to the optimal pixel size of 0.5 µm, or put any other number for manual control of the rescaling. (N.B. This option only affects the nuclei segmentation; it is different from the previously mentioned 'XY binning' parameter, which also changes the pixel size of the foci channels.) (default: 0)

• Probability threshold [0.0-1.0] (StarDist/Cellpose) : Lower values will accept more nuclei; higher values will be more stringent. For Cellpose this is actually the flow_threshold parameter. (default: 0.5)

• Cellpose cell diameter (pixels), 0 for automatic : Estimated diameter of the cells, in pixels. Setting this parameter to 0 will trigger Cellpose to estimate it. Please check the Fiji console for the resulting estimate.

• Remove nuclei with diameter smaller than (units) : Objects smaller than circles having an area corresponding to this diameter will be removed. 'Units' depends on the image, and will almost always be 'µm', or otherwise 'pixels' in case the pxiel calibration values are missing. (default: 4)

• Remove nuclei with diameter larger than (units) : Likewise, but for large objects. (default: 50)

• Exclude nuclei on image edges : When checked, nuclei that touch the image edge will not be analyzed. (default: checked).

• Manual nuclei removal : allows the user to erase ill-segmented nuclei before analysis. (default: No thanks) Options:

  • No thanks means no manual nuclei editing
  • Manually remove nuclei : Remove nuclei by leftclicking them in the image with the mouse. Editings will be saved to a small text file in the output folder.
  • load previously saved removals (from output folder) : If you have edited the segmented nuclei on this image before, it will load the previous nuclei removals from the file in the specified output folder. (Hence, if you change the output folder parameter this option will not work.)

Foci detection settings

• Enable foci parameters optimization mode? : Checking this will allow the user to adapt the foci detection settings on a preview analysis before quantifying. (default: checked)

• Foci size channel A/B (after XY binning) : choices between tiny, small, average, large, huge, and other. This parameter controls several foci image filtering steps and steers the macro towards detecting smaller or larger foci. (default: average).

• Foci detection method :

  • Marker-controlled watershed uses marker-controlled watershed with local maxima as seeds to segment foci
  • AreaMaximum detection tends to detect only the peaks of the foci. Can be tried when the other option doesn't provide satisfactory results.

• Foci intensity threshold bias channel A/B : The macro will automatically estimate the intensity threshold for foci detection (after difference-of-Gaussians background subtraction). This default threshold is set at 3 times the median standard deviation of the nuclear background signal in all nuclei in the image. The user can bias this threshold with the slider to lower values (accepting more low intensity foci) or higher values (gearing towards high intensity foci). The bias slider couples exponentially to the used threshold value: threshold = estimated_threshold * e^bias. Since the minimum and maximum slider values are (-2.5, 2.5) the threshold can be set to anywhere between 0.2 and 36 times the standard deviation of the nuclear background signal. (default: 0)

• Minimum foci size (pixels/voxels) : Foci occupying an area/volume smaller than this value (in pixel/voxels) will be deleted. Note that for the marker-controlled watershed detection method the minimum foci size is 5 pixels for 2D images and 7 voxels for 3D images. Hence, setting sizes smaller than this will not change the number of detected foci.

• Maximum foci size (pixels/voxels) : The upper limit for the foci size, in pixels/voxels.

• Max distance of foci outside nuclei/cells (units); -1 for full image : This controls how far (in units (=microns)) outside the cell/nucleus segmentation foci should be still be counted. (default: 0)

• Minimum overlap of foci to colocalize : Foci in channel A and B will be counted as colocalizing *only if they overlap with at least this area/volume (in pixels/voxels).

Visualization options

• Nuclei outline color : The color of the nuclei outlines overlay.

• Nuclei label color : The color of the nuclei label numbers overlay.

• Nuclei label size : The size of the nuclei label numbers overlay.

• Debug mode (show intermediate images) : Used for development and bug fixing: checking this option will trigger displaying many intermediate results during the processing. It will also slow down the analysis.

Tips and tricks

When the option Enable foci parameters optimization mode? is active, a preview image of the detected foci will be shown during process. A dialog appears where foci detection parameters can be adjusted:

After changing the settings, clicking OK will detect the foci on the same nuclei with the updated parameters and redisplay them in the preview image. Channel display settings and zoom are remembered in between optimization steps. The preview image shows an ImageJ hyperstack that, besides the z-slices of the 3D image (if applicable), contains two frames representing the foci channels A and B (if applicable), and four channels:

1. The nuclei staining channel (azure blue)
2. The original foci data (green)
3. The detected foci (magenta)
4. The centroids of the detected foci (white)

The image below shows a montage layout of such a hyperstack, with vertically the 'frames' (foci channels A and B - here 2 and 3), and horizontally the 'channels' (as described above):

By changing the displayed channels (Shift-Z), adjusting brightness&contrast (Shift-C) of the channels and zooming in ('+' and '-' keys), the user can inspect the foci detections for both foci channels, adjust the detection parameters if desired and rerun the foci detection step. In particular, unchecking channel 1 (nuclei), and then alternating the displaying of channel 3 (detected foci) is most helpful.

Footnotes

1. Currently, Cellpose is run using the 2D 'cyto' model on a single channel, with most options set to the defaults. Look for run("Cellpose Advanced") in the code and change parameters as seen fit. ↩