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
Pipeline for pre-processed (distortion, motion & eddy corrected) DWI data (RECOMMENDED!):
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
-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.