trac-all
Index
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:
Do not submit trac-all as a job on the cluster with pbsubmit or qsub. Run it directly on the command line. If run on a local machine, trac-all will run all analyses locally. If run on the cluster, trac-all will submit the analysis of each subject listed in your configuration file as a job on the cluster.
For non-MGH acquisitions
If your DICOMs were acquired at a different site and mri_convert cannot extract the b-values and gradient vector files from them automatically, you will have to supply them in separate text files and specify them in the trac-all configuration file. To see the required format of these files, please refer to the tutorial.
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 images to match FSL's preferred orientation.
<Optional> Correct for B0 inhomogeneities. This is done using FSL's field map-based EPI unwarping tool, see epdidewarp.fsl. To run this step, B0 field map files should be specified in the configuration file.
- Correct for eddy currents and simple head motion. 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 - Diffusion-to-T1 registration with flirt and/or bbregister.
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 - T1-to-template registration using the MNI template
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
trac-all -<no>inter -c dmrirc
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 and spread them aroundd to diffusion space (Currently possible only for control points from MNI space)
trac-all -<no>prior -c dmrirc
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
<subjid>/dlabel/diff/lowb_brain_mask.nii.gz - Low-b Diffusion brain mask
<subjid>/dmri/dwi_orig.nii.gz - Original Diffusion Weighted image converted from Dicom to Analyze format
<subjid>/dmri/dwi_orig.mghdti.bvecs - Original bvecs for the Diffusion sequence
<subjid>/dmri/dwi_orig.mghdti.bvals - Original bvals for the Diffusion sequence
<subjid>/dmri/dwi_orig_flip.nii.gz - Flipped Diffusion weighted image to be used in FSL.
<subjid>/dmri/bvals.norot - Bvals rotated to match the flipped Diffusion data
<subjid>/dmri/bvecs.norot - bvecs rotated to match the flipped data
<subjid>/dmri/dwi.ecclog - Eddy-current correction log
<subjid>/dmri/dwi.nii.gz - Eddy-current corrected Diffusion image
<subjid>/dmri/bvals - Bvals rotated to compensate Eddy-current correction
<subjid>/dmri/bvecs - Bvecs rotated to compensate Eddy-current correction
<subjid>/scripts/trac-all.cmd - Command file containing all the commands executed by the trac-all script. This is constantly updated during every step unless a seperate command file option (using -cmd flag) is specified for each step.
<subjid>/scripts/trac-all.local-copy - A local copy of the actual trac-all script with which all the steps were run.
<subjid>/scripts/trac-all.log - Complete log of all the commands and processing that was done while running the trac-all script. This is constantly updated during every step unless a seperate log file option (using -log flag) is specified for each step.
<subjid>/scripts/trac-preproc.local-copy - A local copy of the actual trac-preproc script with which all the steps were run.
Outputs from trac-all -intra
Note: <regtype>: flt (FLIRT) / bbr (BBREGISTER)
This step creates a folder <subjid>/dmri/xfms
<subjid>/dmri/brain_anat_orig.nii.gz - Original skull stripped Anatomical (MPRAGE)
<subjid>/dmri/brain_anat.nii.gz - Flipped Anatomical to be used in FSL
<subjid>/dmri/xfms/anatorig2anat.mat(.dat) - Transformation matrix to go from Original Anatomical space to Flipped Anatomical space
<subjid>/dmri/xfms/anat2anatorig.mat(.dat) - Transformation matrix to go from Flipped Anatomical space to Original Anatomical space
<subjid>/dmri/lowb_brain_anat.<regtype>.nii.gz - Low-b Diffusion image in anatomical space
<subjid>/dmri/xfms/diff2anat.<regtype>.mat - Transformation matrix from Diffusion space to Flipped Anatomical space
<subjid>/dmri/xfms/anat2diff.<regtype>.mat - Transformation matrix from Flipped Anatomical space to Diffusion space
<subjid>/dmri/xfms/diff2anatorig.<regtype>.mat - Transformation matrix from Diffusion space to Flipped Anatomical space
<subjid>/dmri/xfms/anatorig2diff.<regtype>.mat - Transformation matrix from Flipped Anatomical space to Diffusion space
Outputs from trac-all -inter
The following outputs get created if registering to an MNI template.
<subjid>/dmri/brain_anat_mni.nii.gz - Flipped Anatomical in MNI space
<subjid>/dmri/xfms/anat2mni.mat - Transformation matrix from Flipped Anatomical space to MNI space
<subjid>/dmri/xfms/mni2anat.mat - Transformation matrix from MNI space to Flipped Anatomical space
<subjid>/dmri/xfms/diff2mni.<regtype>.mat - Transformation matrix from Diffusion to MNI space
<subjid>/dmri/xfms/mni2diff.<regtype>.mat - Transformation matrix from MNI to Diffusion space
<subjid>/dmri/xfms/anatorig2mni.mat - Transformation matrix from Original Anatomical space to MNI
<subjid>/dmri/xfms/mni2anatorig.mat - Transformation matrix from MNI to Original Anatomical space
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:
Original anatomical space (can be found in <subjid>/dlabel/anatorig)
Flipped anatomical space (<subjid>/dlabel/anat)
Diffusion space (<subjid>/dlabel/diff)
MNI space (<subjid>/dlabel/mni)
Note: <space> - anatorig, diff, anat, mni
The following are the output files/images created in this step:
<subjid>/dlabel/<space>/White-Matter.nii.gz - White Matter mask extracted from Freesurfer's aparc+aseg.mgz file
<subjid>/dlabel/<space>/White-Matter++.nii.gz - White Matter mask including Ventral DC and Brainstem
<subjid>/dlabel/<space>/notventricles.nii.gz - White Matter mask excluding Lateral Ventricles.
<subjid>/dlabel/<space>/aparc+aseg+2mm.nii.gz - Cortical parcellation mapped to the volume and grown into 2mm into the WM.
<subjid>/dlabel/<space>/cortex.nii.gz - Mask of the cortex
<subjid>/dlabel/<space>/cortex+2mm.nii.gz - Mask of the grown cortex
<subjid>/dlabel/<space>/Brain-Stem.nii.gz - Brain stem from Freesurfer's aparc+aseg.mgz file
<subjid>/dlabel/<space>/cortex+2mm+bs.nii.gz - Mask of cortex with brain stem
<subjid>/dlabel/<space>/anat_brain_mask.nii.gz - Anatomical brain mask
<subjid>/dlabel/<space>/anat_brain_mask-vent.nii.gz - Anatomical brain mask without ventricles
<subjid>/dlabel/<space>/aparc+aseg_mask.nii.gz - Dilated segmentation mask obtained by dilating Freesurfer's aparc_aseg.nii.gz file
<subjid>/dmri/dwi_snr.txt - SNR of DWIs in the WM mask
<subjid>/dlabel/mni/lowb_brain_mask.<regtype>.nii.gz - low-b Diffusion mask in mni space
<subjid>/dlabel/anatorig/lowb_brain_mask.<regtype>.nii.gz - low-b Diffusion mask in original anatomical space
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)
<subjid>/dmri/dtifit_FA.nii.gz - Fractional Anisotropy image
<subjid>/dmri/dtifit_V1.nii.gz - Primary Eigen Vector image
<subjid>/dmri/dtifit_V2.nii.gz - Secondary Eigen Vector image
<subjid>/dmri/dtifit_V3.nii.gz - Tertiary Eigen Vector image
<subjid>/dmri/dtifit_L1.nii.gz - Primary Eigen Value image
<subjid>/dmri/dtifit_L2.nii.gz - Secondary Eigen Value image
<subjid>/dmri/dtifit_L3.nii.gz - Tertiary Eigen Value image
<subjid>/dmri/dtifit_MD.nii.gz - Mean Diffusivity
<subjid>/dmri/dtifit_MO.nii.gz - Mode of the anisotropy (oblate ~ -1; isotropic ~ 0; prolate ~ 1)
<subjid>/dmri/dtifit_S0.nii.gz - Raw T2 signal with no diffusion weighting
Note: The same set of outputs in MNI space is created under the following directory <subjid>/dmri/mni/dtifit_*.nii.gz