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.

Before you Start

The instructions listed here have several assumptions embedded in them, in particular:

• Your brains are 1x1x1 mm isotropic
• Your brains are in RAS orientation
• Your brains are preprocessed and skull-stripped (extracted)

Violating these assumptions can cause failures, particularly when it comes to the default time assigned to submitted jobs. If you run into timeout issues, please check mb run --help for options to change the walltime requested for jobs.

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. Choose the files that correspond to your contrast, T1 or T2 and whether your subject and template brains have been extracted (aka skullstripped) _extracted. 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. Delete the remaining files. To enable masking during the model registration, rename the appropriate file corresponding to your labels in masks to mask.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

Label name files are found in each directory of:

/project/m/mchakrav/atlases_from_git/

on Niagara, or at https://github.com/cobralab/atlases

Example usage for hippocampal-subfields:

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