Apr 18, 2024
Version 2
CODA (part 2): calculate registration on low-resolution tissue images | 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 2): calculate registration on low-resolution tissue images | HuBMAP | JHU-TMC. protocols.io https://dx.doi.org/10.17504/protocols.io.kxygxym3dl8j/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: 98444
Keywords: CODA, machinelearning, deeplearning, ai, matlab, digitalpathology
Funders Acknowledgement:
Institute of Arthritis and Musculoskeletal and Skin Diseases
Grant ID: U54AR081774
National Cancer Institute
Grant ID: U54CA143868
Abstract
CODA workflow part 2. Calculate registration on low-resolution tissue images
Calculating the tissue space
Calculating the tissue space
For most images, a resolution of 1x should be sufficient. If the 1x results are not well registered, or registration of small tissues (such as needle biopsies) is desired, try calculating registration at a higher resolution such as 2x or 4x.
The quality of the registration depends on first calculating the tissue space in each image, as this allows removal of noise (shadows and lines that aren’t tissue within the whole slide image).
The presence of noise in the images during registration can affect the codes determination of registration accuracy (QC step), as this is determined through pixel-to-pixel cross correlation.
Create logical images indicating locations containing tissue with the function calculate_tissue_ws. This function has two methods of calculating the tissue space.
First try with method 1:
calc_style=1;
calculate_tissue_ws(pth1x, calc_style);
This function will create logical images with the same filenames as the images in pth1x, saved in a subfolder named ‘TA’. Check that these tissue images look correct (are not white over background, nontissue space in the image, only white on tissue regions).
If they do not look correct, delete the images inside the folder named ‘TA’ and try again, using method 2:
calc_style=2;
calculate_tissue_ws(pth1x, calc_style);
Apply the CODA nonlinear image registration to the low-resolution tiff images
Apply the CODA nonlinear image registration to the low-resolution tiff images
Next, apply the CODA nonlinear image registration to the low-resolution tif images. Note, this function can be applied without first creating the tissue masks with calculate_tissue_ws. The registration code will by default use method 1 to create the tissue masks. But it is best practice to first calculate the tissue masks and validate that they are accurate to ensure the best registration quality is achieved.
calculate_image_registration(pth1x);
This function will create output folders containing the globally registered images, the elastically registered images, and the registration transformation metadata:
pth1xG=[pth1x,'registered'];
pth1xE=[pth1x,'registered\elastic registration'];
pthdata=[pth1x,'registered\elastic registration\save_warps\'];
Validate the image registration by loading the elastically aligned, downsampled z-stack in ImageJ. These validation images will be saved in a subfolder within the folder containing the low-resolution tif images:
pth_validate_regisration=[pth1x,'registered\elastic_registration\check'];
Notes on debugging registration: If your results are bad and you would like to re-register with different parameters, first delete the ‘registered’ folder (inside pth1x) created by calculate_image_registration. If you do not delete this subfolder the registration code will skip all images that were previously registered.
If the elastically registered images are too jiggly, try reducing szE and/or diE inside calculate_image_registration
If the elastically registered images are too smeared, try increasing szE and/or diE inside calculate_image_registration
If the registration is taking too long for one image (>5 min), try reducing the resolution of the images, reduce the szE or diE inside calculate_image_registration and/or try a computer with higher RAM