| Deletions are marked like this. | Additions are marked like this. |
| Line 114: | Line 114: |
|
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 a more extensive [[dmrirc|example configuration file,]] which is also available as part of the !FreeSurfer distribution. We will now go through these additional options. ---- |
|
| Line 119: | Line 122: |
|
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 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. ---- '''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). |
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 table''' {{{ set bvecfile = /path/to/bvecs.txt }}} Use this variable to specify the location of the gradient table, if your DWI data is not in Siemens DICOM format. (The tutorial data is in Siemens DICOM format, so this step is not required.) The gradient table must be saved in a simple text file in three-column format, one row for each volume in the DWI series. An example is shown below: |
| Line 154: | Line 144: |
|
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 }}} ---- '''Step8: Perform Eddy Current Correction''' |
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 table''' {{{ set bvalfile = /path/to/bvals.txt }}} Use this variable to specify the location of the b-value table, if your DWI data is not in Siemens DICOM format. (The tutorial data is in Siemens DICOM format, so this step is not required.) The b-value table must be saved in a simple table file in single-column format, one row for each volume in the DWI series. 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=1000mm^-2. ---- '''Step 10: Specify if eddy-current compensation will be performed''' |
| Line 166: | Line 174: |
|
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''' |
Use this variable to specify if eddy-current compensation 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, 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. ---- '''Step 11: Specify if the gradients will be rotate to match eddy-current compensation''' |
| Line 174: | Line 182: |
|
This step specifies if TRACULA will rotate the diffusion gradient table to match the eddy current compensation. ---- '''Step10: Set BET Threshold''' |
Use this variable to specify the vectors in the diffusion-encoding gradient table will be rotate according to the transformations applied by the eddy-current compensation. This is recommended if eddy-current compensation is performed. ---- '''Step 12: Set the threshold for the DWI-based brain mask extraction''' |
| Line 182: | Line 190: |
|
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: |
Use this variable to set the threshold for creating a brain mask from the DWIs using FSL's Brain Extraction Tool (BET). This value is specified as a fraction of the maximum image intensity, so it must be a number between 0 and 1. The default is 0.3. Note that by default the brain mask used by TRACULA is extracted from the T1-weighted images, not the DWIs, in which case this variable will not have much of an effect on the analysis. ---- '''Step 13: 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: |
| Line 200: | Line 208: |
| '''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: | '''Step 14: 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: |
| Line 211: | Line 219: |
| '''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: | '''Step 15: 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: |
| Line 217: | Line 225: |
| '''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. | '''Step 16: 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. |
| Line 250: | Line 258: |
| '''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. | '''Step 17: 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. |
TRACULA Tutorial
This tutorial will take you through the steps necessary to run TRACULA (TRActs Constrained by UnderLying Anatomy) on a set of subjects. 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 a configuration file, then you will only be able to use the default processing options. Below we explore the options that are set in the tutorial configuration file and 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, so you can create it with any text editor (gedit, vi, emacs, etc). 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 "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 (file names relative to dcmroot)
# If original DICOMs don't exist, these can be in other image format
# but then bvecfile and bvalfile must be specified
#
set dcmroot = $TUTORIAL_DATA/diffusion_tutorial
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 )This is the simplest configuration file possible, where only the most basic inputs are specified. We will now go through the options specified in the file above.
Step 2: Specify the FreeSurfer subject directory
setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons
The SUBJECTS_DIR 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 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 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 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 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 DICOMs acquired with the standard Siemens diffusion sequences, the diffusion-encoding gradient table and the b-value table will be determined based on information in the DICOM header. For DICOM files acquired with other sequences or for files formats other than DICOM, you will need to specify the location of the diffusion-encoding gradient table and the b-value table (see 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 a more extensive example configuration file, which is also available as part of the FreeSurfer distribution. We will now go through 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 table
set bvecfile = /path/to/bvecs.txt
Use this variable to specify the location of the gradient table, if your DWI data is not in Siemens DICOM format. (The tutorial data is in Siemens DICOM format, so this step is not required.)
The gradient table must be saved in a simple text file in three-column format, one row for each volume in the DWI series. An example is shown below:
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
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 table
set bvalfile = /path/to/bvals.txt
Use this variable to specify the location of the b-value table, if your DWI data is not in Siemens DICOM format. (The tutorial data is in Siemens DICOM format, so this step is not required.)
The b-value table must be saved in a simple table file in single-column format, one row for each volume in the DWI series. 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=1000mm^-2.
Step 10: Specify if eddy-current compensation will be performed
set doeddy = 1
Use this variable to specify if eddy-current compensation 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, 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.
Step 11: Specify if the gradients will be rotate to match eddy-current compensation
set dorotbvecs = 1
Use this variable to specify the vectors in the diffusion-encoding gradient table will be rotate according to the transformations applied by the eddy-current compensation. This is recommended if eddy-current compensation is performed.
Step 12: Set the threshold for the DWI-based brain mask extraction
set thrbet = 0.3
Use this variable to set the threshold for creating a brain mask from the DWIs using FSL's Brain Extraction Tool (BET). This value is specified as a fraction of the maximum image intensity, so it must be a number between 0 and 1. The default is 0.3. Note that by default the brain mask used by TRACULA is extracted from the T1-weighted images, not the DWIs, in which case this variable will not have much of an effect on the analysis.
Step 13: 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.
Step 14: 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
Step 15: 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
Step 16: 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)Step 17: 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.