MAGeTBrain

Multiple Automatically Generated Templates (MAGeT) brain segmentation algorithm

MAGeT analysis changes very fast due to everyday improvements, we will try to have this tutorial up-to-date. Here is the link to the toolbox: https://github.com/CobraLab/MAGeTbrain

Given a set of labelled MR images (atlases) and unlabelled images (subjects), MAGeT produces a segmentation for each subject using a multi-atlas voting procedure based on a template library made up of images from the subject set.

It is recommended to read over this entire document before going through any of the steps so that you have a high level understanding of the steps involved.

MAGeT brain is configured to run on Niagara, a super computing cluster. To run MAGeT brain you will need a Niagara account.

Setting up Software

MAGeTbrain requires specific software to do its processing. To enable that software in your current running Niagara login:

> module load cobralab/2019b

Next you need to get a copy of MAGeTbrain and turn it on For simplified MAGeTbrain

> git clone -b simplified-labelmask https://github.com/CobraLab/MAGeTbrain.git
> source MAGeTbrain/bin/activate

Or for Morpho:

> git clone -b morpho-labelmask https://github.com/CobraLab/MAGeTbrain.git
> source MAGeTbrain/bin/activate

Setting up inputs

Next you will need to create your directory structure and populate it

> mb init

Now you have a directory structure:

input/
input/subjects
input/subjects/brains
input/templates
input/templates/brains
input/atlases
input/atlases/labels
input/atlases/brains

Populate your subjects/brains/ directory with subject MINC files. Choose a representative subset of ~21 subjects to also place in templates/brains/. Representative is ideally over the range of anatomical variability, but can also be random, or stratified for age/sex/diagnosis. It is strongly recommended to use extracted brains as inputs. If segmenting the Cerebellum, be very careful that none of it is cut off by brain extraction. The *.n4correct.cutneckapplyautocrop.beastextract.mnc files from minc-bpipe-library are the best choice for inputs.

You will also need to supply atlases and labels, which are manually labelled brains used as the ground truth. CoBrALab provides a number of atlases available at https://github.com/cobralab/atlases, which are available locally at: /project/m/mchakrav/atlases_from_git. Copy your atlas brains into atlases/brains/ and your labels into atlases/labels/. Naming for atlases must be of the form atlases/brains/<basename>.mnc with a paired atlases/labels/<basename>_labels.mnc.

Morpho mode

If using morpho, you will additionally need to populate the model directory with a model brain, transforms between the model brain and the atlas brains, and object files for surface analysis. Model resources are located in /project/m/mchakrav/atlases-morpho/morpho_models. You can copy the entire model directory to your inputs. Be sure to select whether you're using an extracted or non-extracted brain by renaming the appropriate file in model/brains to model.mnc.

Running

After setting up everything, you should be able to execute the pipeline, For simplified:

> mb run

For morpho:

> mb run --surfaces --voronoi

Collecting volumes

collect_volumes.sh is available inside MAGeT once you activate it:

usage: collect_volumes.sh [ label-mapping.csv ] input.mnc [ input2.mnc ... inputN.mnc ]

label mapping is an optional CSV to get names instead of numbers for the output, such as: /project/m/mchakrav/atlases_from_git/hippocampus-subfields/label-names.csv

Example usage:

> collect_volumes.sh /gpfs/fs0/project/m/mchakrav/atlases_from_git/hippocampus-subfields/label-names.csv output/fusion/majority_vote/*mnc > volumes.csv