|
Size: 7650
Comment:
|
← Revision 76 as of 2013-11-01 14:24:23 ⇥
Size: 9368
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| [[FsTutorial|top]] | [[FsTutorial/OutputData|previous]] | ## page was renamed from FsTutorial/TroubleshootingData [[FsTutorial|top]] | [[FsTutorial/OutputData|previous]] | [[FsTutorial/LongitudinalTutorial|next]] |
| Line 4: | Line 5: |
| * If you are taking one of the formally organized courses, the data is already installed on the computer provided to you. If not, then to follow this exercise exactly be sure you've downloaded the [[FsTutorial/Data|tutorial data set]] before you begin. This set of exercises is not possible without the [[FsTutorial/Data|tutorial data set]]. Please set the environmental variable {{{TUTORIAL_DATA}}} to the location that you have downloaded the data to (here, it has been copied to $FREESURFER_HOME/subjects): ---- {{{ tcsh setenv TUTORIAL_DATA $FREESURFER_HOME/subjects/buckner_data/tutorial_subjs }}} ---- *Notice the command to open tcsh. If you are already running the tcsh command shell, then the 'tcsh' command is not necessary. |
|
| Line 15: | Line 8: |
| Below is a list of common things that require manual intervention. As you move through this exercise there will be links to pages instructing you how to fix these problems. While you are trying to identify the problems with the subjects listed below you may find it helpful to refer back to the [[FsTutorial/OutputData|previous exercise]], or open your own instance of the subject good_output to compare these subjects to a good example. | '''<<TableOfContents>>''' |
| Line 17: | Line 10: |
| *[[FsTutorial/TopologicalDefect|Correcting topological defects]] *[[FsTutorial/WhiteMatterEdits|Edits to the wm volume]] *[[FsTutorial/PialEdits|Edits to the brainmask volume]] *[[FsTutorial/SkullStripFix|Skull strip]] *[[FsTutorial/ControlPoints|Adding control points]] *[[FsTutorial/Talairach|Talairach transformation]] |
== 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: |
| Line 25: | Line 14: |
| == Correcting topological defects == First make sure you have your SUBJECTS_DIR set to the correct location: ---- |
{{{ 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 [[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: |
| Line 30: | Line 27: |
| setenv SUBJECTS_DIR $TUTORIAL_DATA | source your_freesurfer_dir/SetUpFreeSurfer.csh setenv SUBJECTS_DIR $TUTORIAL_DATA/buckner_data/tutorial_subjs |
| Line 33: | Line 31: |
| 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. -------- == Failure Modes == 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 [[FsTutorial/OutputData|previous exercise]], or open your own instance of the subject good_output to compare these subjects to a good example. |
|
| Line 34: | Line 37: |
| Now you can open the subject, topo_defect_before, in tkmedit. ---- |
=== Edits to the brainmask volume === Open the subject, '''pial_edits_before'''. |
| Line 37: | Line 41: |
| tkmedit topo_defect_before brainmask.mgz \ lh.white -aux wm.mgz -aux-surface rh.white |
tkmedit pial_edits_before brainmask.mgz -aux T1.mgz -surfs |
| Line 41: | Line 44: |
The command above will open the brainmask.mgz volume, the T1.mgz loaded as aux, and the surfaces for both hemispheres. (You can feel free to open other volumes in aux or to load in the aseg.mgz if you want or need to.) Scroll through the slices of this subject to check the pial and white surfaces for accuracy, making sure they follow the actual gray/white boundaries and that they do not include anything that should not be included. If you would like to see the inflated surfaces for each hemisphere of this subject, '''open a second and third terminal window''', then open the surfaces in tksurfer: {{{ tksurfer pial_edits_before lh inflated }}} {{{ tksurfer pial_edits_before rh inflated }}} Once you have identified the problem (or have given up!), click [[FsTutorial/PialEdits|here]] for detailed instructions on how you can fix it. |
|
| Line 42: | Line 61: |
| This will open the brainmask.mgz volume, the wm.mgz loaded as aux, and the surfaces for both hemispheres. | === Edits to the wm volume === Now, take a look at the next subject, '''wm1_edits_before'''. |
| Line 44: | Line 64: |
| You can feel free to open other volumes in aux or to load in the aseg.mgz if you want or need to. Take a look at this subject, inspecting the various outputs that were mentioned in the [[FsTutorial/OutputData|previous exercise]] and see if you can indentify what is wrong. Click [[FsTutorial/TopologicalDefect|here]] for detailed instructions on how you can fix it. You can also compare this to the finished version, topo_defect_after. == Edits to the wm volume == Now, take a look at the next subject, wm1_edits_before. ---- |
|
| Line 52: | Line 65: |
| tkmedit wm1_edits_before brainmask.mgz \ lh.white -aux T1.mgz -aux-surface rh.white |
tkmedit wm1_edits_before brainmask.mgz -aux T1.mgz -surfs |
| Line 56: | Line 68: |
Again, this will bring up the brainmask.mgz volume, the T1.mgz volume, and the surfaces for both hemispheres. 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. Click [[FsTutorial/WhiteMatterEdits|here]] for detailed instructions on how you can fix it. You can also compare the original data to a corrected and rerun version, '''wm1_edits_after'''. To view this corrected subject (which was corrected by following the detailed instructions provided to you): {{{ tkmedit wm1_edits_after brainmask.mgz -aux wm.mgz -surfs }}} |
|
| Line 57: | Line 96: |
=== Skull strip === Now, take a look at the next subject, '''skullstrip1_before''', in tkmedit. {{{ tkmedit skullstrip1_before brainmask.mgz -aux T1.mgz -surfs }}} This will open the brainmask.mgz volume, the T1.mgz loaded as aux, and the surfaces for both hemispheres. The trouble with this subject has occurred in the skull stripping step. Check the brainmask.mgz volume carefully, comparing it to the T1.mgz volume (loaded in aux) to make sure that the skull has been completely stripped away, leaving behind the complete cortex and the cerebellum. You can feel free to open other volumes in aux or to load in the aseg.mgz if you want or need to. Click [[FsTutorial/SkullStripFix|here]] for detailed instructions on how you can fix it. You can also compare this to the finished version, '''skullstrip1_after'''. ---- === Adding control points === Now, take a look at the next subject, '''cp_before'''. {{{ tkmedit cp_before brainmask.mgz -aux T1.mgz -surfs }}} |
|
| Line 60: | Line 123: |
| ---- | |
| Line 62: | Line 125: |
| tksurfer subject2_before lh inflated & tksurfer subject2_before rh inflated & |
tksurfer cp_before lh inflated & tksurfer cp_before rh inflated & |
| Line 65: | Line 128: |
| ---- | |
| Line 68: | Line 131: |
| You may need to open other volumes in order to see or fix the problem. Take a look through this subject and see if you can identify what is wrong. | The trouble with this subject has occured during the intensity normalization. Check the white surface and be sure it is including all of the white matter as it should. If you find an area that is not included as white matter be sure to check to see that the intensity is at (or very close to) 110. |
| Line 70: | Line 133: |
| If you are stuck and you need a [[FsTutorial/TroubleshootingHints|hint]] you can click for some help. | You may need to open other volumes in order to see or fix the problem. |
| Line 72: | Line 135: |
| When you think you've identified the problem, click [[FsTutorial/WhiteMatterEdits|here]] for detailed instructions on how you can fix it. You can also compare this to the finished version, subject2_after | Click [[FsTutorial/ControlPoints|here]] for detailed instructions on how you can fix it. |
| Line 74: | Line 137: |
| == Edits to the brainmask volume == Now, take a look at the next subject, subject3_before. |
|
| Line 77: | Line 138: |
| === Correcting topological defects === Open the subject, '''topo_defect_before''', in tkmedit. |
|
| Line 78: | Line 142: |
| tkmedit subject3_before brainmask.mgz \ lh.white -aux T1.mgz -aux-surface rh.white |
tkmedit topo_defect_before brainmask.mgz -aux wm.mgz -surfs |
| Line 82: | Line 145: |
This will open the brainmask.mgz volume, the wm.mgz loaded as aux, and the surfaces for both hemispheres. Take a look at this subject, inspecting the various outputs that were mentioned in the [[FsTutorial/OutputData|previous exercise]] and see if you can identify what is wrong. ''Hint: It's a very small error in the posterior part of the brain.'' Once you spot the error, click [[FsTutorial/TopologicalDefect|here]] for detailed instructions on how you can fix it. After you have fixed it, you can compare the original data to the a corrected and rerun version, '''topo_defect_after'''. To view this corrected subject: {{{ tkmedit topo_defect_after brainmask.mgz -aux wm.mgz -surfs }}} |
|
| Line 83: | Line 160: |
| Again, this will bring up the brainmask.mgz volume, the T1.mgz volume, and the surfaces for both hemispheres. | === Talairach transformation === |
| Line 85: | Line 162: |
| In your second terminal window, if not already open, open the surfaces in tksurfer: ---- |
Now, take a look at the next subject, '''tal_before'''. |
| Line 88: | Line 165: |
| tksurfer subject3_before lh inflated & tksurfer subject3_before rh inflated & |
tkmedit tal_before brainmask.mgz -aux T1.mgz -surfs |
| Line 91: | Line 168: |
| ---- | Again, this will bring up the brainmask.mgz volume and the T1.mgz volume and the surfaces for both hemispheres. In a second and third terminal window, if not already open, open the surfaces in tksurfer: {{{ tksurfer tal_before lh inflated }}} {{{ tksurfer tal_before rh inflated }}} |
| Line 94: | Line 184: |
| You may need to open other volumes in order to see or fix the problem. Take a look through this subject and see if you can identify what is wrong. | The trouble with this subject is a little tricky to figure out. The midline cutting planes are not actually on the midline, but the real root of this problem is in one of the very initial steps of recon-all. The talairach transform is bad and will need to be fixed. |
| Line 96: | Line 186: |
| If you are stuck and you need a [[FsTutorial/TroubleshootingHints|hint]] you can click for some help. | You may need to open other volumes in order to see or fix the problem. |
| Line 98: | Line 188: |
| When you think you've identified the problem, click [[FsTutorial/PialEdits|here]] for detailed instructions on how you can fix it. | Click [[FsTutorial/Talairach|here]] for detailed instructions on how you can fix it. |
| Line 100: | Line 190: |
| == Skull strip == Now you can open the first subject, subject1_before, in tkmedit. |
|
| Line 103: | Line 191: |
| {{{ tkmedit subject1_before brainmask.mgz \ lh.white -aux T1.mgz -aux-surface rh.white |
=== Editing the Aseg === |
| Line 107: | Line 193: |
| }}} ---- This will open the brainmask.mgz volume, the T1.mgz loaded as aux, and the surfaces for both hemispheres. You can feel free to open other volumes in aux or to load in the aseg.mgz if you want or need to. Take a look at this first subject, inspecting the various outputs that were mentioned in the [[FsTutorial/OutputData|previous exercise]] and see if you can indentify what is wrong. If you are stuck and you need a [[FsTutorial/TroubleshootingHints|hint]] you can click for some help. When you think you've identified the problem, click [[FsTutorial/SkullStripFix|here]] for detailed instructions on how you can fix it. You can also compare this to the finished version, subject1_after. == Adding control points == Now, take a look at the next subject, subject4_before. ---- {{{ tkmedit subject4_before brainmask.mgz \ lh.white -aux T1.mgz -aux-surface rh.white }}} ---- Again, this will bring up the brainmask.mgz volume, the T1.mgz volume, and the surfaces for both hemispheres. In your second terminal window, if not already open, open the surfaces in tksurfer: ---- {{{ tksurfer subject4_before lh inflated & tksurfer subject4_before rh inflated & }}} ---- This will open the inflated surfaces for both hemispheres in tksurfer. You may need to open other volumes in order to see or fix the problem. Take a look through this subject and see if you can identify what is wrong. If you are stuck and you need a [[FsTutorial/TroubleshootingHints|hint]] you can click for some help. When you think you've identified the problem, click [[FsTutorial/ControlPoints|here]] for detailed instructions on how you can fix it. == Talairach transformation == Now, take a look at the next subject, subject5_before. ---- {{{ tkmedit subject5_before brainmask.mgz \ lh.white -aux T1.mgz -aux-surface rh.white }}} ---- Again, this will bring up the brainmask.mgz volume and the T1.mgz volume and the surfaces for both hemispheres. In your second terminal window, if not already open, open the surfaces in tksurfer: ---- {{{ tksurfer subject5_before lh inflated & tksurfer subject5_before rh inflated & }}} ---- This will open the inflated surfaces for both hemispheres in tksurfer. You may need to open other volumes in order to see or fix the problem. Take a look through this subject and see if you can identify what is wrong. If you are stuck and you need a [[FsTutorial/TroubleshootingHints|hint]] you can click for some help. When you think you've identified the problem, click [[FsTutorial/Talairach|here]] for detailed instructions on how you can fix it. |
We generally advise against editing the aseg.mgz unless absolutely necessary. Try using an xopts script first to change the intensity thresholds being used. Editing the aseg will add more variance to your data. Instructions on how to edit the aseg are [[TkMeditGuide/TkMeditWorkingWithData/TkMeditSegmentations|here]]. |
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.
Failure Modes
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 brainmask volume
Open the subject, pial_edits_before.
tkmedit pial_edits_before brainmask.mgz -aux T1.mgz -surfs
The command above will open the brainmask.mgz volume, the T1.mgz loaded as aux, and the surfaces for both hemispheres. (You can feel free to open other volumes in aux or to load in the aseg.mgz if you want or need to.) Scroll through the slices of this subject to check the pial and white surfaces for accuracy, making sure they follow the actual gray/white boundaries and that they do not include anything that should not be included.
If you would like to see the inflated surfaces for each hemisphere of this subject, open a second and third terminal window, then open the surfaces in tksurfer:
tksurfer pial_edits_before lh inflated
tksurfer pial_edits_before rh inflated
Once you have identified the problem (or have given up!), click here for detailed instructions on how you can fix it.
Edits to the wm volume
Now, take a look at the next subject, wm1_edits_before.
tkmedit wm1_edits_before brainmask.mgz -aux T1.mgz -surfs
Again, this will bring up the brainmask.mgz volume, the T1.mgz volume, and the surfaces for both hemispheres.
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.
Click here for detailed instructions on how you can fix it. You can also compare the original data to a corrected and rerun version, wm1_edits_after.
To view this corrected subject (which was corrected by following the detailed instructions provided to you):
tkmedit wm1_edits_after brainmask.mgz -aux wm.mgz -surfs
Skull strip
Now, take a look at the next subject, skullstrip1_before, in tkmedit.
tkmedit skullstrip1_before brainmask.mgz -aux T1.mgz -surfs
This will open the brainmask.mgz volume, the T1.mgz loaded as aux, and the surfaces for both hemispheres.
The trouble with this subject has occurred in the skull stripping step. Check the brainmask.mgz volume carefully, comparing it to the T1.mgz volume (loaded in aux) to make sure that the skull has been completely stripped away, leaving behind the complete cortex and the cerebellum.
You can feel free to open other volumes in aux or to load in the aseg.mgz if you want or need to.
Click here for detailed instructions on how you can fix it. You can also compare this to the finished version, skullstrip1_after.
Adding control points
Now, take a look at the next subject, cp_before.
tkmedit cp_before brainmask.mgz -aux T1.mgz -surfs
Again, this will bring up the brainmask.mgz volume, the T1.mgz volume, and the surfaces for both hemispheres.
In your second terminal window, if not already open, open the surfaces in tksurfer:
tksurfer cp_before lh inflated & tksurfer cp_before rh inflated &
This will open the inflated surfaces for both hemispheres in tksurfer.
The trouble with this subject has occured during the intensity normalization. Check the white surface and be sure it is including all of the white matter as it should. If you find an area that is not included as white matter be sure to check to see that the intensity is at (or very close to) 110.
You may need to open other volumes in order to see or fix the problem.
Click here for detailed instructions on how you can fix it.
Correcting topological defects
Open the subject, topo_defect_before, in tkmedit.
tkmedit topo_defect_before brainmask.mgz -aux wm.mgz -surfs
This will open the brainmask.mgz volume, the wm.mgz loaded as aux, and the surfaces for both hemispheres.
Take a look at this subject, inspecting the various outputs that were mentioned in the previous exercise and see if you can identify what is wrong.
Hint: It's a very small error in the posterior part of the brain.
Once you spot the error, click here for detailed instructions on how you can fix it. After you have fixed it, you can compare the original data to the a corrected and rerun version, topo_defect_after. To view this corrected subject:
tkmedit topo_defect_after brainmask.mgz -aux wm.mgz -surfs
Talairach transformation
Now, take a look at the next subject, tal_before.
tkmedit tal_before brainmask.mgz -aux T1.mgz -surfs
Again, this will bring up the brainmask.mgz volume and the T1.mgz volume and the surfaces for both hemispheres.
In a second and third terminal window, if not already open, open the surfaces in tksurfer:
tksurfer tal_before lh inflated
tksurfer tal_before rh inflated
This will open the inflated surfaces for both hemispheres in tksurfer.
The trouble with this subject is a little tricky to figure out. The midline cutting planes are not actually on the midline, but the real root of this problem is in one of the very initial steps of recon-all. The talairach transform is bad and will need to be fixed.
You may need to open other volumes in order to see or fix the problem.
Click here for detailed instructions on how you can fix it.
Editing the Aseg
We generally advise against editing the aseg.mgz unless absolutely necessary. Try using an xopts script first to change the intensity thresholds being used. Editing the aseg will add more variance to your data. Instructions on how to edit the aseg are here.