TITLE: Mouse Brain Heatmap - Whole brain data compilation and quality control
AUTHORS: Michael X. Henderson, Daniella DeWeerd, Kevin Kurgat

[DESCRIPTION]
This is a protocol for R shiny apps that accept output from the QUINT workflow (or similar mouse brain registration and segmentation data) and allows you to create grid and anatomical heatmaps using the Allen Brain Atlas CCFv3 for mouse brain data. The two applications are compiled onto a singular webpage at: https://github.com/MXHend/Mouse-Brain-Heatmap-Website

[BEFORE_START]

Preparation

First, create a folder that will contain all your data for this project and name it whatever you would like. Within this folder, create two folders labeled ‘left’ and ‘right’ for hemispheres. If you only have one hemisphere of data, just create a singular folder labeled ‘data’.

After completing the QUINT workflow, you should have a folder (or more likely, multiple folders) called “Reports” which contains another folder with an ending label of RefAtlasRegions. In this folder will be at least two files with one of them having the same name as the folder. Ignore that file and copy the rest into the appropriate folder within the project folder you created in the beginning. Do this for every report folder you have until all the files are located in those two (or one) folders in your project folder. You may now open the website. 


[GUIDELINES]

Anatomical heatmap

Purpose

          This program plots regional quantification matrices composed of Nutil outputs in anatomical space (ABA CCFv3). This input matrix can be compiled using N2U or manually. Plots consist of coronal sections based on the Allen Brain Atlas and present options of single or multi-figure plots displaying your parameter of interest in anatomical regions and subregions. 

 


Plotting Options

Users will have the option to develop Raw data single-figure or multi-figure plots with either the mean or median displayed for each anatomical region. Figure Numbers refer to the image numbers on the ABA website.

Under the Raw Data single-figure tab in the MBH webpage, plots can be generated comparing regional data across conditions (MPI, Genotypes, Treatments, Markers, Sex) for a single figure. The Raw data multi-figure tab allows you to generate plots for multiple figures, consisting of coronal sections spanning across the brain, but will only display a single condition at a time.

Users also have the option to plot at the daughter level by default which includes all atlas regions and subregions down to the specific layer/part (e.g. MOp2/3, MOp5, BLAp), or the parent level which plots more generally the main regions at the top of atlas hierarchy inclusive of all layers/parts (e.g. MOp, BLA).


Notes

Min/Max: 

At the moment, the min and max can only be adjusted in N2U. If you would like to adjust the minimum and maximum values displayed, a new MBH Table will need to be created with adjusted min/max. 


[STEPS]
SECTION: Using N2U for the first time
1. Begin by hitting the browse button labeled for the ‘left side’ and select all files in the ‘left’ folder.
SECTION: Using N2U for the first time
2. Hit the ‘open’ button to start loading the data.
SECTION: Using N2U for the first time
1.1. If you have a ‘data’ folder, select all files in that folder instead. 
SECTION: Using N2U for the first time
3. While that is loading you can hit the browse button labeled for the ‘right side’ and select the files in the ‘right’ folder and hit the ‘open’ button to begin loading that data.
SECTION: Using N2U for the first time
4. Wait until there is a message on the right side of the app that says the last side you loaded is done.
SECTION: Using N2U for the first time
5. Double check that the above step has appeared and then click the button labeled ‘click this when all files are done loading’. 
SECTION: Using N2U for the first time
6. Wait until the message on the right side changes and mentions the ‘blank annotation’ and the ‘checkpoint’ are done. 
SECTION: Using N2U for the first time
7. Press the button labeled ‘Download Checkpoint 1’ and save it within your project folder. This will be used the next time you load the data. 
SECTION: Using N2U for the first time
8. Press the button labeled ‘Download blank annotation file’ and save it within your project folder. 
SECTION: Using N2U for the first time
9. Open your file explorer and navigate to your project folder. 
SECTION: Using N2U for the first time
10. Open the annotation file you just downloaded and fill out all columns labeled with “NA” (if you don’t have a column, then you may leave it NA) 

 

SECTION: Using N2U for the first time
11. Save this file as a CSV file with a different name so that you know you have completed it. 
SECTION: Using N2U for the first time
12. Reload the webpage or stop and restart the RStudio app. 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
13. Begin by clicking the Browse button labeled by the phrase ‘Input checkpoint 1 here’ and select “checkpoint1.rds” you saved earlier and click ‘open’.
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
14. Check the right side of the screen for confirmation that the checkpoint is done loading and then click the browse button to input in the annotation file you finished creating.
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
15. Once that has completed (check the right side for text saying has finished), download Checkpoint 2 somewhere you have easy access to

 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
16. Once that is complete you may notice that the box labeled for selecting your ‘x axis variables’ now has options to choose from. Please note the following when you select these variables: 

 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
17. Next, select the ‘y axis variables’ and note the following when selecting them: 

 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
18. Select the ‘display’ y axis variables next noting the following:

 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
19. When you have selected variables for all the above options, click the button labeled ‘Get Options’.

 
 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
20. Next, look at all the options that are selected in the box labeled with ‘variables to see’ and confirm you want to see all of the above variables on the heatmap.


 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
21. This step will determine the values of the heatmap, so pay close attention: From the dropdown list labeled ‘select the nutil variable’, select the variable you will be using as your value (i.e. Load)

 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
22. If you would like to change the variable in any way: 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
22.1. Select Multiply by 100 if you would like to do as stated. 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
23. If you would like the data to be in log 10 scale: check the corresponding box. 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
22.2. Select Use variables if you would like to select variables to create a percentage. Select the variables based on the following information: 

Segments by each variable labeled here and then creates percentages of any other variable you selected above that is not in this box. 
Here the program will group your data based on your selections and create a percentage separating from the largest to the smallest designation. For example: 
 If your rows were ‘mouse’ and ‘marker’ (marker has two options per mouse), your selected nutil variable was ‘object count’, and you selected, ‘Mouse’, ‘side’, and ‘daughter’ here; it would first separate the data by mouse, then by side, then by daughter. Then it would look at the designations of the row and see that it’s separated by mouse and marker so it calculates the percent each marker takes up as it is already segmented by mouse.
If you are hoping to compare the percentage of elements in a variable (such as ‘pSyn+’ to ‘pSyn-‘ in the variable ‘marker’), then do not include that variable in this segmentation as it would then turn out to be 100% for each of them 
Common Examples:
 ‘side’, ‘mouse’, and ‘daughter’
 ‘mouse’, ‘daughter’ 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
22.3. 
 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
24. If you would like your heatmap to be trimmed: check the corresponding box. (This does not affect the calculations.) 

 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
25. If you would like to remove ABA regions from your heatmap, select any amount of them from the drop down labeled ‘Select any regions to remove’.
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
26. If you would like row and column names: select from the corresponding drop down boxes and select what you would like to see. 

 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
27. The color scale is not something you will need to adjust your first time loading the heatmap. 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
28. Now that you are done selecting the base variables for your heatmap, click the button labeled ‘Create heatmap’ and wait for a preview to appear in the right side. 

 

SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
29. Now that the heatmap is done, you will note some text at the top of the right side which says ‘min’ and ‘max’. Please enter these values into the textboxes labeled ‘Min Value’ and ‘Max Value’ for the color scale.
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
30. At this point, you can adjust the options under the label ‘Custom Colors’. If you would like to, then select either the Viridis color scale checkbox, the 2 color scale checkbox, or the 3 color scale box, and then choose or adjust the colors to what you would like. 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
31. When you are done, click the ‘create heatmap’ button again and wait for the preview to appear. 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
32. To save the heatmap: you have two options you can choose from or download both. 

Click the button labeled ‘Download full Heatmap’ and this will download a heatmap with all the information you selected above. Make sure to download it into a directory you can easily access to check if you like your chosen options.
Click the button labeled ‘Download Just the Plot’ and this will download a heatmap without any of the legends for easy editing. Make sure to download it into a directory you can easily access to check if you like your chosen options. 
SECTION: Using N2U when you have saved checkpoint 1 and completed filling out the annotation file
33. Look at your heatmap and determine if you need to change anything. If you do, start from step 3 and check over each step at a time. 

 

SECTION: Using N2U when you have saved checkpoint 2
34. Begin by clicking the Browse button labeled by the phrase ‘Input checkpoint 2 here’ and select “checkpoint2.rds” you saved earlier and click ‘open’.
SECTION: Using N2U when you have saved checkpoint 2
35. Check the right side of the screen for confirmation that the checkpoint is done loading and then continue from step 4 above. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
36. If you would like to display data in anatomical space, take it into the MBH app, click the ‘Download MBH Table’ button and save it wherever you can access it. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
37. If you would like the color scheme to also be the same in the MBH app, click the ‘Download Colors’ button. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
38. If you would like the values of the heatmap or any of the axis annotation information of the heatmap, click the buttons labeled ‘Download Data’, ‘Download AnnoX’, and ‘Download AnnoY'.
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39. Finally, if you would like access to the many variables created during this program running or
the data frame that contains the raw data at any point: 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.1. Open the app in R Studio.
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.2. Run through all of the steps. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.3. Once it has created a heatmap, wait a minute or two for everything to fully load. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.4. Click back into R Studio without closing the app.
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.5. Find the console in the bottom left corner and click the button that looks like a stop sign ONCE and only once. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.6. Wait very patiently for the app to close on its own. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.7. If it gives you an error like below click ‘No’ and wait some more.

 

SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.8. Eventually it will stop the app and variables will appear in the top right box labeled ‘environment’. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.9. To see these variables, double click their names to open a viewer pane. 
SECTION: For integration with the Mouse Brain Heatmap (MBH) app for anatomical heatmaps OR additional numeric and/or annotation information for the heatmap
39.10. To save a variable as a csv file write the following code in the console:

.write.csv(variableName, “filename.csv”)
 If you would like to designate the location of the file, include the file path in front of the filename  with all back slashes replaced with forward slashes 

 “~\projects\file.csv” is incorrect
 “~/projects/file.csv” is correct
SECTION: Anatomical heatmap - Input
40.  Determine whether you want to plot single or multi-figure plots. Upload your compiled matrix by hitting browse on the prompt ‘Please upload the MBH table output’.

This should be labeled as ‘MBHTable’ and is generated after selecting ‘Download MBH
table’ in the N2U program.
 In theory, any csv file following the same format as seen in the MBH table would suffice
for this workflow. 

SECTION: Anatomical heatmap - Heatmap Colors
41. If you generated a custom color scheme in the N2U app, upload the .rds file in the browse button under the ‘If desired, upload heatmapColors.rds here’ (not a necessary step if using the default scheme).
SECTION: Anatomical heatmap - Figure Numbers
42.  Select the Figure Number corresponding to the sections for your project.
SECTION: Anatomical heatmap - Summary Level
43. Select the measure summary you would like to have plotted.

 

SECTION: Anatomical heatmap - Region Level
44. Select the depth level for atlas regions.

 

SECTION: Anatomical heatmap - Conditions
45.  The remaining dropdowns allow you to choose what you would like to plot.
SECTION: Anatomical heatmap - Plot Data
46. Select ‘Plot data’ to create the heatmaps you have set. This may take time to load. Each time you adjust conditions or inputs you will need to reselect ‘Plot data’ to see the new plots.
SECTION: Anatomical heatmap - Plot Data
47. ‘Download Plot’ generates .svg files for generated plots.
SECTION: Anatomical heatmap - Plot Data
48. ‘Download Data’ generates a .csv with information on what anatomical regions are plotting and the values being displayed in each.
SECTION: Anatomical heatmap - Figure Numbers
42.1. This will only be one Figure Number if creating single-figure plots. Multi-figure Numbers should be separated by a comma without spaces between them.
SECTION: Anatomical heatmap - Figure Numbers
42.2. If you are unsure which figure you are working with, visit the ABA website and determine which section (out of 132) corresponds to the anatomical region(s) you are interested in plotting. 
SECTION: Anatomical heatmap - Conditions
45.1. Single-fig allows you to compare across conditions

The MPI, genotype, treatments, and markers can be selected for when plotting. The data for mice within the conditions set here will be summarized and displayed in plots.
By default, plots for each sex will be distinguished. If you would like to combine summary results across sexes, select ‘Averaged’ in the dropdown box under ‘Sexes to Plot’.
SECTION: Anatomical heatmap - Conditions
45.2. Multi-fig will only allow you to plot for a single condition

Whereas single-fig can generate multiple plots for each condition in the same output, multi-fig only displays a single condition at a time.