Troubleshooting your output

This set of exercises will take you through a few examples of problem outputs, asking you to identify the problems and possible methods to fix the problems. Each example will have a before and after picture, as well as an explanation of how to fix the problems seen.

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/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.

Editing a Recon

Below, we ask you to look at several subjects with various errors that require manual intervention. Open each subject and try to identify the problem on your own. For each subject, there is a link to instructions on how to fix the problem. While you are trying to identify the problems with the subjects listed below you may find it helpful to refer back to the previous exercise, or open your own instance of the subject good_output to compare these subjects to a good example.

Edits to the wm volume

Now, take a look at the next subject, wm1_edits_before.

freeview -v wm1_edits_before/mri/wm.mgz:colormap=heat:opacity=0.4 wm1_edits_before/mri/brainmask.mgz  -f wm1_edits_before/surf/lh.white:edgecolor=blue wm1_edits_before/surf/lh.pial:edgecolor=red wm1_edits_before/surf/rh.white:edgecolor=blue wm1_edits_before/surf/rh.pial:edgecolor=red 

Again, this will bring up the brainmask.mgz volume, the wm.mgz volume, and the surfaces for both hemispheres.

Click in the main viewing area and use Alt-C or the arrows to flip between the wm.mgz and brainmask.mgz on top of each other.

with the wm.mgz loaded on top of the brainmask.mgz volume, it should look like this:

In your second and third terminal window, if not already open, open the surfaces in tksurfer:

tksurfer wm1_edits_before lh inflated  

tksurfer wm1_edits_before rh inflated 

This will open the inflated surfaces for both hemispheres in tksurfer.

The trouble with this subject has occurred during the white matter segmentation step. Check the surfaces in the T1 volume to find the spot that does not match the actual gray/white boundary. If you load the wm.mgz volume as the aux volume you will see a hole in this area. If you are looking in tksurfer you will see a hole or dimple in the inflated surface. You can use the "save point" "goto point" commands to find this spot in the volume.

Using the Page Up and Page Down keys, you can scroll towards the anterior portion of the brain until you find an area in the right hemisphere where the white surface (blue line) does not follow the surface of the brain, but in fact cuts into it. This geometric innacuracy is cause by a lesion where the white matter has been marked as non-white matter.

use Alt-C to have the wm.mgz volume loaded on top and you can see that this area has been left out of the wm volume completely.

You can see this as a dimple or hole on the inflated surface in tksurfer too (see next image). If not already open, in a second terminal window, open the rh surface in tksurfer and you can see the dimple or hole on the medial side:

tksurfer wm1_edits_before rh inflated 

To fix this problem you will need to fill in the missing voxels in the wm.mgz volume. First, it's a good idea to use the page up and down keys to scroll through the individual slices in the volume until you get a good idea of where the problem starts and ends. You will want to start filling in voxels when the inaccuracy appears, and keep filling them in slice by slice until the problem is no longer visible. The coronal view and a brush radius of one or two are good settings for painting in voxels. Zoom In and Out either by using the scroll button on your mouse or holding down shift and the up or down keys.

To begin editing voxels, make sure the wm.mgz is highlighted in the volume menu, and on top on the brainmask.mgz. click on the edit voxels option ( ) and enter 255 into the brush value box. your menu should look like this:

Remember: the wm.mgz must be on top and and the brush value 255 in order to edit voxels in the wm.mgz, if it is not visible on top you will be editing the brainmask.mgz. You should only be editing the brainmask for pial edits and not wm edits.

In the Voxel edit menu that pops up, click on the first icon "freehand" and select a Brush size of 1 or 2. Make sure the Reference is the wm volume. This menu should look like this:

You are now ready to edit. click back on the volume, and using your left mouse button fill in the wm hole with voxels. If you fill in too many, you can press shift while using your left mouse button to erase voxels. You can keep flipping back between the brainmask and the wm volume using your Alt-C combination if you want to check that what you are filling in is indeed white matter. At any time you can use the CTRL-Z combination to undo as many actions as you like. When you're done editing the volume should look like this.

While filling the hole in slice 160, you will notice that the hole is not completely enclosed. To see where the boundary should be, switch back and forth between the brainmask.mgz and wm.mgz volume with Alt-C. Use the brainmask.mgz volume as a guide, and make the boundary of the voxels that you paint in correspond as closely as possible to the boundaries suggested in the brain volume. Go to the next slice, and fill in this slice in the same way. You will need to continue filling in slices in this fashion until the region is completely filled in. If you would like to compare your edits to ones that have been done for you you can open a second freeview window with the wm1_edits_after wm.mgz volume, and for each slice check your results with the corresponding slice in the wm1_edits_after volume. At any time, you can save the changes you've made by clicking on the wm.mgz, making sure it is highlighted in the menu to the left side of the viewing area and click the save volume button or save in the file menu. You can verify your results by viewing the changes made to the wm1_edits_after wm.mgz volume

To view this corrected subject (which was corrected by following the detailed instructions provided to you):

freeview -v wm1_edits_after/mri/wm.mgz:colormap=heat:opacity=0.4 wm1_edits_after/mri/brainmask.mgz  -f wm1_edits_after/surf/lh.white:edgecolor=blue wm1_edits_after/surf/lh.pial:edgecolor=red wm1_edits_after/surf/rh.white:edgecolor=blue wm1_edits_after/surf/rh.pial:edgecolor=red 

Tips:

• Sometimes regions may appear enclosed in some slices (i.e. appear as holes), open in subsequent slices (i.e. no longer appear as holes), then enclosed again as you scroll forward. The rule of thumb when editing these is to keep filling until you reach the slice where they finally open up and are no longer enclosed.
• When editing geometric inaccuracies in the future, you may find it easier to edit the first slice and last slice first, thereby 'capping' the slices that need filling. Then you just need to fill all the slices between the endcaps.
• Sometimes there is variation between a subject's left and right hemispheres, so that in a particular slice one hemisphere's region will finally 'open up', but the other hemisphere's region is still enclosed. In such cases, continue to fill the enclosed region only, even though the other is open. This will address the topological problem.
• Problems like the one shown here, due to brain lesions, should always be fixed with edits to the wm.mgz volume. Do not use control points to try and automatically adjust the intensity in these areas.

After you have saved all of your edits, you could recreate the final surfaces with the command:

recon-all -autorecon2-wm -subjid wm1_edits_before

Do not run this command if you are conducting the tutorial! This step will take a long time and there is no need to run it for the tutorial purposes.

Non-white matter classified as white matter

Sometimes non-white matter (i.e., skull) is included as white matter. To load in the example use this command:

freeview -v wm2_edits_before/mri/wm.mgz:colormap=heat:opacity=0.4 wm2_edits_before/mri/brainmask.mgz -f wm2_edits_before/surf/lh.white:edgecolor=blue wm2_edits_before/surf/lh.pial:edgecolor=red wm2_edits_before/surf/rh.white:edgecolor=blue wm2_edits_before/surf/rh.pial:edgecolor=red

Scroll through the brainmask.mgz volume slices and as you go posterior you will see a group of voxels included as white matter, around slice 150. They are surrounded by the white surface (blue line). This group lies outside of the pial surface (red line) and is clearly not white matter. In order to correct this inaccuracy it is necessary to delete the voxels which are not part of the white matter.

Flipping back and forth between the wm.mgz and the brainmask.mgz you can clearly see that this region should not be labeled as white matter. Click the edit voxels tool again and double check wm as the reference and that the wm.mgz is on top and highlighted. Then hold down your shift key as you deleted the voxels you want. This is what it should look like after you have deleted the errant voxels. When you are done, Click on the wm.mgz, make sure it is highlighted in the menu to the left side of the viewing area and click the save volume button or save in the file menu.

Once you have made all the edits to the wm.mgz volume you would regenerate the surfaces using the following command:

recon-all -autorecon2-wm -autorecon3 -subjid wm2_edits_before

Do not run this command if you are conducting the tutorial! This step will take a long time and there is no need to run it for the tutorial purposes.

To view this corrected subject (which was corrected by following the detailed instructions provided to you):

freeview -v wm1_edits_after/mri/wm.mgz:colormap=heat:opacity=0.4 wm1_edits_after/mri/brainmask.mgz  -f wm1_edits_after/surf/lh.white:edgecolor=blue wm1_edits_after/surf/lh.pial:edgecolor=red wm1_edits_after/surf/rh.white:edgecolor=blue wm1_edits_after/surf/rh.pial:edgecolor=red 

Correcting Pial Surfaces

• 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.

The pial surface is created by expanding the white matter surface so that it closely follows the gray-CSF intensity gradient as found in the brainmask.mgz volume. Once an accurate white surface is created then you can work on correcting the pial surface if needed. The pial surface boundary and white matter surface boundary should not cross. After the pial surface has been generated, it's a good idea to visually check it for defects that may have been created during automatic topology fixing. To check the pial surface, it may be loaded into tkmedit and viewed along with the brainmask.mgz volume. If the surface appears not to follow the gray-CSF boundary in the volume, edits may be required.

Editing the Volume

Subject pial_edits_before is an example of the pial surface including non-cortex within the boundaries. This page will take you through fixing this and other similar problems with the pial surface including non-cortex material.

First, make sure you have pial_edits_before loaded in freeview:

 freeview -v pial_edits_before/mri/brainmask.mgz  -f pial_edits_before/surf/lh.white:edgecolor=yellow pial_edits_before/surf/lh.pial:edgecolor=red pial_edits_before/surf/rh.white:edgecolor=yellow pial_edits_before/surf/rh.pial:edgecolor=red 

Use the page up and down keys to go through the volume slice by slice, and view the pial surface (red line) and white matter surface (yellow line). Notice the bright diagonal line in slice 157 that has caused the pial surface to expand past the actual pial boundary. This is the result of a bad segmentation incorporating a piece of the dura within the pial surface.

To fix this type of error you can simply edit away the offending voxels from the brainmask.mgz volume. To do this you will need to select the edit voxels tool and set the brush to a size and shape comfortable for you. A circle brush of radius 2 works well for this edit. Then you can simply use the shift key and your mouse button to erase the voxels in the brainmask.mgz, or you can set the brush value to 0 and simple draw over the voxels you want to disappear. At any time you can use the CTRL-Z combination to undo as many actions as you like.

Find a place in the image where the dura is causing errors in the segmentation. Use the right mouse button to delete the voxels. It is not necessary to completely remove the dura to get an adequate pial surface, but it is good to do so until you are more familiar with manual editing. When you are finished removing the bright diagonal line in slice 157, it should look like this:

Continue on the other slices until the dura is removed.