MAGeTBrain Pipeline

A Nextflow implementation of the Multiple Automatically Generated Templates (MAGeT) brain segmentation pipeline.

Pipitone J, Park MT, Winterburn J, et al. Multi-atlas segmentation of the whole hippocampus and subfields using multiple automatically generated templates. Neuroimage. 2014;

M Mallar Chakravarty, Patrick Steadman, Matthijs C van Eede, Rebecca D Calcott, Victoria Gu, Philip Shaw, Armin Raznahan, D Louis Collins, and Jason P Lerch. Performing label-fusion-based segmentation using multiple automatically generated templates. Hum Brain Mapp, 34(10):2635–54, October 2013. (doi:10.1002/hbm.22092)

Theory of Operation

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.

Here is a schematic comparing 'traditional' multi-atlas segmentation, and MAGeT brain segmentation:

The major difference between algorithms is that, in MAGeT brain, segmentations from each atlas (typically manually delineated) are propogated via image registration to a subset of the subject images (known as the 'template library') before being propogated to each subject image and fused. It is our hypothesis that by propogating labels to a template library, we are able to make use of the neuroanatomical variability of the subjects in order to 'fine tune' each individual subject's segmentation.

Requirements

These are not requirements if running on Niagara see below

• Nextflow (version 20.07.1 or later)
• Docker or Singularity
• ANTs

Data Prerequisites

• Atlases with labels. You can bring your own or use those provided by CoBrALab found here: atlases
• Subject scans with compatible contrast
• Subject scans should be preprocessed in the same way as the atlases (regarding skull-stripping, intensity normalization, etc.)
• It's recommended to have 21 templates as a representative subset

Quick Start

Important

All images should be in NIfTI format (.nii.gz)
.mnc can be converted to NIfTI using mnc2nii from minc-toolkit-v2
link to docs

1. Clone the repository:

git clone --recursive https://github.com/CoBrALab/MAGeTBrain-nextflow.git
cd MAGeTBrain-nextflow

2. Input structure Atlases, templates and subjects need to be in a specific structure in the inputs directory. Labels for each atlas <atlasname>_label_<labelname1>.nii.gz should be included in the atlases directory. Atlases, templates, subjects and labels should be structured in an input directory as follows:

Important

A note about labels for use with collect_volumes_nifti_sh Nextflow uses regex to match volume_label_<label>.csv to the corresponding majorityVote ouput Specifically it matches on \w, that is any letter, digit or underscore. Equivalent to [a-zA-Z0-9_]. /_label_([\w]+)\.nii.gz/. _This means only alphanumerical characters can be used_ other characters like - , . < > etc. will cause errors

inputs
├── atlases
│   ├── atlas1_label_<labelname1>.nii.gz
│   ├── atlas1_label_<labelname2>.nii.gz
│   ├── atlas1_T1w.nii.gz
│   ├── volume_labels_<labelname1>.csv
│   ├── volume_labels_<labelname2>.csv
│   └── ...
├── subjects
│   ├── subject1_T1w.nii.gz
│   ├── subject2_T1w.nii.gz
│   ├── subject3_T1w.nii.gz
│   ├── subject4_T1w.nii.gz
│   ├── subject5_T1w.nii.gz
│   └── ...
└── templates
    ├── subject2_T1w.nii.gz
    ├── subject5_T1w.nii.gz
    └── ...

3. (optional) If you'd like to verify the structure of the inputs directory the nextflow verify_inputs.nf command can be run. This command is also run as part of magetbrain.nf

4. When the inputs directory has been set up as above, the workflow can be run with the following command nextflow magetbrain.nf

Parameters

Parameters can be adjusted by editing nextflow.config. The default values are shown below:

params {
    primarySpectra = 'T1w'
    inputDir = 'inputs'
    outputDir = 'output'
}

Output

An example output of magetbrain.nf is shown below. In this simplified example the amygdala and cerebellum atlases were used to produce the segmentation. Note that this demonstration uses fewer subjects and templates than would be recommended for actual research purposes

output
└── labels
    └── majorityvote
        ├── sub-031274_label_amy.nii.gz
        ├── sub-031274_label_cer.nii.gz
        ├── sub-031275_label_amy.nii.gz
        ├── sub-031275_label_cer.nii.gz
        └── collectedVolumes
            └── combined_volume_output.tsv

In addition to the majorityVote the volumes of the labels are collected using ANT's LabelGeometryMeasures. These are collected in the combined_volume_output.tsv file. The outputs for this function are as follows with some additional manipulation by magetbrain.nf:

SubjectLabels	LabelNumber	LabelName	VolumeInVoxels	VolumeInMillimeters	SurfaceAreaInMillimetersSquared	Eccentricity	Elongation	Roundness	Flatness	Centroid	AxesLengths	BoundingBox
sub-031275_label_amy.nii.gz	26	L_amygdala	159	1272.000000	700.123091	0.687735	1.173662	0.810901	2.080693	[24.4721, -15.6447, -8.4358]	[7.3500, 15.2932, 17.9490]	[28, 63, 50, 36, 70, 57]
sub-031275_label_amy.nii.gz	126	R_amygdala	165	1320.000000	695.146695	0.844847	1.367161	0.837125	1.791465	[-18.3960, -11.7693, -6.5362]	[7.6773, 13.7536, 18.8034]	[49, 63, 51, 59, 69, 58]
sub-031275_label_cer.nii.gz	1	L_I_II	3	24.000000	33.933824	0.997651	3.820754	1.185747	4204927.244023	[2.0291, 6.1486, -28.3473]	[0.0000, 2.1352, 8.1580]	[42, 52, 47, 43, 53, 49]
sub-031275_label_cer.nii.gz	2	L_III	119	952.000000	691.554020	0.975030	2.122034	0.676731	2.229119	[6.7937, 7.2466, -27.6651]	[5.6990, 12.7037, 26.9577]	[35, 48, 45, 43, 58, 53]
sub-031275_label_cer.nii.gz	3	L_IV	386	3088.000000	1588.463573	0.993717	2.989118	0.645592	1.611969	[11.7454, 9.5389, -26.7099]	[8.8352, 14.2420, 42.5711]	[31, 44, 42, 43, 60, 56]
sub-031275_label_cer.nii.gz	4	L_V	630	5040.000000	2244.652713	0.996707	3.511840	0.633318	1.140233	[16.9547, 15.6565, -32.3521]	[12.9096, 14.7199, 51.6940]	[27, 39, 41, 43, 60, 54]
sub-031275_label_cer.nii.gz	5	L_VI	729	5832.000000	2740.769300	0.990676	2.709235	0.571685	1.757259	[21.1760, 25.2954, -36.7663]	[11.6904, 20.5431, 55.6560]	[25, 34, 40, 42, 58, 48]
sub-031275_label_cer.nii.gz	6	L_Crus_I	1056	8448.000000	4040.455378	0.980065	2.243498	0.496466	2.344949	[31.6046, 27.4819, -41.2604]	[11.2453, 26.3697, 59.1605]	[19, 30, 38, 42, 56, 46]
sub-031275_label_cer.nii.gz	7	L_Crus_II	1005	8040.000000	3930.752935	0.989745	2.645862	0.493756	1.617023	[23.8352, 34.2780, -49.6458]	[14.6968, 23.7651, 62.8792]	[20, 29, 33, 42, 56, 42]

Using a container

To enable use of container the standard profile can be used.

nextflow run magetbrain.nf -profile standard

Running on Trillium

Important

Nextflow requires the ssh session to remain active. This can be achieved by keeping the terminal used to ssh into Trillium open and running. A more convenient approach is to use a tool that allows persistent server sessions like Tmux or Screen.

Loading modules and setting SLURM account

The correct modules need to be loaded.

This needs to be done every time. It can be included in a run script.

Important

Do not load modules from .bashrc.

module load nextflow ants

A SLURM account needs to be assigned.

export SLURM_ACCOUNT=def-youruser

Run command on Trillium

To ensure submission to SLURM the Trillium profile must be used. The Trillium profile is loaded automatically if the alliance_canada config is used.

nextflow run magetbrain.nf \
    -profile alliance_canada \
    --inputDir inputs \
    --outputDir output

This should show the text: Config: Alliance Canada (Trillium) cluster profile provided by nf-core/configs. when MAGeTBrain is started.

Other useful flags to pass are -bg to run in background and -resume to resume processing if there was an interruption.

More information about nextflow on DRAC can be found in the Alliance docs.
The DRAC configs are maintained in the nf-core config repo.

Important

A bug when running on HPC requires an additional script to be run to collect volumes. This can be done on the login node without submitting job to SLURM

nextflow run collect_and_combine_volumes_trillium.nf