NuclQ

NuclQ - an ImageJ plugin to quantify intensity levels by distance to the nuclear membrane.

Copyright notice

Copyright (C) 2020-2023: Jan N. Hansen

Contact

For questions, e.g., on using, copyright, and citing the plugin, please contact:

jan.hansen (at) uni-bonn.de

Installing NuclQ

NuclQ is an ImageJ plugin that can be run in ImageJ or the extended ImageJ version FIJI. Thus to use NuclQ you need to first have an ImageJ or FIJI software downloaded to your computer. ImageJ/FIJI are open-source, freely available softwares that can be downloaded here.

Donwload the NuclQ....jar file from the latest release at the release page, launch your ImageJ or FIJI and install the plugin by drag and drop of the downloaded NuclQ....jar file into ImageJs/FIJIs status bar (this is the red marked region in the following image).

Next, a dialog will pop up asking you to save the plugin. Just confirm the dialog.

FIJI/ImageJ will ask you to restart the software. Close the software and open it again.

Now, the installed plugin can be launched via the FIJI/ImageJ menu entry at Plugins > JNH > NuclQ ...

Manual / Instructions on how to use NuclQ

Scope of the plugin

NuclQ allows you to determine intensity levels in cells as a function of the distance to the nuclear border. It is thus useful for determining nuclear intensity level and also intensity levels in the cytoplasm / close to the nucleus. The same program may also be used to study intensity levels as a function of the distance to any other object(s) of interest as long as you can provide a channel in which these objects are clearly distinguishable from the background.

NuclQ allows to prefilter the objects based on intensity levels in two more channels (e.g., including only objects that are considered "signal-positive" in another channel).

Input

The input image needs to be a multi-channel image that features at least one channel reporting an object marker (e.g., for nuclei (DAPI, Hoechst)) and a channel of interest from which intensity levels shall be determined. From the object-marker channel, NuclQ will detect the objects, i.e., nuclei.

Optionally, your image may contain two more channels that can be used to select NuclQ to quantify only nuclei that are considered "signal-positive" in these channels.

Note for segmented input images

You may also use an image in which the object channel is already segmented (= "binarize") - in this case, unselect blurring and select the "Default" auto-threshold algorithm in the settings dialog:

Processing & Analysis

Launching NuclQ

Launch NuclQ via the menu entry Plugins > JNH > NuclQ...

Settings dialog

The following settings dialog pops up when launching the plugin - here is an explanation of a few general seetings, for more understanding how it affects the analysis workflow please see the sections below that will explain few settings in more detail and show how they affect the analysis workflow.

• The process option allows you to decide whether you want to process the active image or all images open in FIJI or use the multi-task manager to select a list of files to be analyzed that are not open in FIJI (see below). Note that any processed image needs to be saved somewhere on your file system for proper functioning and output of plots.
• Calibration Settings: if your image has no pixel calibration specified, you should check the box "manually calibrate image" and add the information here. To check whether your image is calibrated just look at the bar on top of the image window. If there is a calibration unit specified there is no reason for recalibrating:

• Output settings: if you add the processing date to the output file names you avoid that you will override an analysis run on the same image.

Note for customizing settings

You will in any case need to adapt the parameters Minimum size of accepted nuclei and the Maximum distance to the nuclear membrane to your study question. - Minimum size of accepted nuclei should be selected as small that still obejcts are excluded that are too small to be considered an object according to your study question.

• Maximum distance to the nuclear membrane defines the length of the intensity profiles in the output files (see section on intensity profile plots, x-axis of these plots). E.g., if you select "5.0" for this parameter, the profiles will only range from -5.0 to +5.0.

(Optionally) select images

If the option was selected, NuclQ allows you to compile a list of files to be analyzed. After generating the list, start the processing.

Initial selection of negative cells by the user

NuclQ first asks the user to draw a region of interest (ROI) in each image to be analyzed. This ROI needs to circumscribe / contain only objects that are "signal-negative" in the channels used for filtering. If you do not want to use the filtering for "signal-positive" objects you can just circumscibe any objects (nuclei) here - you however need to make sure that the ROI contains at least one object (or at least a part of it).

When all ROIs are set, all images are subjected to the analysis pipeline and all the following processing is fully-automated. A "progress dialog" informs about analysis progress. When the analysis is done the bar will turn green (on windows computers - not so on Mac computers) and the status bar will say "analysis done!" (on any opereating system).

Example for initial selection of negative cells by the user

In the following image we want to detect the blue DAPI nuclei, we want to detect only the nuclei that have a strong green and magenta signal (= that are "signal-positive" in the green and magenta channel). Thus we draw a ROI around two negative nuclei that are signal negative. Note that to add multiple regions to one ROI you need to hold shift while encircling regions. Holding shift and encircling additional nuclei allows to add more regions to the same ROI.

Image: (c) Jan N. Hansen.

Automatic Processing and Quantification

Preprocessing

NuclQ uses the channel specified as the "DAPI channel" to determine and detect objects as follows:

1. If selected by the user, NuclQ blurs the channel with a Gaussian blur based on the user-defined sigma.
2. NuclQ segments the channel into for- and background by using the selected auto-threshold algorithm.
3. NuclQ applies a Watershed algorithm to split joint objects

Detection & Filtering

NuclQ detects all the individual particles in the image as individual objects. Particles are not included if they contain less pixels than what the user has specified at .

NuclQ filters the detected objects based on intensity information in Channel 1 and Channel 2

1. NuclQ retrieves the pixel intensities in the additional channels "Channel 1" and "Channel 2" for those pixels that are positive in the segmented "DAPI channel" and that are inside the ROI selected by the user.
2. NuclQ determines the mean and standard deviation of these pixel intensities for each channel ("Channel 1", and "Channel 2").
3. NuclQ determines a threshold for each channel as mean + "fold" * standard deviation, where "fold" is the value specified by the user in the settings dialog at .
4. NuclQ segments the "Channel 1" and "Channel 2" using the determined threshold: all pixel intensities < the threshold are set to zero, all pixel intensities >= the threshold are set to the maximum intensity value (e.g., 255 in an 8-bit image)
5. The created masks are improved (made more round and less noisy) by applying a series of dilations, erosions, and hole-filling onto the masks.
   • Dilation by 1 px
   • Dilation by 1 px
   • Fill holes
   • Erosion by 1 px
   • Erosion by 1 px
   • Dilation by 1 px
   • Dilation by 1 px
   • Fill holes
   • Erosion by 1 px
   • Erosion by 1 px
6. Now objects retrieved from the "DAPI channel" (i.e., nuclei) are removed from the list of objects further analyzed if they do not overlap with the channels "Channel 1" and "Channel 2" by the percentages selected by the user in the settings dialog:

Quantification

NuclQ determines the intensity profiles that are output later:

• For each pixel in the image the distance to all outline points of all objects is computed, the closest outline point will be assigned the pixel.

• The pixel is however ignored and left unassigned, if the closest outline point is not within the acceptable range specified by the user:

• The pixel intensity is added to the individual intensity profile of the assigned outline point.

• For each object the intensity profiles of the surrounding points are analyzed.

• Depending on what the user has selected at the fraction of continuous outline points with the highest sum of intensity profile values is selected as the fraction of interest. E.g., if the user selected "4" the quarter of the outline points with the highest intensity sum is selected for further quantification.

In a final step, for each object, all intensity profiles from all surrounding points are collected and merged into the intensity profiles that are output later.

Output

NuclQ outputs a lot of different files that allow you to inspect the success of your analysis:

The naming of the file is based on the input file name (e.g., "ExampleFile.tif" above) and adding the label "_NuQ" for a NuclQ analysis, the number specified for fractioning at (e.g., "_4" above) and an outputfile specific ending. Some tif files (see e.g., ..._mp.tif below) also contain the object IDs as overlays allowing you to find a certain object in the numeric output data.

Here follows a description of each file with a screenshot of an example file - for clarity, we also provide the original image and the ROI drawn by the user on the left of some output files by their specific endings.

Output maps

• ..._bg.tif: This file shows you which objects were used for calculating the threshold for "Channel 1" and "Channel 2"

• ..._mp.tif: This image provides a distance map to show as intensity how far a pixel was to an object. The mp.tif file can be best displayed by changing the LUT to "phase" in FIJI (Image > Look-Up-Table > Phase) - see bottom screenshot.

• ..._msk.tif: This image shows the detected objects from the DAPI channel (as blue outlines), the segmeneted Channel 1 in red (2nd channel in the file), and the segmeneted Channel 2 in green (3rd channel in the file). Note that the colors here are not corresponding to the colors of the input image! The same file is also available as a rendered ..._msk.png file for direct display outside FIJI.

• ol.tif: This image outlines the detected objects after filtering and provides also the IDs of the objects, allowing to find the results for a specific object in the image also in the output text files and plot. The same file is also available as a rendered ..._ol.png file for direct display outside FIJI.

Intensity profile plots

The intensity profile plots are output for the different channels "Channel 1" (name contains ..._C1_...), "Channel 2" (name contains ..._C2_...), and "Channel of interest" (name contains ..._COI_...). For each channel there is the following .png files output:

• ..._AVG.png
• ..._SD.png
• ..._QAVG.png
• ..._QSD.png

..._AVG.png and ..._SD.png show, for each individual object (labeled as "N1", "N2", ... in the plot), the mean and standard deviation, respectively, of the pixel intensities around the object, as a function of the distance to the object border (called "outline points" in the quantification section above). The outline object border is defined as the distance value of 0. Negative distance values refer to pixels inside the object, positive distance values refer to pixels outside the object.

..._QAVG.png and ..._QSD.png are computed as the ..._AVG.png and ..._SD.png profiles but including only the continuous stretch of outline points that yielded the largest sum of pixel intensities in the profile (the length of this stretch is defined by the parameter , see quantification section for more information).

The raw values for each plot are provided in the text file (see below).

Text file with raw data

• ...m.txt: This is a tab-delimited text file that allows you to retrieve the settings applied in the analysis and the numeric values for all intensity profiles. For better seeing the table structure you may copy the contents into a table software (e.g., Excel or similar). The file starts with a Settings:-Block in which the different settings selected by the user are logged. Later the exact numeric data for each Intensity profile plot follow, in the Results:-Block. Each object is denoted as a line, the distance coordinates are denoted in columns. For each object, also the overlap with the analyzed channel is given for "Channel 1" and "Channel 2".

ROI file

• ..._.roi: This file stores the ROI that the user selected for the image. Open the image and drag and drop this .roi file into FIJI to display the ROI again in the image.

Special notes for special use cases

Extra use case 1: Use binarized input image

You may also use an image in which the object channel is already segmented (= "binarize") - in this case, unselect blurring and select the "Default" auto-threshold algorithm in the settings dialog:

Extra use case 2: No filtering

You can also run this software without filtering the object channel - to do this set the following settings to the described values:

• Set the identifiers for "Channel 1" and "Channel 2" to the same number as what you select as the object channel ("DAPI channel"). E.g., if your object channel is channel 1, set:

• Set the fold SD threshold to 0.0:

• Set the minimum overlaps to 0:

Extra use case 2: No "divisioning"

You can also run this software without revealing results for the highest-intensity region, which will speed up the analysis. In this case set the "Divisioning" to 1: