|
Size: 14346
Comment:
|
Size: 17323
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| ## page was renamed from FsTutorial/Tracula_tktools ## page was renamed from FsTutorial/Tracula |
|
| Line 3: | Line 5: |
| = 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. |
= 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. |
| Line 6: | Line 10: |
| === Organized Course === If you are taking one of the formally organized courses, everything has been set up for you. The only thing you need to do is run: {{{ setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons |
=== 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 |
| Line 12: | Line 17: |
| on '''each new''' terminal that you open. === Your Computer === If you are '''NOT''' taking one of the formally organized courses, then to follow this exercise exactly be sure you've downloaded the [[FsTutorial/Data|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: {{{ tcsh source your_freesurfer_dir/SetUpFreeSurfer.csh setenv SUBJECTS_DIR your_tutorial_data/diffusion_recons |
''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 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 [[FsTutorial/Data|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: {{{ <source_freesurfer> export TUTORIAL_DATA=<path_to_your_tutorial_data> export SUBJECTS_DIR=$TUTORIAL_DATA/diffusion_recons |
| Line 22: | Line 30: |
| Notice the command to open tcsh. If you are already running the tcsh command shell, then the 'tcsh' command is not necessary. | |
| Line 24: | Line 31: |
| '''IMPORTANT: MAKE SURE YOU HAVE DOWNLOADED THE LATEST UPDATE OF TRACULA FROM [[http://surfer.nmr.mgh.harvard.edu/fswiki/Tracula/#Updates|HERE]] BEFORE DOING THIS TUTORIAL! ''' | |
| Line 25: | Line 33: |
| == Setting Up A Configuration File == 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: {{{ # # 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 # |
== 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 [[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 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). 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 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: {{{ |
| Line 63: | Line 46: |
| setenv SUBJECTS_DIR $TUTORIAL_DATA/diffusion_recons | # T1 images and FreeSurfer segmentations are expected to be found here # export SUBJECTS_DIR=$TUTORIAL_DATA/diffusion_recons |
| Line 65: | Line 51: |
| # Default: Same as SUBJECTS_DIR # |
|
| Line 66: | Line 54: |
| Line 67: | Line 56: |
| set subjlist = (Diff001 Diff002 Diff003) set runlist = (1) |
# set subjlist = ( elmo.2005 \ elmo.2008 \ elmo.2012 ) |
| Line 70: | Line 62: |
| 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''' |
# 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''' {{{ export 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''' |
| Line 110: | Line 87: |
| 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). |
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 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 (see {{{bvecfile}}} or {{{bveclist}}} below) and the b-value table (see {{{bvalfile}}} 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 [[dmrirc|example configuration file,]] which is 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 table''' You can specify either a different gradient table for each of the scans in the study (with {{{bveclist}}}) or a single gradient table for all scans in the study (with {{{bvecfile}}}). To specify a different gradient table for each of the scans in the study: {{{ set bveclist = ( /path/to/elmo.2005/bvecs.txt \ /path/to/elmo.2008/bvecs.txt \ /path/to/elmo.2012/bvecs.txt ) }}} To specify a single gradient table for all scans in the study: {{{ set bvecfile = /path/to/bvecs.txt }}} Use either one of these variables to specify the location of the gradient table(s), if your DWI data is not in Siemens DICOM format. (The tutorial data is in Siemens DICOM format, so this step is not required.) A gradient table must be saved in a simple text file either in three-column format (one row for each volume in the DWI series) or in three-row format (one column for each volume in the DWI series). An example is shown below: |
| Line 174: | Line 159: |
| 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''' |
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 text file, one value 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 190: | Line 189: |
| 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 dorotvecs = 1 }}} 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 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 rotated to match eddy-current compensation''' {{{ set dorotbvecs = 1 }}} Use this variable to specify if the vectors in the diffusion-encoding gradient table will be rotated to match the rotations applied to the corresponding images by the eddy-current compensation. This is recommended if eddy-current compensation is performed. ---- '''Step 12: Specify if an anatomical brain mask will be used''' {{{ set usemaskanat = 1 }}} Use this variable to specify if the T1-weighted scan will be used to extract the brain mask instead of the DWI scan. If this is set to 1, which is the default, the brain mask will be obtained by dilating the aparc+aseg.mgz from the !FreeSurfer segmentation and then mapping it to DWI space. To use a mask derived by thresholding the DWI scan instead, set this to 0. ---- '''Step 13: Set the threshold for DWI-based brain mask extraction''' |
| Line 202: | Line 213: |
| 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: |
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 (see {{{usemaskanat}}} above). ---- '''Step 14: Specify the intra-subject registration method''' 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: |
| Line 216: | Line 225: |
| 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: |
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). ---- '''Step 15: 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 [[mri_cvs_register|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: |
| Line 223: | Line 236: |
| }}} Setting the path of the MNI template, this is the default: |
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: |
| Line 228: | Line 245: |
| ---- '''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 }}} |
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 16: 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 17: 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. |
| Line 274: | Line 297: |
| [[FsTutorial/Diffusion|Top]] | [[FsTutorial/Diffusion|Previous]] | [[FsTutorial/RunningTracula|Next]] | [[FsTutorial|Top]] | [[FsTutorial/RunningTracula|Next]] |
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 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 (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 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:
<source_freesurfer> export TUTORIAL_DATA=<path_to_your_tutorial_data> export SUBJECTS_DIR=$TUTORIAL_DATA/diffusion_recons cd $TUTORIAL_DATA/diffusion_tutorial
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: MAKE SURE YOU HAVE DOWNLOADED THE LATEST UPDATE OF TRACULA FROM HERE BEFORE DOING THIS TUTORIAL!
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). 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 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
#
export 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
export 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 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 (see bvecfile or bveclist below) and the b-value table (see bvalfile 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 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 table
You can specify either a different gradient table for each of the scans in the study (with bveclist) or a single gradient table for all scans in the study (with bvecfile).
To specify a different gradient table for each of the scans in the study:
set bveclist = ( /path/to/elmo.2005/bvecs.txt \
/path/to/elmo.2008/bvecs.txt \
/path/to/elmo.2012/bvecs.txt )To specify a single gradient table for all scans in the study:
set bvecfile = /path/to/bvecs.txt
Use either one of these variables to specify the location of the gradient table(s), if your DWI data is not in Siemens DICOM format. (The tutorial data is in Siemens DICOM format, so this step is not required.)
A gradient table must be saved in a simple text file either in three-column format (one row for each volume in the DWI series) or in three-row format (one column 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 text file, one value 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 rotated to match eddy-current compensation
set dorotbvecs = 1
Use this variable to specify if the vectors in the diffusion-encoding gradient table will be rotated to match the rotations applied to the corresponding images by the eddy-current compensation. This is recommended if eddy-current compensation is performed.
Step 12: Specify if an anatomical brain mask will be used
set usemaskanat = 1
Use this variable to specify if the T1-weighted scan will be used to extract the brain mask instead of the DWI scan. If this is set to 1, which is the default, the brain mask will be obtained by dilating the aparc+aseg.mgz from the FreeSurfer segmentation and then mapping it to DWI space. To use a mask derived by thresholding the DWI scan instead, set this to 0.
Step 13: Set the threshold for 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 (see usemaskanat above).
Step 14: Specify the intra-subject registration method
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).
Step 15: 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 16: 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 17: 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.
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.