Usage

This document explains the usage of the PSMD tool and refers both to the original version (1.0, released with the paper in 2016) and the revised version (1.5, updated in 2019). The changes introduced with version 1.5 are described on this page.

Components

The PSMD tool comprises the following items:

  • PSMD shell script: psmd.sh
  • Custom skeleton masks:
    • skeleton_mask.nii.gz (original mask from 2016)
    • skeleton_mask_v1.5.nii.gz (updated mask from 2019)
  • Sample dataset (2 subjects) to test the pipeline

Prerequisites

In addition to the PSMD tool (provided on this page), you will need:

  • Computer with Linux or macOS. For Windows, a Linux virtual machine is needed, e.g. the NeuroDebian Virtual Machine
  • An installation of the FMRIB Software Library (FSL)

Important remarks regarding FSL

  • The PSMD pipeline has been tested with FSL versions 5.0.6 and 5.0.9, but other FSL versions may also work. Go to FSL download page.
  • The terms of the FSL license apply! The PSMD tool itself is neither part of nor affiliated with FSL.
  • Diffusion imaging data with multiple diffusion directions ("diffusion tensor imaging, DTI")

DTI requirements

  • DTI data with at least 20 diffusion directions and a b-value between 700 and 1200 is required. An isotropic resolution around 2 mm is usually best, but other geometries might also work.
  • The use of unprocessed data (in Nifti format) is recommended. The script will perform all pre-processing.
  • As an alternative, already processed fractional anisotropy (FA) and mean diffusivity (MD) can be used as input. However, this is not recommended, since correct pre-processing of data (especially brain extraction) is crucial. Therefore, we recommend to let the script handle pre-processing!
  • DTI data should undergo quick visual inspection to exclude large artefacts. No further human intervention is required in subsequent steps.

Usage

From unprocessed DTI data

./psmd.sh -d DTI_data -b bvals -r bvecs -s skeleton_mask

DTI_data: Raw/unprocessed DTI data, Nifti format
bvals: Text file containing b-values (in FSL format)
bvecs: Text file containing diffusion vectors (in FSL format)
skeleton_mask: Skeleton mask file, e.g. the mask provided with the PSMD tool

From processed DTI data

./psmd.sh -f FA_image -m MD_image -s skeleton_mask

FA_image: The fractional anisotropy image, brain extracted, Nifti format
MD_image: The mean diffusivity image, brain extracted, Nifti format
skeleton_mask: Custom skeleton mask provided with this script

Additional options

The -q option can be used to output only the final result. This is very useful e.g. when writing the output into a file: psmd.sh -q <other options> > result.txt

Type ./psmd.sh -h for additional usage information.

Pipeline

The following steps will be performed through the PSMD tool:

  • Pre-processing of DTI data (eddy current and motion correction, brain extraction, tensor fitting). This step is skipped when using already processed data as input.
  • Skeletonization using the FA image and the FSL-TBSS pipeline with the standard FMRIB skeleton as target.
  • Projection of MD data onto the skeleton.
  • Masking of the skeleton in order to focus the analysis on the cerebral hemispheres and to exclude areas with frequent CSF contamination.
  • Histogram analysis with calculation of peak width.
  • The entire calculation will take approx. 12 minutes per subject on a standard desktop computer

Sample Dataset

Data from two subjects (already pre-processed) are provided for testing the pipeline at your site. The calculated PSMD should be 0.000267824 for Subject A and 0.000894987 for Subject B.

Simply run:
./psmd.sh -f subjectA_FA.nii.gz -m subjectA_MD.nii.gz -s skeleton_mask.nii.gz
./psmd.sh -f subjectB_FA.nii.gz -m subjectB_MD.nii.gz -s skeleton_mask.nii.gz

Caution

Slight deviations might occur depending on the platform and FSL version.
The results presented were obtained with FSL 5.0.9 on macOS 10.12.

 


Last update: 2019-12-06