trac-all

Index

Contents

  1. Name
  2. Usage
  3. Arguments
    1. Required Arguments
      1. Processing step options
    2. Optional arguments
      1. Status and log files
      2. Other arguments
  4. Processing steps
  5. Output directories and files
    1. Outputs from trac-all -corr
    2. Outputs from trac-all -intra
    3. Outputs from trac-all -inter
    4. Outputs from trac-all -masks
    5. Outputs from trac-all -tensor
    6. Outputs from trac-all -prior

Name

trac-all: White-matter pathway reconstruction from diffusion-weighted MR images using TRACULA

Usage

Using a configuration file to set analysis options: 

trac-all -[step] -c <configfile>

Using only mandatory inputs with all default options (no configuration file needed): 

trac-all -[step] -s <subjectname> --i <dicomfile>

In the above -[step] is one or more command-line options that specify which steps of the processing to run (see details below).

For Martinos Center users:

For non-MGH acquisitions

Arguments

Required Arguments

-c <dmrirc>

configuration file that specifies analysis options

OR:

-s <subjectname>

name of the subject upon which to operate (if not specified via a configuration file)

-i <file>

path to the input diffusion-weighted images (if not specified via a configuration file)

In addition to the above, one of the processing step options below must be provided to specify which parts of the analysis to run.

Processing step options

Choosing which part of the analysis to do:

-prep

Run all preprocessing (steps 1.1-1.6, see below)

-bedp

Run FSL's bedpost (step 2)

-path

Run pathway reconstruction (step 3)

Performing a part of the preprocessing or skipping a part:

-corr

Run image corrections (step 1.1)

-nocorr

Skip step 1.1

-intra

Run intra-subject registration (step 1.2)

-nointra

Skip step 1.2

-inter

Run inter-subject registration (step 1.3)

-nointer

Skip step 1.3

-masks

Run mask creation (step 1.4)

-nomasks

Skip step 1.4

-tensor

Run tensor fit (step 1.5)

-notensor

Skip step 1.5

-prior

Run estimation of pathway priors (step 1.6)

-noprior

Skip step 1.6

Optional arguments

Status and log files

-log <file>

Log file (default: $SUBJECTS_DIR/<your_subjectid>/scripts/trac-all.log)

-cmd <file>

Command file (default: $SUBJECTS_DIR/<your_subjectid>/scripts/trac-all.cmd)

-noappendlog

Start new log files instead of appending to existing files

Other arguments

-no-isrunning

Do not check whether subjects are currently being processed

-sd <dir>

Specify subjects dir (default: $SUBJECTS_DIR)

-umask <umask>

Set unix file permission mask (default: 002)

-grp <groupid>

Check that current group is alpha groupid

-allowcoredump

Set coredump limit to unlimited

-debug

Generate much more output

-dontrun

Do everything except executing commands

-onlyversions

Print version of each binary and exit

-version

Print version of this script and exit

-help

Print full contents of help

Processing steps

  1. Preprocessing

    • 1.1 Image corrections

      • This step does the following:
      • Convert the input diffusion-weighted image files to NIfTI. (This is skipped if a NIfTI file is given as the input.)
      • Change orientation of the input diffusion-weighted images to match FSL's preferred orientation.

      • Correct for B0 inhomogeneities (optional). This is done using FSL's field map-based EPI unwarping tool, see epidewarp.fsl. To run this step, B0 field map files should be specified in the configuration file.

      • Correct for eddy currents and simple head motion (optional). This is done using FSL's eddy_correct.
      • Create a brain mask from the low-b diffusion images. This done using FSL's bet. The configuration file can be used to specify if this brain mask will actually be used in the following processing steps or if the anatomical brain mask from recon-all will be used instead.

      1.2 Intra-subject registration This step does the following:

      • Change orientation of the T1 anatomical image to match FSL's orientation
      • Compute forward and inverse transformation matrices between the original T1 and re-oriented T1.
      • Compute forward and inverse transformation matrices between T1(Original and re-oriented) and low-b Diffusion image using FLIRT and/or BBREGISTER

      1.3 Inter-subject registration This step does the following:

      For MNI template

      • Compute forward and inverse transformations between T1(Original and re-oriented) and the MNI atlas using FLIRT/BBREGISTER
      • Combine the low-b to T1 transformation (from the intra subject registration step) with the above transformation to get Diffusion to MNI/MNI to Diffusion transformations

      1.4 White-matter, cortical and whole-brain masks - Generate masks of the white matter and cortex from FreeSurfer outputs, whole-brain masks from T1 and DWIs. This step does the following:

      • Create masks of cerebral White Matter (WM), cerebellar WM, ventral DC and brainstem.
      • Map cortical parcellation to volume, growing 2mm into the WM and create a mask of the grown cortex.
      • Dilate the brain segmentation output from freesurfer (aparc+aseg.nii.gz) to make a brain mask.
      • Transform all the necessary labels (Anatomical masks) from Anatomical space to Diffusion space and MNI space using the transformation matrices computed in steps 1.2-1.3
      • Transform diffusion brain masks to individual anatomical space and MNI space
      1.5 Tensor fit - Tensor model fitting on DWIs. This step does the following:
      • Compute least squares tensor estimation using the anatomical mask created in step 1.4 as the brain mask.
      • Check for scalar outputs of tensor fit.
      • Map scalar outputs of tensor fit to MNI template.
      1.6 Pathway priors from atlas to T1 - Combine training data and subject's own data to generate pathway priors.
      • Compute priors, end ROIs and intial control points from the training set
      • Map initial control points to diffusion space
  2. Ball-and-stick model fitting with bedpost (Cluster highly recommended for this step)

    This step runs FSL's bedpostx step for modeling crossing fibers using the ball-and-stick model of diffusion. It uses two anisotropic compartments and 1 isotropic compartment by default for modeling the diffusion data.

  3. Pathway reconstruction This step does the following:
    • Estimate apriori probabilities (Priors) that a certain path will intersect/ neighbor certain anatomical segmentation labels (obtained from step 1.4) from the training set.
    • Estimate the posterior probability distribution of the path using an MCMC algorithm given the Priors obtained from the training set and the Likelihood estimates of the underlying data obtained from the ball and stick model fitting.

Output directories and files

Running trac-all creates a new directory named <subjid> (if subject id is specified through the commandline) or <subjlist(i)> (if a subjectlist is specified through the configuration file, where i is index of the subject that is currently being processed)

Outputs from trac-all -corr

Note: The list below does not include outputs from B0 inhomogenity correction

This creates three directories under the <subjid> directory (i) dlabel/diff (ii) dmri (iii) scripts

Outputs from trac-all -intra

Note: <regtype>: flt (FLIRT) / bbr (BBREGISTER)

This step creates a folder <subjid>/dmri/xfms

Outputs from trac-all -inter

The following outputs get created if registering to an MNI template.

Outputs from trac-all -masks

This step creates the following folders (i) <subjid>/dlabel/anatorig (ii) <subjid>/dlabel/anat (iii) <subjid>/dlabel/diff (iv) <subjid>/dlabel/mni

The images given below are created in all four spaces:

Note: <space> - anatorig, diff, anat, mni

The following are the output files/images created in this step:

Outputs from trac-all -tensor

The following are the scalar outputs that are computed after fitting a tensor model to the Diffusion data (This is done with FSL's dtifit. For more information refer to the FSL's dtifit page here)

Note: The same set of outputs in MNI space is created under the following directory <subjid>/dmri/mni/dtifit_*.nii.gz

Outputs from trac-all -prior