trac-all Index
Contents
Name
trac-all : Performs reconstruction of white matter pathways using an atlas of underlying anatomy
Usage
trac-all |
-[Directive] -c <Configuration File> (Using Configuration File to set analysis options) |
For NMR-Center-Users Only
Do not submit trac-all as a command in the cluster but run it on the command line. It will submit each subject listed in the Configuration File file as a seperate job to the cluster.
trac-all |
-[Directive] -subject subjectname -i dicomfile |
For Non-MGH Acquisitions - Please supply the bvals and bvecs in the Configuration File. To see the format of the bvals and bvecs accepted by trac-all, refer to this page
Arguments
Required Arguments
-s subjid |
the subject data upon which to operate (If not specified in the Configuration File) |
-i DWI file |
the full path of the raw Diffusion weighted MR images |
-[Directive] |
one or more directives (see next) |
Optional Arguments
-c dmrirc |
Configuration File to set analysis options |
Here is how you set up a Configuration File to run Tracula
Clustered Workflow Directives
-prep |
(Preprocessing) Process steps 1.1 -1.6 (see below) |
-bedp |
(Bedpost) Process step 2 |
-path |
(Pathway Reconstruction/Tractography) Process step 3 |
Processing Stages/Stepwise Directives
(Detailed Explanation for each of these steps is given below) 1.1 Image corrections - Eddy current correction with eddy_correct, B0 field map correction with epidewarp.fsl
-corr |
to do this step (Default) |
-nocorr |
to skip this step |
This step performs the following sub-steps:
- Convert the input Diffusion Dicoms 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 orientation
<Optional> B0 inhomogenity correction (This is done using fsl's fieldmap based EPI unwarping tool epdidewarp.fsl. In order to do this step, B0 field map magnitude dicoms should be specified in the Configuration file)
- Eddy Current / Simple head motion Correction (Eddy currents within the gradient coils induce distortions which can be corrected by a simple affine registration to a reference volume (low-b volume). This step is done using fsl's eddy_correct)
- Create a low-b Diffusion brain mask
trac-all -<no>corr -c dmrirc
1.2 Intra-Subject Registration - Diffusion-to-T1 registration with flirt and/or bbregister.
-intra |
to do this step (Default) |
-nointra |
to skip this step |
This step performs the following sub-steps:
- 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
trac-all -<no>intra -c dmrirc
1.3 Inter-Subject Registration - T1-to-template registration using MNI and/or CVS templates.
-inter |
to do this step (Default) |
-nointer |
to skip this step |
This step performs the following sub-steps: (You can register to either MNI template or CVS template or both. This option can be set in the configuration file) 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
For CVS template
- Compute forward and inverse transformations between T1(Original and re-oriented) and the CVS atlas using a highly non-linear registration called Combined Volumetric and Surface based registration (CVS).
- Combine the low-b to T1 transformation (from the intra subject registration step) with the above transformation to get Diffusion to CVS/CVS 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.
-masks |
to do this step (Default) |
-nomasks |
to skip this step |
- 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, MNI space and CVS space using the transformation matrices computed in steps 1.2-1.3
- Transform diffusion brain masks to individual anatomical space, MNI space and CVS space.
trac-all -<no>masks -c dmrirc
1.5 Tensor fit - Tensor model fitting on DWIs.
-tensor |
to do this step (Default) |
-notensor |
to skip this step |
This step performs the following sub-steps:
- 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 and CVS template.
trac-all -<no>tensor -c dmrirc
1.6 Pathway priors from atlas to T1 - Combine training data and subject's own data to generate pathway priors.
-prior |
to do this step (Default) |
-noprior |
to skip this step |
- 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. Stick and ball model fitting with bedpost (Cluster highly recommended for this step)
Runs FSL's bedpostx step for modeling crossing fibers using ball and stick model of diffusion. It uses two anisotropic compartments and 1 isotropic compartment by default for modeling the diffusion data.
trac-all -bedp -c dmrirc
3. Pathway reconstruction - Perform tractography for a single subject
- 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.
trac-all -path -c dmrirc
Status and Log files (Optional)
-log file |
default is $SUBJECTS_DIR/<your_subjectid>/scripts/trac-all.log |
-cmd file |
default is $SUBJECTS_DIR/<your_subjectid>/scripts/trac-all.cmd |
-noappendlog |
start new log and status files instead of appending |
Other Arguments (Optional)
-no-isrunning |
do not check whether dubjects are currently being processed |
-sd subjectsdir |
specify 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 but execute each command |
-onlyversions |
print version of each binary and exit |
-version |
print version of this script and exit |
-help |
print full contents of help |
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
The following outputs get created if registering to CVS template. This step creates a symbolic link <subjid>/dmri/xfms/cvs to the folder $SUBJECTS_DIR/cvs where the freesurfer recons are present. It also creates a folder under $SUBJECTS_DIR/cvs for each of the image used as a CVS template. We recommend using the template given with the freesurfer distribution (cvs_avg35) although you can use your own atlas.
$SUBJECTS_DIR/cvs_avg35/combined_tocvs_avg35_elreg_afteraseg-norm_aseg.mgz $SUBJECTS_DIR/cvs_avg35/combined_tocvs_avg35_elreg_afteraseg-norm.m3z $SUBJECTS_DIR/cvs_avg35/combined_tocvs_avg35_elreg_aseg.m3z $SUBJECTS_DIR/cvs_avg35/combined_tocvs_avg35_elreg_aseg_norm.mgz $SUBJECTS_DIR/cvs_avg35/el_reg_tocvs_avg35_aseg.mgz $SUBJECTS_DIR/cvs_avg35/el_reg_tocvs_avg35.mgz $SUBJECTS_DIR/cvs_avg35/lh.dbg_surf.pial $SUBJECTS_DIR/cvs_avg35/lh.dbg_surf.white $SUBJECTS_DIR/cvs_avg35/lh.resample.aparc.annot $SUBJECTS_DIR/cvs_avg35/lh.resample.pial $SUBJECTS_DIR/cvs_avg35/lh.resample.white $SUBJECTS_DIR/cvs_avg35/nlalign-afteraseg-norm.m3z $SUBJECTS_DIR/cvs_avg35/nlalign-afteraseg-norm.mgz $SUBJECTS_DIR/cvs_avg35/nlalign-aseg.m3z $SUBJECTS_DIR/cvs_avg35/nlalign-aseg.mgz $SUBJECTS_DIR/cvs_avg35/rh.dbg_surf.pial $SUBJECTS_DIR/cvs_avg35/rh.dbg_surf.white $SUBJECTS_DIR/cvs_avg35/rh.resample.aparc.annot $SUBJECTS_DIR/cvs_avg35/rh.resample.pial $SUBJECTS_DIR/cvs_avg35/rh.resample.white $SUBJECTS_DIR/cvs_avg35/transform.txt