1. FreeSurfer: Troubleshooting surfer.nmr.mgh.harvard.edu
-talk is about what to do when freesurfer doesn’t do what it was expected to do
-Everything is automated
-But, still have to check results & in some cases manually intervene to fix a problem
-still faster than if had to segment brain yourself

2. Categories of Errors
Hard failures = recon-all quits before it finishes
Soft failures = recon-all finishes but results need modification
Talk will cover the different categories of errors & various types of troubleshooting
Hard failure: Recon-all doesn’t run to the end. Exits with error.
Possible reasons- No UNIX permissions, missing files, wrong path
Soft failure: finishes without errors, but results might not be totally accurate.
Most of talk will focus on the different kinds of soft failures

3. Types of Soft Failures Skull Strip Errors Segmentation Errors
Intensity Normalization Error
Pial Surface Misplacement
If you have good quality data, you won’t usually have all of these
But you should still check your recons
----- Meeting Notes (4/27/15 14:44) -----
remove topological

4. Upon Completion of recon-all…
bert
scripts mri surf label stats
recon-all.log
recon-all.done
If you remember, this is the typical directory structure after running recon- all on subject
Under scripts you have recon-all.log
At end of recon-all you should see a little section saying “recon-all finished without error”
This just means it finished without a hard error
Does not mean that everything okay
You still have to check your recons
Just because it finishes “without error” does not mean that everything is ok!
Could be a “soft” failure. 4

5. Troubleshooting: Hard Failures
bert
scripts mri surf label stats
recon-all.log
recon-all.error
Ran out of disk space?
Ran out of RAM?
Unix file permissions?
Pathological conditions (brain, artifact)
??????
If there is a hard error…will see recon-all exited with errors in log
Also will create .error files
May or may not be obvious to you what the error is
If this happens and you don’t know what the error is, you can send us your log file
We will not know what the error is unless we can see your log file
Could be many things!
Send us recon-all.log 5

6. Hard Failure: What to do
Check recon-all.log for error message
Examine data quality
Rerun step that failed
Verify output from last successful step
Search FreeSurfer mailing list for this problem
Run modified version of command if needed
the mailing list
A list of some things to try when you have a hard failure
When in doubt, the mailing list

7. Hard Failure: Help Us Help You!
Report version currently using
see top of recon-all.log
cat $FREESURFER_HOME/build-stamp.txt
Operating System/hardware
Exact command-line tried to run
Send recon-all.log
Output from terminal window if appropriate
If you do us, remember to send us these things
Helps give us a better idea of your situation

8. Troubleshooting: Soft Failures
recon-all finishes but surfaces or aseg not accurate
It is not possible to directly edit the location of a surface.
When the surfaces are inaccurate, you have to (manually) change the information in a volume and regenerate the surface.
So that was information about the first category of errors- hard failures.
In the second category, soft failures,

9. Check Your Recon for Accuracy
Do your surfaces follow gm/wm borders?
Does the subcortical segmentation follow intensity boundaries?
How do you manually edit? I will get into more specifics, but the basic questions are:

10. Manual Interventions Erase voxels Fill voxels
Clone voxels (ie, copy from one volume to another)
Add “Control Points”
Manual interventions should take less than 30min
After manual intervention, re-run parts of recon-all
4 manual interventions you can make to fix these errors
After you make changes, re-run PARTS will take less time
Just as a reassurance, manual edits should take <30 min
Not that bad!
Might seem overwhelming now
But we will show you some common errors later in the troubleshooting tutorial and how to fix
The more you do it, the faster you will get
Lastly, can adjust parameters to help optimization process, but this is more advanced—should I take this out?
It is also possible to re-run recon-all with different parameters which is good for systematic or large errors

11. Manual Edits Applied to Volumes not Surfaces
bert
scripts mri surf label stats
wm.mgz
Erase
Fill
Clone to
Control Points
brainmask.mgz X
wm.mgz
brainmask.mgz
Again, remember edits applied to vols
Changes in vol will influence surf
Table of four main edits and some volumes you would apply them to
Can erase things, can fill them in, clone,
Vols are in “mri” folder
Use brain.finalsurfs to delete cerebellum from pial surface; norm.mgz to check aseg; T1 to clone from
*Other volumes involved in QA: brain.finalsurfs.mgz, norm.mgz, T1.mgz 11

12. Processing Stream Overview
T1 Weighted
Input
Skull Stripping
Volumetric Labeling
Intensity Normalization
-just remember, changes in your vols affect surfs, and ultimately, your stats!
-T1-weighted (wm brighter than gm)
-If higher res, gets downsampled (1mm isotropic)
-Can’t go lower than 1.5mm^3
Gyral Labeling
White Matter
Segmentation
Surface Atlas
Registration
Surface Extraction
Stats! 12 12

13. Skull Strip Failure: Too Much Removed
T1.mgz
brainmask.mgz
Example of skull strip error
Removed too much, took away cerebellum
Remember, 4 manual interventions you can make
Erase voxels
Fill or add voxels
Clone voxels
Add control points
To fix this, we will clone (or copy) voxels from unskullstripped image (T1), back into skull strip image (brainmask)
Watershed parameters for quicker parameter adjust…try it out!
Why do we care about cerebellum?—aseg uses an atlas that includes cerebellum. It’s going to try to find a way to make it fit.
----- Meeting Notes (4/27/15 14:44) -----
explain error- skull strip-
explain phenomenom of intervention- cloning
below command line
Use “clone” tool to manually correct, or adjust watershed parameters and run (default wsthresh is 25, higher means strip less):
recon-all -skullstrip -wsthresh 35 -clean-bm -no-wsgcaatlas -s <subj>
recon-all -s <subject> -autorecon2 -autorecon3

14. recon-all -s <subject> -autorecon-pial
Skull Strip Failure: Not enough Removed
Dura or blood vessel.
the white surface is OK, but
the pial surface is inaccurate
Another skull strip failure, not enough removed
Very common
Could be dura or blood vessel show up bright right at edge
Dura and gm have similar intensities, so thought it was gm, pushes pial surf out
You can see wm still okay
You edit brainmask.mgz, erase the blood vessel and pial surf will be pulled back and stop where gm ends
----- Meeting Notes (4/27/15 14:44) -----
blood vessel
Dura and GM have extremely similar intensity characteristics on most T1-weighted sequences (but different T2*!). Typical fix: edit the brainmask.mgz to erase dura/blood vessels, and run:
recon-all -s <subject> -autorecon-pial

15. recon-all -s <subject> -autorecon2-wm -autorecon3
Skull Strip Failure: Not Enough Removed
Another time not enough removed
Recon-all saw bright transition, thought it was wm and built surface around it
Affected the pial surf too because pial grows from white!!
You would erase these eyeball voxels in wm mask and brainmask in this case
Delete from both white and pial (wm.mgz and brainmask.mgz)
Eye Socket classified as WM due to Skull Strip Failure.
Erase in wm.mgz then run:
recon-all -s <subject> -autorecon2-wm -autorecon3

16. This is NOT a Skull Strip Error
It appears that the skull strip left a lot of dura. It did, but it does not affect the surface, so leave it!
Other times, you will see that pia or dura is left by skull stripping
This is not a failure!
Check surfaces! Look fine
So leave it, this is one of the ways you can save yourself time
Remember you are editing to make surfs more accurate

17. Segmentation Errors White Matter classified as non-White Matter
Gray Matter classified as White Matter
Causes:
Intensity Normalization Failures
Partial voluming
The second class of errors are segmentation errors
Two types—gm as wm and wm as non-white
Basically error in wm segmentation
Causes—will become clear as we go along

18. recon-all -s <subject> -autorecon2-wm -autorecon3
Segmentation Error
wm.mgz
“Hypo-Intensities”
White Matter Lesions
Misclassified as gray matter
In this case, we have wm classified as non-wm
Wm lesion, lower intensity
Draws surface around it.
Go into wm.mgz, and there will be a hole in the mask. Fill it in to say no this is really wm
Wm.mgz is just everything inside of the cortical surface…includes subcort too…not actually saying it is wm.
----- Meeting Notes (4/27/15 14:44) -----
hard to see actual lesion. not going crazy.
Fill in wm.mgz then run:
recon-all -s <subject> -autorecon2-wm -autorecon3

19. Is this a segmentation error?
How do we know if something is a segmentation error?
Looks like a hole
Coronal View

20. This is NOT an an error. Sagittal View Coronal View Axial View
But you need to check all three dimensions
This slice coronal is cutting off the end of this gyrus
If you check the other two views you can see that yes, this is correct
This will happen often
Check all 3 views and scroll in each
Often times will open up into rest of gyrus, or you will see it disappear.
If a random hole pops up on one slice and is gone the next, that is an error!
----- Meeting Notes (4/27/15 14:44) -----
loaf of bread metaphor- gyrus like heel of loaf
Axial View
Make sure to look at all 3 views before deciding!

21. Intensity Bias Left side of the image much brighter than right side
Two classes of soft failures so far- Brainmask errors (skull strip) and Segmentation errors (which we just covered)
Third is intensity bias error
Intensity = brightness of voxel – ideally only indicative of the MR params of the tissue (PD, T2, T1).
GM = dark, WM = bright.
Bias error: changes in intensity across space that are unrelated to biology. i.e. tissue gets further away from receive coil, gets darker in intensity. brain areas closer to coil are brighter than others,
Hard to see with human eye, right demonstrates map of intensity bias. Want to make it uniform.
FreeSurfer tries to estimate the bias and remove it
----- Meeting Notes (4/27/15 14:44) -----
gray matter on left is same intensity as wm on right.
Left side of the image much brighter than right side
Worse with many coils
Makes gray/white segmentation difficult 21

22. Intensity Normalization
Removes B0 and B1 bias
Most WM = 110 intensity
Pre- and Post-Skull Strip
bert
mri
orig_nu.mgz
T1.mgz
nu.mgz
norm.mgz
brain.mgz
110.9
If there are places with bias, makes it hard to segment wm from gm
FS finds high probability of voxel being wm, and then if its not 110, estimates the bias and tries to remove it
B0 is from scanner
B1 is from coil
The B1 bias field is estimated by measuring the variation in the white matter intensity. The main body of the white matter is used to estimate the field across the entire volume. The intensity at each voxel is then divided by the estimated bias field at that location in order to remove the effect of the bias field.
T1 – adjust intensity so that wm is around 110
Makes wm more uniform; segment easier and generate wm surface
----- Meeting Notes (4/27/15 14:44) -----
when vary from 110, when problems arise
93.9
110.0
Before Normalization
After Normalization

23. recon-all -s <subject> -autorecon2-cp -autorecon3
Troubleshooting: Intensity Normalization + + +
Temporal lobes are an area that usually has errors due to norm failures because the signal intensity isn’t good
Wm looks darker here, so surfs don’t go all the way out
Check wm.mgz and look at intensities
Can use control points to fix, put them in areas where not 110, but it is definitely wm (partial voluming)
Cps affect area around them so use sparingly
(NOTE-Change snapshot to show freeview control points which are dots)
In freeview, control points are dots, not crosshairs
Intensity Normalization Failure. Most WM in T1 volume (T1.mgz) should be close to 110. Can fix by editing wm.mgz or adding “Control Points” (+). Beware partial voluming!
recon-all -s <subject> -autorecon2-cp -autorecon3

24. Control Points: Summary+
Used to rescale intensity near the control point
Must go in voxels that are fully WM but not 110 !!!
Use sparingly
Can be created viewing any volume
Saved in a separate text file (e.g., bert/tmp/control.dat)
Here is a summary about using control points that is good to reference
Doesn’t matter what is highlighted when you place them…not associated with a volume
Just a point in space
Make sure you follow tutorials on how and where to save them

25. Noncortical Regions: These are not errors
Amygdala, Putamen, Hippocampus, Caudate, Ventricles, CC
Touched on this slide in jargon talk, but very important!
Surfaces near the medial wall and around subcort aren’t accurate but that is OK
not included in any cortical measures. Filled in to create continuous surface for each hemi, makes certain calculations easier
image of masked out area, blue is the cortical surface you are getting stats from
view in three different planes.
?h.cortex.label 25

26. How Do You Know What to Edit?
If pial surface includes too much:
edit brainmask.mgz
If white surface includes too much/little: OR
If pial surface includes too little:
edit the wm.mgz (if segmentation error)
add control points (if normalization error)
So, just a quick refresher about things so far:
If pial surf too much, edit brainmask, pulls it back.
If white surf affected, or pial is not far out enough, add to the wm mask or add control points.
Pushes surfs out
Why does editing wm mask (and therefore surf) affect pial?
----- Meeting Notes (4/27/15 14:22) -----
fix "it"
----- Meeting Notes (4/27/15 14:44) -----
start from scratch.

27. Pial surf grows from white surf
Because pial surf grows from white! FS takes white surf as starting point, so that is why errors in pial stem from errors in the white matter surf.
----- Meeting Notes (4/27/15 14:44) -----
possibly move.
Errors in pial surface placement are typically caused by underlying errors in the white surface placement, and can be corrected by interventions that fix the white surface.

28. Which Volumes to Edit & When…
Non-gm in pial surf
Non-wm in white surf
wm excluded from surf & intensity = 110
wm excluded from surf & intensity < 110
Cerebellum in pial surf
brainmask.mgz X
brain.finalsurfs.mgz
wm.mgz
add control points
Cheat sheet to reference later, no need to go over in detail during talk

29. Reconstruction Stages
recon-all is broken into three stages
autorecon1
autorecon2
autorecon3
these 3 stages together are equivalent to -all
Once you’ve finished making your edits, you need to rerun your subject through recon-all
But you don’t have to start over from scratch. Recon-all is broken up into three stages so you can restart running it from the stage you started making edits to
Reminder that it is broken into 3 stages
There are around 30 individual steps, but they are chunked together.
-And depending on where you edit….
----- Meeting Notes (4/27/15 14:44) -----
put after examples

30. Processing Stream Overview
T1 Weighted
Input
Skull Stripping
Volumetric Labeling
Intensity Normalization
Adjust skull strip algorithm:
recon-all –autorecon2
Add control points:
recon-all –autorecon2-cp
-you can start recon-all where your changes come in and run to end with special flags
-saves time
-multiple interventions, do them both and then run from earliest step.
Location of interventions along processing stream
If need to make more than one intervention, can do at same time and run from the earliest step
----- Meeting Notes (4/27/15 14:44) -----
summary slide at end
Gyral Labeling
White Matter
Segmentation
Surface Atlas
Registration
Surface Extraction
Fix white surf:
recon-all –autorecon2-wm
Fix pial surf:
recon-all –autorecon3-pial
Stats! 30 30

31. Processing Stream Order
If you are curious about what goes on under the hood of FS, you can check out the recon-all dev table
Lists every step, the flag you would use to run it, the command, and the input and output volumes for that step
Very helpful if you make an edit and just want to regenerate a certain part of your recon
----- Meeting Notes (4/27/15 14:44) -----
put at end or not put at all

32. recon-all -make all -s subjid
Or Make Life Easier
recon-all -make all -s subjid
Make all figures out what edits you have done (files you have touched) and runs from whatever step is earliest

33. FreeSurfer Remembers!
When edits are made, the changes are saved in a way that indicates manual changes were made (e.g. voxels that are erased are set to 1, not 0, so we can detect them)
Re-running with a new version preserves these changes
To rerun without edits, use –clean flags or start from scratch

34. Summary Hard Errors (recon-all.log file)
Soft Errors – surfaces not accurate
Change volumes, regenerate surfaces
Manual touch ups (erase, fill, clone, control points)
Volumes: brainmask.mgz, wm.mgz
Skull strip: too much, not enough
Segmentation: WM classified as non-WM, or reverse
FreeSurfer keeps track of edits
Look at all 3 views and scroll back and forth a few slices
If you don’t know, leave it alone
Should take less than 30 min (or even 15 min)

35. End of Presentation ----- Meeting Notes (4/27/15 14:22) -----
remove topological defects

36. recon-all
Visually check
Visually
check
recon-all
Done
Edits
Erase voxels
Fill voxels
Clone voxels
Add control points
recon-all -i <one_dicom.dcm> -s <subjid> -all

37. These are NOT errors
It appears that the aseg cortical ribbon is inaccurate. It is, but the aseg cortical ribbon is not used for anything!
Surfaces are not valid in subcortical regions along the medial wall.
4/27/15- DOUG SAID TO REMOVE THIS SLIDE SINCE SHOULDN’T BE A PROBLEM ANYMORE IN V6.0
(aseg cortical ribbon now will be constrainted by pial surface, so will no longer be inaccurate like this
Some other things that are not errors
This is an example of the aseg color map. For subcort structures, but also labels wm and cortical gray matter.
Not an error, because cortical ribbon not used from vol segs. From the surfaces
Again with surfs on medial wall, these do not matter because color tables for this
----- Meeting Notes (4/27/15 14:44) -----
remove this.
It is possible to edit the segmentation.

38. Segmentation Errors: Topological Defects
Hole: Partial Voluming: WM + GM looks like non-WM, it is segmented as non-WM and creates a hole
Handle: Something bright in a sulcus that gets classified as WM.
Holes: fill voxels in the wm.mgz
Handles: erase voxels in the wm.mgz
4/27/15- DOUG SAID TO REMOVE- EXPLAINING TOPOLOGICAL DEFECTS IS CONFUSING
Another error, just a type of segmentation error
Pretty complicated, but basically the two types are a hole and handle
Hole- wm labeled as gm, like the lesion example we saw before
Handle- gm labeled as wm so built a surface around it where there should not be one. Two gyri next to each other, get filled in with wm
wm.mgz

39. Segmentation Errors: Topological Defects
Fornix
hippocampus
Ventricles and Caudate
Cortical Defects
Pallidum and Putamen
4/27/15- DOUG SAID TO REMOVE- EXPLAINING TOPOLOGICAL DEFECTS IS CONFUSING
Typical places where you might see these topological defects
Holes, Handles
Automatically Fixed
Not always fixed correctly
Edit wm.mgz

40. Topology Correction BEFORE AFTER
4/27/15- DOUG SAID TO REMOVE- EXPLAINING TOPOLOGICAL DEFECTS IS CONFUSING
Freesurfer has a built in topology corrector, so normally you won’t see these errors often
But sometimes not fixed correctly and you have to manually edit
BEFORE
AFTER

41. Automatic Defect Correction
Corrected defect
Initial cortical surface
Topological defect
4/27/15- DOUG SAID TO REMOVE- EXPLAINING TOPOLOGICAL DEFECTS IS CONFUSING
In the volume vs on the surface
So there are breaks in the wm mask, and so the surfaces are built and leave parts out, or form connections where there should be a break.
Green lines- original surface
Red lines- topology corrector fixed surfaces
Sagittal view
Coronal view

42. Troubleshooting – Advice (Bruce)
Always look at the data in multiple views and scroll back and forth a few slices – 3D structure is difficult to discern!
If large regions of white matter are significantly darker than 110 (the target white matter intensity for normalization) then try adding control points, but make sure they are in the interior of the white matter.
If the ?h.orig surface misses white matter that is accurately labeled in the wm.mgz or extends into regions where there is no wm in the wm.mgz, then there is an incorrectly fixed topological defect.
Even one or two missing voxels can cause large-scale defects, so very minor editing (e.g. filling in white matter voxels that are holes, or erasing handles) may fix the problem.
Don’t edit too much! This will reduce reliability and is almost never needed. Usually this means you need to start over as you’ve done something wrong (e.g. put control points in the wrong place).

43. Troubleshooting – Advice
FLOW
AMBIGUITY
CONSISTENCY
Edit consistently within and across subjects.
SPEED
You will get faster with time; certain sections go faster.
Leave this slide up for Allison’s QA demo

44. What are the Common Interventions?
Manually edit the wm.mgz to change incorrectly labeled voxels (only for small errors).
Manually edit the brainmask.mgz to erase dura/vasculature.
Adjust watershed parameters or use –gcut to fix large-scale skull-strip errors.
Manually erase/clone regions of skull strip failure.
Control Points – add locations that are in the interior of the white matter and <110 to bring regional wm intensity up.
Use tkregister2 to fix incorrect talairach.xfm

45. New Morphometry Protocol: Identifying Dura with Multi-echo MP-RAGE
*joint work with Andre van der Kouwe

46. Automatic Defect Correction
TR=40,TE=20,a=15o, BW=30Hz/voxel
Difference between uncorrected (green) and corrected (red)

47. Troubleshooting: Topology Fixer Error
White Matter
“disconnects”
orig.nofix will be
accurate

48. Troubleshooting – Common Cases (≈98% of surface accurate in about 98% of cases for good data [1])
Symptom: white matter not accurate in wm.mgz
Interventions
add control points (if wm << 110).
Expert opts to set intensity thresholds in segmentation (almost never).
Manually erase/draw wm in wm.mgz
Symptom: skull strip not accurate
Adjust mri_watershed parameters or try –gcut
Manually erase skull/clone T1.mgz to recover brain
Symptom: surfaces are not accurate.
Interventions:
Add control points (if white matter << 110).
Erase dura/blood vessels
Check topology on ?h.inflated.nofix (if ?h.orig surface doesn’t follow wm.mgz)
[1] Salat, D, Personal Communication.