Apr 16, 2024

Public workspaceCODA (part 6): register the nuclear coordinates and construct 3D cell matrix | HuBMAP | JHU-TMC V.2

DOI
dx.doi.org/10.17504/protocols.io.n2bvjnrnxgk5/v2
  • 1Johns Hopkins University;
  • 2Johns Hopkins Medicine
Kyu Sang Han
Open access
DOI: dx.doi.org/10.17504/protocols.io.n2bvjnrnxgk5/v2
Protocol Citation: Kyu Sang Han, Pei-Hsun Wu, Joel Sunshine, Ashley Kiemen, Sashank Reddy, Denis Wirtz 2024. CODA (part 6): register the nuclear coordinates and construct 3D cell matrix | HuBMAP | JHU-TMC. protocols.io https://dx.doi.org/10.17504/protocols.io.n2bvjnrnxgk5/v2Version created by Kyu Sang Han
Manuscript citation:
A.M. Braxton, A.L. Kiemen, M.P. Grahn, A. Forjaz, J. Parksong, J.M. Babu, J. Lai, L. Zheng, N. Niknafs, L. Jiang, H. Cheng, Q. Song, R. Reichel, S. Graham, A.I. Damanakis, C.G. Fischer, S. Mou, C. Metz, J. Granger, X.-D. Liu, N. Bachmann, Y. Zhu, Y.Z. Liu, C. Almagro-Pérez, A.C. Jiang, J. Yoo, B. Kim, S. Du, E. Foster, J.Y. Hsu, P.A. Rivera, L.C. Chu, D. Liu, E.K. Fishman, A. Yuille, N.J. Roberts, E.D. Thompson, R.B. Scharpf, T.C. Cornish, Y. Jiao, R. Karchin, R.H. Hruban, P.-H. Wu, D. Wirtz, and L.D. Wood, “3D genomic mapping reveals multifocality of human pancreatic precancers”, Nature (2024)

A.L. Kiemen, A. Forjaz, R. Sousa, K. Sang Han, R.H. Hruban, L.D. Wood, P.H. Wu, and D. Wirtz, “High-resolution 3D printing of pancreatic ductal microanatomy enabled by serial histology”, Advanced Materials Technologies 9, 2301837 (2024)

T. Yoshizawa, J. W. Lee, S.-M. Hong, D.J. Jung, M. Noe, W. Sbijewski, A. Kiemen, P.H, Wu, D. Wirtz, R.H. Hruban, L.D. Wood, and K. Oshima. “Three-dimensional analysis of ductular reactions and their correlation with liver regeneration and fibrosis”, Virchows Archiv (2023).

A.L. Kiemen, A.I. Damanakis, A.M. Braxton, J. He, D. Laheru, E.K. Fishman, P. Chames, C. Almagro Perez, P.-H. Wu, D. Wirtz, L.D. Wood, and R. Hruban, “Tissue clearing and 3D reconstruction of digitized, serially sectioned slides provide novel insights into pancreatic cancer”, Med 4, 75-91 (2023)

A. Kiemen, Y. Choi, A. Braxton, C. Almagro Perez, S. Graham, M. Grahm, N., N. Roberts, L. Wood, P. Wu, R. Hruban, and D. Wirtz, “Intraparenchymal metastases as a cause for local recurrence of pancreatic cancer”, Histopathology 82: 504-506 (2022)

A.L. Kiemen, A.M. Braxton, M.P. Grahn, K.S. Han, J.M. Babu, R. Reichel, A.C. Jiang, B. Kim, J. Hsu, F. Amoa, S. Reddy, S.-M. Hong, T.C. Cornish, E.D. Thompson, P. Huang, L.D. Wood, R.H. Hruban, D. Wirtz and P.H. Wu, “CODA: quantitative 3D reconstruction of large tissues at cellular resolution”, Nature Methods 19: 1490-1499 (2022)

K.S.Han, I. Sander, J. Kumer, E. Resnick, C. Booth, B. Starich, J. Walston, A.L. Kiemen, S. Reddy, C. Joshu, J. Sunshine, D. Wirtz, P.-H. Wu "The microanatomy of human skin in aging." bioRxiv (2024): 2024-04.
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
We use this protocol and it's working
Created: April 16, 2024
Last Modified: April 16, 2024
Protocol Integer ID: 98299
Keywords: CODA, deeplearning, machinelearning, semanticsegmentation
Funders Acknowledgement:
Institute of Arthritis and Musculoskeletal and Skin Diseases
Grant ID: U54AR081774
National Cancer Institute
Grant ID: U54CA143868
Abstract
Using the registration transformations calculated in low-resolution (as described CODA (part 2): calculate registration on low-resolution tissue images), register the nuclear coordinates generated in CODA (part 5): nuclear coordinate generation
register the nuclear coordinates
register the nuclear coordinates
As input, this function needs the path to the low-resolution images that were registered in CODA-part2 (pth1x), the path containing the coordinates calculated in CODA-part4 (pthcoords), and the scale factor between these images. For cell detection performed in 10x and registration calculated in 1x,

scale=10;
register_cell_coordinates(pth1x,pthcoords,scale);

*if the yellow dots do not line up over the tissue, there is a problem in your code.
This function will create a subfolder inside pthcoords named ‘cell_coordinates_registered.’ Inside that subfolder will be a mat file corresponding to each tif image. Inside each mat file will be a variable named ‘xy’ (unregistered cell coordinates), ‘xyg’ (globally registered cell coordinates), and ‘xye’ (elastically registered cell coordinates), all saved at the same low-resolution as the original registration images used in CODA-part2.

pthcoordsE=[pthcoords,'cell_coordinates_registered'];
construct 3D cell matrix
construct 3D cell matrix
Next, create volcell, a matrix containing the nuclear labels in a volumetric matrix the same size and resolution of the tissue matrix constructed in CODA-part4. To call this function, you need to define the folder containing the registered, classified images created in CODA-part4, the folder containing the registered cell coordinates, the folder containing the tissue matrix created in CODA-part4, and the scale between the high-resolution, classified images and the high-resolution images used for cell detection (this is probably 1).
Define the folders containing the registered, classified images, the registered nuclear coordinates, and the tissue volume matrix:

pthclassifiedE=[pthclassified,'registeredE'];
pthcoordsE=[pthcoords,'cell_coordinates_registered'];
pthvolume=[pth,'lung_data'];
Next, define the scale between the high-resolution images used for tissue classification in CODA-part3 and the high-resolution images used for cell detection in CODA-part5. If the classification and cell detection were applied to the same resolution images (this is likely), the scale is 1.

scale=1;
Finally, nwhite is the whitespace class from the deep learning model. Here, let’s again use nwhite=6 (the background class number from the sample lung model.

nwhite=6;
Now, call the make_volcell function:

build_cell_volume(pthclassifiedE,pthcoordsE,pthvolume,scale,nwhite)

This function will create a 3D matrix containing nuclear coordinates. The matrix will be at the same resolution as the tissue volume matrix, and automatically crop out the same background space that was manually selected for removal in CODA-part4.
To validate that the function creates a variable volcell that is the same resolution and crop as the tissue matrix vol, the function will display two images.

1. the function will display an overlay of the center image from vol and volcell.
2. the function will display an overlay of the z-projections of vol and volcell.
If either of these images do not appear overlayed (you see two separate, unaligned tissues), there was a problem with the construction of either vol or volcell.
Beyond the scope of this guide, consider volshow or patch
Notes on quantification
Notes on quantification
Primarily beyond the scope of this guide, as most spatial calculations must are custom to the biological question. Some basic considerations are in the following sections
Smooth data
Smooth data
To smooth your data. Your segmentation algorithm and 3D volumetric matrix will likely contain small false positive and false negative data. Try smoothing your volumetric data with the following.

vol = volumetric matrix of size [m n z] containing 6 labels for 5 tissue structures plus background

ws = 6; % background class for volumetric matrix

to lightly smooth the tissue labels inside vol:
volS=vol; %
create a smoothing variable

for b=1:max(vol(:))
tmp=vol==b;
tmp=imclose(tmp,strel(‘sphere’,2)); % morphological closing to fill small holes
tmp=imopen(tmp,strel(‘sphere’,1)); % morphological opening to remove small noise
tmp=bwareaopen(tmp,500); % delete 3D objects that are fewer than 500 voxels;
volS(volS==b)=ws;
volS(tmp==1)=b;
end

Note: be VERY CAUTIOUS using imopen to smooth thin structures (glands and vasculature), as imopen may eliminate “true positive” thin walls. Consider skipping imopen when you smooth
Quantify volume
Quantify volume
To quantify volumes. volume of tissue class 2 (use vol or your smoothed volS):

sxy=4; % resolution of ‘vol’ matrix in xy in units of micron / pixel
sz=4; % distance between serial histological sections
volume_type_2=sum(vol(:)==2)*sx*sx*sz; % volume of type 2 in units of micron3
volume_type_2=volume_type_2/(10^9); % volume of type 2 in units of mm3
Quantify cellularity
Quantify cellularity
To quantify cellularity.  number of cells in class 2 (use vol or your smoothed volS):

tmp=double(volcell).*double(vol==2);
cell_type_2=sum(tmp(:));
And more
And more
For more complex quantifications:

Consider the functions bwdist, regionprops3, and custom functions you create.