NOTE: CURRENTLY MOVING CODE FROM PYTHON 2 TO PYTHON 3...

The Mindboggle software package automates shape analysis of anatomical labels and features extracted from human brain MR image data. Mindboggle can be run as a single command, and can be installed as a cross-platform virtual machine for convenience and reproducibility of results. Behind the scenes, open source Python and C++ code run within a modular Nipype pipeline framework.

Release

Date

Contents:

• GitHub
• Contributors
• genindex
• modindex

Mindboggle comes as a single installation script, install_mindboggle.sh, that may be directly called to install Mindboggle on a Linux machine ($ source install_mindboggle.sh). However, for reasons of convenience and reproducibility of results, we recommend using a different script, configure_mindboggle_vm, to perform the same installation on Linux, MacOSX, or Windows, but in a virtual machine (VM). Download the VM script to wherever you want the startup directory to be, and do the following (type commands in a terminal for steps 2 and 3).

1. Install VM dependencies:

   Vagrant manages virtual machines.

   Vagrant provides reproducible and portable work environments that isolate dependencies and their configuration within a single disposable, consistent environment that can run on Linux, MacOSX, or Windows.

   Virtualbox provides

   virtual machines used by Vagrant. Alternative backend providers for Vagrant include VMware and Amazon Web Services.

2. Download and configure the virtual machine to access your local brain image (usually FreeSurfer output) data by typing the following in the same directory as the VM script. This generates a configuration file called "Vagrantfile":

python configure_mindboggle_vm

For help with more options, such as how to mount your local ANTs data directory, set the number of processors, etc., add "-h" to the above:

python configure_mindboggle_vm -h

3. Henceforth, whenever running Mindboggle, first type the following in the same directory as the Vagrantfile:

vagrant up
vagrant ssh

To run Mindboggle, you must first preprocess brain MR image data (see Preprocessing below). To get up and running with the following examples, download and uncompress ("tar xvfz example.tar.gz") the example.tar.gz directory (over 500MB), which includes abridged freesurfer, ANTs, and mindboggle output for one person.

For help after installing, type the following in a terminal window:

mindboggle -h

Example 1: The following bare-bones command runs Mindboggle on data processed by FreeSurfer but not ANTs:

mindboggle $HOME/example/freesurfer_subjects/arno

Example 2: The same command, but takes advantage of ANTs output (backslash denotes line return):

mindboggle $HOME/example/freesurfer_subjects/arno \
--ants $HOME/example/ants_subjects/arno/antsBrainSegmentation.nii.gz

Example 3: To generate only volume (and not surface) labels and shape measures from FreeSurfer data, using 8 processors:

mindboggle $HOME/example/freesurfer_subjects/arno --no_surfaces -p 8

As you may have inferred from the "Running Mindboggle" examples and example data above, Mindboggle currently takes output from FreeSurfer (preferably v6 or higher) and optionally from ANTs (preferably v2.1.0rc3 or higher).

FreeSurfer generates labeled cortical surfaces, and labeled cortical and noncortical volumes. Run recon-all on a T1-weighted IMAGE file (e.g., subject1.nii.gz) and set the output SUBJECT name (e.g., subject1):

recon-all -all -i IMAGE -s SUBJECT

ANTs provides brain volume extraction, segmentation, and registration-based labeling. To generate the ANTs transforms and segmentation files used by Mindboggle, run the antsCorticalThickness.sh script on the same IMAGE file, set an output PREFIX, and provide paths to the OASIS-30 Atropos template files (backslash denotes a line return):

antsCorticalThickness.sh -d 3 -a IMAGE -o PREFIX \
  -e OASIS-30_Atropos_template/T_template0.nii.gz \
  -t OASIS-30_Atropos_template/T_template0_BrainCerebellum.nii.gz \
  -m OASIS-30_Atropos_template/T_template0_BrainCerebellumProbabilityMask.nii.gz \
  -f OASIS-30_Atropos_template/T_template0_BrainCerebellumExtractionMask.nii.gz \
  -p OASIS-30_Atropos_template/Priors2/priors%d.nii.gz

1. Create hybrid gray/white segmentation from FreeSurfer and ANTs output (combine_2labels_in_2volumes).
2. Fill hybrid segmentation with FreeSurfer- or ANTs-registered labels.

3. Compute volume shape measures for each labeled region:

   • volume (volume_per_brain_region)
   • thickness of cortical labels (thickinthehead)

4. Compute surface shape measures for every cortical mesh vertex:

   • surface area
   • travel depth
   • geodesic depth
   • mean curvature
   • convexity (from FreeSurfer)
   • thickness (from FreeSurfer)

5. Extract cortical surface features:

   • folds
   • sulci
   • fundi

6. For each cortical surface label/sulcus, compute:

   • area
   • mean coordinates: means_per_label
   • mean coordinates in MNI152 space
   • Laplace-Beltrami spectrum
   • Zernike moments

7. Compute statistics (stats_per_label in compute.py) for each shape measure in #4 for each label/feature:

   • median
   • median absolute deviation
   • mean
   • standard deviation
   • skew
   • kurtosis
   • lower quartile
   • upper quartile

Example output data is in the example/mindboggled/ directory downloaded in the Preprocessing section above. By default, output files are saved in $HOME/mindboggled/SUBJECT, where $HOME is the home directory and SUBJECT is a name representing the person's brain that has been scanned. Volume files are in NIfTI format, surface meshes in VTK format, and tables are comma-delimited. Each file contains integers that correspond to anatomical labels <labels> or features (0-24 for sulci). All output data are in the original subject's space. The following include outputs from most, but not all, optional arguments.

mindboggled / SUBJECT /

labels /

freesurfer_wmparc_labels_in_hybrid_graywhite.nii.gz: hybrid segmentation filled with FS labels

ants_labels_in_hybrid_graywhite.nii.gz: hybrid segmentation filled with ANTs + FS cerebellar labels

[left,right]_cortical_surface / freesurfer_cortex_labels.vtk: DKT cortical surface labels

features / [left,right]_cortical_surface /

folds.vtk: (unidentified) depth-based folds

sulci.vtk: sulci defined by DKT label pairs in depth-based folds

fundus_per_sulcus.vtk: fundus curve per sulcus -- UNDER EVALUATION --

cortex_in_MNI152_space.vtk: cortical surfaces aligned to an MNI152 template

shapes / [left,right]_cortical_surface /

area.vtk: per-vertex surface area

mean_curvature.vtk: per-vertex mean curvature

geodesic_depth.vtk: per-vertex geodesic depth

travel_depth.vtk: per-vertex travel depth

freesurfer_curvature.vtk: FS curvature files converted to VTK

freesurfer_sulc.vtk: FS sulc (convexity) files converted to VTK

freesurfer_thickness.vtk: FS thickness files converted to VTK

tables /

volume_per_freesurfer_label.csv: volume per FS label

volumes_per_ants_label.csv: volume per ANTs label

thickinthehead_per_freesurfer_cortex_label.csv: FS cortex label thickness

thickinthehead_per_ants_cortex_label.csv: ANTs cortex label thickness

[left,right]_cortical_surface /

label_shapes.csv: per-label surface shape statistics

sulcus_shapes.csv: per-sulcus surface shape statistics

fundus_shapes.csv: per-fundus surface shape statistics -- UNDER EVALUATION --

vertices.csv: per-vertex surface shape statistics