Multi Atlas Segmentation and Morphometric Analysis Toolkit (MASMAT)

Originally designed for mouse brain MRI, but is applicable to any spicious (e.g. Non-human primate, or even human neuroimages)

Author: Da Ma (dma@wakehealth.edu; d.ma.11@ucl.ac.uk)

Description

Automatic brain structural parcellation through registration-based segmentation-propagation and multi-atlas-based label-fusion This bash scripts is created for Multi-atlas based automatic brain structural parcellation, mainly for mouse brain MRI.

This script achieve automatic brain MRI image segmentation with given mouse brain MRI atlases - which is a set of pairs of template images along with their manually labells. Sample atlases can be downloadable from the Github respsitory here. For detailed description of the pipeline, please refer to the papers [1] [2]. Citation of the two papers are listed at the bottom of this page. The MASMAT tool has been extensively tested to segment mouse brain MRI. It should be also capable of handelling the multi-atlas-based parcellation/segmentation for other type of images, organs, or species (e.g. CT, heart, embryo, human, macaque, etc.), providing appropriate atlases are givien.

[Updates] Please refer to HelperFunctions/python for the python library to call/use the MASMAT tools

Installation

Pre-requisite package installation: NityReg, NitySeg, and FSL (FSL is optional, but recommended as it is used to generate QuickCheck figures which will make the inspection of the results much easier).
- Ther easist and recommended way to install NiftyReg and NiftySeg is by installing NifTK which includes both of the two packages, as well as other useful tools, including a 3D nifti file viewer.
For example, to download and install NifTK version v18.05.4 on ubuntu to your home folder, using the following lines:
```
cd $HOME
# Download binary files
wget https://github.com/NifTK/NifTK/releases/download/v18.05.4/niftk-v18.05.4-ubuntu-14.04-x64.tar.bz2
# extracct the binary files
tar -xvjf niftk-v18.05.4-ubuntu-14.04-x64.tar.bz2
# A folder called 'niftk-18.5.4' will be created under your $HOME folder
```
If you choose to compile the NiftyReg and NiftySeg from source code instead, please make sure you have downloaded and installed the latest version, since the earlier version might not be compatible with this tool.
- For NiftyReg, please use the command line below to download the lastest version of the source code, and follow the compile instruction from the NiftyReg's install page to build and compile the binary files.
```
git clone git://git.code.sf.net/p/niftyreg/git niftyreg
```
  or
```
git clone git@cmiclab.cs.ucl.ac.uk:mmodat/niftyreg.git niftyreg
```
- For NitySeg, please use the command line below to download the lastest version of the source code for compile, and follow the compile instruction from the NitySeg's install page to build and compile the binary files.
```
`git clone https://github.com/KCL-BMEIS/NiftySeg.git`
```
[Important] After install or compilation the executable binary files, do remember to add the directories of the executable binary files - which is the bin subdirectory within directory where ther packages are installed) - to the system $PATH variable.
- For example, if you're using Linux, and installed the NifTK at: /home/YourUserName/niftk-18.5.4, then add the following 2 lines to the file /home/YourUserName/.bashrc (e.g. by typing: gedit $HOME/.bashrc or nano $HOME/.bashrc or emacs $HOME/.bashrc):
```
export PATH=${PATH}:"$HOME/niftk-18.5.4/bin"
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:"$HOME/niftk-18.5.4/bin"
```
- Otherwise, if you download and compiled NiftyReg and NiftySeg separately at: /home/YourUserName/nifty_reg and /home/YourUserName/nifty_seg, then add the following 4 lines to the file ~/.bashrc:
```
export PATH=${PATH}:"$HOME/nifty_reg/bin"
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}/"$HOME/nifty_reg/lib"
export PATH=${PATH}:"$HOME/nifty_seg/bin"
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:"$HOME/nifty_seg/lib"
```
  ($HOME represent your home directory, which is located at /home/YourUserName/).
- After setting up the system variables, refresh your bash environment by simply type bash in the terminal, or open a new termina, or logout/login again. Type the following two command in the refreshed terminal to check whether the NiftyReg and NiftySeg has been installed and loaded successfully in the correct locations:
  
  which reg_resample
  
  which seg_LabFusion
If correct installation location is given with the two command above, now you're ready to use the MASHelperFunctions.sh script, or test the demo script. The bash script is compatible with Linux/Windows/Mac system.

Usage

The core functions of MASMAT toolbox are in the main script: the MASHelperFunctions.sh, which is capable of handling batch brain parcellation (functions with suffix _batch) either on the local workstation or on PBS cluster by simply specifying the -e flag as either local or cluster). To load the script, simply type source MASHelperFunctions.sh to load all corresponding functions.

To get help for each function, type function_name -h. For example: mas_mapping -h

To run the MASMAT in python, and take advantage of the cluster-based parallel computation pipeline (i.e. on SLURM cluster), import and load the python helper function segmentation_propagation.py in HelperFunctions/python folder.

[Important]

Please make sure the orientation information in the header of your test image is correct before process. Sometimes, it is a bit tricky to get the correct orientation for nifty images (please see the detailed explanation at FSL website Ref1 and Ref 2. Additional information in the answer of the first question in the Q/A session.

Please make sure the voxel dimension (voxel size) of the image is correct. If the images are reconstructed using tools for human brian MRI, sometimes the voxel dimension will be set to 1mm isotropic, which is incorrect and will affect the registration algorithm. A typical resolution for in vivo mouse brain MRI would be around 0.1-0.2mm, and for ex vivo can be as small as 0.05mm.

You can check the voxel dimension using:
- the fslinfo command in the FSL package (field name: pixdim);
- the mri_info command in the FreeSurfer package (field name: voxel sizes),
- the nifti_tool command in the AFNI package: nifti_tool -disp_hdr -infiles $input_filename.
- or other GUI tools such as ITK-SNAP (in: Tools - Image Information).
A convenient tool to change the voxel dimension (field name: pixeldim) is: nifti_tool from the AFNI package. Here is an example to change the input with incorrected voxel size (e.g. 1mm) into the correct one (0.1mm): nifti_tool -mod_hdr -mod_field pixdim '0.0 0.1 0.1 0.1 0.1 0.1 0.1 0.1' -infiles $input_filename -prefix $output_filename
Sometimes, the image origin in the nifty head will be misplaced after the pixeldim change, which will make the affine registration fail (for both the mas_masking step and the mas_parcellation). A quick solution is to load the image into the NifTK, and "save as" a .nii or .nii.gz file, which will effectively reinitialize the image origin information int he nifti file header. We will post a more elegant solution with future update.

Pipeline example

Processing pipeline schematic diagram

pipeline schematic "Click here for the paper with detailed description of the processing pipeline"

pipeline demo

A demo script is provided, which contains a complete end-to-end demonstration showing how to build and run the pipeline. It first download the atlas and test image from the mouse brain atlas. It then run the following steps in sequential: brain extraction => N4 Bias Field Correction => brain structural parcellation (which itself consists of 3 sub-steps: atlas-to-test image registration (using dilated mask and bias-field-corrected brain image) -> atlas label propagation -> and multi-atlas label fusion).

Function demo

Load script:

source MASHelperFunctions.sh
Step 1: brain extraction (masking)

mas_masking_batch -T “targe t_dir” -t “target_list” -A “atlas_dir” -r “result_dir”
- -h: Use mas_masking_batch -h to show help for usage
- -T: specify folder contain the target image to be segmented (images should be in nifty format: nii or nii.gz. The image orientation should be correctly indicated in the nif

Masmat

Install / Use

README