Welcome to the aMAP companion guide. This guide contains all the information needed to perform automated mouse atlas propagation on full-brain 3D datasets. If you have any questions regarding this manual or run into any issues trying to use aMAP, please contact me at Christian.Niedworok.12[at]ucl.ac.uk

aMAP is a tool for optimized automated mouse atlas propagation based on clinical registration software (NiftyReg) for anatomical segmentation of high-resolution 3D fluorescence images of the adult mouse brain. aMAP permits propagation of a 3D mouse atlas of the entire adult mouse brain in 40 min and its accuracy and reliability is shown to be on par with expert human raters. Publication.

aMAP, internally uses and provides a graphical front-end to NiftyReg (a rapid image registration toolkit, originally developed for human MRI data), that we modified to enable rapid processing of high-resolution 3D light microscopy data. NiftyReg being originally devloped for MRI data, it uses the Neuroimaging Informatics Technology Initiative (NIfTI) image format which is often referred to by its .nii file extension.

aMAP has been verified using a smoothed version of the atlas developed by Kim et al (2014), (see below). The structure associations for the brightness values in the segmentation file are noted in the accompanying .csv file and follow the nomenclature of the Allen Mouse Brain Atlas.

aMAP consists of 3 main packages and an additional package with matlab tools to work with .nii images. The main packages are:

• the binaries for the registration software
• the atlas used in the publication
• test data.

First see the prerequisites section below for a list of hardware and software requirements.

To install aMAP:

1. Download the above packages
2. Unpack the first (registration binaries) into any directory. This will create a new folder called aMAP-0.0.1.
3. Into this folder, uncompress the atlas and, if needed, the test data. This will create respective subfolders containing the relevant data.

We have also compiled a package to make working with .nii files in Matlab easier (download here). It contains the Nifti/Analyze toolkit and a few additional helper functions used in this manual. The Matlab tools package can be extracted anywhere, but it will have to be added to matlab's search path (including subfolders).

NOTE: Segmentation requires a powerful machine. A workstation computer (e.g. Mac Pro or Dell Precision) with at least 16GB of RAM is necessary. For smooth viewing of .nii fils in matlab, we recommend at least 24GB of RAM.

aMAP has been tested on Mac (OS X Yosemite) and Linux (Debian Jessie) machines, for which binaries are provided. The NiftyReg command line interface has been designed to also run on Windows, but this has not yet been tested by us and will require compilation from source. The following software is necessary:

The program is written in java and requires an appropriate JRE/JDK (at least version 1.7). In most cases this should available on your system already, if not please follow these instructions for windows and mac or these instructions for ubuntu.

Necessary to check the output of the registration. Recommended are Fiji/ImageJ or ICY

NOTE: Currently there is still a bug in the BioFormats library, that will likely prevent ImageJ and ICY from opening stitching results .nii files. Due to that, Matlab with the addition of the Nifti/Analyze toolkit (which is also part of our matlab tools package) is required to view the results or convert them to a format that ImageJ or ICY can read (see below)!

Since NiftyReg, the registration tool used for aMAP, has been originally developed with MRI data in mind, it does not read .tiff files, but requires data to be either in the Analyze (.img/.hdr) or Nifti (.nii, .nii.gz) format. These formats provide additional information about the origin, physical size and orientation of the data that is necessary for the image registration. Fiji or ICY can read and display Nifti files, as long as the BioFormats library is installed, however BioFormats currently has a bug preventing it from reading large Nifti files. We have submitted a bugfix which has been accepted and should be included in the upcoming release of BioFormats. Until then, we recommend using Matlab with the addition of the Nifti/Analyze toolkit (which is also part of our matlab tools package to generate and open Nifti files.

For the image registration to work, the image data needs to be in the Nifti format. The Nifti format defines the default origin of the coordinate system as the most ventral, posterior, left voxel of the dataset. The positive axes are pointing away from that point, with x being left/right, y posterior/anterior and z ventral/dorsal:

The atlas's coordinate system respects this default and using input data with a different axes arrangement will most likely result in failed segmentations. For comparability reasons, we further advise downsampling the images to the resolution used in our study (12.5µm isotropically) prior to conversion and registration. We have provided an example dataset in the testBrain folder showing a correctly oriented and formated Nifty file. When setting the voxel dimensions, please note that Nifti uses mm as its unit. Wrongly set units will cause the segmentation to fail.

Converting .tif to .nii using Matlab

The easiest way to do automated segmentation is to use the aMAP.jar executable, which will provide a graphical interface to the whole process (part of the aMAP binaries package). This interface has been tested on Mac and Linux machines. It is programmed in Java 7 and will require an adequate JRE/JDK. If you would rather use the command line interface, see the corresponding section below.

If your java installation is done correctly, aMAP should start when double-clicking on aMAP.jar. If that doesn't work, you can start it from the command line by running

java -jar /path/to/aMAP.jar

(with /path/to/ being replaced by the path to the .jar file).

For novice users, the following parameters should be sufficient to get started. For more advanced users, please read this page listing all the available parameters in detail.

• -ref (all) The "reference" image, the image that remains unchanged during the registration. This parameter is set to the downscaled brain that is to be segmented.
• -flo (all) The "floating" image, the image that is morphed to increase similarity to the reference. This parameter is set to the average brain belonging to the atlas (aladin/f3d) or the atlas itself (resample).
• -res (all) The output path for the resampled (transformed) floating image.
• -aff The text file for the affine transformation matrix. The parameter can either be an output or input parameter: Aladin will output the affine matrix to this file, f3d will use the affine matrix generated by aladin as an input.

Additional Details about the underlying algorithms can be found in Modat, M. et al. Fast free-form deformation using graphics processing units. Computer methods and programs in biomedicine 98, 278-284, doi:10.1016/j.cmpb.2009.09.002 (2010).

Nifty data with invalid headers or wrong dimensions (e.g. voxel size of 12.5mm instead of 12 microns) can cause reg_aladin to crash with a segfault, which prevents the error log from being written.

When run from the graphical interface, aMAP will produce the following output files (myImage.nii is used as a placeholder for the dataset that is to be segmented):

• myImage.niiAVERAGE_TRANSFORMED.nii The average brain registered onto myImage.nii (-res above)
• myImage.niiSEGMENTATION.nii The automated segmentation of myImage.nii
• myImage.niiAFF.txt The transformation matrix describing the affine registration of the average brain to myImage.nii (-aff above)
• myImage.niiCPP.nii The the control-point grid describing the complete (affine and free-form) registration of the average brain to myImage.nii

As described above, Matlab with the addition of the Nifti/Analyze toolkit can be used to work with and view .nii files. To open and view e.g. the segmentation, use

segmentation=load_nii('/path/to/myImage.niiSEGMENTATION.nii');
view_nii(segmentation);

In the near future, ImageJ and ICY should be able to open .nii files without requiring file conversion. In the meantime, .nii files can be converted to .tiff using Matlab (this section assumes you have installed our matlab tools package):

segmentation=load_nii('/path/to/myImage.niiSEGMENTATION.nii');
saveTiffStack(uint16(permute(segmentation.img, [2 1 3])), '/path/to/myImage.niiSEGMENTATION.tif');

It is advisable to check all automated segmentations to ensure that the image registration worked correctly. A convenient way is to overlay the structure borders of the segmentations (e.g. myImage.niiSEGMENTATION.nii) with the downscaled dataset that should be segmented (-ref above). The outlines can be generated in matlab by first loading the segmentation file and then using our helper script to generate coronal outlines (this section assumes you have installed our matlab tools package):

segmentation=load_nii('/path/to/myImage.niiSEGMENTATION.nii');
outlines = makeMultiOutline(segmentation.img);
saveTiffStack(uint16(permute(outlines, [2 1 3])), '/path/to/myImageOutlines.tif');

(You will need to adjust the path to your images accordingly.) The tiff can then be opened in e.g. Fiji/ImageJ and overlaid with the original image. Similarly, the registered average brain can be overlaid as well. It is stored as myimage.niiAVERAGE_TRANSFORMED.nii (where myimage.nii is the name of the original .nii file to be segmented).

Instead of using the aMAP GUI, the registration can also be run by directly running the NiftyReg backend via the command line. The niftyReg/bin folder contains subdirectories with the NiftyReg command line binaries for Linux and Mac systems.

The following assumes these binaries are available in the path (i.e. they can be started by typing the command in the terminal from any folder). If not you will need to provide the full path to the commands (e.g. /home/myusername/aMAP/niftyReg/bin/linux_x64/reg_f3d).

This can be achieved by any of the following methods:

1. Linking/copying them to an executable folder like /usr/bin/
2. Using the "make install" command when compiling from source)
3. Adding the path manually by exporting through the ~/.bashrc or ~/.bash_profile for linux and Mac users respectively.

Any files marked in angle brackets in the instructions below e.g. <MyDownscaledDataset.nii> are placeholders which need to be replaced with the full path to the relevant file.

First, the average brain of the atlas dataset has to be registered to the downscaled version of the individual dataset in two steps:

1. The affine registration (This is the most time-consuming step and will produce the output the transformation matrix to <MyDownscaledDatasetAFF.txt>.):

reg_aladin -ref <MyDownscaledDataset.nii> -flo <Kim_OstenRef_ARA_v2_Average_Brain.nii> -ln 6 -lp 5 -aff <MyDownscaledDatasetAFF.txt>

2. The free-form registration using the transformation matrix output by the command above:

reg_f3d -ref <MyDownscaledDataset.nii> -flo <Kim_OstenRef_ARA_v2_Average_Brain.nii> -ln 6 -lp 4 -be 0.95 -smooR -1 -smooF -1 --fbn 128 --rbn 128 -sx -10 -aff <MyDownscaledDatasetAFF.txt> -cpp <MyDownscaledDatasetCPP.nii>

Finally, the combined transformation has to be applied to the atlas segmentation data:

reg_resample -ref <MyDownscaledDataset.nii> -flo <Kim_ORL_ARA_v2.3_Segmentation_Smoothed.nii> -cpp <MyDownscaledDatasetCPP.nii> -res <MyDownscaledDataset_SEGMENTATION.nii> -inter 0

Detailed instructions can be found here

The pipeline and manual segmentation data with which aMAP has been validated is available here