.. _README:

==============================================================================
Software
==============================================================================
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
easily installed as a cross-platform virtual machine for convenience and
reproducibility of results. Behind the scenes runs open source
Python and C++ code within a Nipype pipeline framework.

------------------------------------------------------------------------------
Help
------------------------------------------------------------------------------
- Help in a terminal window (see below for inputs and outputs)::

    mindboggle --help

- `Documentation <http://mindboggle.info/documentation.html>`_
- `Installation <http://mindboggle.info/users/INSTALL.html>`_
- `FAQ <http://mindboggle.info/faq/index.html>`_
- `License <http://mindboggle.info/users/LICENSE.html>`_
- `Contributors <http://mindboggle.info/users/THANKS.html>`_

------------------------------------------------------------------------------
Mindboggle
------------------------------------------------------------------------------
    1. combines non/cortex segmentations from FreeSurfer and ANTs software packages
    2. propagates FreeSurfer and ANTs-registered labels through cortex and noncortex voxels
    3. computes label volumes and cortical label thicknesses
    4. computes shape measures on every vertex of FreeSurfer cortical surface meshes
    5. extracts cortical surface features
    6. computes statistics on shape measures per cortical surface label/feature:

        - Surface area
        - Travel depth
        - Geodesic depth
        - Mean curvature
        - Convexity (FreeSurfer)
        - Thickness (FreeSurfer)
        - Laplace-Beltrami spectra
        - Zernike moments [UNDER EVALUATION]

------------------------------------------------------------------------------
Examples
------------------------------------------------------------------------------
If running Mindboggle in a virtual machine (recommended),
type the following two commands in the same directory as the Vagrantfile
you generated (see `INSTALL <INSTALL.html>`_) to launch and log into the
Mindboggle virtual machine (requires an active internet connection)::

    vagrant up
    vagrant ssh

Once logged in, you can type the following in a terminal window to run
mindboggle on data that has been processed by FreeSurfer
(replace SUBJECT with the name of a subject directory created by FreeSurfer)::

    mindboggle SUBJECT

The following example also makes use ANTs output files and 8 processors
(replace SEGMENTS with the ANTs segmented output, such as
``ants_subjects/subject1/tmpBrainSegmentation.nii.gz``)::

    mindboggle SUBJECT --ants_segments SEGMENTS -n 8

This example uses many of the currently available options within Mindboggle
(backslash denotes a line return)::

    mindboggle SUBJECT --ants_segments SEGMENTS -n 8 \
               --sulci --fundi --vertices --spectra 10 --thickness --visual hier

------------------------------------------------------------------------------
Inputs
------------------------------------------------------------------------------
Mindboggle currently takes output from FreeSurfer_ (preferably v5.3 and above)
and the latest ANTs_ software packages.

**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., to ``subject1``)::

    recon-all -all -i IMAGE -s SUBJECT

..
    - mri/orig/001.mgz
    - mri/[wmparc,aparc+aseg].mgz
    - surf/[lh,rh].pial
    - label/[lh,rh].aparc.annot

**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
`OASIS-30 template <http://mindboggle.info/data/templates/atropos/OASIS-30_Atropos_template.tar.gz>`_
files::
    antsCorticalThickness.sh -d 3 -n 3 -w 0.25 \
      -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

------------------------------------------------------------------------------
Outputs
------------------------------------------------------------------------------
By default, final outputs are saved in $HOME/mindboggled/SUBJECT, where
$HOME is the home directory and SUBJECT is the name of the subject
(all data are in the original subject's space).
Each output in the labels directory is assumed to be a
Nifti_ image volume (.nii.gz) that stores anatomical `labels <http://mindboggle.info/faq/labels.html>`_;
if in a surface directory it refers to a cortical surface in VTK_ format (.vtk),
whose vertices are number-labeled by anatomical label, feature, or shape measure.
All tables are in CSV format (.csv) where each row represents a label/feature/vertex,
and the columns contain shape statistics.

+-+---------------+----------------------------------------------+--------------+
| |  **Folder**   | **Contents**                                 | **Format**   |
+-+---------------+----------------------------------------------+--------------+
| |   labels/     |  number-labeled surfaces and volumes         | .vtk, .nii.gz|
+-+---------------+----------------------------------------------+--------------+
| |   features/   |  surface features: folds, sulci, fundi       | .vtk         |
+-+---------------+----------------------------------------------+--------------+
| |   shapes/     |  surfaces with shape measures (per vertex)   | .vtk         |
+-+---------------+----------------------------------------------+--------------+
| |   tables/     |  tables of shape measures per label/feature  | .csv         |
+-+---------------+----------------------------------------------+--------------+

**mindboggled** / SUBJECT /

    **labels** /

        **FreeSurfer_wmparc_labels**:  *[FS wmparc+aseg labels for a given subject brain]*

        **FreeSurfer_wmparc_filled_labels**:  *[segmentation modified and filled with FS labels]*

        **ANTs_labels**:  *[joint-fusion atlas labels registered to the subject]*

        **ANTs_filled_labels**:  *[revised segments filled with ANTs + FS cerebellar labels]*

        **ATLAS_labels**:  *[subject labeled with ATLAS labels, from "--atlases ATLAS"]*

        [left,right]_surface /

            **FreeSurfer_cortex_labels**:  *[FS or DKT atlas cortical surface labels assigned to subject]*

    **features** /

        [left,right]_surface /

            **folds**:  *[depth-based cortical surface folds (invaginations)]*

            **sulci**:  *[folds segmented into sulci using label pairs]*

            **fundus_per_fold**:  *[curves running along depths of folds]*  **UNDER EVALUATION**

            **fundus_per_sulcus**:  *[fundus curves segmented by sulcus labels]*  **UNDER EVALUATION**

    **shapes** /

        [left,right]_surface /

            **area**:  *[per-vertex surface area]*

            **mean_curvature**:  *[per-vertex mean curvature]*

            **geodesic_depth**:  *[per-vertex geodesic depth]*

            **travel_depth**:  *[per-vertex travel depth]*

            **FreeSurfer_convexity**:  *[FreeSurfer's [lh,rh].sulc files converted to VTK format]*

            **FreeSurfer_thickness**:  *[FreeSurfer's [lh,rh].thickness files converted to VTK format]*

    **tables** /

        **FreeSurfer_filled_labels_volumes**:  *[volume per FS-filled label]*

        **FreeSurfer_filled_labels_volumes_areas_thicknesses**:  *[measure per FS-filled cortical label]*

        **ANTs_filled_labels_volumes**:  *[volume per ANTs-filled label]*

        **ANTs_filled_labels_volumes_areas_thicknesses**:  *[measure per ANTs-filled cortical label]*

        **ATLAS_labels_volumes**:  *[volume per ATLAS label, from "--atlases ATLAS"]*

        [left,right]_surface /

            **label_shapes**:  *[per-label surface shape statistics]*

            **sulcus_shapes**:  *[per-sulcus surface shape statistics]*

            **fundus_shapes**:  *[per-fundus surface shape statistics]*  **UNDER EVALUATION**

            **vertices**:  *[per-vertex surface shape statistics]*