Differences between revisions 88 and 89
Deletions are marked like this. Additions are marked like this.
Line 280: Line 280:
{{{
set doeddy = 1
}}}
Use this variable to specify if eddy-current compensation (commonly referred to as [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy|eddy-current correction]]) will be performed as part of DWI pre-processing. This compensation consists of an affine registration of all DWIs to the first image in the series using FSL's {{{eddy_correct}}}, which is meant to mitigate distortions due to eddy currents and head motion. By default this variable is set to 1, so eddy-current compensation is performed. Set it to 0 to disable it.
To specify if you want to compensate for eddy-current distortions, use the {{{doeddy}}} variable. Possible options are 0 (none), 1 (using FSL's [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#Distortion_Correction|eddy_correct]]), or 2 (using FSL's [[[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy|eddy]]).

{{{
set doeddy = 2
}}}

The default is to use {{{eddy}}}. Set {{{doeddy}}} to 0 to disable it.
Line 288: Line 291:
There are two options for registering each subject's DWIs to the subject's own T1-weighted image: [[bbregister]] or FSL's FLIRT. They both perform affine registration but bbregister also uses the !FreeSurfer surface reconstruction to optimize the affine registration between the diffusion and anatomical scan.

The following selects the default option, which is to use bbregister and not FLIRT:

{{{
set doregflt = 0
set doregbbr = 1
}}}
To use FLIRT and not bbregister, set {{{doregflt}}} to 1 and {{{doregbbr}}} to 0. If you do not have a preference and want the analysis performed with both options for comparison purposes, set both of these variables to 1 (this will take longer and create two sets of outputs).
The intra-subject registration (from each subject's DWIs to the subject's own T1-weighted image) can be done either with [[bbregister]] or with FSL's [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FLIRT|FLIRT]]. They both perform affine registration but bbregister also uses the !FreeSurfer surface reconstruction to optimize the affine registration between the diffusion and T1 scan.

To specify the intra-subject registration method, use the {{{intrareg}}} variable:
{{{
set intrareg = 3
}}}

The options are {{{1}}} ({{{FLIRT}}} with a correlation ratio cost), {{{2}}} ({{{FLIRT}}} with a mutual information cost), and {{{3}}} ({{{bbregister}}}, which uses a boundary-based cost).

For additional options related to the intra-subject registration method, see [[dmrirc|the example configuration files]].

Back to list of all tutorials | Back to course page | Next

TRACULA tutorial

This tutorial will take you through the steps necessary to run TRACULA (TRActs Constrained by UnderLying Anatomy). You will learn how to set up a configuration file, how to run the analyses, and how to view the results.

Preparations

If you are at an organized course

If you are taking one of the formally organized courses, everything has been set up for you on the provided laptop. The only thing you will need to do is run the following commands in each new terminal window you open throughout this tutorial. Copy and paste the commands below to get started:

export SUBJECTS_DIR=$TUTORIAL_DATA/diffusion_recons
cd $TUTORIAL_DATA/diffusion_tutorial

To copy: Highlight the command in the box above, right click and select copy (or use keyboard shortcut Ctrl+c), then use the middle button of your mouse to click inside the terminal window to paste the command (or use keyboard shortcut Ctrl+Shift+v). Press enter to run the command.

These two commands set the SUBJECTS_DIR variable to the directory where the recon-all structural data is stored and then navigates into the directory with the TRACULA data. You can now skip ahead to the tutorial (below the gray line).

If you are not at an organized course

If you are NOT taking one of the formally organized courses, then to follow this exercise exactly be sure you've downloaded the tutorial data set before you begin. If you choose not to download the data set you can follow these instructions on your own data, but you will have to substitute your own specific paths and subject names. These are the commands that you need to run before getting started:

## bash
export FREESURFER_HOME=/path/to/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh
export TUTORIAL_DATA=<path_to_your_tutorial_data>
export SUBJECTS_DIR=$TUTORIAL_DATA/diffusion_recons
cd $SUBJECTS_DIR

## tcsh
setenv FREESURFER_HOME /path/to/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.csh
setenv TUTORIAL_DATA <path_to_your_tutorial_data>
setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons
cd $SUBJECTS_DIR

If you are not using the tutorial data you should set your SUBJECTS_DIR to the directory in which the recon(s) of the subject(s) you will use for this tutorial are located.

IMPORTANT: Check to make sure you have the latest version of FreeSurfer available before running this tutorial as Tracula is updated with new FreeSurfer version. To see the latest Tracula updates, click here.


Setting up a configuration file

Example configuration files for TRACULA are included in the FreeSurfer distribution at $FREESURFER_HOME/bin/dmrirc*example and are also available on the wiki.

The configuration file is a Unix shell script where you set variables to specify the location of the input data and various processing preferences. If you run TRACULA without a configuration file, then you will only be able to use the default processing options. Below we explore the bare minimum options that you have to set in the configuration file, as well as some additional options that you may want to set depending on the specifics of your analysis.

Step 1: Create a configuration file. This is a simple text file that contains Unix (C shell) commands. You can create it with any text editor (gedit, vi, emacs, etc). On a Mac, run  open -e  to open a text file. For the purposes of this tutorial, we have already created a configuration file called dmrirc.tutorial. Open this file to see the example and follow along as we explain the commands:

gedit $TUTORIAL_DATA/diffusion_tutorial/dmrirc.tutorial &

NOTE: on Macs, run the following command:

open -e $TUTORIAL_DATA/diffusion_tutorial/dmrirc.tutorial &

Note that lines preceded by the # sign are "comments" and so will not be run as commands. The # symbol can be handy for adding descriptions of what each command will do, or to "comment out" commands that you want to disable temporarily. The tutorial configuration file looks like this:

# FreeSurfer SUBJECTS_DIR
# T1 images and FreeSurfer segmentations are expected to be found here
#
setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons

# Output directory where trac-all results will be saved
# Default: Same as SUBJECTS_DIR
#
set dtroot = $TUTORIAL_DATA/diffusion_tutorial

# Subject IDs
#
set subjlist = ( elmo.2005 \
                 elmo.2008 \
                 elmo.2012 )

# Input diffusion DICOMs
# If original DICOMs don't exist, these can be in other image format
# but then the gradient table and b-value table must be specified (see below)
#
set dcmlist = ( $TUTORIAL_DATA/diffusion_tutorial/elmo.2005/orig/656000-11-1.dcm \
                $TUTORIAL_DATA/diffusion_tutorial/elmo.2008/orig/97000-000017-000001.dcm \
                $TUTORIAL_DATA/diffusion_tutorial/elmo.2012/orig/MR.1.3.12.2.1107.5.2.32.35006.2012121819455034689828982 )

# Diffusion gradient tables (if there is a different one for each scan)
# Must be specified if they cannot be read from the DICOM headers
# The tables must have either three columns, where each row is a gradient vector
# or three rows, where each column is a gradient vector
# There must be as many gradient vectors as volumes in the diffusion data set
# Default: Read from DICOM header
#
set bveclist = ( $TUTORIAL_DATA/diffusion_tutorial/elmo.2005/orig/gradients.txt \
                 $TUTORIAL_DATA/diffusion_tutorial/elmo.2008/orig/gradients.txt \
                 $TUTORIAL_DATA/diffusion_tutorial/elmo.2012/orig/gradients.txt )

# Diffusion b-value tables (if there is a different one for each scan)
# Must be specified if they cannot be read from the DICOM headers
# There must be as many b-values as volumes in the diffusion data set
# Default: Read from DICOM header
#
set bvallist = ( $TUTORIAL_DATA/diffusion_tutorial/elmo.2005/orig/bvalues.txt \
                 $TUTORIAL_DATA/diffusion_tutorial/elmo.2008/orig/bvalues.txt \
                 $TUTORIAL_DATA/diffusion_tutorial/elmo.2012/orig/bvalues.txt )

This a very simple configuration file, where only the absolutely necessary inputs are specified. We will now go through the options specified in the file above.


Do not run the rest of the commands on this page!

These are just the commands that would go into a configuration file, and are listed and explained here as an example.


Step 2: Specify the FreeSurfer subject directory

setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons

This variable must be set to the directory where all the subjects' FreeSurfer reconstructions are located. It is assumed that FreeSurfer has already been run on the subjects' T1-weighted data. TRACULA will use the aparc+aseg.mgz from each subject's FreeSurfer reconstruction - this is where the "underlying anatomy" part of TRACULA comes from.


Step 3: Specify the TRACULA output directory

set dtroot = $TUTORIAL_DATA/diffusion_tutorial

Use this variable to specify the directory where the TRACULA outputs for all subjects will be saved. If this is not specified, results will be saved under $SUBJECTS_DIR by default.


Step 4: Specify the list of subject IDs

set subjlist = (elmo.2005 elmo.2008 elmo.2012)

Use this variable to specify the ID of all the subjects you want to process with TRACULA. This can be a single subject, or it can be multiple subjects for batch processing.


Step 5: Specify the location of diffusion DICOM files

set dcmroot = $TUTORIAL_DATA/diffusion_tutorial

Use this variable to specify the directory under which the diffusion DICOM files for all subjects can be found.


Step 6: Specify the list of input DWIs

set dcmlist = ( elmo.2005/orig/656000-11-1.dcm \
                elmo.2008/orig/97000-000017-000001.dcm \
                elmo.2012/orig/MR.1.3.12.2.1107.5.2.32.35006.2012121819455034689828982 )

Use this variable to specify the input DWI data, one entry per subject. The file names are assumed to be relative to the directory specified in dcmroot above. If DICOM files are available, you just need to specify the first DICOM file in the series that contains the DWIs, assuming the remaining DICOM files from the same series are in the same directory. If your DWIs are in a format other than DICOM, you can still specify the DWI volumes here, as long as they are in a format that can be read by mri_convert.

For DICOM files where the diffusion-encoding gradients and b-values are stored in a standard location in the DICOM header, these will be read from the header. In that case, you do NOT need to specify anything else in your configuration file.

For non-standard DICOM formats or for files formats other than DICOM, you will need to specify the location of the diffusion-encoding gradient table (see bveclist below) and the b-value table (see bvallist below).


In addition to the basic options in the simple configuration file above, there are several other options that you can use to customize data processing for your study. These are listed in more extensive example configuration files, which are also available as part of the FreeSurfer distribution. We will now go through some of these additional options.


Step 7: Specify which subjects to analyze

set runlist = (2 3)

Use this variable if you only want to run the analysis on a subset of the subjects included in subjlist. The example above would run the analysis only on the second and third subject. This is useful if, e.g., you need to rerun a specific part of the analysis on a few of your subjects only. If this variable is not set, the analysis will be run on all subjects by default.


Step 8: Specify the diffusion-encoding gradient tables

You can specify the gradient table that corresponds to each of the scans in the study with bveclist. For example:

set bveclist = ( /path/to/subject1/bvecs.txt \
                 /path/to/subject2/bvecs.txt \
                 /path/to/subject3/bvecs.txt )

Use this variable to specify the location of the gradient tables, if your DWI data are not in a DICOM format that allows mri_convert to read the gradients from the header.

Each gradient table must be a simple text file, either in three-column format (one row for each volume in the corresponding DWI scan) or in three-row format (one column for each volume in the corresponding DWI scan). An example is shown below:

 0     0      0
 0     0      0
 0     0      0
 0.707 0      0.707
-0.707 0      0.707
 0     0.707  0.707
 0     0.707 -0.707
 0.707 0.707  0
-0.707 0.707  0

In this example the first 3 rows of the gradient table are all zero, indicating that 3 low-b (non-diffusion-weighted) volumes were acquired first, while the remaining 6 rows correspond to 6 diffusion-weighted volumes acquired with different diffusion-encoding gradients.


Step 9: Specify the b-value tables

You can specify the b-value table that corresponds to each of the scans in the study with bvallist. For example:

set bvallist = ( /path/to/subject1/bvals.txt \
                 /path/to/subject2/bvals.txt \
                 /path/to/subject3/bvals.txt )

Use either this variables to specify the location of the b-value tables, if your DWI data are not in a DICOM format that allows mri_convert to read the b-values from the header.

Each b-value table must be a simple text file, with one value for each volume in the corresponding DWI scan. An example is shown below:

0
0
0
1000
1000
1000
1000
1000
1000

In this example the DWI series would include 3 non-diffusion-weighted (b=0) images, followed by 6 diffusion-weighted images acquired with b=1000.


Step 10: Specify a method for compensating for B0 inhomogeneity distortions

To specify if you want to compensate for B0 inhomogeneity distortions, use the dob0 variable. Possible options are 0 (none), 1 (using field maps), or 2 (using reverse-polarity images). Depending on which method you choose, you may need to provide additional inputs.

To skip this (default):

set dob0 = 0

To use field maps:

set dob0 = 1

set b0mlist = (subject1/fmag/XXX-1.dcm subject2/fmag/XXX-1.dcm subject3/fmag/XXX-1.dcm)
set b0plist = (subject1/fphas/XXX-1.dcm subject2/fphas/XXX-1.dcm subject3/fphas/XXX-1.dcm)
set echospacing = 0.7

This option calls epidewarp.fsl. To use it, your scan protocol must include a field mapping sequence. You must specify the following in the configuration file:

  • b0mlist: The paths to the input B0 field map magnitude DICOMs (can be absolute or relative to dcmroot)

  • b0plist: The paths to the input B0 field map phase DICOMs (can be absolute or relative to dcmroot)

  • echospacing: The echo spacing (is found in the scanner protocol printout)

To use reverse-polarity images:

set dob0 = 2

set subjlist = (subject1 subject1 subject2 subject2 subject3 subject3)
set dcmlist = (subject1/dwi1/XXX-1.dcm subject1/dwi2/XXX-1.dcm subject2/dwi1/XXX-1.dcm subject2/dwi2/XXX-1.dcm subject3/dwi1/XXX-1.dcm subject1/dwi2/XXX-1.dcm)
set pedir = ( AP PA AP PA AP PA)
set echospacing = 0.35
set epifactor = 140

This option calls FSL's topup. To use it, your scan protocol must include more than one DWI scan, and these scans must be collected with different phase-encode directions. These scans may or may not contain the same number of directions. For example, you may have collected your full DWI series twice, once with phase-encode direction A->P and once with phase-encode direction P->A; or you may have collected your full DWI series with phase-encode direction A->P and only the b=0 volume with phase-encode direction P->A.

Note that, because you now have more than one DWI scan per subject, each subject ID shows up more than once in the subjlist. In the example above, each subject ID shows up twice in the subjlist because there are two scans for each subject in the dcmlist (.../dwi1/... and .../dwi2/...). In this example, these are two scans that were collected with opposite phase-encode direction (AP and PA) and can thus be passed to topup to estimate the off-resonance field map.

You must also specify the following in the configuration file:

  • pedir: The phase-encode direction, one for each DWI scan in dcmlist (is found in the scanner protocol printout)

  • echospacing: The echo spacing (is found in the scanner protocol printout)

  • epifactor: The EPI factor (is found in the scanner protocol printout)

An example configuration file for the case where you have more than one DWI scan per session is included in the FreeSurfer distribution at $FREESURFER_HOME/bin/dmrirc.multiscan.example and is also available on the wiki.


Step 11: Specify a method for compensating for eddy-current distortions

To specify if you want to compensate for eddy-current distortions, use the doeddy variable. Possible options are 0 (none), 1 (using FSL's eddy_correct), or 2 (using FSL's eddy).

set doeddy = 2

The default is to use eddy. Set doeddy to 0 to disable it.


Step 12: Specify the intra-subject registration method

The intra-subject registration (from each subject's DWIs to the subject's own T1-weighted image) can be done either with bbregister or with FSL's FLIRT. They both perform affine registration but bbregister also uses the FreeSurfer surface reconstruction to optimize the affine registration between the diffusion and T1 scan.

To specify the intra-subject registration method, use the intrareg variable:

set intrareg = 3

The options are 1 (FLIRT with a correlation ratio cost), 2 (FLIRT with a mutual information cost), and 3 (bbregister, which uses a boundary-based cost).

For additional options related to the intra-subject registration method, see the example configuration files.


Step 13: Specify the inter-subject registration method

There are two options for registering each subject to the tract atlas used by TRACULA: affine registration to the MNI template (MNI152) or nonlinear registration to the CVS template (cvs_avg35). Although TRACULA performs tractography in each subject's own native diffusion space, this inter-subject registration is needed to map the individual to the tract atlas that TRACULA's anatomical priors are derived from. Note that the prior information extracted from this atlas is not the exact spatial location of the tracts, but the IDs of the anatomical segmentation labels that the tracts go through or next to. Thus, a rough spatial alignment is sufficient for these anatomical priors to be accurate. However, another purpose for which the mapping to a common template is used is to choose an initial guess of the tract location to initialize TRACULA. If the study subject's anatomy is significantly different from that of a normal population, this initialization may be more accurate when nonlinear registration is used.

The following selects the default options, which is to use MNI and not CVS registration:

set doregmni = 1
set doregcvs = 0

To use CVS and not MNI registration, set doregcvs to 1 and doregmni to 0 (this will take much longer). If you do not have a preference and want the analysis performed with both options for comparison purposes, set both of these variables to 1 (this will take even longer).

It is possible to specify the location of MNI template. If it is not specified, this will be assumed by default:

set mnitemp = $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz

It is also possible to specify the location of CVS template. If it is not specified, this will be assumed by default:

set cvstemp = cvs_avg35
set cvstempdir = $FREESURFER_HOME/subjects


Step 14: Specify which white-matter pathways to reconstruct

set pathlist = ( lh.cst_AS rh.cst_AS \
                 lh.ilf_AS rh.ilf_AS \
                 lh.unc_AS rh.unc_AS \
                 fmajor_PP fminor_PP \
                 lh.atr_PP rh.atr_PP \
                 lh.cab_PP rh.cab_PP \
                 lh.ccg_PP rh.ccg_PP \
                 lh.slfp_PP rh.slfp_PP \
                 lh.slft_PP rh.slft_PP )

Use this variable to specify which of the 18 pathways included in the TRACULA tract atlas to reconstruct. The default is to reconstruct all 18 pathways, defined below:

  • lh.cst_AS: Left corticospinal tract
  • rh.cst_AS: Right corticospinal tract
  • lh.ilf_AS: Left inferior longitudinal fasciculus
  • rh.ilf_AS: Right inferior longitudinal fasciculus
  • lh.unc_AS: Left uncinate fasciculus
  • rh.unc_AS: Right uncinate fasciculus
  • fmajor_PP: Corpus callosum - forceps major
  • fminor_PP: Corpus callosum - forceps minor
  • lh.atr_PP: Left anterior thalamic radiations
  • rh.atr_PP: Right anterior thalamic radiations
  • lh.ccg_PP: Left cingulum - cingulate gyrus endings
  • rh.ccg_PP: Right cingulum - cingulate gyrus endings
  • lh.cab_PP: Left cingulum - angular bundle
  • rh.cab_PP: Right cingulum - angular bundle
  • lh.slfp_PP: Left superior longitudinal fasciculus - parietal endings
  • rh.slfp_PP: Right superior longitudinal fasciculus - parietal endings
  • lh.slft_PP: Left superior longitudinal fasciculus - temporal endings
  • rh.slft_PP: Right superior longitudinal fasciculus - temporal endings


Step 15: Specify the number of path control points

set ncpts = (6 6 5 5 5 5 7 5 5 5 5 5 4 4 5 5 5 5)

Use this variable to specify the number of control points that will be used to model each of the pathways in pathlist as a spline. Any number greater than 2 is a valid choice but, as a rule of thumb, a fairly straight pathway can be modeled using only a few control points, whereas a highly curved pathway may require more control points. The default, as shown above, is to use 7 for the forceps major, 6 for the corticospinal tract, 4 for the angular bundle, and 5 for all other pathways.

In TRACULA the control points are perturbed (moved just a little bit) many times to create a distribution of curves. The exact number of perturbations is defined by the nsamples in the config file - the default is set to 7500. For each of these curves, we find which explain the diffusion data well and which do not. Those that do are accepted and the others are rejected. The accepted curves are all added up to give you the heat map that you see when you view path.pd.nii.gz (pd = probability distribution).


Now that the configuration file is all set, you can run TRACULA! Hit Next below to move on to the next part of the tutorial.


Summary

By the end of this page, you should know how to:

  • Create a configuration file
  • Supply the correct steps/parameters for processing
  • Set additional options depending on the specifics of your analysis

Back to list of all tutorials | Back to course page | Next

FsTutorial/Tracula (last edited 2023-07-17 08:52:23 by AnastasiaYendiki)