MaPPeRTrac

MaPPeRTrac is an edge-centric tractography pipeline that automates either probabilistic or deterministic tractography in a wide range of high-performance computing environments.

Input: T1-weighted anatomical MRI image (.nii.gz), diffusion MRI image (.nii.gz), the b-value file and the b-vector file for the diffusion MRI image (*.bval and *.bvec)

Output: Edge density image (.nii.gz) and connectome matrix (.mat)

Quick Setup

Requirements

• Python 3.7+
• Singularity
• CUDA 10.2-compatible GPU (Fermi thru Volta)
• FreeSurfer license (available for free here)

Installation

pip install mappertrac

# Singularity requires sudo to build from a def recipe file
cd mappertrac/data/container
# FreeSurfer license must be copied to the build context
cp path/to/freesurfer/license.txt ./license.txt
# Singularity build script, without installation of Datalad for downloading sample data
./build.sh no

Usage

If all requirements are installed:

mappertrac --s1_freesurfer <SUBJECT_INPUT_DIRECTORY> # this will take several hours

mappertrac --s2_bedpostx <SUBJECT_INPUT_DIRECTORY>

mappertrac --s3_probtrackx <SUBJECT_INPUT_DIRECTORY>

If running via Singularity containers:

mappertrac --multi_container mappertrac/data/container/ --s1_freesurfer <SUBJECT_INPUT_DIRECTORY> # this will take several hours

mappertrac --multi_container mappertrac/data/container/ --s2_bedpostx <SUBJECT_INPUT_DIRECTORY>

mappertrac --multi_container mappertrac/data/container/ --s3_probtrackx <SUBJECT_INPUT_DIRECTORY>

Note: the input directory must adhere to BIDS. See this example.

---

Instructions

Conda Installation

If you're having trouble installing MaPPeRTrac, please use a clean environment using virtualenv or conda.

conda create -n myenv
conda activate myenv
pip install mappertrac

Example Testing

Check that your installation works by running the example input data.

mappertrac --s1_freesurfer --test

Multiple subjects

You can specify multiple subjects with specific paths or Unix-style globbing

mappertrac --s1_freesurfer <SUBJECT1_DIR> <SUBJECT2_DIR> <SUBJECT3_DIR>
mappertrac --s1_freesurfer <ALL_SUBJECTS_DIR>/*/

Job scheduling

Multiple subjects can be run on distributed systems using Slurm, Cobalt, or Grid Engine.

mappertrac --s1_freesurfer --slurm -b mybank -p mypartition <SUBJECT_INPUT_DIRECTORY>

Additional options

mappertrac --help

usage: mappertrac [-h] [--test] (--freesurfer | --bedpostx | --probtrackx) [--outputs OUTPUTS] [--container CONTAINER]
                  [--trac_sample_count TRAC_SAMPLE_COUNT] [--slurm | --cobalt | --grid_engine] [--nnodes NNODES] [--bank BANK]
                  [--partition PARTITION] [--walltime WALLTIME]
                  inputs [inputs ...]

positional arguments:
  inputs                Paths to BIDS subject folder(s).

optional arguments:
  -h, --help            show this help message and exit
  --test                Test using the example subject.
  --freesurfer, --s1_freesurfer, -s1
                        Run step 1: freesurfer.
  --bedpostx, --s2_bedpostx, -s2
                        Run step 2: bedpostx.
  --probtrackx, --s3_probtrackx, -s3
                        Run step 3: probtrackx.
  --outputs OUTPUTS, -o OUTPUTS
                        Path to output directories.
  --container CONTAINER
                        Path to Singularity container image.
  --multi_container PATH/TO/CONTAINER_DIRECTORY
                        Path to Singularity containers directory.
  --trac_sample_count   TRAC_SAMPLE_COUNT
                        Number of probtrackx samples per voxel.
  --slurm               Use the Slurm scheduler.
  --cobalt              Use the Cobalt scheduler.
  --grid_engine         Use the Grid Engine scheduler.
  --nnodes NNODES, -n NNODES
                        Scheduler: number of nodes.
  --bank BANK, -b BANK  Scheduler: bank to charge for jobs.
  --partition PARTITION, -p PARTITION
                        Scheduler: partition to assign jobs.
  --walltime WALLTIME, -t WALLTIME
                        Scheduler: walltime in format HH:MM:SS.

---

If you would like to cite MaPPeRTrac in your study, please use the following references:

Moon, J. Y., Mukherjee, P., Madduri, R. K., Markowitz, A. J., Cai, L. T., Palacios, E. M., ... & Bremer, P. T. (2022). The Case for Optimized Edge-Centric Tractography at Scale. Frontiers in Neuroinformatics, 16, 752471.

Cai, L. T., Moon, J., Camacho, P. B., Anderson, A. T., Chwa, W. J., Sutton, B. P., ... & Madduri, R. K. (2024). MaPPeRTrac: A Massively Parallel, Portable, and Reproducible Tractography Pipeline. Neuroinformatics, 1-15.

License

MaPPeRTrac is distributed under the terms of the BSD-3 License.

LLNL-CODE-811655