Differences between revisions 6 and 7
Deletions are marked like this. Additions are marked like this.
Line 33: Line 33:
Included with each !FreeSurfer distribution, is an example configuration file located in $FREESURFER_HOME/bin/dmrirc.example. The configuration script allows you to set certain variables necessary for running TRACULA (i.e. data location) and to select how the data will be processed (i.e. which registration method should be used). If you run TRACULA without using a configuration file, then you will only be able to run the default options. Below, we explore the commands in the example configuration file and how they can be altered to better suit your analysis purposes. Step 1: Create a text file to specify configurations for running a subject through TRACULA. You can use any text editor like gedit, vi, emacs, etc to open a text file. For the purposes of this tutorial, we have already created a configuration file called '''dmrirc_single_subject'''. Open this file to see the example and follow along as we explain the commands:

{{{
gedit $TUTORIAL_DATA/diffusion_tutorial/scripts/dmrirc_single_subject &
}}}
Note that lines preceded by the # sign are "commented out" and so will not be run as commands. The # symbol can be handy for adding descriptions of what each command will do. The configuration file will look like this:
An example configuration file for TRACULA is included in the !FreeSurfer distribution at $FREESURFER_HOME/bin/dmrirc.example and it is also [[dmrirc|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 using a configuration file, then you will only be able to use the default options. Below, we explore the options included in the tutorial configuration file and some additional options that you may want to change in your analysis.

Step 1: Create a simple text file that will serve as your
TRACULA configuration file. You can use any text editor like gedit, vi, emacs, etc 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/scripts/dmrirc.tutorial &
}}}
Note that lines preceded by the # sign are "commented out" and so will not be run as commands. The # symbol can be handy for adding descriptions of what each command will do. The tutorial configuration file looks like this:

Top | Next

TRACULA Tutorial

This TRACULA tutorial will take you through the steps necessary to run TRACULA on a dataset. You will learn how to set up a configuration file, how to run TRACULA, and how to view the results.

Preparations

If You're 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 every new terminal window (aka shell) you open throughout this tutorial. Copy and paste the commands below to get started:

setenv 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 (this will paste the command). Press enter to run the command.

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

If You're 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:

tcsh
source your_freesurfer_dir/SetUpFreeSurfer.csh
setenv SUBJECTS_DIR your_tutorial_data/diffusion_recons
cd $TUTORIAL_DATA/diffusion_tutorial

Notice the command to open tcsh. If you are already running the tcsh command shell, then the 'tcsh' command is not necessary. 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.


Setting Up A Configuration File

An example configuration file for TRACULA is included in the FreeSurfer distribution at $FREESURFER_HOME/bin/dmrirc.example and it is 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 using a configuration file, then you will only be able to use the default options. Below, we explore the options included in the tutorial configuration file and some additional options that you may want to change in your analysis.

Step 1: Create a simple text file that will serve as your TRACULA configuration file. You can use any text editor like gedit, vi, emacs, etc 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/scripts/dmrirc.tutorial &

Note that lines preceded by the # sign are "commented out" and so will not be run as commands. The # symbol can be handy for adding descriptions of what each command will do. The tutorial configuration file looks like this:

#
# Set locations of diffusion DICOMs, diffusion output, FreeSurfer recons
#
# This file contains commands that will be run by trac-all before an analysis.
# It is used to set all parameters needed for the analysis.
#
# Remove a parameter from your dmrirc file if you want to use the default value.
# Parameters that don't have default values must be specified.
#
# Any other commands that you might want to run before an analysis can be added
# to this file.
#
# Original Author: Anastasia Yendiki
# CVS Revision Info:
#    $Author: ayendiki $
#    $Date: 2010/12/15 08:36:00 $
#    $Revision: 1.1 $
#
# Copyright (C) 2010
# The General Hospital Corporation (Boston, MA).
# All rights reserved.
#
# Distribution, usage and copying of this software is covered under the
# terms found in the License Agreement file named 'COPYING' found in the
# FreeSurfer source code root directory, and duplicated here:
# https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferOpenSourceLicense
#
# General inquiries: freesurfer@nmr.mgh.harvard.edu
#
# FreeSurfer SUBJECTS_DIR
setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons
# Output directory where trac-all results will be saved
set dtroot = $TUTORIAL_DATA/diffusion_tutorial
# Subject IDs
set subjlist = (Diff001 Diff002 Diff003)
set runlist = (1)
# Input diffusion DICOMs (file names relative to dcmroot)
set dcmroot = $TUTORIAL_DATA/diffusion_tutorial/
set dcmlist = (Diff001/orig/484000-6-1.dcm \
               Diff002/orig/312000-6-1.dcm \
               Diff003/orig/781000-6-1.dcm)
set doeddy = 1
set dorotbvecs = 1
set thrbet = 0.3
set doregflt = 1
set doregbbr = 1
set doregmni = 1
set mnitemp = $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz
set trainfile = $TUTORIAL_DATA/diffusion_tutorial/subj,train,difftutorial23.txt
# Paths to reconstruct
# Default: All paths
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)

# Number of path control points
# Default: 5
set ncpts = 5

Below, we will go through what the different lines in the above script accomplish.


Step 2: Set Expected FreeSurfer Enviroment Variables

setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons

TRACULA uses the aparc+aseg.mgz from the FreeSurfer recon (T1-weighted volume) as ROIs to construct the tracts. Because of this, we must set the SUBJECTS_DIR variable to the directory where the subject's recon is located.


Step3: Setting The Output Directory

set dtroot = $TUTORIAL_DATA/diffusion_tutorial

The above step specifies the directory where the results from TRACULA will be saved. If this is not specified, results will automatically be saved under $SUBJECTS_DIR.


Step4: Specify Subject ID

set subjlist = (Diff001 Diff002 Diff003)

Use this variable to specify the ID of the subject(s) you want to process with TRACULA. Diff002 and Diff003 are not a part of the tutorial. It is given as an example to illustrate that multiple subjects can be specified in the subjlist variable. This is very useful for batch processing multiple subjects.


Step5: Specify Subjects To Be Analyzed The following step is useful when you want to analyze only a subset of subjects from the list of subjects specified above. If it is not set, it will run the analysis on all subjects by default.

set runlist = (1)


Step6: Specify Input Diffusion DICOM Directory If not specified on the commandline with trac-all, the dicom directory and diffusion dicoms must be specified in the configuration file.

set dcmroot = $TUTORIAL_DATA/diffusion_tutorial/

The above variable specifies the location of the diffusion dicoms.


Step7: Specify Input DICOMS List

set dcmlist = (Diff001/orig/6-1.dcm \
               Diff002/orig/312000-6-1.dcm \
               Diff003/orig/781000-6-1.dcm)

This variable should list the 1st DICOM in each series that is to serve as the diffusion input data for each subject. The filenames should be relative to the path dcmroot is set to. When you specify the first dicom file name, it automatically recognizes the others within that folder. The Diffusion gradient table, b-value table and # of low-b images will be automatically read from the dicom header. No DICOM? No problem. If original DICOMs don't exist, other image formats may be used however, bvec, bval, and number of lowb volumes must be specified in the configuration file (see below).


Step7.1: Specifying Diffusion bvalue Table The b-value file must be in single-column format with one value for each volume in the diffusion data set. For example, if your data set includes 3 non-diffusion-weighted (b=0) images followed by 6 diffusion-weighted images acquired with b=1000mm^-2, then you would create a bvals.txt file that looks like this: (You do not need to copy/paste the text below into the terminal window, the b-value file has already been created for you).

0
0
0
1000
1000
1000
1000
1000
1000

In the configuration file, you would need to specify the location of the b-value file, like so:

set bvalfile = /path/to/bvals.txt


Step7.2: Specifying Diffusion Gradient Table The diffusion gradient table file must be in three-column format, one row for each volume in the diffusion data set. The first three rows of the gradient table example below are 0s because as in the example above, 3 low-b (non-diffusion-weighted) volumes were collected. The remaining values are determined based on the scanner. (You do not need to copy/paste the text below into the terminal window, the gradient table file has already been created for you).

 0  0  0
 0  0  0
 0  0  0
 1  0  1
-1  0  1
 0  1  1
 0  1 -1
 1  1  0
-1  1  0

As with the bvals.txt, the gradient table must also be specified in the configuration file as the following:

set bvecfile = /path/to/bvecs.txt


Step7.3: Specifying Number Of low-b Images The last step to set up if not using original DICOMs would be to specify the number of low-b images with the following variable:

set nb0 = *No. of low-b images*

** - To be replaced with the actual number from the acquisition.


Step8: Perform Eddy Current Correction

set doeddy = 1

This step specifies if TRACULA will perform eddy current correction on the image data. This correction compensates for distortions caused due to eddy currents from gradient coils and slight head motion. It performs an affine registration of each volume in the dataset to the low-b volume. Setting this variable (and most of those remaining in this tutorial) to 1 means that this step will be done. If you do not want it to be done, set it to 0.


Step9: Rotate Diffusion Gradients

set dorotbvecs = 1

This step specifies if TRACULA will rotate the diffusion gradient table to match the eddy current compensation.


Step10: Set BET Threshold

set thrbet = 0.3

This step sets the threshold for skull stripping in FSL's Brain Extraction Tool (BET) to get the skull-stripped low-b images. This value is specified as a fraction of the maximum image intensity and can range from 0.0 to 1.0. The default is 0.3.


Step11: Set Registration Method For Resampling Diffusion To T1 To register the diffusion data to the structural data, you can choose either FSL's FLIRT or FreeSurfer's bbregister (or do both for comparison purposes) from within the configuration file. If you would like to use only FLIRT to perform the diffusion-to-T1 registration, set the FLIRT variable (doregflt) to 1 and the bbregister variable (doregbbr) to 0:

set doregflt = 1
set doregbbr = 0

To perform the diffusion-to-T1 registration using only bbregister, do the opposite:

set doregflt = 0
set doregbbr = 1

When both these variables are set to '1', TRACULA computes transformations using both FLIRT and bbregister.


Step12: Registration To A Common Template With this step, you specify which common template to register the diffusion data to (MNI template). Although tractography is performed in the subject's native diffusion place, this inter-subject registration is needed to map the individual to the training set where TRACULA's anatomical priors are derived from. To register diffusion data to MNI space, set doregmni to 1 and specify the location of the template:

set doregmni = 1

Setting the path of the MNI template, this is the default:

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


Step13: Set Up A Training File The training file consists of a collection of normal subjects whose major white matter bundles were delineated manually by trained raters. These manual labels serve as an atlas for guiding the automated tractography in TRACULA. These training subjects are supplied with your FreeSurfer distribution and the full list, used by default, is $FREESURFER_HOME/trctrain/trainlist.txt. You would specify this file with the command below:

set trainfile = $TUTORIAL_DATA/diffusion_tutorial/subj,train,difftutorial23.txt


Step14: Specify Paths To Reconstruct This option allows us to specify the paths we want to reconstruct for the given subject. The default is to reconstruct the complete set of paths, 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 Radiation
  • rh.atr_PP: Right Anterior Thalamic Radiation
  • lh.ccg_PP: Left Cingulum - Cingulate Gyrus
  • rh.ccg_PP: Right Cingulum - Cingulate Gyrus
  • lh.cab_PP: Left Cingulum - Angular Bundle
  • rh.cab_PP: Right Cingulum - Angular Bundle
  • lh.slfp_PP: Left Superior Longitudinal Fasciculus - Parietal
  • rh.slfp_PP: Right Superior Longitudinal Fasciculus - Parietal
  • lh.slft_PP: Left Superior Longitudinal Fasciculus - Temporal
  • rh.slft_PP: Right Superior Longitudinal Fasciculus - Temporal

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)


Step15: Specify Number Of Path Control Points This option allows us to specify the number of control points along the length of the tract. A fairly straight pathway may be well-defined by a few control points, whereas a highly curved pathway may require more control points. The default is 5 but you may choose any number greater than 2 using the variable below.

set ncpts = 5


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.

Top | Next

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