connectomicslab/connectomemapper3: Connectome Mapper v3.0.0

Connectome Mapper 3 implements, in accordance to the BIDS-App standard, full anatomical, diffusion, and resting/state functional MRI processing pipelines, from raw T1 / DWI / BOLD data to multi-resolution brain parcellation with corresponding connection matrices, based on a new version of the Lausanne parcellation atlas (Cammoun et al, 2012), aka Lausanne2018.

This corresponds to the first offical release of Connectome Mapper 3 ! 🎄🎁✨

What's changed

New features

• CMP3 can take custom segmentation (brain, white-matter, gray-matter and CSF masks, Freesurfer\'s aparcaseg - used for ACT for PFT) and parcellation files as long as they comply to BIDS Derivatives specifications, by providing the label value for the different entity in the filename. This has led to the creation of the new module cmtklib.bids.io, which provides different classes to represent the diversity of custom input BIDS-formatted files. (PR #88)

• CMP3 generates generic label-index mapping .tsv files along with the parcellation files, in accordance to BIDS derivatives. This has led to the creation of the ~cmtklib.bids.utils.CreateBIDSStandardParcellationLabelIndexMappingFile and ~cmtklib.bids.utils.CreateCMPParcellationNodeDescriptionFilesFromBIDSFile interfaces, which allows us to create the BIDS label-index mapping file from the parcellation node description files employed by CMP3 (that includes \_FreeSurferColorLUT.txt and \_dseg.graphml), and vice versa.

• CMP3 provide python wrappers to the Docker and Singularity container images connectomemapper3_docker and connectomemapper3_singularity that generate and execute the appropriate command to run the BIDS App. (PR #109, PR #115, PR #130)

Major changes

• Lausanne2018 parcellation has completely replaced the old Lausanne2008 parcellation. In brief, the new parcellation was introduced to provide (1) symmetry of labels between hemispheres, and (2) a more optimal generation of the volumetric parcellation images, that now are generated at once from .annot files. This fixes the issue of overwritten labels encountered by in the process of creating the Lausanne2008 parcellation. Any code and data related to Lausanne2008 has been removed. If one still wish to use this old parcellation scheme, one should use CMP3 v3.0.0-RC4.

Pipeline Improvements

• Better handle of existing Freesurfer outputs. In this case, CMP3 does not re-create the mri/orig/001.mgz and connect the reconall interface anymore.

• Creation of 5TT, gray-matter / white-matter interface, and partial volume maps images are performed in the preprocessing stage of the diffusion pipeline only if necessary.

Output updates

• Directories for the derivatives produced by cmp ([cmp]{.title-ref}, freesurfer, nipype were renamed to cmp-\<cmp_version>, freesurfer-\<freesurfer_version>, and nipype-\<nipype_version> to comply with BIDS 1.4.0+. (PR #3 (fork)) Code refactoring

• Creation in AnatomicalPipeline, DiffusionPipeline, fMRIPipeline of create_datagrabber_node()and create_datasinker_node() methods to reduce the code in create_workflow().

• The run(command) function of cmp.bidsappmanager.core has been moved to cmtklib.process, which is used by the python wrappers in cmp.cli.

Code Style

• Clean code and remove a number of commented lines that are now obsolete. Code related to the connection of nodes in the Nipype [Workflow]{.title-ref} adopts a specific format and are protected from being reformatted by BLACK with the # fmt: off and # fmt: on tags.

Documentation

• Add instructions to use custom segmentation and parcellation files as inputs.

• Add description in contributing page of format for code related to the connection of the nodes in a Nipype Workflow.

• Add instructions to use the python wrappers for running the BIDS App. (PR #115)

• Add notification about the removal of the old Lausanne2008 parcellation, and remove any other mentions in the documentation.

Software container

• Define multiple build stages in Dockerfile, which can be run in parallel at build with BUILDKIT. (PR #88)

Software development life cycle

• Update the list of outputs of circleci tests with the new names of directories produced by cmp in output_dir/.

• Following major changes in the pricing plans of CircleCI but also to improve its readability, .circleci/config.yml has been dramatically refactored, including:

  • Use BUILDKIT in docker build to take advantage of the multi-stage build
  • Reordering and modularization of the tests:
    • tests 01-02 (Docker): anatomical pipeline for each parcellation scheme
    • tests 03-06 (Docker): diffusion pipeline for dipy/mrtrix deterministic/probabilistic tractography
    • tests 07-08 (Docker): fMRI pipeline for FLIRT and BBRegistration registrations
    • test 09 (Singularity): anatomical pipeline for Lausanne2018 scheme
  • Creation of commands for steps that are shared between jobs to reduce code duplication (PR #88)

Contributors

• Sebastien Tourbier
• Anil Tuncel
• Jakub Jancovic
• Jonathan Wirsich

Please check the main pull request 88 page for more details.