bullseye pipeline

Pipeline for creating a bullseye parcellation of the cerebral whiter matter using part of the FreeSurfer output and commands. It provides an (anatomy-independent) spatial localization based on an radial component (ie, lobes) and a depth component. It can be used to obtain region-specific quantification of white matter parameters (eg, a similar approach has been used to quantify regional white matter hyperintensity load in this and this papers).

This document explains how to use the package. The internals of the process are explained in this blog post.

• the bullseye parcellation is the intersection of a lobar parcellation and a depth parcellation

• the lobar parcellation consists of 4 lobes per hemisphere (frontal, parietal, temporal and occipital) + 1 consisting of the basal ganglia and thalamus as an additional region: (4*2) + 1 = 9 lobes

• the depth parcellation consists of 4 equidistant parcels spanning from the surface of the ventricles to the internal surface of the cortex

requirements

• a working FreeSurfer 6.0.0 installation
• Python 2.7 (with packages nibabel, nipype, numpy and scipy)

installation

After cloning the repository, install the pipeline with python setup.py install

When the pipeline is installed, it can then be executed from the command line as run_bullseye_pipeline -h / [ARGS]

arguments

run_bullseye_pipeline accepts the following arguments:

• -s, --scansdir: scans directory with the data for each subject (mandatory)
• -w, --workdir: work directory where data will be processed' (mandatory)
• -o, --output_dir: output directory where results will be stored (mandatory)
• --subjects: one or more subject IDs (space separated)
• -b, --debug: debug mode (saves the pipeline graph in the work directory)
• -p, --processes: overall number of parallel processes
• -n, --name: pipeline workflow name (default='bullseye_pipeline')

scans directory

The pipeline can be run by passing an input scans directory following the FreeSurfer structure (typically pointed by SUBJECTS_DIR). However, not all the FreeSurfer output is required. The following is the mandatory portion of FreeSurfer data that is required by the pipeline:

• scansdir
  • subject-id1
  • mri
    • aseg.mgz
    • ribbon.mgz
  • label
    • lh.aparc.annot
    • rh.aparc.annot
  • surf
    • lh.white
    • rh.white
    • lh.pial
    • rh.pial
  • subject-id2
    ...

output directory structure

After execution of the pipeline a directory output_dir is created with the following structure:

• output_dir
  • subject-id1
  • bullseye_wmparc.nii.gz
  • lobes_wmparc.nii.gz
  • shells_wmparc.nii.gz
  • subject-id2
    ...

containing, respectively, the final bullseye parcellation, and the lobar and depth parcellations used to create it.