|
Size: 5841
Comment:
|
Size: 5964
Comment: updated version of QAtools
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #acl JenniPacheco:read,write,delete,revert BradDickerson:read,write,delete,revert DavidSalat:read,write,delete,revert VasanthPappu:read,write,delete,revert StephanieLee:read,write,delete,revert | = FreeSurfer QA Tools = <<TableOfContents>> |
| Line 3: | Line 4: |
| == STATUS == | The QA Tools are intended to be used in assessing the quality of one or more FreeSurfer recons. These scripts are capable of verifying all steps in the FreeSurfer recon-all stream were executed and in the correct order, as well as verifying all files exist and were created in the correct order. Additionally, these scripts can be used to detect potential outlier regions in the aseg.mgz within a dataset, calculate SNR and WM intensity values, and collect detailed snapshots of various volumes. The following people have been major contributors in developing these scripts: David Koh, Stephanie Lee, Jenni Pacheco, Vasanth Pappu, and Louis Vinke. The QA Tools scripts are a work-in-progress. Any feedback, bug reports, or feature requests are appreciated (email vinke[at]nmr.mgh.harvard.edu). Click [[QuickQaQdec|here]] to view steps for an alternate QA procedure using Qdec. == Setup == Click the link below to download the QA Tools scripts. Extract all the contents of the tar file into a new directory. Source your local version of FreeSurfer, set your subjects directory variable, and set the QA Tools path: |
| Line 5: | Line 14: |
| scripts are all here: /autofs/space/tensor_017/users/jpacheco/QAtools |
<source freesurfer> |
| Line 8: | Line 16: |
| * they should all be working now. | In tcsh: setenv SUBJECTS_DIR /path/to/your/subjects_dir setenv QA_TOOLS /path/to/QATools/scripts |
| Line 10: | Line 20: |
| To-Do: * add a flag for -noasegoutlier - DONE by vp on 9/28/06 * make version checker scripts output to the same log file as recon_checker - DONE by jp on 9/29/06 * figure out a better way to define RECON_CHECKER_SCRIPTS and scriptDirs....INSTEAD, set QA_SCRIPTS to be the QAtools directory, and then [[BR]] within the scripts set RECON_CHECKER_SCRIPTS to be $QA_SCRIPTS/data_checker/ * add greconversion and greconversions to ALWAYS run first when the recon-checker is run - DONE by jp on 09/29/06 * -outputfileorder appears to not work. - DONE by vp 10/10/06 * i think i can fix the snapshot script to make it run faster. - DONE by jp 10/12/06 Things I've done: * I've created the pages ReconChecker and QAnotepad which will be the only place that full usage options for these scripts will be, eventually. * VP added 3 scripts to the data_checker directory: gnicv, gparcvalnorm, gparcmeannorm. Now the recon_all_aseg_outlier_checker now compares and looks for outliers after the segmentation volumes have been corrected for ICV, per David's suggestion |
In bash: export SUBJECTS_DIR=/path/to/your/subjects_dir export QA_TOOLS=/path/to/QATools/scripts }}} |
| Line 23: | Line 26: |
| [[attachment:QAtools_v1.2.tar.gz]] | |
| Line 24: | Line 28: |
| }}} | === Dependencies === QA Tools requires: |
| Line 26: | Line 31: |
| = FreeSurfer QA Tools = [[TableOfContents]] QA mini-intro coming soon... |
* !ImageMagick Studio version 6.2.8 or higher when using the snapshots option. This can be downloaded [[http://www.imagemagick.org/script/index.php|here]]. * The GNU awk (gawk) utility. This can be downloaded [[http://www.gnu.org/software/gawk/|here]]. |
| Line 31: | Line 34: |
| == To check the output of one reconned subject == First you'll need to properly set your SUBJECTS_DIR. Also you'll need to set your QA_SCRIPTS directory. This should be the directory that you downloaded the QAtools directory. For our example here QAtools is in /space/tensor/17/users/jpacheco/QAtools. {{{ setenv QA_SCRIPTS /space/tensor/17/users/jpacheco/QAtools }}} Now, from your SUBJECTS_DIR you are ready to run: {{{ $QA_SCRIPTS/data_checker/recon_checker -nocheckasegoutliers -s bert -o QAsnap.html }}} where {{{bert}}} is your subject ID and {{{QAsnap.html}}} is the name of the output html file that you want to create.[[BR]] For complete usage instructions please see the ReconChecker page. [[BR]] ----- '''What it does: '''[[BR]] *checks the version of FreeSurfer used to process this subject *checks the {{{recon-all-status.log}}} file to be sure each step was run *checks the order of the output files to be sure that they were created in the correct order *takes snapshots of the talairach, skullstrip, surfaces, curvature, and parcellations *outputs two different log files and an html file (called QAsnap.html in this example) with the snapshots ''**NOTE: while it takes the snapshots tkmedit and tksurfer will flash up on the screen. You do not need to do anything, the snap shots are taken automatically. To ensure good quality snapshots make sure there are no other windows over the tkmedit/tksurfer windows.'' ----- '''Outputs'''[[BR]] There will be two log files output into your subjects scripts directory: {{{ ls bert/scripts recon_checker.bert.details.log recon_checker.bert.summary.log }}} The {{{recon_checker.bert.summary.log}}} contains a summary of the status of that subject: {{{ ------------------------------------------------------------- Running recon_checker on: Thu Oct 5 15:00:42 EDT 2006 Checking Last Version Used: /usr/local/freesurfer/dev/bin/recon-all In output_file_checker In recon_all_status_log_checker bert COMPLETE }}} This subject was run most recently using the dev version of !FreeSurfer and all the steps have been run. Another example of this log file is: {{{ ------------------------------------------------------------- Running recon_checker on: Wed Oct 4 13:54:30 EDT 2006 Checking Last Version Used: /space/dijon/28/users/jpacheco/freesurfer_stable3_centos64//bin/recon-all In output_file_checker In recon_all_status_log_checker bert STEPS_MISSING }}} This subject was run most recently using a version of !FreeSurfer located /space/dijon/28/users/jpacheco/freesurfer_stable3_centos64 and there are steps missing from the processing stream. The {{{recon_checker.bert.details.log}}} will give more details as to what might be wrong if there are problems. For the second subject above, with steps missing, the {{{recon_checker.bert.details.log}}} looks like: |
== Getting Started == Run the following command to view explanations for all the QA Tools options: |
| Line 92: | Line 38: |
| ------------------------------------------------------------- Running recon_checker on: Wed Oct 4 13:54:30 EDT 2006 Checking Last Version Used: /space/dijon/28/users/jpacheco/freesurfer_stable3_centos64//bin/recon-all Checking ALL Versions Used: /usr/local/freesurfer/dev/bin/recon-all, /space/dijon/28/users/jpacheco/freesurfer_stable3_centos64//bin/recon-all, In output_file_checker SUBJECTS_DIR is /autofs/space/tensor_014/users/jenni |
$QA_TOOLS/recon_checker -help }}} By default QA-Tools will check the status log, the order files were created, the aseg for any outliers, create snapshots of slices throughout various volumes, and calculate SNR and WM measures. See the flags below if you want to disable one or more of these options. == Arguments == === Required Flagged Arguments === ||-s <subject1> [<subject2>...] ||Case ID for one or more subjects located in $SUBJECTS_DIR (use -s-file as alternative) || |
| Line 104: | Line 47: |
| In recon_all_status_log_checker bert STEPS_MISSING Expected to see the following steps before #@# Tessellate rh Wed Jun 7 14:43:02 EDT 2006 in the recon-all-status.log file (line # 98): --> Tessellate lh --> Smooth1 lh --> Inflation1 lh --> QSphere lh --> Fix Topology lh --> Make Final Surf lh --> Smooth2 lh --> Inflation2 lh --> Cortical ribbon mask lh --> Sphere lh --> Surf Reg lh --> Contra Surf Reg lh --> AvgCurv lh --> Cortical Parc lh --> Parcellation Stats lh --> Cortical Parc 2 lh --> Parcellation Stats 2 lh However, these LH processes were executed previously. Perhaps the RH output was modified and re-run without re-running the LH processes. }}} This log shows that the dev version of !FreeSurfer was used for a previous set of processing, but most recently the private version was used. The output from the |
=== Optional Flagged Arguments === ||-subjid <subject1> [<subject2>...] ||Specify subject(s) to process || ||-s-file ||Specify a file with a list of subjects. May be used instead of -s or -subjid || ||-snaps-out ||Full path and name of snapshots HTML file. Default: "$SUBJECTS_DIR/QA/QA_check.html" || ||-snaps-detailed ||Take a more detailed set of snapshots || ||-snaps-overwrite ||Take all snapshots, overwriting any existing snapshots || ||-no-snaps ||Do not take snapshots || ||-snaps-only ||Only take snapshots || ||-outputFOF <file-order list> ||Specify a file which lists the proper order of output files || ||-asegLUT <file> ||Specify a file containing aseg outlier lookup table || ||-gen-outputFOF ||Generate the file order list from the first subject || ||-gen-asegLUT <file> ||Generate an aseg look up table from your subjects that can be used to identify aseg outliers || ||-nocheck-aseg ||Do not check for aseg outliers || ||-nocheck-status ||Do not check status log file for each subject || ||-nocheck-outputFOF ||Do not check output order of files for each subject || ||-nocheck-SNR-WM ||Do not calculate SNR and WM measures for each subject || ||-completeStatusFile <file> ||Compares each subject's status log file to the specified log file || ||-completeStatusFiles <file> ||Compares each subject's status log file to each of the complete status logs listed in <file> || ||-ignore <process1> [<process2> ...] ||Specify one or more FreeSurfer processes to ignore while checking status files || |
| Line 132: | Line 68: |
| == To check the output of a group of reconned subjects == | == Future Directions == * Implement -gen-status flag * Shorter alternative flags * Handle cases where FS ran multiple times (status_file_checker) * Generate status log file from specified subject * Create file order and status step lists for longitudinal QA * Snapshots taken using Freeview * Specify snapshots be taken of specific regions found in aparc+aseg.mgz with Freeview * Automatically adjust intensity/contrast of volumes before taking snapshots * Compile snapshots into GIF animations * Detect outliers in aparc and aparc2009 volumes * Handle cases where two files flip/flop in creation order (output_file_checker) * WM/SNR measurement outputs to seperate file (tab-delimited) * Make image & html links for snapshots relative so directory can be moved or renamed |
| Line 134: | Line 83: |
| == Release Notes == v1.1 (3/5/2012) |
|
| Line 135: | Line 86: |
| == To check the output of a group analysis == | * Log and screen output modified * Created default file order list for *.long subject folders processed with FSv5.1 (default_FOF_FSv5.1_long) == Known Issues == * To get the "-gen-asegLUT" flag of 'recon_checker' to work on FS 5.3 data, you need to change the helper 'gnicv' script to grep on "!EstimatedTotalIntraCranialVol" rather than "ICV" (due to the name change of that variable in the stats/aseg.stats file relative to FS 5.1). * When taking snapshots, the tkmedit and tksurfer windows that appear can't be blocked by other windows, and the screensaver can't be activated while these scripts are running. Otherwise, the script will take snapshots of the screensaver or the interfering windows. The monitor can be physically turned off while the scripts are running, however, to save power. == For internal users == If you want to disable your screensaver so snaps can be taken overnight, set the value in . ~/.gconf/desktop/gnome/session/%gconf.xml to the number of minutes you want to pass before your screensaver activates (eg 960 for 16 hours). Also, go to System Preferences -> Screensaver and click on Power Management. In the "On AC Power" tab, choose Never in both of the pull down menus. |
FreeSurfer QA Tools
Contents
The QA Tools are intended to be used in assessing the quality of one or more FreeSurfer recons. These scripts are capable of verifying all steps in the FreeSurfer recon-all stream were executed and in the correct order, as well as verifying all files exist and were created in the correct order. Additionally, these scripts can be used to detect potential outlier regions in the aseg.mgz within a dataset, calculate SNR and WM intensity values, and collect detailed snapshots of various volumes. The following people have been major contributors in developing these scripts: David Koh, Stephanie Lee, Jenni Pacheco, Vasanth Pappu, and Louis Vinke.
The QA Tools scripts are a work-in-progress. Any feedback, bug reports, or feature requests are appreciated (email vinke[at]nmr.mgh.harvard.edu).
Click here to view steps for an alternate QA procedure using Qdec.
Setup
Click the link below to download the QA Tools scripts. Extract all the contents of the tar file into a new directory. Source your local version of FreeSurfer, set your subjects directory variable, and set the QA Tools path:
<source freesurfer> In tcsh: setenv SUBJECTS_DIR /path/to/your/subjects_dir setenv QA_TOOLS /path/to/QATools/scripts In bash: export SUBJECTS_DIR=/path/to/your/subjects_dir export QA_TOOLS=/path/to/QATools/scripts
Dependencies
QA Tools requires:
ImageMagick Studio version 6.2.8 or higher when using the snapshots option. This can be downloaded here.
The GNU awk (gawk) utility. This can be downloaded here.
Getting Started
Run the following command to view explanations for all the QA Tools options:
$QA_TOOLS/recon_checker -help
By default QA-Tools will check the status log, the order files were created, the aseg for any outliers, create snapshots of slices throughout various volumes, and calculate SNR and WM measures. See the flags below if you want to disable one or more of these options.
Arguments
Required Flagged Arguments
-s <subject1> [<subject2>...] |
Case ID for one or more subjects located in $SUBJECTS_DIR (use -s-file as alternative) |
Optional Flagged Arguments
-subjid <subject1> [<subject2>...] |
Specify subject(s) to process |
-s-file |
Specify a file with a list of subjects. May be used instead of -s or -subjid |
-snaps-out |
Full path and name of snapshots HTML file. Default: "$SUBJECTS_DIR/QA/QA_check.html" |
-snaps-detailed |
Take a more detailed set of snapshots |
-snaps-overwrite |
Take all snapshots, overwriting any existing snapshots |
-no-snaps |
Do not take snapshots |
-snaps-only |
Only take snapshots |
-outputFOF <file-order list> |
Specify a file which lists the proper order of output files |
-asegLUT <file> |
Specify a file containing aseg outlier lookup table |
-gen-outputFOF |
Generate the file order list from the first subject |
-gen-asegLUT <file> |
Generate an aseg look up table from your subjects that can be used to identify aseg outliers |
-nocheck-aseg |
Do not check for aseg outliers |
-nocheck-status |
Do not check status log file for each subject |
-nocheck-outputFOF |
Do not check output order of files for each subject |
-nocheck-SNR-WM |
Do not calculate SNR and WM measures for each subject |
-completeStatusFile <file> |
Compares each subject's status log file to the specified log file |
-completeStatusFiles <file> |
Compares each subject's status log file to each of the complete status logs listed in <file> |
-ignore <process1> [<process2> ...] |
Specify one or more FreeSurfer processes to ignore while checking status files |
Future Directions
- Implement -gen-status flag
- Shorter alternative flags
- Handle cases where FS ran multiple times (status_file_checker)
- Generate status log file from specified subject
- Create file order and status step lists for longitudinal QA
- Snapshots taken using Freeview
- Specify snapshots be taken of specific regions found in aparc+aseg.mgz with Freeview
- Automatically adjust intensity/contrast of volumes before taking snapshots
- Compile snapshots into GIF animations
- Detect outliers in aparc and aparc2009 volumes
- Handle cases where two files flip/flop in creation order (output_file_checker)
- WM/SNR measurement outputs to seperate file (tab-delimited)
Make image & html links for snapshots relative so directory can be moved or renamed
Release Notes
v1.1 (3/5/2012)
- Log and screen output modified
- Created default file order list for *.long subject folders processed with FSv5.1 (default_FOF_FSv5.1_long)
Known Issues
To get the "-gen-asegLUT" flag of 'recon_checker' to work on FS 5.3 data, you need to change the helper 'gnicv' script to grep on "EstimatedTotalIntraCranialVol" rather than "ICV" (due to the name change of that variable in the stats/aseg.stats file relative to FS 5.1).
- When taking snapshots, the tkmedit and tksurfer windows that appear can't be blocked by other windows, and the screensaver can't be activated while these scripts are running. Otherwise, the script will take snapshots of the screensaver or the interfering windows. The monitor can be physically turned off while the scripts are running, however, to save power.
For internal users
If you want to disable your screensaver so snaps can be taken overnight, set the value in
- ~/.gconf/desktop/gnome/session/%gconf.xml
to the number of minutes you want to pass before your screensaver activates (eg 960 for 16 hours). Also, go to System Preferences -> Screensaver and click on Power Management. In the "On AC Power" tab, choose Never in both of the pull down menus.