Commandline Usage

Connectome Mapper 3 (CMP3) is distributed as a BIDS App which adopts the BIDS standard for data organization and 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 a T1w or MPRAGE structural image and a DWI and/or resting-state fMRI image. See Connectome Mapper 3 and the BIDS standard page that provides links for more information about BIDS and BIDS-Apps as well as an example for dataset organization and naming.

Warning

As of CMP3 v3.0.0-RC2, the BIDS App includes a tracking system that anonymously reports the run of the BIDS App. This feature has been introduced to support us in the task of fund finding for the development of CMP3 in the future. However, users are still free to opt-out using the --notrack commandline argument.

Commandline Arguments

The command to run CMP3 follows the BIDS-Apps definition standard with additional options for loading pipeline configuration files.

Entrypoint script of the BIDS-App Connectome Mapper version v3.0.0-RC2

usage: connectomemapper3 [-h]
                         [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                         [--session_label SESSION_LABEL [SESSION_LABEL ...]]
                         [--anat_pipeline_config ANAT_PIPELINE_CONFIG]
                         [--dwi_pipeline_config DWI_PIPELINE_CONFIG]
                         [--func_pipeline_config FUNC_PIPELINE_CONFIG]
                         [--number_of_threads NUMBER_OF_THREADS]
                         [--number_of_participants_processed_in_parallel NUMBER_OF_PARTICIPANTS_PROCESSED_IN_PARALLEL]
                         [--mrtrix_random_seed MRTRIX_RANDOM_SEED]
                         [--ants_random_seed ANTS_RANDOM_SEED]
                         [--ants_number_of_threads ANTS_NUMBER_OF_THREADS]
                         [--fs_license FS_LICENSE] [--coverage] [--notrack]
                         [-v]
                         bids_dir output_dir {participant,group}

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 the participant level analysis.

analysis_level

Possible choices: participant, group

Level of the analysis that will be performed. 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.

--session_label
The label(s) of the session that should be analyzed.

The label corresponds to ses-<session_label> from the BIDS spec (so it does not include “ses-“). If this parameter is not provided all sessions should be analyzed. Multiple sessions can be specified with a space separated list.

--anat_pipeline_config

Configuration .txt file for processing stages of the anatomical MRI processing pipeline

--dwi_pipeline_config

Configuration .txt file for processing stages of the diffusion MRI processing pipeline

--func_pipeline_config

Configuration .txt file for processing stages of the fMRI processing pipeline

--number_of_threads

The number of OpenMP threads used for multi-threading by Freesurfer, FSL, MRtrix3, Dipy, AFNI (Set to [Number of available CPUs -1] by default).

--number_of_participants_processed_in_parallel

The number of subjects to be processed in parallel (One by default).

Default: 1

--mrtrix_random_seed

Fix MRtrix3 random number generator seed to the specified value

--ants_random_seed

Fix ANTS random number generator seed to the specified value

--ants_number_of_threads

Fix number of threads in ANTs. If not specified ANTs will use the same number as the number of OpenMP threads (see —-number_of_threads option flag)

--fs_license

Freesurfer license.txt

--coverage

Run connectomemapper3 with coverage

Default: False

--notrack

Do not send event to Google analytics to report BIDS App execution, which is enabled by default.

Default: False

-v, --version

show program’s version number and exit

Important

Before using any BIDS App, we highly recommend you to validate your BIDS structured dataset with the free, online BIDS Validator.

Participant Level Analysis

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

$ docker run -t --rm -u $(id -u):$(id -g) \
        -v /home/localadmin/data/ds001:/bids_dir \
        -v /media/localadmin/data/ds001/derivatives:/output_dir \
        (-v /usr/local/freesurfer/license.txt:/bids_dir/code/license.txt \)
        sebastientourbier/connectomemapper3:v3.0.0-RC2 \
        /bids_dir /output_dir participant --participant_label 01 \(--session_label 01 \)
            --anat_pipeline_config /bids_dir/code/ref_anatomical_config.ini \)
        (--dwi_pipeline_config /bids_dir/code/ref_diffusion_config.ini \)
        (--func_pipeline_config /bids_dir/code/ref_fMRI_config.ini \)
        (--number_of_participants_processed_in_parallel 1)

Note

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

The user is requested to use its own Freesurfer license (available here). CMP expects by default to find a copy of the FreeSurfer license.txt in the code/ folder of the BIDS directory. However, one can also mount with the -v docker run option a freesurfer license.txt, which can be located anywhere on its computer (as in the example above, i.e. /usr/local/freesurfer/license.txt) to the code/ folder of the BIDS directory inside the docker container (i.e. /bids_dir/code/license.txt).

Note

At least a configuration file describing the processing stages of the anatomical pipeline should be provided. Diffusion and/or Functional MRI pipeline are performed only if a configuration file is set. The generation of such configuration files, the execution of the BIDS App docker image and output inpection are facilitated through the use of the Connectome Mapper GUI, i.e. cmpbidsappmanager (see dedicated documentation page)

Debugging

Logs are outputted into <output dir>/cmp/sub-<participant_label>/sub-<participant_label>_log-cmpbidsapp.txt.

Support, bugs and new feature requests

If you need any support or have any questions, you can post to the CMTK-users group.

All bugs, concerns and enhancement requests for this software are managed on GitHub and can be submitted at https://github.com/connectomicslab/connectomemapper3/issues.

Not running on a local machine?

If you intend to run CMP3 on a remote system such as a high-performance computing cluster where Docker is not available due to root privileges, a Singularity image is also built for your convenience and available on Sylabs.io. Please see instructions at Running on a cluster (HPC).

Also, 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. A tutorial is provided in Adopting Datalad for collaboration.