Differences between revisions 100 and 101
Deletions are marked like this. Additions are marked like this.
Line 248: Line 248:
 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>.txt''' -- Coordinates (in MNI space) of the control points of the spline that was chosen from the atlas to initialize tractography.

 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>_std.txt''' -- Standard deviation of the streamlines in the atlas around the above coordinates (in MNI space).

 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>.nii.gz''' -- The spline that was chosen from the atlas to initialize tractography.

 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_all.txt''' -- Coordinates (in MNI space) of all points of the streamline that was chosen from the atlas to initialize tractography.

 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_all.nii.gz''' -- Streamline that was chosen from the atlas to initialize tractography.
Pathway initialization:
 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_all.nii.gz''' -- Streamline that was chosen from the atlas to initialize tractography in subject <subjid>.

 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_all.txt''' -- Coordinates (in MNI space) of all points of the above streamline.

 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>.nii.gz''' -- Spline with <npts> control points that was fit to the initial streamline above.

 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>.txt''' -- Coordinates (in MNI space) of the <npts> control points of the spline.

 * '''<subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>_std.txt''' -- Standard deviation of the streamlines in the atlas around the <npts> control points above (in MNI space).

Pathway end ROIs:
Line 262: Line 264:
Pathway priors:

Index

Name

trac-all: White-matter pathway reconstruction from diffusion-weighted images (DWIs) 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 to be analyzed (if not specified via a configuration file)

-i <file>

path to the input DWIs (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 DWI files to NIfTI.
        • Correct for B0 inhomogeneities (optional). This is done using epidewarp.fsl. This step can be turned on or off in the configuration file. To run this step, B0 field map files for each subject must be specified in the configuration file.

        • Correct for eddy currents and simple head motion (optional). This is done using FSL's eddy_correct. This step can be turned on or off in the configuration file.

        • Create a brain mask from the low-b diffusion images. This done using FSL's bet. The threshold can be specified in the configuration file. The configuration file can also 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 performs an affine registration between the individual's low-b diffusion and T1 images. This can be done with bbregister and/or with FSL's flirt, as specified in the configuration file.

      1.3 Inter-subject registration

      • This step does the following:
        • Register the individual's T1 image to an atlas template. Currently the only available option is to use the MNI template and compute an affine registration between the individual T1 and the template using FSL's flirt.

        • Compose the diffusion-to-T1 transformation (from step 1.2) and the T1-to-template transformation to get the diffusion-to-template transformation.

      1.4 Mask creation

      • This step does the following:
        • Create a white-matter (WM) mask. This is done by extracting the cerebral WM, cerebellar WM, ventral DC, and brainstem from the individual's FreeSurfer cortical parcellation and subcortical segmentation (mri/aparc+aseg.mgz).

        • Create a mask of the cortex. This is done by mapping the cortical parcellation labels to the volume, growing them into the WM by 2mm and combining all the grown cortical labels into a mask.
        • Create an anatomical brain mask. This is done by binarizing and dilating the entire cortical parcellation and subcortical segmentation.
        • Transform all the above masks from individual T1 space to individual diffusion space and to the template space. This is done using the registrations that were computed in steps 1.2 and 1.3.
        • Transform the diffusion brain mask created in step 1.1 from the individual diffusion space to individual T1 space and to the template space.

      1.5 Tensor fit

      • This step does the following:
        • Perform least-squares tensor estimation using FSL's dtifit.

        • Map all scalar output volumes of the tensor fit (FA, MD, etc.) from diffusion space to the template space. This is done using the registrations that were computed in steps 1.2 and 1.3. (One could use these transformed volumes to do voxel-based statistical analyses in the template space, if one is so inclined.)

      1.6 Estimation of pathway priors

      • This step does the following:
        • Compute pathway priors. This is done in template space by combining the atlas data (training subjects' manually labeled pathways and anatomical segmentations) with the individual's own masks from step 1.4. The training data is used to estimate a priori probabilities that each pathway intersects/neighbors each of the labels in the cortical parcellation and subcortical segmentation, at each point along the pathway's trajectory. The training set is also used to obtain ROIs for the two endings of each pathway, as well as an initial guess of the location of the control points of each pathway, to be used in the tractography of step 3.

        • Map the selected initial control points from the template space to individual diffusion space, using the registrations that were computed in steps 1.2 and 1.3.
  2. Ball-and-stick model fitting

    • This step runs FSL's bedpostx to fit the ball-and-stick model of diffusion to the DWIs. One isotropic and two anisotropic compartments are assumed by default to model the diffusion signal in each voxel. Parallel processing on a computer cluster is highly recommended for this step.

  3. Pathway reconstruction

    • This step does the following:
      • Estimate the a posteriori probability distribution of the location of each pathway in the individual. This distribution consists of a likelihood term (the fit of the pathway orientation to the anisotropic compartments of the ball-and-stick model at each voxel) and a prior term (computed in step 1.6 from the atlas). The estimation is done by an MCMC algorithm and several parameters of that algorithm can be set in the configuration file.

      • Use the estimated pathway distributions to extract statistics on standard diffusion measures (FA, MD, etc.) for each of the pathways

Output directories and files

When trac-all runs, it generates output files for each subject under a directory that is denoted by <subjid> in the following. This subject name is provided either on the command line via the -s option, where only one subject can be specified, or in the configuration file, where multiple subjects can be specified.

By default the <subjid> directory is the same as the one under $SUBJECTS_DIR, where the subject's FreeSurfer recon is saved. An alternative location for trac-all subject directories can be specified either in the configuration file or with the -sd command-line option.

Outputs from trac-all -corr

  • <subjid>/dlabel/diff/lowb_brain_mask.nii.gz -- Diffusion brain mask

  • <subjid>/dmri/dwi_orig.nii.gz -- Original DWI file converted to NIfTI format

  • <subjid>/dmri/dwi_orig.mghdti.bvals -- Original list of b-values (generated by mri_convert or specified by the user)

  • <subjid>/dmri/dwi_orig.mghdti.bvecs -- Original list of gradient vectors (generated by mri_convert or specified by the user)

  • <subjid>/dmri/dwi_orig_flip.nii.gz -- DWI converted to the orientation preferred by FSL

  • <subjid>/dmri/bvals.norot -- List of b-values in FSL format

  • <subjid>/dmri/bvecs.norot -- List of gradient vectors in FSL format

  • <subjid>/dmri/dwi.ecclog -- Log file generated by eddy_correct, if eddy-current correction is performed

  • <subjid>/dmri/dwi.nii.gz -- DWI after all corrections, if any are performed

  • <subjid>/dmri/bvals -- List of b-values in FSL format

  • <subjid>/dmri/bvecs -- List of gradient vectors in FSL format (rotated to account for eddy-current correction, if this option is specified)

  • <subjid>/scripts/trac-all.cmd -- Command file containing all the commands executed by trac-all. This file is constantly appended to every time that trac-all is run unless a new command file is specified using the -cmd flag.

  • <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 run and terminal output generated while running trac-all. This file is constantly appended to every time that trac-all is run unless a new log file is specified using the -log flag.

  • <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

In the following, <regtype> is used to denote the intra-subject registration method. Depending on what configuration options were used, it can be flt (flirt) or bbr (bbregister).

  • <subjid>/dmri/brain_anat_orig.nii.gz -- Original skull-stripped anatomical from FreeSurfer recon

  • <subjid>/dmri/brain_anat.nii.gz -- Anatomical converted to the orientation preferred by FSL

  • <subjid>/dmri/xfms/anatorig2anat.mat(.dat) -- Registration matrix from original anatomical space to converted anatomical space

  • <subjid>/dmri/xfms/anat2anatorig.mat(.dat) -- Registration matrix from converted anatomical space to original anatomical space

  • <subjid>/dmri/lowb_brain_anat.<regtype>.nii.gz -- Low-b diffusion image in converted anatomical space

  • <subjid>/dmri/xfms/diff2anat.<regtype>.mat -- Registration matrix from diffusion space to converted anatomical space

  • <subjid>/dmri/xfms/anat2diff.<regtype>.mat -- Registration matrix from converted anatomical space to diffusion space

  • <subjid>/dmri/xfms/diff2anatorig.<regtype>.mat -- Registration matrix from diffusion space to original anatomical space

  • <subjid>/dmri/xfms/anatorig2diff.<regtype>.mat -- Registration matrix from original anatomical space to diffusion space

Outputs from trac-all -inter

  • <subjid>/dmri/brain_anat_mni.nii.gz -- Anatomical in MNI space

  • <subjid>/dmri/xfms/anat2mni.mat -- Registration matrix from converted anatomical space to MNI space

  • <subjid>/dmri/xfms/mni2anat.mat -- Registration matrix from MNI space to converted anatomical space

  • <subjid>/dmri/xfms/diff2mni.<regtype>.mat -- Registration matrix from diffusion to MNI space

  • <subjid>/dmri/xfms/mni2diff.<regtype>.mat -- Registration matrix from MNI to diffusion space

  • <subjid>/dmri/xfms/anatorig2mni.mat -- Registration matrix from original anatomical space to MNI

  • <subjid>/dmri/xfms/mni2anatorig.mat -- Registration matrix from MNI to original anatomical space

Outputs from trac-all -masks

In the following, <space> is used to denote the space that the volume is in. It can be anatorig (original anatomical space), anat (converted anatomical space in the orientation preferred by FSL), diff (diffusion space) or mni (MNI template space).

  • <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 grown into the WM by 2mm + subcortical segmentation

  • <subjid>/dlabel/<space>/cortex.nii.gz -- Mask of the cortex

  • <subjid>/dlabel/<space>/cortex+2mm.nii.gz -- Mask of the cortex grown into the WM by 2mm

  • <subjid>/dlabel/<space>/Brain-Stem.nii.gz -- Brainstem from FreeSurfer's aparc+aseg.mgz file

  • <subjid>/dlabel/<space>/cortex+2mm+bs.nii.gz -- Mask of grown cortex with brainstem

  • <subjid>/dlabel/<space>/aparc+aseg_mask.nii.gz -- Anatomical brain mask obtained by dilating FreeSurfer's aparc+aseg.mgz

  • <subjid>/dmri/dwi_snr.txt -- SNR of DWI intensities within the WM mask

  • <subjid>/dlabel/<space>/lowb_brain_mask.<regtype>.nii.gz -- Diffusion brain mask (in MNI space or original anatomical space)

Outputs from trac-all -tensor

  • <subjid>/dmri/dtifit_FA.nii.gz -- Fractional anisotropy

  • <subjid>/dmri/dtifit_V1.nii.gz -- Primary eigenvector

  • <subjid>/dmri/dtifit_V2.nii.gz -- Secondary eigenvector

  • <subjid>/dmri/dtifit_V3.nii.gz -- Tertiary eigenvector

  • <subjid>/dmri/dtifit_L1.nii.gz -- Primary eigenvalue

  • <subjid>/dmri/dtifit_L2.nii.gz -- Secondary eigenvalue

  • <subjid>/dmri/dtifit_L3.nii.gz -- Tertiary eigenvalue

  • <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

  • <subjid>/dmri/mni/dtifit_*.nii.gz -- All of the above files, mapped to MNI space

Outputs from trac-all -prior

In the following, <tract> is used to denote the name of the pathway, <nsubj> the number of training subjects used to calculate the priors (by default all 33 subjects in the atlas), <regtype> the intra-subject registration method (flt for flirt or bbr for bbregister), and <npts> the number of spline controls points.

Pathway initialization:

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_all.nii.gz -- Streamline that was chosen from the atlas to initialize tractography in subject <subjid>.

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_all.txt -- Coordinates (in MNI space) of all points of the above streamline.

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>.nii.gz -- Spline with <npts> control points that was fit to the initial streamline above.

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>.txt -- Coordinates (in MNI space) of the <npts> control points of the spline.

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_cpts_<npts>_std.txt -- Standard deviation of the streamlines in the atlas around the <npts> control points above (in MNI space).

Pathway end ROIs:

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_end[1,2].nii.gz -- End points of all the streamlines included in the atlas.

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_end[1,2]_dil.nii.gz -- End ROIs used to constrain tractography solutions (obtained by dilating the end points of all the streamlines included in the atlas and masking with the anatomy of subject <subjid>).

Pathway priors:

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_histo_str.nii.gz -- Histogram of the streamlines from the atlas that were used to compute the priors (number of atlas streamlines in each voxel).

  • <subjid>/dlabel/mni/<tract>_avg<nsubj>_mni_<regtype>_histo.nii.gz -- Histogram of the streamlines from the atlas that were used to compute the priors (number of atlas subjects in each voxel).

Text Files containing information about Priors

  • Before computing priors, each streamline from the training set is defined into a certain no.of segments along their arc length. The no. of segments is chosen such that every training streamline has atleast 3 voxels in each segment. For each segment of each of the streamlines the priors are calculated. In the following text files, information obtained from each segment is written out in the consecutive rows. (i.e if a certain tract is divided into 26 segments, there will be 26 rows in the text file, Row_number ~ Segment_number). Details about the column values are explained below: There are two types of Prior related text files written out during the prior step:

Local Neighbor Aseg Priors from the training data

  • fsids - Every column in a single row consists of segmentation label numbers from aparc+aseg. This information is collected by looking at the segmentation label to which each voxel (that is traversed or neighbored by the training streamlines) in that segment belongs.
  • fshisto - Every column in a single row corresponds to the no.of voxels belonging to a certain segmentation label from the "fsids file". This gives the histogram of anatomical segmentation within a certain segment of the training streamlines.
  • fsprior - From the above files, fsids and fshisto the final apriori probability for each of the segment passing through various anatomical segmentations is calculated.

Near Neighbor Aseg Priors from the training data

  • fsnnids - Same as "fsids", but instead of looking at the structures through which the streamline traverses, it looks at the neighboring anatomical segmentation structures.
  • fsnnhisto - Same as "fshisto", but looks at the no. of voxels that pass through the neighboring anatomical segmentations specified in fsnnids file.
  • fsnnprior - From the above files, fsnnids and fsnnhisto, the final apriori probability for each of the segment neighboring various anatomical segmentations is calculated.

Directions of the Priors

  • The above prior text files are written out for different directions (for example, 1) at a specific voxel that that one of the training streamline 2) left 3) right 4) anterior 5) posterior 6) Superior 7) inferior ). Hence the above text files have the following suffixes indicating the directions

'Local Neighbor Aseg Priors Directions:'

  • 0 0 0 - At the voxel location through which the training streamline traverses
  • 1 0 0 - One voxel to the left of the current voxel through which the training streamline traverses
  • -1 0 0 - One voxel to the right of the current voxel through which the training streamline traverses
  • 0 1 0 - One voxel anterior to the current voxel through which the training streamline traverses
  • 0 -1 0 - One voxel posterior to the current voxel through which the training streamline traverses
  • 0 0 1 - One voxel superior to the current voxel through which the training streamline traverses
  • 0 0 -1 - One voxel inferior to the current voxel through which the training streamline traverses
  • 1 1 1 - One voxel left of, anterior to and superior to the current voxel through which the training streamline traverses
  • -1 1 1 - One voxel right of, anterior to and superior to the current voxel through which the training streamline traverses
  • 1 -1 1 - One voxel left of, posterior to and superior to the current voxel through which the training streamline traverses
  • -1 -1 1 - One voxel right of, posterior to and superior to the current voxel through which the training streamline traverses
  • 1 1 -1 - One voxel left of, anterior to and inferior to the current voxel through which the training streamline traverses
  • -1 1 -1 - One voxel right of, anterior to and inferior to the current voxel through which the training streamline traverses
  • 1 -1 -1 - One voxel left of, posterior to and inferior to the current voxel through which the training streamline traverses
  • -1 -1 -1 - One voxel right of, posterior to and inferior to the current voxel through which the training streamline traverses

Near Neighbor Aseg Priors Directions:

Instead of looking locally, this prior looks at the segmentation structure that neighbors the voxel's (through which the training streamlines are passing through) current segmentation structure in all the different directions.

  • 1 0 0 - The nearest unique segmentation label to the left of the current voxel through which the training streamline traverses
  • -1 0 0 - The nearest unique segmentation label to the right of the current voxel through which the training streamline traverses
  • 0 1 0 - The nearest unique segmentation label anterior to the current voxel through which the training streamline traverses
  • 0 -1 0 - The nearest unique segmentation label posterior to the current voxel through which the training streamline traverses
  • 0 0 1 - The nearest unique segmentation label superior to the current voxel through which the training streamline traverses
  • 0 0 -1 - The nearest unique segmentation label inferior to the current voxel through which the training streamline traverses
  • 1 1 1 - The nearest unique segmentation label left of, anterior to and superior to the current voxel through which the training streamline traverses
  • -1 1 1 - The nearest unique segmentation label right of, anterior to and superior to the current voxel through which the training streamline traverses
  • 1 -1 1 - The nearest unique segmentation label left of, posterior to and superior to the current voxel through which the training streamline traverses
  • -1 -1 1 - The nearest unique segmentation label right of, posterior to and superior to the current voxel through which the training streamline traverses
  • 1 1 -1 - The nearest unique segmentation label left of, anterior to and inferior to the current voxel through which the training streamline traverses
  • -1 1 -1 - The nearest unique segmentation label right of, anterior to and inferior to the current voxel through which the training streamline traverses
  • 1 -1 -1 - The nearest unique segmentation label left of, posterior to and inferior to the current voxel through which the training streamline traverses
  • -1 -1 -1 - The nearest unique segmentation label right of, posterior to and inferior to the current voxel through which the training streamline traverses
  • [Under construction...]

Outputs from trac-all -bedp

  • <subjid>/dmri.bedpostX/ -- bedpostx output directory (see the bedpostx documentation for a list of the files in this directory)

Outputs from trac-all -path

  • [Under construction...]

See Also

dmrirc

Links

TRACULA

References

Automated probabilistic reconstruction of white-matter pathways in health and disease using an atlas of the underlying anatomy. Yendiki A, Panneck P, Srinivasan P, Stevens A, Zöllei L, Augustinack J, Wang R, Salat D, Ehrlich S, Behrens T, Jbabdi S, Gollub R and Fischl B (2011). Front. Neuroinform. 5:23. doi: 10.3389/fninf.2011.00023

Reporting Bugs

Report bugs to < analysis-bugs@nmr.mgh.harvard.edu >

Author/s

Anastasia Yendiki

trac-all (last edited 2021-12-08 16:06:06 by AnastasiaYendiki)