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. |
See also
More information about BIDS Apps? Please check directly on the BIDS Apps Website.
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.