Inspection of Freesurfer Output
In this exercise you will visualize and inspect correctly processed output data so that you can become familiar with what the end product should look like. The exercise will take you through a variety of output, but is not necessarily the recommended procedure to take when trying to verify each subject. Some outputs are only necessary to check when there are problems or for a particular type of study. However it is a good idea for new users to become familiar with what the expected output should look like and how to view it.
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/buckner_data/tutorial_subjs cd $SUBJECTS_DIR
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 $TUTORIAL_DATA/buckner_data/tutorial_subjs cd $SUBJECTS_DIR
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.
Viewing Volumes with Tkmedit
Output volumes can be loaded into tkmedit, along with surface outlines and the subcortical segmentation. With one command line, you can load in the brainmask.mgz and wm.mgz volumes, the rh.white and lh.white surfaces (outlines), and the subcortical segmentation. Copy and paste the command below inside the terminal window:
tkmedit good_output brainmask.mgz \ -aux T1.mgz -surfs -aseg
Some notes on the above command line:
- good_output : name of subject
- brainmask.mgz : skull-stripped volume primarily used for troubleshooting (found in $SUBJECTS_DIR/good_output/mri).
- -aux T1.mgz : pre-skull-stripped volume loaded as 2nd volume (in $SUBJECTS_DIR/good_output/mri)
- -surfs : loads all surfaces (orig, white, and pial, for left and right hemispheres)
- -aseg : loads automatic volume segmentation called aseg.mgz
You should see a tkmedit window open:
(use the zoom and move buttons to match the snapshot below)
You are currently looking at the brainmask.mgz with the surfaces displayed and the aseg.mgz (subcortical segmentation) overlayed. The pial (red line), and white (yellow line) surfaces are shown. You can toggle between the brainmask.mgz (loaded as the "main" volume) and the T1.mgz (loaded as the "auxiliary" or 2nd volume) with buttons and . As you switch between these two buttons, notice that at the top of the display window, the asterisks (**) surround the name of the volume you are currently looking at.
Keyboard Shortcut: Alt-c will allow you to quickly switch back and forth between the two volumes instead of clicking between these buttons.
If you hover your mouse over a button in the Tkmedit Tools window, a pop-up will tell you what it does and its keyboard shortcut. When the Navigation button is chosen, you can drag the brain around in the display window. Try it out. Notice how you are not able to move around the cursor (the little red cross-hair).
- To change the location of the cursor, choose any button to the right of the Navigation button and then left-click in the display window. Notice the cursor move to wherever you click. When you zoom, it will zoom into the location of the cursor. When you change brain orientation (to axial or sagittal), you will be viewing the slice where the cursor was located in that plane.
To change which brain slice you are viewing, you can use the + or - buttons next to where it says "Slice".
Keyboard Shortcut: Use the Up or Down arrows on your keyboard to change slices faster (this will only work when the Display window is selected and not on the Tools window).
Now that you know the basics, you can make your way through the data. To verify that FreeSurfer did a good job, you will want to check:
- Whether the surfaces accurately follow the gray matter and white matter boundaries.
- Whether the aseg accurately follows the subcortical intensity boundaries.
Checking the Surfaces
Toggle to the brainmask volume, if not already in view, by using the button or Alt-c. The white surface (yellow line) is used to calculate total white matter volume and should accurately follow the boundary between white matter and gray matter. The pial surface is used to calculate cortical gray matter volume and should accurately follow the boundary between the gray matter and the CSF.
Tip: It may be easier to concentrate on the surfaces if you toggle off the aseg with the button.
Keyboard Shortcut: Ctrl-g will also turn off the aseg.
As you scroll through the slices checking the surfaces, keep in mind that you are looking at a 2-dimensional rendering of a 3-dimensional image - be sure to look at more than just one view (i.e., sagittal, coronal and horizontal). To check your surfaces, toggle them off and on with for the pial surface and for the white surface. Would you draw the boundary in the same location? Adjust the brightness and contrast so you can see the shift in intensity between gray and white. You can do this by going to View > Configure > Brightness/Contrast in the Tkmedit Tools window and then moving the sliders to adjust the levels.
Keyboard Shortcuts: You can also use Ctrl-p and Cltr-m to turn on and off the pial and white surfaces.
- If the Tkmedit Tools window is highlighted, Ctrl+b will open the Brightness/Contrast window. Alternatively, you can hold down the shift button and drag the left mouse button in the display window and this will change the brightness/contrast without using the sliders.
There are regions where the surfaces are not intended to be accurate that you should be aware of:
- Areas around the hippocampus and amygdala. The surfaces will not completely include or exclude certain subcortical regions. These inaccuracies can be ignored as subcortical regions are excluded from the cortical measures and subcortical volume is measured by the aseg, not the surfaces.
- For an example of this, see coronal slice 137 (enter 137 into the box next to where it says "Slice" and hit enter).
- Along the midline cut, it is possible to see some overlapping of the surfaces from one hemisphere to another. The medial wall is not included in the cortical measures so this can generally be ignored.
Toggle on the subcortical segmentation with the button or Ctrl-g. This will show the complete segmentation of the subcortical structures. Each structure is labeled with a unique color/number distinction. If you click on a voxel the structures name and number label will be shown in the Tkmedit Tools window (under where it says "Cursor"). Toggle the aseg on and off to make sure the aseg is accurately following the underlying intensity boundaries of each structure. Scrolling through the slices you will be able to see that everything is labeled, and done so accurately. Sometimes it is easier to see the structures and their boundaries looking in either the sagittal or horizontal view, so be sure to check around in all of them. If you hold down the Ctrl button and left click on the button, a window will pop up that will allow you to adjust the segmentation opacity.
Other Things To Do in Tkmedit
Below, we introduce you to other volumes and techniques which are good to be familiar with, especially when troubleshooting.
To load the aparc+aseg segmentation you can go to File > Load Segmentation and browse to the aparc+aseg.mgz. Hit OK once you have selected the file and then OK again in the Load Segmentation window. When loaded, it will look like this:
This segmentation shows the same subcortical structures that are labeled in the aseg.mgz, but also displays the cortical parcellation labels in the volume (later we will look at the labels on the surface). Click around the cortex to see the name of each cortical region in the Tools window. The aparc+aseg.mgz uses the Desikan-Killiany atlas. To see the Destrieux atlas, you would load the aparc.a2009s+aseg.mgz
Turn off the segmentation (Ctrl-g) and scroll through the brainmask volume. Notice that there is no skull left in your image. Notice also that the cerebellum is still included in the volume. You should not see any large areas of skull left behind, or any areas of cortex or cerebellum removed from this volume. You can toggle between the brainmask.mgz volume and the non-skull-stripped, T1.mgz volume using Alt-c to ensure that the skullstrip has worked properly. In the TroubleshootingData tutorial, we'll go over what to do if there was a skull strip error.
Scroll through the brainmask volume and notice that the intensity is all uniform. You should not see any very bright or very dark spots in the white matter or gray matter. If you click on a voxel in the white matter, you can see that it has been normalized to an intensity of (or very close to) 110 in the Tkmedit Tools Window (under Cursor, next to where it says "brainmask.mgz val"). When wm voxels are not close to 110, they may be erroneously excluded from the white surface. In the TroubleshootingData tutorial, we'll go over what to do if there was an intensity normalization error.
To check the wm volume you should load it in as a new aux volume. To do this go to File > Aux Volume > Load Aux Volume and browse to wm.mgz. This should open:
This volume is FreeSurfer's initial segmentation of the white matter (shown in shades of gray) with additions from the automatic topology fixer (in white). This "mask" is the starting point for the white surface which grows out from here and stops at a more accurate location along the wm/gm boundary using the intensity gradients in the brainmask.mgz volume as a guide. The wm.mgz can be used to add missing wm voxels or delete voxels that are not wm but were included in the surface. In the TroubleshootingData tutorial, we'll go over what to do if there was a wm segmentation error.
You can now close Tkmedit by hitting the X on the display window. You can also use Ctrl-q to close it.
Viewing Surfaces with Tksurfer
Now that you've checked out everything in the volume using tkmedit, you can close it and begin to inspect your data on the surface. For this, you will use tksurfer. Tksurfer displays one hemisphere at a time. This exercise will go through visualizing things on the left hemisphere only, but everything works the same on the right hemisphere (except in the Tksurfer command, you would specify rh instead of lh).
Here are the things you can look at with tksurfer:
- pial, white and inflated surface
- sulc and curv curvature files
- thickness maps
- cortical parcellation
To open Tksurfer with the left hemisphere inflated surface of your subject, open a new terminal window, then use the following command:
setenv SUBJECTS_DIR $TUTORIAL_DATA/buckner_data/tutorial_subjs cd $SUBJECTS_DIR tksurfer good_output lh inflated
You should see a Tksurfer window open up to this:
You are currently looking at the inflated surface. The surface can be rotated using the buttons in the navigation toolbar: . Use the redraw button to repaint the image if it gets corrupted by window movement.
Mouse Shortcut: Right click in the Tksurfer window to redraw.
The inflated surface is good to look at when checking to see if you need to make edits to the wm.mgz volume. You'll notice as you inspect this surface that it is smooth and free from holes, bumps and other defects. If you click on the surface, you will see the coordinates of the vertex you clicked on in the Tools window under "Cursor". To clear the marks made on the surface after clicking on it, you can go to Edit > Unmark All Vertices.
Keyboard Shortcut: You can unmark one vertex at a time by using Ctrl+Shift+middle click on each. Troubleshooting Tip: If at any point clicking in the Tksurfer window automatically causes you to zoom in, your Ctrl key is stuck. Trying hitting the Ctrl button a few times to get it unstuck.
All surfaces (pial, white, orig) have been loaded as a default along with the inflated surface. You can switch to the pial surface by clicking the button. You should see this:
The pial surface is showing you the outer boundary between the gray matter and CSF (cerebrospinal fluid). This is the same file that was viewed in Tkmedit, just represented as a 3D surface image rather than the red outline on the 2D slices in the brainmask volume. You can inspect this surface by rotating it around as you wish.
Click on the button to view the white surface. This is what the white surface will look like:
The white surface shows the boundary between the white and the gray matter. Again, this is the same file that was viewed in Tkmedit (as the yellow outline) just represented in a 3D manner. You can inspect this surface by rotating it around as you wish.
Curv and Sulc Files
Switch back to viewing the inflated surface of the brain by pushing the button. You can now load in the curvature file, lh.curv, by holding Ctrl and right clicking on the button on the Tksurfer Tools window. The box that pops up will automatically have selected the lh.curv file, so click ok. The curvature file will look like this:
This is showing the slightly smoothed mean curvature. It has the units of 1/mm, and with an outward pointing normal vector field. Negative regions are folded-out and shown in green (gyral), and positive regions are folded-in and shown in red (sulcal)
To view the sulc file you could have changed the dialog box to say lh.sulc when right clicking on the curv button as described above, or you can go to File > Curvature > Load Curvature and browse to the lh.sulc file (found in $TUTORIAL_DATA/buckner_data/tutorial_subjs/good_output/surf/). Be sure you select the curvature file for the correct hemisphere, if you select the wrong one it will not look right. The lh.sulc file will load a slightly different display of green/red values than the lh.curv. These are showing the sulcal depth and again here the red regions are sulcal and the green regions are gyral. You can still view this overlay as you switch to the pial or white surfaces using the and buttons.
To view the thickness maps it is probably best to toggle off the curvature . You can load the thickness map, lh.thickness, by holding Ctrl and right clicking on the Tksurfer Tools window. Browse to the lh.thickness file (you may have to find the subject "good_output" from the list of subjects, then navigate to the surf directory and select lh.thickness). Be sure you select the thickness file for the correct hemisphere, if you select the wrong one it will not look right. The lh.thickness map should open up and look like this:
You can adjust the thresholds of the map by going to View > Configure > Overlay which will open a new window that will allow you to change the thresholds. First click the Thresholds: Linear checkbox. Then try some different settings and see how it affects the display on the map (try a Min of 1.0 and Max of 3.0, Min of 2 and Max of 5, etc). After you change the min and max values be sure to hit Apply to see the changes. If the Apply button is not visible to you, hit the space bar to Apply the changes.
To view the cortical parcellation it is probably best to toggle off the curvature and thickness files (if any are still visible), and to switch to the pial surface, . You can load the parcellation by going to File > Label > Import Annotation and browsing to the lh.aparc.annot file (found in $TUTORIAL_DATA/buckner_data/tutorial_subjs/good_output/label/). Be sure you select the label file for the correct hemisphere, if you select the wrong one it will not look right. The lh.aparc.annot should open up and like this:
Click on a color and view the name of the cortical region in the Tksurfer Tools box. Rotate the brain so you are looking at the medial wall. Notice that all subcortical gray matter is not a part of the surface labels (because again, those areas do not count towards the cortical surface measures). You can also switch to the inflated view and turn the labels to outlines using the button.
The parcellation that is loaded here was created with the Desikan-Killiany atlas. By default there are two parcellations that are made when recon-all is run. The second parcellation, called ?h.aparc.a2009s.annot, is created with the Destrieux atlas. The difference is the number and designation of the areas that are labeled. You can load this second parcellation by first going to File -> Label -> Delete all Labels. This will remove the first parcellation. Then you can repeat the steps for loading a parcellation, this time browsing to lh.aparc.a2009s.annot to load the second parcellation.
Using Tkmedit and Tksurfer together
When you are viewing the same subject in Tkmedit and Tksurfer at the same time you can click on a point on the surface (in tksurfer) and automatically locate the same point in the volume (in tkmedit). To do this, first open a new terminal window so you can open up the same subject in Tkmedit as you have open in Tksurfer:
tkmedit good_output brainmask.mgz \ -aux T1.mgz -surfs -aseg
Click on a location in Tksurfer. Next, click the save point button in the Tksurfer Tools window. This will save the cursor position. Then, in the Tkmedit Tools window, click the "goto saved point" button . This will now bring you to the same point, only in the volume. Look for the new location of the cursor in Tkmedit. If you are having trouble finding it, the red lines on the edges of the Tkmedit display window will indicate which row and column it is located within. You can also click on a point in Tkmedit, save it using the button and opening the same point in Tksurfer using the button.
This technique is very useful when you see something wrong on the surface of a subject (in Tksurfer) and you want to see what is happening in the volume in that same place and vice versa.
When you are done, you can close Tksurfer by going to File > Quit. You can close Tkmedit by hitting the X on the display window or going to File > Quit . You can also do Ctrl-q to quit for both.
This tutorial was meant as an introduction to Tkmedit and Tksurfer. For information on buttons or menu options not covered here, you can find out about them on the Freesurfer Tools wiki.