Jan 24, 2024
QuPath Immunofluorescence Cell Detection and Co-localization Protocol
- Patricia Lumanto1,2,
- Diana Nakib1,2,
- Xinle Wang1,2,
- Sonya Macparland1,2
- 1University of Toronto;
- 2University Health Network
Protocol Citation: Patricia Lumanto, Diana Nakib, Xinle Wang, Sonya Macparland 2024. QuPath Immunofluorescence Cell Detection and Co-localization Protocol. protocols.io https://dx.doi.org/10.17504/protocols.io.e6nvwdmnwlmk/v1
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
Created: November 13, 2023
Last Modified: January 24, 2024
Protocol Integer ID: 90862
Abstract
QuPath is an open-source imaging software that provides a user-friendly platform for digital pathology and whole slide image analysis. This protocol aims to provide a step-by step introduction to optimizing and running total cell detection and positive cell detection on QuPath for Immunofluorescence (IF) images. The protocol offers the possibility of assessing stain localization and co-localization within the liver immune environment and can be further applied to other tissues. Positive cell detection allows for the quantification of marker-specific positive cells across the tissue sample, and stain co-localization allows for the characterization of cells that are positive for two markers of interest, representing specific cell-cell interaction within the tissue sample, both providing a better understanding of the liver microenvironment.
This protocol was used to quantify and characterize the localization of different liver immune cell subpopulations (presence of liver sinusoidal endothelial cells, Kupffer cells, cholangiocytes, and bipotent hepatocytes) as seen in Andrews & Nakib et al. (J Hepatol 2024 doi:10.1016/j.jhep.2023.12.023).
Materials
QuPath v0.4.3
Image Brightness and Contrast Adjustment
Image Brightness and Contrast Adjustment
Click on File: Project to start a project.
Note: a project must be created in order for annotations and measurements to be exported.
Tip: prepare an empty folder with an appropriate folder name prior to starting the project.
Import the desired image by clicking on File: Open.
Note: scanned image files (e.g. .czi, .tiff) may take up quite a bit of space on your internal memory, make sure sufficient space is available on your local drive.
Select View: Brightness/Contrast
- Select the desired channels for visualization (e.g. DAPI, AF568)
Table containing the different stains used for this experiment and their respective colors.
Double click on any channel to change its name and color.
Note: the original scan colors are not permanent and can be changed to make visualization easier.
Tip: complementary colors (e.g. red and green, yellow and purple) will be easiest to distinguish for visualization.
Pop up box to be used to change the channel name and channel color, through the drop down menu.
Adjust the brightness and contrast of the image by changing the min and max display values using the slider.
Note: The default gamma value is 1.
Tip: Refer to IHC experiments (e.g. from The Human Protein Atlas) to help visualize expected stain localization and intensity.
Comparison of an optimally adjusted image (left) vs oversaturated image (right).
Region of Interest Selection and Annotation
Region of Interest Selection and Annotation
Use rectangle tool to select region of interest.
Rotate the rectangle by using the transform tool (Objects: Annotations: Transform annotations).
Select the rectangle and run the following script (Automate: Show script editor).
Note: if lengthwise sections are preferred, change "d1 < d2" to "d1 > d2" (on line 45 of the script).
Tip: change the name for each region of interest by changing the ROI number ("ROI 1 Layer ${i+1}") on the last line of the script.
-----------------------------------------------------------------------------------------------
/**
* Split a rectangle into equal parts along its longest dimension.
* Rotated rectangles are supported.
*
* Written for https://forum.image.sc/t/how-to-divide-annotation-roi-into-equal-dimension-bins/51563/8
*
* @author Pete Bankhead
* Taken from https://gist.github.com/petebankhead/e177b07784460a76d70f89347edd988d
*/
// Number of regions to create
int nRegions = 10
// Get selected object
def selected = getSelectedObject()
if (selected == null) {
println 'No object selected!'
}
// Get points, removing duplicates
def roi = selected.getROI()
def points = new LinkedHashSet<>(roi.getAllPoints()) as List
if (points.size() != 4) {
println 'I need a ROI with exactly 4 points'
return
}
// Get the side lengths
double d1 = points[1].distance(points[0])
double d2 = points[2].distance(points[1])
double d3 = points[3].distance(points[2])
double d4 = points[0].distance(points[3])
// Check we really have a rectangle
// (Set this to a higher number of it's too strict)
double eps = 0.01
if (Math.abs(d1 - d3) > eps || Math.abs(d4 - d2) > eps) {
println 'Points do not appear to form a rectangle!'
return
}
// Get starting point based on longest side
int ind = 0
if (d1 < d2) {
points.add(0, points.remove(3))
}
double x = points[ind].x
double y = points[ind].y
double dx = (points[ind+1].x - x) / nRegions
double dy = (points[ind+1].y - y) / nRegions
double dx2 = (points[ind+2].x - points[ind+1].x)
double dy2 = (points[ind+2].y - points[ind+1].y)
// Add annotations
def annotations = []
for (int i = 0; i < nRegions; i++) {
double originX = x + dx*i
double originY = y + dy*i
def polygon = ROIs.createPolygonROI(
[originX, originX+dx, originX+dx+dx2, originX+dx2] as double[],
[originY, originY+dy, originY+dy+dy2, originY+dy2] as double[],
roi.getImagePlane()
)
def newAnnotation = PathObjects.createAnnotationObject(polygon)
newAnnotation.setName("ROI 1 Layer ${i+1}") //To change ROI number
annotations << newAnnotation
}
addObjects(annotations)
-----------------------------------------------------------------------------------------------
Script editor pop up box to be used when a script is required.
Rename Annotations by right clicking on the selected layer then select Set properties.
List containing the different layers and regions of interest along with their given names.
Positive Cell Detection and Measurements
Positive Cell Detection and Measurements
Select the region (largest rectangle) and click on Analyze: Cell detection: Positive Cell Detection.
Select the desired stain for cell detection by clicking on the drop down menu next to Detection channel.
Modify the Threshold value such that all positive cells are accounted for.
Note: a threshold of 300-400 would be ideal for a DAPI nuclei stain.
Change the Score compartment by clicking on the dropdown menu next to it such that the stain selected matches its localization within the cell.
Note: it is easier to adjust the threshold when stain localization is known (e.g. Nucleus: DAPI max)
Tip: if unsure about stain localization, select the cell option for easiest detection.
Positive cell detection pop up box containing the different adjustable parameters.
Click Run to start positive cell detection.
- Keep adjusting the Threshold value until the correct cells are detected.
- Note: it may take several adjustments to optimize the threshold value, zoom in and our of the image, if necessary, to help determine appropriate detection.
- Repeat for other regions
Cell Detection and Co-localization
Cell Detection and Co-localization
Select the annotation and run cell detection by clicking Analyze: Cell detection: Cell detection.
Select the desired stain for cell detection by clicking on the drop down menu next to Detection channel.
Modify the Threshold value such that all positive cells are accounted for.
Note: a threshold of 300-400 would be ideal for a DAPI nuclei stain.
Change the Score compartment by clicking on the dropdown menu next to it such that the stain selected matches its localization within the cell.
Note: it is easier to adjust the threshold when stain localization is known (e.g. Nucleus: DAPI max)
Tip: if unsure about stain localization, select the cell option for easiest detection.
Cell detection pop up box containing the different adjustable parameters.
- If only cell detection or cell count is required, skip steps 12 to 16 and move forward with the file export.
- If co-localization assessment is required proceed to step 12.
Create new classes by going to Annotations, and right clicking on the class list to add a new class.
Tip: creating classes for both positive and negative cells makes classification easier (e.g. HNF4A and non-HNF4A).
Class list containing positive and negative cell classes for a particular stain.
Create cell classifications by clicking Classify: Object classification: Create single measurement classifier.
Select the desired channel filter (e.g. DAPI, AF647) by clicking on the dropdown menu next to Object filter.
Adjust the Threshold using the slider.
Note: turn on live preview for better visualization.
Save the classifier using the stain name.
Single measurement classifier window with the different adjustable parameters.
Select the region of interest (previously selected using the rectangle tool).
Classify object by clicking Classify: Object classification: Load object classifier.
Apply object classification by clicking on the name of each classifier then clicking Apply classifier.
Tip: To apply more than one classifier to the same region select both using the command or control key and click Apply classifier sequentially.
Classifier window showing the different classes created applied to an immunofluorescence image. Colors shown corresponds to the same color as previously picked when creating classes on the Annotations window. The blue and yellow circles represent single positive cells, respective to stain; while the green and white circles represent double positive and negative cells, respectively.
File Export
File Export
Click on Measurements: Export measurements to export data into a tsv file.
- Click on export annotations.
- Click on browse to select a name and file path for the export.
Note: the generated tsv file can be opened on spreadsheet programs such as Microsoft Excel and copied to data analyzing softwares.
Protocol references
1. Tallulah S. Andrews*, Diana Nakib*, Catia T. Perciani, Xue Zhong Ma, Lewis Liu, Erin Winter, Damra Camat, Sai W. Chung, Patricia Lumanto, Justin Manuel, Shantel Mangroo, Bettina Hansen, Bal Arpinder, Cornelia Thoeni, Blayne Sayed, Jordan Feld, Adam Gehring, Aliya Gulamhusein, Gideon M. Hirschfield, Amanda Ricciuto, Gary D. Bader, Ian D. McGilvray, Sonya MacParland 2024. Single-cell and spatial transcriptomics characterisation of the immunological landscape in the healthy and PSC human liver. Journal of Hepatology.
2. Xinle Wang, Catia Perciani, Xue-Zhong Ma, Chao Jiang, Justin Manuel, Sai Chung, Cornelia Thoeni, Trevor McKee, Ian McGilvray, Sonya Macparland 2021. QuPath Digital Quantification of Liver Immune Cells. protocols.io. https://dx.doi.org/10.17504/protocols.io.bs6gnhbw