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).

Parallel processing

• General: If you want to process multiple subjects in parallel by submitting jobs for each one on a compute cluster, add -jobs <filename> to any of the trac-all command lines above. This will not actually run the analysis. It will process the configuration file, set up the analysis for all subjects included in it, and write the commands that need to be run into a text file called <filename>. You can then submit each line in this text file as a separate job on your cluster, using your cluster's job submission commands.

• For Martinos Center users (and others with a cluster running torque): You can run trac-all directly on the command line of the cluster, and it will do the job submission for you. If run on your local machine, trac-all will run all analyses on that machine. If run on the cluster, however, trac-all will submit the analysis of each subject listed in your configuration file as a job on the cluster. (Note that, if you submit trac-all itself as a job with qsub or pbsubmit, it will run all subjects in the configuration file serially on a single node.)

Input image formats

• The input DWIs can be in any format recognized by mri_convert. If the format is DICOM, mri_convert will attempt to extract the b-values and the diffusion gradient vectors from the DICOM header. In any other scenario, 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 the b-value table and gradient table files, please refer to the tutorial.

NOTE: This page contains a much greater level of detail than what you need to know to use TRACULA. The simplest way to get started is by going over the TRACULA tutorial.

Arguments

Required arguments

OR:

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:

Performing a part of the preprocessing or skipping a part:

Optional arguments

Parallel processing

Status and log files

Other arguments

Processing steps

1. Preprocessing

   • 1.1 Image corrections

     • This step does the following:

       • Convert the input DWI files to NIfTI, using mri_convert.

       • Correct for B0 inhomogeneities (optional). The method to use for this step (if any) can be specified in the configuration file. Possible methods are: (i) With epidewarp.fsl, if a field map has been collected. To use this method, the B0 field map magnitude and phase files for each subject, as well as the echo spacing, must be specified in the configuration file. (ii) With FSL's topup, if some of the input DWIs have been collected with reverse phase-encode direction. To use this method, the phase-encode direction for each of the input DWI scans, as well as the EPI factor and echo spacing, must be specified in the configuration file. The default is not to use either method.

       • Correct for eddy currents and simple head motion (optional). The method to use for this step (if any) can be specified in the configuration file. Possible methods are: (i) With FSL's eddy_correct. (ii) With FSL's eddy (the default).

       • 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. This is actually only a temporary brain mask, used in early pre-processing steps, before the diffusion-to-T1 registration has been performed (see 1.3 below). The default is to use the whole-brain anatomical segmentation from recon-all as the mask in all subsequent steps.

     1.2 Image quality assessment

     • This step computes the four measures of head motion from Yendiki et al. 2014, based on the DWIs and the output of the eddy-current correction of step 1.1.

     1.3 Intra-subject registration

     • This step does the following:

       • Perform an affine registration between the individual's low-b diffusion and T1 images. Depending on what has been specified in the configuration file, this can be done either with bbregister (the default) or with FSL's flirt.

       • Use this registration to map the individual's anatomical segmentations from T1 to DWI space. These segmentations are found in the individual's FreeSurfer directory. A whole-brain segmentation is required. The default whole-brain segmentation is mri/aparc+aseg.mgz, which comprises the cortical parcellation and subcortical segmentation. A thalamic nuclei segmentation is also recommended and used by default, in conjunction with the whole-brain segmentation.

       • Create an anatomical brain mask. The mask is created by binarizing and dilating the whole-brain segmentation.

     1.4 Tensor fit

     • This step performs least-squares tensor estimation using FSL's dtifit.

     1.5 Inter-subject registration

     • This step does the following:

       • Perform an affine or nonlinear registration from the individual to a template brain. This can be done with the following methods, depending on what has been specified in the configuration file: (i) Affine registration from the individual T1 to the MNI T1 template, using FSL's flirt), with a correlation ratio cost or a mutual information cost. (ii) Affine registration from the individual T1 to a T1 template using mri_robust_register), which utilizes a robust cost. (ii) Non-linear registration from the individual T1 to the CVS template, using mri_cvs_register. (iii) Non-linear registration from the individual fractional anisotropy (FA) map to an FA template, using symmetric normalization from ANTs. The latter is the default method.

       • Compose the intra-subject (step 1.3) and inter-subject transformations to get the DWI-to-template transformation.
       • Transform all anatomical segmentations and masks from the individual T1 space to the template space.

     1.6 Estimation of anatomical neighborhood priors for the pathways of interest

     • 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 segmentation. The training data are 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.3 and 1.5.

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 compute cluster is highly recommended for this step.

3. Pathway-of-interest 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 training data). 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 of interest. This includes average measures over the entire pathway, as well as profiles along the trajectory of the pathway.
     • Project the cortical end points of the pathways onto surface labels, and use them to extract anatomical stats such as cortical thickness.

4. Assemble pathway measures from all subjects

   • This step can be run after each of the subjects has been processed with all of the previous steps. It will combine all subjects' diffusion measures (FA, MD, etc.) along each pathway and output a table for each diffusion measure (FA, MD, etc.) and each pathway. In these tables, each row is a different position along the trajectory of the pathway and each column is a different subject. The user can then use these tables to perform Pointwise Assessment of Streamline Tractography Attributes (PASTA) analyses.

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.

The most basic output of trac-all is the concatenation of the volumetric distributions of all the pathways that were specified in the configuration file (by default all 42 pathways included in the atlas). This output is called merged_*.mgz (the actual name depends on processing options). It can be visualized with freeview's -tv option. More information on this can be found in the TRACULA tutorial.

A detailed list of output files from each step of trac-all is given below.

General log files

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

• <subjid>/dmri/dwi_orig.?.nii.gz -- Original DWI file converted to NIfTI format, one for each DWI scan available for this subject/visit

• <subjid>/dmri/dwi_orig.?.bvals -- Original list of b-values, one for each DWI scan available for this subject/visit (extracted from DICOM by mri_convert or specified by the user)

• <subjid>/dmri/dwi_orig.?.bvecs -- Original list of gradient vectors, one for each DWI scan available for this subject/visit (extracted from DICOM by mri_convert or specified by the user)

• <subjid>/dmri/dwi_orig_las.?.nii.gz -- As above but converted to LAS orientation

• <subjid>/dmri/dwi_orig_las.?.bvals -- As above but converted to LAS orientation

• <subjid>/dmri/dwi_orig_las.?.bvecs -- As above but converted to LAS orientation

• <subjid>/dmri/lowb_orig_las.?.nii.gz -- First low-b volume from each DWI scan, in LAS orientation

• <subjid>/dmri/lowb_orig_las.nii.gz -- Concatenated first low-b volumes from each DWI scan, in LAS orientation (used as input for topup and/or eddy)

• <subjid>/dmri/acqp.txt -- Acquisition parameter file for topup and/or eddy

• <subjid>/dmri/b02b0.cnf -- Configuration file for topup

• <subjid>/dmri/lowb_topup.nii.gz -- First low-b volumes from each DWI scan, after distortion correction with topup

• <subjid>/dmri/topup_*.nii.gz -- Off-resonance field estimation outputs from topup

• <subjid>/dmri/lowb*_brain_mask.nii.gz -- Temporary brain mask from low-b volume (after topup correction, if topup is used), used as input for eddy

• <subjid>/dmri/dwi.eddy_* -- Output files generated by eddy, if eddy is used

• <subjid>/dmri/dwi.ecclog -- Log file generated by eddy_correct, if eddy_correct is used

• <subjid>/dmri/b0mag*.nii.gz -- Fieldmap magnitude volume(s), used as input for epidewarp (there can be one for all DWI scans or one per DWI scan, depending on what the user specified)

• <subjid>/dmri/b0pha*.nii.gz -- Fieldmap phase volume(s), used as input for epidewarp (there can be one for all DWI scans or one per DWI scan, depending on what the user specified)

• <subjid>/dmri/vsm.nii.gz -- Voxel shift map generated by epidewarp, if epidewarp is used

• <subjid>/dmri/dwi.nii.gz -- Full set of DWIs after all corrections, if any corrections were performed

• <subjid>/dmri/dwi.bvals -- Full list of b-values

• <subjid>/dmri/dwi.bvecs -- Full list of gradient vectors, after rotation to account for eddy-current correction (if any such correction was performed)

• <subjid>/dmri/dwi.b*.nii.gz -- Optional: Partial set of corrected DWIs to be used for further analysis (e.g., specific shells or all shells up to a maximum b-value)

• <subjid>/dmri/dwi.b*.bvals -- Optional: Partial set of b-values to be used for further analysis (e.g., specific shells or all shells up to a maximum b-value)

• <subjid>/dmri/dwi.b*.bvecs -- Optional: Partial set of corrected gradient vectors to be used for further analysis (e.g., specific shells or all shells up to a maximum b-value)

• <subjid>/dlabel/diff/lowb_brain_mask.nii.gz -- Brain mask from average low-b volume (after all corrections, if any corrections were performed)

Outputs from trac-all -qa

• <subjid>/dmri/dwi_motion.txt -- Four measures of head motion in the DWIs (see Yendiki et al. 2014): Average volume-to-volume translation, average volume-to-volume rotation, percentage of slices with excessive intensity drop-out, and average drop-out score for slices with excessive drop-out. These values may be used, e.g., as regressors in group analysis.

• <subjid>/dmri/dwi_motion_byvol.txt -- The above measures, with separate values for each DWI volume. These values may be used, e.g., to decide which volumes to discard.

Outputs from trac-all -intra

In the following, <intra> is used to denote the intra-subject registration method. Depending on what configuration options were used, it can be bbr (bbregister) or flt (flirt). For volumes derived from anatomical segmentations, <space> is used to denote the space that the volume is in. It can be anatorig (FreeSurfer anatomical space) or diff (diffusion space).

• <subjid>/dmri/xfms/diff2anatorig.<intra>.lta -- Registration matrix from diffusion space to FreeSurfer anatomical space

• <subjid>/dmri/xfms/anatorig2diff.<intra>.lta -- Registration matrix from FreeSurfer anatomical space to diffusion space

• <subjid>/dlabel/<space>/aparc+aseg.nii.gz -- Cortical parcellation + subcortical segmentation

• <subjid>/dlabel/<space>/aparc+aseg+thalnuc.nii.gz -- Cortical parcellation + subcortical segmentation merged with thalamic nuclei segmentation

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

• <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>/dmri/dwi_snr.txt -- SNR of DWI intensities within the white matter only

• <subjid>/dlabel/anatorig/lowb_brain_mask.<intra>.nii.gz -- Diffusion brain mask in FreeSurfer 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

Outputs from trac-all -inter

In the following, <inter> is the inter-subject registration method (mni for affine registration to the MNI template, rob for affine registration to a robust template, cvs for nonlinear registration to the CVS template, or syn for nonlinear registration to an FA template), and <intra> the intra-subject registration method (bbr for bbregister or flt for flirt).

• For affine registraton from individual T1 to a T1 template (if <inter> is either mni or rob):

  • <subjid>/dmri/xfms/anatorig2<inter>.lta -- Affine registration matrix from FreeSurfer anatomical space to template space

  • <subjid>/dmri/xfms/<inter>2anatorig.lta -- Affine registration matrix from template to FreeSurfer anatomical space

  • <subjid>/dmri/xfms/diff2<inter>.<intra>.lta -- Affine registration matrix from diffusion space to template space

  • <subjid>/dmri/xfms/<inter>2diff.<intra>.lta -- Affine registration matrix from template space to diffusion space

  • <subjid>/dlabel/<inter>/lowb_brain_mask.<intra>.nii.gz -- Diffusion brain mask mapped to template space

• For nonlinear registraton from individual T1 to a T1 template (if <inter> is cvs):

  • <subjid>/dmri/xfms/cvs -- Symbolic link to the subject's CVS registration output directory (if applicable)

  • <subjid>/dlabel/cvs/lowb_brain_mask.<intra>.nii.gz -- Diffusion brain mask mapped to template space

• For nonlinear registraton from individual FA to an FA template (if <inter> is syn):

  • <subjid>/dmri/xfms/diff2syn.lta -- Affine registration matrix from diffusion space to template space

  • <subjid>/dmri/xfms/syn_warp.m3z -- Nonlinear registration warp to template space (applied after affine above)

  • <subjid>/dmri/xfms/syn2diff.lta -- Affine registration matrix from template space to diffusion space

  • <subjid>/dmri/xfms/anatorig2syn.<intra>.lta -- Affine registration matrix from FreeSurfer anatomical space to template space

  • <subjid>/dmri/xfms/syn2anatorig.<intra>.lta -- Affine registration matrix from template to FreeSurfer anatomical space

  • <subjid>/dlabel/syn/lowb_brain_mask.nii.gz -- Diffusion brain mask mapped to template space

• For any registration method (<inter> is mni, rob, cvs, or syn):

  • <subjid>/dlabel/<inter>/White-Matter.nii.gz -- White matter mask extracted from FreeSurfer's aparc+aseg.mgz file, mapped to template space

  • <subjid>/dlabel/<inter>/White-Matter++.nii.gz -- White matter mask including ventral DC and brainstem, mapped to template space

  • <subjid>/dlabel/<inter>/aparc+aseg.nii.gz -- Cortical parcellation + subcortical segmentation, mapped to template space

  • <subjid>/dlabel/<inter>/aparc+aseg+thalnuc.nii.gz -- Cortical parcellation + subcortical segmentation merged with thalamic nuclei segmentation, mapped to template space

  • <subjid>/dlabel/<inter>/aparc+aseg_mask.nii.gz -- Anatomical brain mask obtained by dilating the aparc+aseg.nii.gz, mapped to template 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 subjects in the manually annotated training set), <inter> the inter-subject registration method (mni for affine registration to the MNI template, rob for affine registration to a robust template, cvs for nonlinear registration to the CVS template, or syn for nonlinear registration to an FA template), and <intra> the intra-subject registration method (bbr for bbregister or flt for flirt).

Pathway initialization:

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

• <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_cpts_all.txt -- Coordinates (in template space) of all points of the above streamline

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

• <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_cpts_<npts>.txt -- Coordinates (in template space) of the <npts> control points of the initial spline

• <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_cpts_<npts>.nii.gz -- Spline with <npts> control points that was fit to the initial streamline above (in diffusion space)

• <subjid>/dlabel/diff/<tract>_avg<nsubj>_<inter>_<intra>_cpts_<npts>.txt -- Coordinates (in diffusion space) of the <npts> control points of the initial spline.

• <subjid>/dlabel/diff/<tract>_avg<nsubj>_<inter>_<intra>_cpts_<npts>_std.txt -- Standard deviation of the streamlines in the atlas around the <npts> control points above (in diffusion space)

Pathway end ROIs:

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

• <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_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 histograms:

• <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_histo_str.nii.gz -- Histogram of the streamlines from the training set that were used to compute the priors (number of training streamlines in each voxel)

• <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_histo.nii.gz -- Histogram of the streamlines from the training set that were used to compute the priors (number of training subjects in each voxel)

Priors on the underlying anatomy of the pathways

Before computing these, each pathway is split into segments along its arc length. The number of segments depends on the average length of the pathway. Prior information on the underlying anatomy is extracted from the training subjects for each segment along the length of each pathway. In the following text files, each row corresponds to a different segment along the pathway, i.e., the number of rows equals the number of segments. The information in the text files relates to the frequency with which each label in the aparc+aseg is found in the immediate neighborhood of each segment of the pathway, in the left, right, anterior, posterior, superior, and inferior direction. There is a different text file for each of these directions, denoted by the <x>, <y>, and <z> suffixes for the L-R, A-P, and I-S direction respectively. Specifically, x=1: Left; x=-1: Right; y=1: Anterior; y=-1: Posterior; z=1: Superior; z=-1: Inferior.

• Local neighbor anatomical priors:

  • <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_fsids_<x>_<y>_<z>.txt -- List of the aparc+aseg label IDs that were found in the training subjects in the immediate neighborhood of the pathway (0 or 1 voxels away) in the direction denoted by <x>, <y>, <z>

  • <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_fshisto_<x>_<y>_<z>.txt -- Histogram (number of occurrences) of the label IDs above

  • <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_fsprior_<x>_<y>_<z>.txt -- Prior probability of each of the label IDs, calculated from the histogram above

  Nearest neighbor anatomical priors:

  • <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_fsnnids_<x>_<y>_<z>.txt -- List of the aparc+aseg label IDs that were found in the training subjects, adjacent to but different than the label traversed by the pathway, in the direction denoted by <x>, <y>, <z>

  • <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_fsnnhisto_<x>_<y>_<z>.txt -- Histogram (number of occurrences) of the label IDs above.

  • <subjid>/dlabel/<inter>/<tract>_avg<nsubj>_<inter>_<intra>_fsnnprior_<x>_<y>_<z>.txt -- Prior probability of each of the label IDs, calculated from the histogram above

Outputs from trac-all -bedp

See bedpostX documentation for a detailed explanation of the bedpostX algorithm and its outputs. Every voxel in the diffusion volume is modeled as a combination of two anisotropic compartments and one isotropic compartment. In the following <i> denotes the anisotropic compartment (1, 2, ... up to the maximum number that was specified).

• <subjid>/dmri.bedpostX/merged_th<i>samples.nii.gz - Samples from the distribution on the orientation angle theta of each anisotropic compartment

• <subjid>/dmri.bedpostX/merged_ph<i>samples.nii.gz - Samples from the distribution on the orientation angle phi of each anisotropic compartment

• <subjid>/dmri.bedpostX/merged_f<i>samples.nii.gz - Samples from the distribution on the volume fraction of each anisotropic compartment

• <subjid>/dmri.bedpostX/mean_th<i>samples.nii.gz - Mean orientation angle theta of each anisotropic compartment

• <subjid>/dmri.bedpostX/mean_ph<i>samples.nii.gz - Mean orientation angle phi of each anisotropic compartment

• <subjid>/dmri.bedpostX/mean_f<i>samples.nii.gz - Mean volume fraction of each anisotropic compartment

• <subjid>/dmri.bedpostX/mean_dsamples.nii.gz - Mean diffusivity

• <subjid>/dmri.bedpostX/mean_S0samples.nii.gz - Mean baseline signal intensity

• <subjid>/dmri.bedpostX/dyads<i>.nii.gz - Mean of PDD (Principal Diffusion Direction) distribution in a vector form

• <subjid>/dmri.bedpostX/dyads<i>_dispersion.nii.gz - Uncertainty on the estimated fiber orientation.

• <subjid>/dmri.bedpostX/nodif_brain_mask.nii.gz - Brain mask from low-b diffusion image

• <subjid>/dmri.bedpostX/bvals - List of b-values (copy of <subjid>/dmri/bvals)

• <subjid>/dmri.bedpostX/bvecs - List of gradient vectors (copy of <subjid>/dmri/bvecs)

Outputs from trac-all -path

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 subjects in the manually annotated training set), <inter> the inter-subject registration method (mni for affine registration to the MNI template, rob for affine registration to a robust template, cvs for nonlinear registration to the CVS template, or syn for nonlinear registration to an FA template), and <intra> the intra-subject registration method (flt for flirt or bbr for bbregister).

All volumes and coordinate files below are in the native diffusion space of subject <subjid>. Tractography is run in diffusion space, even though the anatomical priors are derived in the template space.

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/endpt[1,2].pd.nii.gz -- Posterior distribution of the two end points of the path, in the volume

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/endpt[1,2].surf.mgz -- As above, projected onto the individual cortical surface

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/endpt[1,2].surf.label -- As above, converted into FreeSurfer cortical label files

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/endpt[1,2].surf.stats -- Anatomical stats from the above label files

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/length.samples.txt -- Text file containing the length of all path samples drawn by the MCMC algorithm and used to estimate the path distribution

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/log.txt -- Text file containing a list of the input files that were used to generate the path distribution

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/path.map.nii.gz -- Volume of the maximum a posteriori (highest-probability) path

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/path.map.txt -- Text file containing the coordinates of the maximum a posteriori (highest-probability) path

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/path.pd.nii.gz -- Posterior distribution of the path

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/path.pd.trk -- All sample paths saved as streamlines

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/pathstats.byvoxel.txt -- Text file containing the values of various diffusion measures (axial diffusivity, radial diffusivity, mean diffusivity, fractional anisotropy) at consecutive cross-sections along the path

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/pathstats.overall.txt -- Text file containing the average values of the diffusion measures above over the entire path

• <subjid>/dpath/<tract>_avg<nsubj>_<inter>_<intra>/pd.samples.txt -- Text file containing the likelihood and anatomical prior of all path samples drawn by the MCMC algorithm and used to estimate the path distribution

• <subjid>/dpath/merged_avg<nsubj>_<inter>_<intra>.mgz -- Merged 4D volume of all the pathway distributions that were estimated. Opening this file in freeview will display the distributions as isosurfaces thresholded at 20% of their maximum value

For more information on the stats files, see Tract statistics in the TRACULA tutorial.

For more information on how to visualize the merged 4D volume, see Visualizing the posterior distribution of all reconstructed tracts in the TRACULA tutorial.

Outputs from trac-all -stat

Outputs from this step will be saved in a subdirectory named stats, directly under the root TRACULA output directory. Outputs are saved separately for each WM pathway and each diffusion measure (FA, MD, etc.)

In the following, <meas> denotes the name of the diffusion measure, <tract> the name of the pathway, <nsubj> the number of training subjects used to calculate the priors (by default all subjects in the manually annotated training set), <inter> the inter-subject registration method (mni for affine registration to the MNI template, rob for affine registration to a robust template, cvs for nonlinear registration to the CVS template, or syn for nonlinear registration to an FA template), and <intra> the intra-subject registration method (bbr for bbregister or flt for flirt).

• stats/<tract>.avg<nsubj>_<inter>_<intra>.inputs.txt -- Complete list of input files from all study subjects that were processed to create the group tables

• stats/<tract>.avg<nsubj>_<inter>_<intra>.log -- Log file, which also contains information about which inputs were flagged as outliers (potential failed pathway reconstructions) and excluded from the group tables

• stats/<tract>.avg<nsubj>_<inter>_<intra>.<meas>.txt -- Group table for this measure and pathway, where each row is a different position along the trajectory of the pathway and each column is a different subject

• stats/<tract>.avg<nsubj>_<inter>_<intra>.<meas>.nii.gz -- The above group table converted into a NIfTI file that can be passed to FreeSurfer group analysis tools (mri_glmfit/mri_glmfit-sim)

See also

dmrirc, dmri_bids_config

Links

TRACULA

References

If you use TRACULA, please cite:

• 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

• Using diffusion MRI data acquired with ultra-high gradients to improve tractography in routine-quality data. Maffei C, Lee C, Planich M, Ramprasad M, Ravi N, Trainor D, Urban Z, Kim M, Jones R, Henin A, Hofmann S, Pizzagalli D, Auerbach R, Gabrieli J, Whitfield-Gabrieli S, Greve D, Haber N, Yendiki A (2021). NeuroImage 245:118706.

If you use our measures of head motion, please cite:

• Spurious group differences due to head motion in a diffusion MRI study. Yendiki A, Koldewyn K, Kakunoori S, Kanwisher N, Fischl B (2014). NeuroImage 88:79–90.

If you use the longitudinal stream of TRACULA, please cite:

• Joint reconstruction of white-matter pathways from longitudinal diffusion MRI data with anatomical priors. Yendiki A, Reuter, M, Wilkens P, Rosas H D, Fischl B (2016). NeuroImage 127:277–286.

Reporting Bugs

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

Author/s

Anastasia Yendiki