Skip to content

How to use the PSMD tool

This page always refers to the latest version of PSMD. For an older version, run ./psmd.sh -h on the command line to get usage information.

Prerequisites

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

  • Computer with Linux or macOS.
  • An installation of the FMRIB Software Library (FSL), version 6.0 or higher

Important remarks regarding FSL

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.
  • For Windows, we recommend using the Singularity container together with a virtual machine setup. Please see the PSMD Singularity Container

Usage

Pipeline for unprocessed DTI data:

psmd.sh -d <DWI_data> -b <bvals> -r <bvecs> -s <skeleton_mask>

Mandatory arguments:
-d <DWI_data>: Unprocessed DWI data in Nifti format
-b <bvals>: Text file containing b-values (in FSL format)
-r <bvecs>: Text file containing diffusion vectors (in FSL format)
-s <skeleton_mask>: Skeleton mask file, e.g. the mask provided with the PSMD tool

psmd.sh -p <PP_DWI_data> -b <bvals> -r <bvecs> -s <skeleton_mask>

Mandatory arguments:
-p <PP_DWI_data>: Pre-processed DWI data in Nifti format
-b <bvals>: Text file containing b-values (in FSL format)
-r <bvecs>: Text file containing diffusion vectors (in FSL format)
-s <skeleton_mask>: Skeleton mask file, e.g. the mask provided with the PSMD tool

Pipeline for fully processed and fitted DTI images (FA and MD images):

psmd.sh [options] -f FA_image -m MD_image -s skeleton_mask_file

Mandatory arguments:
-f <FA_image>: The fractional anisotropy image, brain extracted, Nifti format
-m <MD_image>: The mean diffusivity image, brain extracted, Nifti format
-s <skeleton_mask>: Skeleton mask file, e.g. the mask provided with the PSMD tool

Additional, optional arguments:

-e <bvalue>: Enhanced masking of CSF and hyperintense voxels (e.g. certain artefacts). Please specify of the diffusion shell to use (usually 1000) (requires unprocessed or pre-processed DWI data)

-l <lesion_mask>: Supply custom lesion mask in order to exclude a region from analysis

-o: Output mean skeletonized mean diffusivity (MSMD) instead of PSMD

-g: Output PSMD (or MSMD) separately for each hemisphere, comma-separated (left,right)

-c: Clear temporary psmdtemp folder from previous run (if present)
-q: Quiet, no messages are displayed, only result (suitable for writing result into file)
-v: Verbose. very detailed status and error messages are displayed.
-t: Troubleshooting, temporary files (folder psmdtemp) will not be deleted

Type ./psmd.sh -h for usage information on the command line.

Version history

Please see the Github Releases page.

 


Last update: 2020-12-09