Nipype and mrtrix3 based pre-/post- processing pipeline for brain diffusion-MRI and generation of structural connectomes of the brain.

CI docker

The pre-processing pipeline has been updated to reflect what's seen in the optimal DESIGNER pipeline and on mrtrix3 cloud apps on brainlife.io.

The post-processing pipeline, including co-registration of atlases and connectome generation is now included in the connectomes module

Install

Since most usages will be on HPC resources, I highly recommend that you use the Singularity definition file in the repository instead of installing the Python module.

Singularity:

  • This is a large image, you will need to set the following environment variables to somewhere other than /tmp if you want to avoid memory errors:

    • export SINGULARITY_TMPDIR={YOUR DESTINATION DIR}
    • export SINGULARITY_LOCALCACHEDIR={YOUR DESTINATION DIR}
    • export SINGULARITY_CACHEDIR={YOUR DESTINATION DIR}
    • export SINGULARITY_PULLFOLDER={YOUR DESTINATION DIR}

  • Build the singularity image with the singularity.def file provided in Github, you will need to have sudo permissions to perform singularity build. If you run into memory problems, consider building as a sandbox at first with the -s flag.

    • sudo singularity build {image_file_name}.sif singularity.def

  • OR pull the built singularity image from cloud library:

    • singularity pull --arch amd64 library://axiezai/pipetography/pipetography:latest

Docker:

  • Docker often encounters permission problems on HPC resources, using the docker container is only recommended if you have sudo permissions to the machine.
  • Use the Dockerfile in this repo to build your own Docker container.

Usage:

  • To run the singularity container interactively, you will need a few flags:
    • -e flag for a clean environnment upon container start
    • -B flag to bind your BIDS directory into the container.
  • Example:
    • singularity shell -e -B <BIDS_DIR>:<SINGULARITY_BIDS_DIR> {Path to singularity .sif} will start an interactive shell.
    • singualrity exec -e -B <BIDS_DIR>:<SINGULARITY_BIDS_DIR> {Path to singularity .sif} python dwi_pipeline.py will execute the input python code. See pipeline for an example python script that preprocesses BIDS DWI data.

Creating your own environment and install pipetography as a Python module:

pip install pipetography

Since pipetography is a Nipype wrapper around mrtrix3, ANTs, and FSL, you have to follow their installation instructions and set them up appropriately on your machine as well:

Everything listed in this section is included in the Singularity and Docker containers.

The pipeline:

Currently supports acquisitions with no reverse phase encoding (-rpe_none) and reverse phase encoding in all DWI directions (-rpe_all) options. See pipeline for preprocessing details, and connectomes for postprocessing details.