## page was renamed from FsTutorial/Tracula_tktools ## page was renamed from FsTutorial/Tracula ## page was renamed from FsTutorial/Tracula [[Tutorials|Back to list of all tutorials]] | [[FsTutorial|Back to course page]] | [[FsTutorial/RunningTracula|Next]] <> = TRACULA tutorial = This tutorial will take you through the steps necessary to run TRACULA ('''TRA'''cts '''C'''onstrained by '''U'''nder'''L'''ying '''A'''natomy). 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/tracula_tutorial/fs cd $TUTORIAL_DATA/tracula_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 are 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 [[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: If you are '''NOT''' taking one of the formally organized courses, then to follow this exercise exactly be sure you've downloaded the [[https://surfer.nmr.mgh.harvard.edu/pub/data/tracula_tutorial.tar.gz|TRACULA 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= export SUBJECTS_DIR=$TUTORIAL_DATA/tracula_tutorial/fs cd $TUTORIAL_DATA/tracula_tutorial ## tcsh setenv FREESURFER_HOME /path/to/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.csh setenv TUTORIAL_DATA setenv SUBJECTS_DIR $TUTORIAL_DATA/tracula_tutorial/fs cd $TUTORIAL_DATA/tracula_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:''' Please make sure that you have [[Tracula/#Updates|the latest version of TRACULA,]] before running this tutorial. -------- == Setting up a configuration file == If your data are organized according to the BIDS standard, you can run [[dmri_bids_config]] to generate the TRACULA configuration file automatically (see '''step 1a''' below). Otherwise, you will have to create the TRACULA configuration file yourself (see '''step 1b''' below). Example configuration files for TRACULA are included in the !FreeSurfer distribution at {{{$FREESURFER_HOME/bin/dmrirc*example}}} and are 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 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 1a: Create a configuration file (if your data are in BIDS format).''' Run the following command, specifying the top-level location of your BIDS-formatted dataset (here, {{{$TUTORIAL_DATA/tracula_tutorial/bids}}}) and the name of the configuration file that will be created (here, {{{dmrirc.tutorial}}}): {{{ dmri_bids_config --in $TUTORIAL_DATA/tracula_tutorial/bids --c dmrirc.tutorial }}} You can skip the following steps and move on to the next page in the tutorial, or keep reading if you want to know how to modify the configuration file to change any of the analysis options. '''Step 1b: Create a configuration file (if your data are not in BIDS format).''' The configuration file is a simple text file, so you can create it or modify 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/tracula_tutorial/dmrirc.tutorial & }}} '''NOTE: on Macs, run the following command:''' {{{ open -e $TUTORIAL_DATA/tracula_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/tracula_tutorial/fs # Output directory where trac-all results will be saved # set dtroot = ($TUTORIAL_DATA/tracula_tutorial/trc) # Subject IDs # set subjlist = (sub-BANDA001 sub-BANDA001 sub-BANDA002 sub-BANDA002) # Input DWI volumes (file names relative to dcmroot) # set dcmroot = ($TUTORIAL_DATA/tracula_tutorial/bids) set dcmlist = (sub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.nii.gz sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.nii.gz) # Input gradient tables (file names relative to dcmroot) # set bveclist = (sub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.bvec sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.bvec) # Input b-value tables (file names relative to dcmroot) # set bvallist = (sub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.bval sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.bval sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.bval sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.bval) }}} This is what a basic configuration file, that contains only the absolutely necessary inputs, might look like. We will now go through these inputs, as well as some additional ones, one by one. '''NOTE:''' A backslash ('''\''') in a Unix script indicates that the same command continues onto the following line. It can be used as above to make the configuration file (or, indeed, any Unix script) more readable. However, it is optional; you could list all the contents of a variable in a single line instead. If you do use a backslash, it must be the very last character on its line, with no white space or other characters following it. ---- {{{#!wiki caution '''There is no need to run the rest of the commands on this page!''' These commands would go into the configuration file, and are listed and explained here as an example. }}} ---- '''Step 2: Specify the !FreeSurfer subject directory''' {{{ setenv SUBJECTS_DIR $TUTORIAL_DATA/tracula_tutorial/fs }}} 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/tracula_tutorial/trc }}} Use this variable to specify the directory where the TRACULA outputs for all subjects will be saved. You can skip this line, in which case the TRACULA outputs will be saved under {{{$SUBJECTS_DIR}}}, together with the outputs of {{{recon-all}}}. ---- '''Step 4: Specify the list of subject IDs''' {{{ set subjlist = (sub-BANDA001 sub-BANDA002) }}} 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. If each subject has 1 diffusion scan, then each subject's ID will show up only once here. If each subject has N diffusion scans, then each subject's ID will just show up N times here (in the example config file above, N=2). ---- '''Step 5: Specify the location of the diffusion scans''' {{{ set dcmroot = $TUTORIAL_DATA/tracula_tutorial/bids }}} Use this variable to specify the top-level directory under which the diffusion scans (DICOM or NIfTI files) for all subjects can be found. ---- '''Step 6: Specify the list of input DWIs''' {{{ set dcmlist = (sub-BANDA001/dwi/sub-BANDA001_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_dwi.nii.gz) }}} Use this variable to specify the input DWI volumes. There have to be as many scans here as entries in the {{{subjlist}}} above. 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 (e.g., NIfTI, or any format that can be read by [[mri_convert]]), you would still specify them here. If your input DWIs are DICOM files, and 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. If your input DWIs are in another format (e.g., NIfTI) or in a non-standard DICOM format, 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 [[dmrirc|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 a subset of scans to analyze''' {{{ set runlist = (3 4) }}} 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 third and fourth scan (assuming there are at least 4 scans listed in the config file). 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 scans listed in the config file. ---- '''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 = (sub-BANDA001/dwi/sub-BANDA001_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_dwi.bvec) }}} 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. The paths specified here are either relative paths with respect to the '''dcmroot''' directory, if the latter is specified, or absolute paths otherwise. If you are using this, there have to be as many files listed here as entries in the {{{subjlist}}} above. 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 = (sub-BANDA001/dwi/sub-BANDA001_dwi.bval sub-BANDA002/dwi/sub-BANDA002_dwi.bval) }}} 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. The paths specified here are either relative paths with respect to the '''dcmroot''' directory, if the latter is specified, or absolute paths otherwise. If you are using this, there have to be as many files listed here as entries in the {{{subjlist}}} above. 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) The paths specified here are either relative paths with respect to the '''dcmroot''' directory, if the latter is specified, or absolute paths otherwise. '''To use reverse-polarity images:''' {{{ set dob0 = 2 set subjlist = (sub-BANDA001 sub-BANDA001 sub-BANDA002 sub-BANDA002) set dcmlist = (sub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.nii.gz sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.nii.gz sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.nii.gz) set bveclist = (ssub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.bvec sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.bvec sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.bvec) set bvallist = (ssub-BANDA001/dwi/sub-BANDA001_run-dir98_AP_dwi.bval sub-BANDA001/dwi/sub-BANDA001_run-dir98_PA_dwi.bval sub-BANDA002/dwi/sub-BANDA002_run-dir98_AP_dwi.bval sub-BANDA002/dwi/sub-BANDA002_run-dir98_PA_dwi.bval) set pedir = (AP PA AP PA) set echospacing = 0.35 set epifactor = 140 }}} This option calls FSL's [[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup|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}}} ({{{...dir98_AP_dwi.nii.gz}}} and {{{...dir98_PA_dwi.nii.gz}}}). 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 [[dmrirc#Example3.3ACross-sectionalstudy.2Cmultiplediffusionscanspersession|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 [[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. ---- '''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 [[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 in the configuration file, 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). The default is option 3 ({{{bbregister}}}). For additional configuration options related to the intra-subject registration method, such as the degrees of freedom and the maximum rotation angle, see [[dmrirc|the example configuration files]]. ---- '''Step 13: Specify the inter-subject registration method''' The inter-subject registration (from each subject to a common space) can be done either with affine or with nonlinear methods. Although TRACULA performs tractography in each subject's own native diffusion space, this inter-subject registration is needed to map the individual to the manually annotated training set of streamlines that TRACULA's anatomical priors are derived from. Note that the prior information extracted from this training set is not the exact coordinates of the tracts the common space, 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 space 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. To specify the inter-subject registration method in the configuration file, use the {{{interreg}}} variable: {{{ set interreg = 5 }}} The options are {{{1}}} (affine registration from the individual T1 to the MNI T1 template with {{{FLIRT}}} and a correlation ratio cost), {{{2}}} (affine registration from the individual T1 to the MNI T1 template with {{{FLIRT}}} and a mutual information cost), {{{3}}} (affine registration from the individual T1 to a custom T1 template with [[mri_robust_register|mri_robust_register]] and a robust cost), {{{4}}} (nonlinear registration from the individual T1 to the cvs_avg35 T1 template with [[mri_cvs_register|CVS]]), or {{{5}}} (nonlinear registration from the individual FA map to a custom FA template with symmetric normalization from [[http://picsl.upenn.edu/software/ants/|ANTs]]). The default is option 5 ({{{ANTs}}}). For additional configuration options related to the inter-subject registration method, such as the path to the template, see [[dmrirc|the example configuration files]]. ---- '''Step 14: Specify which white-matter pathways to reconstruct''' To specify which of the 42 pathways included in the TRACULA [[https://dmri.mgh.harvard.edu/tract-atlas|tract atlas]] to reconstruct, use the {{{pathlist}}} variable: {{{ set pathlist = ( lh.uf rh.uf cc.rostrum ) }}} The default is to reconstruct the [[https://dmri.mgh.harvard.edu/tract-atlas|full set of 42 pathways]]. The abbreviated names for these pathways, as they should be specified in {{{pathlist}}}, are given in the first column of {{{$FREESURFER_HOME/trctrain/hcp/pathlist.txt}}}. ---- '''Step 15: Specify the number of path control points''' {{{ set ncpts = ( 7 7 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 numbers of controls points have been chosen to be proportional to the length of each pathway, and are given in the last column of {{{$FREESURFER_HOME/trctrain/hcp/pathlist.txt}}}. TRACULA runs a random sampling algorithm, which perturbs these control points repeatedly to draw samples from the underlying probability distribution of the pathway. The exact number of sample paths to draw can be specified in the configuration file using the {{{nsamples}}} variable (the default is 7500). Sample paths are retained if they fit both the diffusion data and the anatomical neighborhood priors well, and rejected otherwise. The accepted paths are added up to give the heat map that you see when you view {{{path.pd.nii.gz}}} (pd = probability distribution), as desribed later in this tutorial. ---- 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 necessary input files for processing * Set additional options depending on the specifics of your analysis [[Tutorials|Back to list of all tutorials]] | [[FsTutorial|Back to course page]] | [[FsTutorial/RunningTracula|Next]]