Mindboggle 2016

From HPC users
Revision as of 09:45, 19 August 2019 by Schwietzer (talk | contribs) (→‎Third step: Mindboggle)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Introduction

Mindboggle’s open source brain morphometry platform takes in preprocessed T1-weighted MRI data, and outputs volume, surface, and tabular data containing label, feature, and shape information for further analysis. Mindboggle can be run on the command line as “mindboggle”. The program is written in Python 3 and Python-wrapped C++ code called within a Nipype pipeline framework.

Installed version(s)

This version is installed and currently available on environment hpc-env/6.4:

Mindboggle/1.2.4-foss-2017b-Python-3.6.3

About Mindboggle

If you want to find out more about Mindboggle on the HPC Cluster, you can use the command

module spider Mindboggle

This will show you basic informations e.g. a short description and the currently installed version.

To load the desired version of the module, use the command, e.g.

module load hpc-env/6.4 
module load Mindboggle

Always remember: this command is case sensitive!


Besides Mindboggle itself, the module also loads various dependencies, which can all be used separately. Some of the dependencies are:

To list every single loaded dependency, type in the following after loading the Mindboggle module:

module list

Using Mindboggle

On the following lines, we will describe how you can use Mindboggle combined with ANTs and FreseSurfer. Bur we are besically just redescribing the official Mindboggle tutorial, because our environment differs from the tutorial since we don't work with a Docker image. (Starting at section Run separate commands, because the all-in-one-command mindboggle123 generates errors on our system.)

First step: FreeSurfer

At first, you need a brain image file, a target location, and an output ID.

  • Let's assume, the brain image is stored on location ~/brain_image.
  • As for the target location, FreeSurfer already generated the path ~/freesurfer/subjects
  • The ID can be chosen freely. Let's call it arno
IMAGE=~/brain_image/T1.nii.gz  # Setting variable for image
FREESURFER_OUT=~/freesurfer/subjects # setting variable for output path
ID=arno                              # setting variable for ID

recon-all -all -i $IMAGE -s $ID -sd $FREESURFER_OUT  # starting the first step

Explanation: "FreeSurfer generates labeled cortical surfaces, and labeled cortical and noncortical volumes. Run recon-all on a T1-weighted IMAGE file (and optionally a T2-weighted image), and set the output ID name as well as the $FREESURFER_OUT output directory:" ¹

Second step: ANTs

Secondly, use ANTs on a template which must be downloaded first:

wget -O OASIS-30_Atropos_template.zip "https://files.osf.io/v1/resources/36gdy/providers/osfstorage/57a234b4594d900203319182?action=download&version=2&direct"
mkdir ~/ants_template                                  # create a folder for the template
unzip OASIS-30_Atropos_template.zip -d ~/ants_template # extract the template archive to the new folder
TEMPLATE=~/ants_template/OASIS-30_Atropos_template     # link a new variable to the  template path
mkdir ~/ants_out                                       # create folder for ANTs output
ANTS_OUT=~/ants_out                                    # create variable for ANTs output

# start processing with ANTs on the template data 
antsCorticalThickness.sh -d 3 -a $IMAGE -o $ANTS_OUT/$ID/ants \
  -e $TEMPLATE/T_template0.nii.gz \
  -t $TEMPLATE/T_template0_BrainCerebellum.nii.gz \
  -m $TEMPLATE/T_template0_BrainCerebellumProbabilityMask.nii.gz \
  -f $TEMPLATE/T_template0_BrainCerebellumExtractionMask.nii.gz \
  -p $TEMPLATE/Priors2/priors%d.nii.gz \
  -u 0

Explanation: "ANTs provides brain volume extraction, segmentation, and registration-based labeling. antsCorticalThickness.sh generates transforms and segmentation files used by Mindboggle, and is run on the same IMAGE file and ID as above, with $ANTS_OUT output directory. TEMPLATE points to the OASIS-30_Atropos_template folder already installed in the Docker container ('\' splits the command for readability):"

Third step: Mindboggle

Now it is time to hand over the results to mindboggle. First off, you need to set some variables again:

FREESURFER_SUBJECT=$FREESURFER_OUT/$ID
ANTS_SUBJECT=$ANTS_OUT/$ID
mkdir ~/mindboggled                                    # create output folder 
OUT=~/mindboggled                                      # use output folder on variable

Example 1: Run Mindboggle on data processed by FreeSurfer but not ANTs:

mindboggle $FREESURFER_SUBJECT --out $OUT

Example 2: Same as Example 1 with output to visualize surface data with roygbiv: mindboggle $FREESURFER_SUBJECT --out $OUT --roygbiv

Example 3: Take advantage of ANTs output as well ('\' splits for readability):

mindboggle $FREESURFER_SUBJECT --out $OUT --roygbiv \
    --ants $ANTS_SUBJECT/antsBrainSegmentation.nii.gz

Example 4: Generate only volume (no surface) labels and shapes:

mindboggle $FREESURFER_SUBJECT --out $OUT \
    --ants $ANTS_SUBJECT/antsBrainSegmentation.nii.gz \
    --no_surfaces

Documentation

The full documentation can be found here. More information about the first commands and a short tutorial can be found here.