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

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

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

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

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 freesurfer@nmr.mgh.harvard.edu 5

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 Email the mailing list A list of some things to try when you have a hard failure When in doubt, email the mailing list (freesurfer@nmr.mgh.harvard.edu)

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 email us, remember to send us these things Helps give us a better idea of your situation

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,

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:

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

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

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

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

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

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

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

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

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

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

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!

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

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

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

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

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

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.

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.

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

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

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

Processing Stream Order http://surfer.nmr.mgh.harvard.edu/fswiki/ReconAllDevTable 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

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

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

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)

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

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

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.

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

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

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

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

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

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

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

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

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

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

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, 2009. Personal Communication.