TITLE: CODA (part 4): register the deep learning labelled images and Construct 3D tissue matrix | HuBMAP | JHU-TMC
AUTHORS: Kyu Sang Han, Pei-Hsun Wu, Joel Sunshine, Ashley Kiemen, Sashank Reddy, Denis Wirtz

[DESCRIPTION]
CODA (part 4): register the deep learning labelled images and Construct 3D tissue matrix

[STEPS]
SECTION: Register the deep learning labelled images
1. 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.
SECTION: Function requirements
2. High-resolution images from CODA-part3 (pthclassified)
SECTION: Function requirements
3. The path containing the image registration information from CODA-part2 (pthdata),
SECTION: Function requirements
4. 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)
SECTION: Function requirements
5. The pixel number of the background class in the segmentation model built in CODA-part3 (here, nwhite=3)
SECTION: Execution
6. pthim=pthclassified;
pthdata=[pth,'1x\registered\elastic
registration\save_warps'];
scale=10;
padnum=3;
apply_image_registration(pthim,pthdata,scale,padnum);
SECTION: Execution
7. This function will create an subfolder named ‘registeredE’ inside the pthclassified folder that contains the registered, classified images. pthclassifiedE=[pthclassified,'registeredE'];
SECTION: Construct 3D tissue matrix
8. 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.
SECTION: Construct 3D tissue matrix
9. 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
SECTION: Construct 3D tissue matrix
10. pthclassifiedE is the subfolder with the registered, classified images created in earlier steps in this protocol:

pthclassifiedE=[pthclassified,'registeredE'];
SECTION: Construct 3D tissue matrix
11. Define a subfolder where you would like to save the volumetric data:
pthvolume=[pth,'lung_data'];
  
SECTION: Construct 3D tissue matrix
14. cmap is the matrix containing RGB triplets for each class in the deep learning model
cmap=[];
  
build_tissue_volume(pthclassifiedE,pthvolume,sk,nwhite,cmap);
SECTION: Construct 3D tissue matrix
12. Set sk to 4 so that 10x image (1 um / pixel resolution) are downsampled to 4 micron / pixel:
sk=4;
 
SECTION: Construct 3D tissue matrix
13. nwhite is the background class from the deep learning model. Here, let’s use 6:
nwhite=6; 
  
SECTION: Construct 3D tissue matrix
15. 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.
SECTION: Construct 3D tissue matrix
16. 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.  
SECTION: Construct 3D tissue matrix
17. 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.
SECTION: Note: When determining what resolution to make your volumetric matrix, there are a few considerations:
18. 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
SECTION: Note: When determining what resolution to make your volumetric matrix, there are a few considerations:
19. 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.