TITLE: Visualize Data with Brainrender
AUTHORS: Moritz Negwer

[DESCRIPTION]
Supplemementary protocol for our submitted paper "FriendlyClearMap: An optimized toolkit for mouse brain mapping and analysis".
This protocol describes how to pre-process cell locations in mouse brains (in different reference atlases) and visualize them using BrainRender (Claudi et al,. eLife 2021). 

[STEPS]
SECTION: Setup
1. After you have generated your cell table with Clearmap 1 or 2, do the following: 
(Note this has only been tested on Ubuntu Linux 20.04 and 21.10) 

1. If you haven't, install Conda and Spyder 

https://docs.anaconda.com/anaconda/install/linux/
 

Create a new conda environment:
 
(this might take several minutes)

Install Spyder with all dependendcies via conda:
 


2. Install Brainrender from here: https://github.com/brainglobe/brainrender
 

3. Install Elastix (e.g. on Ubuntu / Debian Linux): 
 

4. Download the brainrender script from github: https://github.com/MoritzNegwer/FriendlyClearMap-scripts/tree/main/Young_Mouse_Atlas_Alignments
SECTION: Transform your data to CCF3
2. If you used a different atlas from CCF3 (e.g. when using Clearmap 1 or one of the young mouse atlases), you need to transform it to CCF3 space. 

We have pre-computed a number of transforms for CCF2 (=CM1) and the young mouse atlases from the Kim lab, using Elastix. Download them from github here: XXX_needs_to_be_added


SECTION: Visualize neurons in the brain with Brainrender
3. Adapt the visualize_brainrender script as follows: 

1. Adapt the transformix_path variable to your own. Check in the command line: 
 
and take the first entry, e.g. "/usr/bin/transformix"


2. Make a list of your mice in the target_mice list, pointing to the cellls_transformed_to_Atlas_aligned.npy in each folder:

 
The colors are defined via the myterial package. Refer here for the color palette: https://github.com/FedeClaudi/myterial 


3. Define the target_folder. If it does not exist yet, it will be created when running the script. 
Note: If it does contain images already, those will be overwritten during the process! 

 

4. Define the transformation you want to use to get your cells to CCF3 coordinate space (refer to step 2 above).

for Clearmap 1: 
 

for young mouse atlases, a series is needed. In this case adapt the location and the atlas in question (here: P21):
 


5. Adapt the regions you want to make specific visualizations for (optional). If you do, the script will create one image for each region. An easy way to check for the regions and the acronyms is via the 3D Atlas Viewer of the Allen Brain Institute. 
We used the following list: 
 

6. Adapt the camera position. The default camera can be found: brainrender_folder/brainrender/cameras.py 
If you want to define your own, run the following code in spyder (after adapting the brainrender_folder):
 

Subsequently, a window with an empty mouse brain silhouette should open. 

Note: If it does not appear, brainrender´s default setting could be set to offscreen rendering. Change the last line of brainrender_folder/brainrender/settings.py from OFFSCREEN = False to OFFSCREEN = True

Move the brain around until you like the angle, then type "C" to export the current camera parameters to your spyder console. It should looke like this: 
 

Reformat them to this format to use in the script: 
 

Define the camera to be used in the script as follows (boldened part):
 


7. If you want to render only one hemisphere, set render_hemisphere to True (boldened part):

 

SECTION: Visualize neurons in the brain with Brainrender
4. Run the script. If all goes according to plan, you should get a series of images from each mouse brain, one per brain region defined under substep 5. 

If you suspect that the cell coordinates are wrong, run the following code in the spyder command line: 
 

This should render the brain without any regions cropping and reveal the full extent of your cells. If for example all cells are rendered outside of the CCF3 mouse brain, then you will need to adapt the transformation or the cells, e.g. refer to the flip_CCF2_axes function. 
SECTION: Render cell densities
5. If you want to render the points densities (such as in Fig 2 c / f), do the following: 

For densities for individual brains, simply adapt the render_screenshot call with render_densities:
 

SECTION: Render cell densities
6. If you want to sum all densities across a group, uncomment the following line and move the next for loop out of the for mouse [...] loop: 

 

Then, adapt the name_path. The end_folder is the name the resulting average density will have. 
(Note that this folder does not need to exist, this is just a workaround to create a name). 
 

SECTION: Render cell densities
7. By default this script renders rather coarse maps, suitable to assess changes across e.g. large cortical regions. If you want more fine-grained heatmaps, you can set the "radius" parameter in the render_screenshot function to a lower value (i.e. 250). 
 

If you want the heatmap object itself to have a higher resolution (and have lots of RAM and time), you can additionally define the "dims" parameter for the PointsDensity function:
 
The default is (40,40,40), which works as a reasonable compromise between computing speed and display accuracy.
SECTION: Render cell densities
8. Run the script. Depending on the number of cells, computing the density might take some time (>30 min on a Ryzen 4600H with 64GB RAM). 

Note: The color scales for the heatmaps are set to the min/max of the dataset and are not comparable between different datasets. The underlying data can be retrieved by digging deep into the vtk code underlying brainrender, but is not easily accessible (and then needs to be re-rendered).