Apr 18, 2024
Version 2
CODA (part 4): register the deep learning labelled images and Construct 3D tissue matrix | HuBMAP | JHU-TMC V.2
- Kyu Sang Han1,
- Pei-Hsun Wu1,
- Joel Sunshine2,
- Ashley Kiemen2,
- Sashank Reddy2,
- Denis Wirtz1,2
- 1Johns Hopkins University;
- 2Johns Hopkins Medicine
Protocol Citation: Kyu Sang Han, Pei-Hsun Wu, Joel Sunshine, Ashley Kiemen, Sashank Reddy, Denis Wirtz 2024. CODA (part 4): register the deep learning labelled images and Construct 3D tissue matrix | HuBMAP | JHU-TMC. protocols.io https://dx.doi.org/10.17504/protocols.io.yxmvme7eog3p/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 18, 2024
Last Modified: April 18, 2024
Protocol Integer ID: 98442
Keywords: CODA, deeplearning, semanticsegmentation
Funders Acknowledgement:
Institute of Arthritis and Musculoskeletal and Skin Diseases
Grant ID: U54AR081774
National Cancer Institute
Grant ID: U54CA143868
Abstract
CODA (part 4): register the deep learning labelled images and Construct 3D tissue matrix
Register the deep learning labelled images
Register the deep learning labelled images
Using the registration transformations calculated in low-resolution (as described in CODA-part2), register the segmentation masks of the high-resolution tif images generated in CODA-part3.
Function requirements
Function requirements
The scale between the high-resolution classified images and the low-resolution registration images (here for registration of 1x images and classification of 10x images, scale=10)
The pixel number of the background class in the segmentation model built in CODA-part3 (here, nwhite=3)
Execution
Execution
pthim=pthclassified;
pthdata=[pth,'1x\registered\elastic
registration\save_warps'];
scale=10;
padnum=3;
apply_image_registration(pthim,pthdata,scale,padnum);
This function will create an subfolder named ‘registeredE’ inside the pthclassified folder that contains the registered, classified images. pthclassifiedE=[pthclassified,'registeredE'];
Construct 3D tissue matrix
Construct 3D tissue matrix
Next, we will create a 3D quantifiable matrix from the tissue labels using the registered, segmented images we just created above. vol will be a 3D matrix containing the registered, labelled data.
To call this function, you need to locate the subfolder containing the registered classified images, define a location to save the output matrix, define the desired resolution of the volume matrix (relative to the current resolution of the images, and identify the RGB color map used in the deep learning model in CODA-part3
pthclassifiedE is the subfolder with the registered, classified images created in earlier steps in this protocol:
pthclassifiedE=[pthclassified,'registeredE'];
Define a subfolder where you would like to save the volumetric data:
pthvolume=[pth,'lung_data'];
Set sk to 4 so that 10x image (1 um / pixel resolution) are downsampled to 4 micron / pixel:
sk=4;
nwhite is the background class from the deep learning model. Here, let’s use 6:
nwhite=6;
cmap is the matrix containing RGB triplets for each class in the deep learning model
cmap=[];
build_tissue_volume(pthclassifiedE,pthvolume,sk,nwhite,cmap);
First, the function will display to you a concatenated image containing the first, center, and last classified image in your image stack. Here, you will manually drag a rectangle to surround the tissue in the image, then double-click. This allows you to crop out excess whitespace from your 3D matrix to save RAM.
Next, the function will load all serial images, crop them, downsample them using the variable sk, and build them into the matrix vol. A z-projection will be created and displayed showing a combination of all non-background classes. This z-projection will be saved inside the folder pthvolume.
Additionally, this function will create a .mat file named volume.mat saved inside the subfolder pthvolume. Inside this file will be a variable named vol containing the volumetric tissue labels, rr containing the cropping information defined inside the function, pthclassifiedE the folder containing the registered classified images used to create the volume, imlist containing the filenames of the images comprising the 3D matrix, and sk the downsample factor between the images in imlist and the data in vol.
Note: When determining what resolution to make your volumetric matrix, there are a few considerations:
Note: When determining what resolution to make your volumetric matrix, there are a few considerations:
You may want to make your 3D matrix isometric (same resolution in x, y, and z) to simplify 3D quantifications. In this case, define sk such that your classified images will be downsampled to the spacing between adjacent histological images
You may want to consider the size of structures you are trying to quantify. If you need to maintain classification of very fine structures (such as thin blood vessels), down sampling too much may eliminate the connectivity between these thin objects.