Multi-Scale Brain Parcellator¶

This pipeline is developed by the Hagmann’s group at the University Hospital of Lausanne (CHUV) for use within the SNF Sinergia Project 170873, as well as for open-source software distribution.

About¶

Multi-Scale Brain Parcellator, part of the Connectome Mapping Toolkit (CMTK), is a BIDS App that implements a full anatomical MRI processing pipeline, from raw T1w data to structural brain parcellation at five different scales.

The Multi-Scale Brain Parcellator pipelines uses a combination of tools from well-known software packages, including FSL, FreeSurfer, ANTs as well as in-house tools from CMTK.

This tool allows you to easily do the following:

Take T1 from raw to brain parcellations at 5 different scales.
Implement tools from different software packages.
Automate and parallelize processing steps, which provides a significant speed-up from typical linear, manual processing.

Reproducibility and replicatibility are promoted through the distribution of a BIDSApp, a software container image which provide a frozen environment where versions of all external softwares and libraries are fixed.

Funding¶

Work supported by the SNF Sinergia Grant 170873 (http://p3.snf.ch/Project-170873).

License information¶

This software is distributed under the open-source license Modified BSD. See license for more details.

All trademarks referenced herein are property of their respective holders.

Contents¶

Installation Instruction¶

Warning

This software is for research purposes only and shall not be used for any clinical use. This software has not been reviewed or approved by the Food and Drug Administration or equivalent authority, and is for non-clinical, IRB-approved Research Use Only. In no event shall data or images generated through the use of the Software be used in the provision of patient care.

The Multi-Scale Brain Parcellator is a BIDS App that relies on Docker. Make sure that you have Docker installed or follow the instructions found in Installation of Docker. Then, install the Multi-Scale Brain Parcellator by following the instructions found in Installation of the Multi-Scale Brain Parcellator.

Installation of Docker¶

Installed Docker Engine corresponding to your system
- For Ubuntu 14.04/16.04/18.04, follow the instructions from the web page:
```
$ firefox https://docs.docker.com/install/linux/docker-ce/ubuntu/
```
- For Mac OSX (>=10.10.3), get the .dmg installer from the web page:
```
$ firefox https://store.docker.com/editions/community/docker-ce-desktop-mac
```
- For Windows (>=10), get the installer from the web page:
```
$ firefox https://store.docker.com/editions/community/docker-ce-desktop-windows
```

Note

Multi-Scale Brain Parcellator BIDSApp has been tested only on Ubuntu and MacOSX. For Windows users, it might be required to make few patches in the Dockerfile.

For Ubuntu, Docker could be managed as a non-root user
- Open a terminal
- Create the docker group:
```
$ sudo groupadd docker
```
- Add the current user to the docker group:
```
$ sudo usermod -G docker -a $USER
```
- Reboot
  
  After reboot, test if docker is managed as non-root:
```
$ docker run hello-world
```

Installation of the Multi-Scale Brain Parcellator¶

Installation and use of the Multi-Scale Brain Parcellator has been facilitated through the distribution of a Docker container image.

Open a terminal

Get the latest release of the BIDS App:

$ docker pull sebastientourbier/multiscalebrainparcellator:latest

To display all docker images available:
```
$ docker images
```

You should see the docker image “multiscalebrainparcellator” with tag “latest” is now available.

Help/Questions¶

If you run into any problems or have any questions, you can post to the CMTK-users group. Code bugs can be reported by creating a “New Issue” on the source code repository.

Usage¶

Execution and the BIDS format¶

The Multi-Scale Brain Parcellator workflow takes as principal input the path of the dataset that is to be processed.

The input dataset is required to be in valid BIDS format, and it must include at least one T1w or MPRAGE structural image. For example:

ds-example/

    README
    CHANGES
    participants.tsv
    dataset_description.json

    sub-01/
        anat/
            sub-01_T1w.nii.gz
            sub-01_T1w.json

    ...

    sub-<subject_label>/
        anat/
            sub-<subject_label>_T1w.nii.gz
            sub-<subject_label>_T1w.json
        ...
    ...

For more information about BIDS, please consult the BIDS Website and the Online BIDS Specifications. HeuDiConv can assist you in converting DICOM brain imaging data to BIDS. A nice tutorial can be found @ BIDS Tutorial Series: HeuDiConv Walkthrough .

Important

We highly recommend that you validate your dataset with the free, online BIDS Validator.

Commandline Arguments¶

The command to run Multi-Scale Brain Parcellator follow the BIDS-Apps definition with additional options specific to this pipeline.

Multi-scale Brain Parcellator BIDS App.

usage: multiscalebrainparcellator [-h]
                                  [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                                  [--multiproc_number_of_cores MULTIPROC_NUMBER_OF_CORES]
                                  [--number_of_participants_processed_in_parallel NUMBER_OF_PARTICIPANTS_PROCESSED_IN_PARALLEL]
                                  [--fs_number_of_cores FS_NUMBER_OF_CORES]
                                  [--fs_license FS_LICENSE]
                                  [--isotropic_resolution ISOTROPIC_RESOLUTION]
                                  [--thalamic_nuclei]
                                  [--hippocampal_subfields]
                                  [--brainstem_structures]
                                  [--skip_bids_validator] [-v]
                                  bids_dir output_dir {participant}

Positional Arguments¶

bids_dir

The directory with the input dataset formatted according to the BIDS standard.

output_dir

The directory where the output files should be stored. If you are running group level analysis this folder should be prepopulated with the results of theparticipant level analysis.

analysis_level

Possible choices: participant

Level of the analysis that will be performed. Note that only participant level analysis is available.Multiple participant level analyses can be run independently (in parallel) using the same output_dir.

Named Arguments¶

`--participant_label`
	The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“). If this parameter is not provided all subjects should be analyzed. Multiple participants can be specified with a space separated list.
`--multiproc_number_of_cores`
	The number of cores to be used by the MultiProc plugin of Nipype (One core used by default).
`--number_of_participants_processed_in_parallel`
	The number of subjects to be processed in parallel (One core used by default).
`--fs_number_of_cores`
	The number of cores to be used by Freesurfer (One core used by default).
`--fs_license`	Path to Freesurfer license.
`--isotropic_resolution`
	The isotropic resolution in mm used to resample the original anatomical images and applied a tthe beginning of the processing pipeline.
`--thalamic_nuclei`
	Whether or not to parcellate the thalamic nuclei. Default: False
`--hippocampal_subfields`
	Whether or not to parcellate the hippocampal subfields. Default: False
`--brainstem_structures`
	Whether or not to parcellate the brainstem structures. Default: False
`--skip_bids_validator`
	Whether or not to perform BIDS dataset validation. Default: False
`-v, --version`	Display the version of Multi-scale Brain Parcellator BIDS-App.

Participant Level Analysis¶

To run the docker image in participant level mode (for one participant):

$ docker run -it --rm \
-v /home/localadmin/data/ds-example:/bids_dir \
-v /media/localadmin/data/ds-example/derivatives:/output_dir \
-v /usr/local/freesurfer/license.txt:/bids_dir/code/license.txt \
sebastientourbier/multiscalebrainparcellator:v1.1.0 \
/bids_dir /output_dir participant --participant_label 01 \
--isotropic_resolution 1.0 \
--thalamic_nuclei \
--hippocampal_subfields \
--brainstem_structures

Important

The local directory of the input BIDS dataset (here: /home/localadmin/data/ds001) and the output directory (here: /media/localadmin/data/ds001/derivatives) used to process have to be mapped to the folders /bids_dir and /output_dir respectively using the -v docker run option.

Important

Multi-scale brain parcellator needs your own Freesurfer license. As a result, you must map your license (for instance /usr/local/freesurfer/license.txt) to the file /bids_dir/code/license.txt inside the BIDS App.

Debugging¶

Logs are outputted to sub-<participant_label>_log-multiscalebrainparcellator.txt located in <output dir>/cmp/sub-<participant_label>/ directory.

Support and communication¶

The documentation of this project is found here: http://multiscalebrainparcellator.readthedocs.org/en/latest/.

All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/sebastientourbier/multiscalebrainparcellator/issues.

If you run into any problems or have any questions, you can post to the CMTK-users group.

Not running on a local machine? - Data transfer¶

If you intend to run multiscalebrainparcellator on a remote system, you will need to make your data available within that system first. Comprehensive solutions such as Datalad will handle data transfers with the appropriate settings and commands. Datalad also performs version control over your data.

Processing Pipeline Details¶

Workflow¶

The Multi-Scale Brain Parcellator pipelines uses a combination of tools from the well-known software packages FSL, FreeSurfer, ANTs as well as in-house tools from the Connectome Mapping ToolKit (CMTK).

Segmentation¶

Surfaces are extracted using Freesurfer.

T1 is segmented using Freesurfer.

Brainstem sub-structures are segmented using Freesurfer.

Hippocampal subfields are segmented using Freesurfer.

Thalamic nuclei are segmented using an in-house tool of CMTK which implement the probabilistic atlas-based thalamic segmentation method with the help of ANTs (See Najdenovska 2018 in Citing Section).

Parcellation¶

Desikan-Killiany brain parcellation is performed using Freesurfer.

5-Scale Brain parcellation is created according to Cammoun et al. 2012 (See Citing) at 5 different scales. All structures are then combined to create the final brain parcellation at each scale.

Outputs of Multi-Scale Brain Parcellator¶

Note

Multi-Scale Brain Parcellator outputs are currently being updated to conform to the BIDS Common Derivatives specification (see BIDS Common Derivatives Extension).

Multi-Scale Brain Parcellator Derivatives¶

Processed, or derivative, data are written to <bids_dataset/derivatives>/cmp/sub-<subject_label>/. In this folder, a configuration file generated and used for processing each participant is saved as sub-<subject_label>_anatomical_config.ini. It summarizes pipeline workflow options and parameters used for processing.

Anatomical derivatives in the original T1w space are placed in each subject’s anat subfolder including:

anat/sub-<subject_label>_desc-head_T1w.nii.gz
anat/sub-<subject_label>_desc-brain_T1w.nii.gz
anat/sub-<subject_label>_desc-brain_mask.nii.gz
anat/sub-<subject_label>_label-WM_dseg.nii.gz
anat/sub-<subject_label>_label-GM_dseg.nii.gz
anat/sub-<subject_label>_label-CSF_dseg.nii.gz

The five different brain parcellation are saved as:

anat/sub-<subject_label>_label-L2018_desc-<scale_label>_atlas.nii.gz

where <scale_label> : scale1, scale2, scale3, scale4, scale5 corresponds to the parcellation scale.

Additionally, the description of parcel labels and the updated FreeSurfer color lookup table are saved as:

anat/sub-<subject_label>_label-L2018_desc-<scale_label>_atlas.graphml
anat/sub-<subject_label>_label-L2018_desc-<scale_label>_atlas_FreeSurferColorLUT.txt

Finally, parcel volumetry results for each scale are saved in a TSV file as:

anat/sub-<subject_label>_label-L2018_desc-<scale_label>_stats.tsv

FreeSurfer Derivatives¶

A FreeSurfer subjects directory is created in <bids_dataset/derivatives>/freesurfer.

freesurfer/
    fsaverage/
        mri/
        surf/
        ...
    sub-<subject_label>/
        mri/
        surf/
        ...
    ...

The fsaverage subject distributed with the running version of FreeSurfer is copied into this directory.

BSD 3-Clause License¶

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Citing¶

Important

If your are using Multi-Scale Brain Parcellator in your work, please acknowledge this software and its dependencies. To help you to do so, we recommend you to use, modify to your needs, and include in your work the following text:

Results included in this manuscript come from the Connectome Mapper 3 version latest [1,2], a processing pipeline, written in Python which uses Nipype [3,4]. It is encapsulated in a BIDS app [5] based on Docker [6] and Singularity [7] container technologies. Resampling to isotropic resolution, Desikan-Killiany brain parcellation [8], brainstem parcellation [9], and hippocampal subfields segmentation [10] were performed using FreeSurfer 6.0.1. Final parcellations were created by performing cortical brain parcellation on at 5 different scales [11], probabilistic atlas-based segmentation of the thalamic nuclei [12],and combination of all segmented structures, using in-house CMTK tools and the antsRegistrationSyNQuick tool of ANTS v2.2.0 [13].

References

1.Tourbier S, Aleman-Gomez Y, Griffa A, Bach Cuadra M, Hagmann P (2019, October 22) sebastientourbier/multiscalebrainparcellator: Multi-Scale Brain Parcellator (Version v1.1.0). Zenodo. http://doi.org/10.5281/zenodo.2536778

2.Tourbier S, Aleman-Gomez Y, Griffa A, Bach Cuadra M, Hagmann P (2019, June 12). Multi-Scale Brain Parcellator: a BIDS App for the Lausanne Connectome Parcellation. 25th Annual Meeting of the Organization for Human Brain Mapping (OHBM), abstract #1714, poster #W616.

3.Gorgolewski K, Burns CD, Madison C, Clark D, Halchenko YO, Waskom ML, Ghosh SS (2011). Nipype: a flexible, lightweight and extensible neuroimaging data processing framework in python. Front Neuroinform, vol. 5, no. 13. doi:10.3389/fninf.2011.00013.

4.Gorgolewski KJ, Esteban O, Ellis DG, Notter MP, Ziegler E, Johnson H, Hamalainen C, Yvernault B, Burns C, Manhães-Savio A, Jarecka D, Markiewicz CJ, Salo T, Clark D, Waskom M, Wong J, Modat M, Dewey BE, Clark MG, Dayan M, Loney F, Madison C, Gramfort A, Keshavan A, Berleant S, Pinsard B, Goncalves M, Clark D, Cipollini B, Varoquaux G, Wassermann D, Rokem A, Halchenko YO, Forbes J, Moloney B, Malone IB, Hanke M, Mordom D, Buchanan C, Pauli WM, Huntenburg JM, Horea C, Schwartz Y, Tungaraza R, Iqbal S, Kleesiek J, Sikka S, Frohlich C, Kent J, Perez-Guevara M, Watanabe A, Welch D, Cumba C, Ginsburg D, Eshaghi A, Kastman E, Bougacha S, Blair R, Acland B, Gillman A, Schaefer A, Nichols BN, Giavasis S, Erickson D, Correa C, Ghayoor A, Küttner R, Haselgrove C, Zhou D, Craddock RC, Haehn D, Lampe L, Millman J, Lai J, Renfro M, Liu S, Stadler J, Glatard T, Kahn AE, Kong X-Z, Triplett W, Park A, McDermottroe C, Hallquist M, Poldrack R, Perkins LN, Noel M, Gerhard S, Salvatore J, Mertz F, Broderick W, Inati S, Hinds O, Brett M, Durnez J, Tambini A, Rothmei S, Andberg SK, Cooper G, Marina A, Mattfeld A, Urchs S, Sharp P, Matsubara K, Geisler D, Cheung B, Floren A, Nickson T, Pannetier N, Weinstein A, Dubois M, Arias J, Tarbert C, Schlamp K, Jordan K, Liem F, Saase V, Harms R, Khanuja R, Podranski K, Flandin G, Papadopoulos Orfanos D, Schwabacher I, McNamee D, Falkiewicz M, Pellman J, Linkersdörfer J, Varada J, Pérez-García F, Davison A, Shachnev D, Ghosh S (2017). Nipype: a flexible, lightweight and extensible neuroimaging data processing framework in Python. doi:10.5281/zenodo.581704.

5.Gorgolewski KJ, Alfaro-Almagro F, Auer T, Bellec P, Capota M, Chakravarty MM, Churchill NW, Cohen AL, Craddock RC, Devenyi GA, Eklund A, Esteban O, Flandin G, Ghosh SS, Guntupalli JS, Jenkinson M, Keshavan A, Kiar G, Liem F, Raamana PR, Raffelt D, Steele CJ, Quirion P, Smith RE, Strother SC, Varoquaux G, Wang Y, Yarkoni T, Poldrack RA (2017). BIDS apps: Improving ease of use, accessibility, and reproducibility of neuroimaging data analysis methods. PLOS Computational Biology, vol.13, no. 3, e1005209. doi:10.1371/journal.pcbi.1005209.

6.Merkel D (2014). Docker: lightweight Linux containers for consistent development and deployment. Linux Journal, vol. 2014, no. 239. https://dl.acm.org/citation.cfm?id=2600239.2600241

7.Kurtzer GM, Sochat V, Bauer MW (2017). Singularity: Scientific containers for mobility of compute. PLoS ONE, vol. 12, no. 5, e0177459. doi: 10.1371/journal.pone.0177459

8.Desikan RS, Ségonne F, Fischl B, Quinn BT, Dickerson BC, Blacker D, Buckner RL, Dale AM, Maguire RP, Hyman BT, Albert MS, Killiany RJ. An automated labeling system for subdividing the human cerebral cortex on MRI scans into gyral based regions of interest. NeuroImage, vol. 31, no. 3, pp. 968-980. doi:10.1016/j.neuroimage.2006.01.021.

9.Iglesias JE, Van Leemput K, Bhatt P, Casillas C, Dutt S, Schuff N, Truran-Sacrey D, Boxer A, Fischl B (2015). Bayesian segmentation of brainstem structures in MRI. Neuroimage, vol. 113, pp. 184-195. doi: 10.1016/j.neuroimage.2015.02.065.

10.Iglesias JE, Augustinack JC, Nguyen K, Player CM, Player A, Wright M, Roy N, Frosch MP, McKee AC, Wald LL, Fischl B, Van Leemput K (2015). A computational atlas of the hippocampal formation using ex vivo, ultra-high resolution MRI: Application to adaptive segmentation of in vivo MRI. Neuroimage, vol. 115, July, pp. 117-137. doi: 10.1016/j.neuroimage.2015.04.042.

11.Cammoun L, Gigandet X, Meskaldji D, Thiran JP, Sporns O, Do KQ, Maeder P, Meuli RA, Hagmann P (2012). Mapping the human connectome at multiple scales with diffusion spectrum MRI. Journal of neuroscience methods, vol. 203, no. 2, pp. 386-397. doi: 10.1016/j.jneumeth.2011.09.031.

12.Najdenovska E, Alemán-Gómez Y, Battistella G, Descoteaux M, Hagmann P, Jacquemont S, Maeder P, Thiran JP, Fornari E, Bach Cuadra M (2018). In-vivo probabilistic atlas of human thalamic nuclei based on diffusion- weighted magnetic resonance imaging. Scientific Data, vol. 5, no. 180270. doi: 10.1038/sdata.2018.270

13.Avants BB, Epstein CL, Grossman M, Gee JC (2008). Symmetric diffeomorphic image registration with cross-correlation: evaluating automated labeling of elderly and neurodegenerative brain. Medical Image Analysis, vol. 12, no. 1, pp. 26–41. doi:10.1016/j.media.2007.06.004.

Poster¶

Organization for Human Brain Mapping 2019 (Abstract; Poster)

Contributing¶

Coming