Differences between revisions 65 and 66
Deletions are marked like this. Additions are marked like this.
Line 181: Line 181:
recon-all -s bert -label-v1 recon-all -all -s bert -label-v1
Line 183: Line 183:
The accuracy of the Hinds and Fischl V1 labeling method compared to retinotopy depends first of all under what conditions the retinotopy is carried out (field strength, # of coils elements, voxel size, etc.). In our comparision, the folding patterns predict the border location to about 2.5mm, which is probably better than you can get with retinotopy. The accuracy of the Hinds and Fischl V1 labeling method compared to retinotopy depends under what conditions the retinotopy is carried out (field strength, # of coils elements, voxel size, etc.). In our comparision, the folding patterns predict the border location to about 2.5mm, which is probably better than you can get with retinotopy.

top


  • FAQ


  • The purpose of this FAQ is to provide a Wiki space where users can add the most frequent questions to avoid asking already answered questions in the support list.

Contents

  1. General
    1. Q. How can I help this FAQ?
    2. Q. What are the advantages of FreeSurfer over VBM?
    3. Q. How do I know the version of FreeSurfer I'm running?
    4. Q. Is the FreeSurfer source code available?
  2. Computing
    1. Q. How long does it take to finish a reconstruction?
    2. Q. How can I reduce the time of recon-all in a group of patients?
    3. Q. I want to use freesurfer to quantify cortical thickness, and I want to use the software under Linux. What equipment for computer do you recommend?
    4. Q. Is it possible to run FreeSurfer in Ubuntu Linux?
    5. Q. Could I run multiple instances of Freesurfer (on my virtual box)?
    6. Q. Is it recommended that people use memprage? How are they analyzed? Just sqrt sum sqr of the echoes? Or is there something more elaborate?
  3. Processing/Re-processing Data in FreeSurfer
    1. Q. Can I run some cases in my dataset using one version of FreeSurfer and others using a different version of FreeSurfer?
    2. Q. How to run recon-all in a ssh terminal
    3. Q. I had a [Power Outage|Computer Failure|Spilled coffee on computer|etc], how can I resume the recon-all?
    4. Q. I have already skull-stripped data. Can I submit it to recon-all?
    5. Q. I made white matter and pial edits to my volume. Do I need to run -autorecon2-wm and when that is finished run -autorecon2-pial?
    6. Q. One of my cases doesn't have the cerebellum so I adjusted the watershed threshold to fix it. However, at one threshold, the cerebellum is still not included, and at the next the entire skull is there. What should I do?
  4. Common Error messages
    1. Q. Help! I got this error message: "mri_watershed error: GLOBAL region of the brain empty!" - what should I do?
    2. Q. I get an error message from the Talairach Failure Detection. What does this mean?
    3. Q. I get an error during the mri_ca_label step while running recon-all. The last thing it says is: "saving intensity scales to aseg.auto_noCCseg.label_intensities.txt". What's wrong?
    4. Q. I get an error during the Talairach transform step when running recon-all on ANALYZE images. Why is this happening?
  5. FreeSurfer Output Questions
    1. Q. The surfaces near the medial wall, hippocampus, and amygdala aren't accurately following the structures there. How can I fix this?
    2. Q: It seems that there is a 5mm thickness upper limit in my volumes, is it normal? How can I change this?
    3. Q. Why in many subjects the insular cortical surface seems so thick? Is the convoluted nature of the Insula that causes that?
    4. Q. What are the sulc and curv overlays (in QDEC) showing us?
    5. Q. How would I put a FreeSurfer output volume and/or segmentation back into the same space as my original anatomical input (native space)?
    6. Q. How do I transform coordinates in one space to those in another space (eg, a point on the surface to MNI305 space or to the col, row, slice of a functional volume)?
    7. Q. The pial surface includes some cerebellum. How can I fix this?
    8. Q. How do I get the cortical thickness maps for several subjects into the same template space (fsaverage)?
    9. Q. Where can I find V1 labels?
  6. Analysis of FreeSurfer Data
    1. Q. I am trying to measure the cortical thickness of specific ROI how can I do this?
    2. Q. I am using QDEC to examine the anatomical differences between two groups of subjects. The surface-based measures I can select are thickness, area, area.pial, sulc, curv, and jacobian_white. Could anybody tell me what anatomical features the later three (sulc, curv, and jacobian_white) actually measure?
    3. Q: How can I get measurements of the lobes (parietal, temporal, frontal, & occipital)?
    4. Q. How would I calculate the total CSF volume?
    5. Q. What is the unit measure of mean curvature and Gaussian curvature?
    6. Q. What goes into the calculation of subcortical volume? We have tried adding volumes of individual subcortical areas but the total does not equal the subcortical volume provided by aseg. Is the subcortical volume calculation accurate?
    7. Q. How would you perform a power analysis for a whole brain group comparison QDEC analysis?
  7. FreeSurfer & Matlab
    1. Q. Can I load FreeSurfer output in Matlab?
    2. Q. How can I make a histogram of cortical thickness?
    3. Q. How can I obtain the thickness of each vertex, and how can you identify which structure each vertex belongs to?

General

Q. How can I help this FAQ?

A: If you are able to edit pages go ahead! If you don't have permission to write on the Wiki send an e-mail to ppj at netfilter dot com dot br

Q. What are the advantages of FreeSurfer over VBM?

A:

  1. FS uses geometry to do inter-subject registration, which experience has shown results in a much better matching of homologous cortical regions than volumetric techniques.
  2. FS allows you to look at the two components of volume separately (thickness and surface area). It has been found that these two do not necessarily track one another, and in the worst case where one is increasing and the other decreasing the volume change can be 0.
  3. The target that FS uses for registration (the white matter surface geometry) is completely invariant to gm atrophy, so gm changes won't result in a different registration.

Q. How do I know the version of FreeSurfer I'm running?

A: Run:

  • recon-all -version

Q. Is the FreeSurfer source code available?

A: Yes, the source code is accessible via CVS access using the instructions described here.

It is also recommended that you subscribe to the freesurfer mailing list to post questions and monitor solutions from other users.


Computing

Q. How long does it take to finish a reconstruction?

A: It depends on your processor speed and machine performance (notice that dual/quad/hex core or hyperthead won't speed up one analysis significantly), give a look at the link below in the section "Step-wise directives": http://surfer.nmr.mgh.harvard.edu/fswiki/recon-all

Also you can contribute to our running time statistics: https://surfer.nmr.mgh.harvard.edu/fswiki/ReconAllRunTimes

Q. How can I reduce the time of recon-all in a group of patients?

A: FreeSurfer run its process in a non-parallel environment, so you won't have benefit from a dual/quad/hex core machine for a single case analysis. However if you have many cases you can start two FreeSurfer recon-all process in the same machine and theoretically you can reduce by half the time to analyze your group of cases. A similar procedure can also be used in quad/hex-core environment. Note that to take benefit of a multi-core environment you need to use a SMP kernel in your OS.

Q. I want to use freesurfer to quantify cortical thickness, and I want to use the software under Linux. What equipment for computer do you recommend?

This answer requires constant updates:

For Best Performances:

Use a multi-Core processor Intel (a i7-900 or newer series processor or Xeon 6500/7500 Series)

Install at Least 8GB of Memory

If you prefer AMD you can use:

AMD Opteron 12-Core or Phenon II X6

Other alternative much more expensive is: Mac Pro with 12 cores and 16GB RAM.

The number of cores is roughly the number of studies you can process simultaneously. Notice that each process will take 20-24 hrs.

Keep in mind that you need to use the fastest memory in order to achieve maximum benefit from multi-core architecture.

Q. Is it possible to run FreeSurfer in Ubuntu Linux?

A: Yes. Ubuntu Linux is basically a Debian distro, so you should use FreeSurfer RH9 version. Depending on your video card you should disable the DRI using the option NoDRI in the Device section of your X configuration file. Notice that in older Ubuntu version there's a bug that prevents NoDRI from working.

Q. Could I run multiple instances of Freesurfer (on my virtual box)?

A: Yes, it is certainly possible (even advisable) to run more than one copy of Freesurfer on a machine. It depends on how many processor cores you have. You'll need at least 2Gb per process if not 3Gb, one core per process. Open one terminal window for each instance of FreeSurfer, using serperate commands in each terminal window. When running four individual recon-all jobs on four cores, we have found that they will all complete in about 110% of the time of a single run.

When using a virtual box, assign N-1 cores to your virtual box, where N is the total number of processor cores you have, along with at least (N-1) x 2Gb of RAM.

Q. Is it recommended that people use memprage? How are they analyzed? Just sqrt sum sqr of the echoes? Or is there something more elaborate?

A: Yes, particularly for longitudinal. The increased bandwidth makes a huge difference in being able to register across time. And at the moment we do use the rms. An optimal combo would maybe be a tiny bit better, but probably not much difference.


Processing/Re-processing Data in FreeSurfer

Q. Can I run some cases in my dataset using one version of FreeSurfer and others using a different version of FreeSurfer?

A: No, mixing versions is never a good idea as results are expected to differ, if only slightly. The same version of FreeSurfer should be used to process all cases within a dataset.

If you are sourcing the stable or dev version of FreeSurfer from within the NMR center, you are strongly encouraged to created a frozen copy of FreeSurfer for your study. Instructions can be found here.

Q. How to run recon-all in a ssh terminal

A: This is tricky, because recon-all spawns many process and redirect I/O to the terminal that opened it. Run

  • recon-all -s subjid -all > /dev/null 2>&1 </dev/null & disown -a

Q. I had a [Power Outage|Computer Failure|Spilled coffee on computer|etc], how can I resume the recon-all?

A: You can try

recon-all -make all -s subject

Also, depending on your version, there might be a file in the scripts directory called "IsRunning". You should delete this if it is there.

Q. I have already skull-stripped data. Can I submit it to recon-all?

A: If your skull-stripped volume does not have the cerebellum, then no. If it does, then yes, however you will have to run the data a bit differently.

First you must run only -autorecon1 like this:
recon-all -autorecon1 -noskullstrip -s <subjid>

Then you will have to make a symbolic link or copy T1.mgz to brainmask.auto.mgz and a link from brainmask.auto.mgz to brainmask.mgz. Finally, open this brainmask.mgz file and check that it looks okay (there is no skull, cerebellum is intact; use the sample subject bert that comes with your FreeSurfer installation to make sure it looks comparable). From there you can run the final stages of recon-all:
recon-all -autrecon2 -autorecon3 -s <subjid>

Q. I made white matter and pial edits to my volume. Do I need to run -autorecon2-wm and when that is finished run -autorecon2-pial?

A: No. If you made both white matter and pial edits, you only need to run -autorecon2-wm which is higher up in the processing stream (before the steps of -autorecon2-pial). By running -autorecon2-wm, it will perform the steps necessary to fix a white matter edit and then all the remaining steps in -autorecon2 including those steps that -autorecon2-pial would run. The OtherUsefulFlags wiki shows the hierarchy of the -autorecon2 flag shortcuts (-autorecon2-cp starts before -autorecon2-wm which starts before -autorecon2-pial). In general, you should start the processing stream at the earliest step where you made an manual intervention and the rest will be taken care of. Don't forget to run -autorecon3!

Q. One of my cases doesn't have the cerebellum so I adjusted the watershed threshold to fix it. However, at one threshold, the cerebellum is still not included, and at the next the entire skull is there. What should I do?

A: Removal of cerebellum is always bad and must be fixed (cerebellum is included in the subcortical segmentation portion and is needed for a proper atlas alignment). Including skull is not good, but leaving skull is acceptable. The problem being sometimes the wm seg catches skull. So make adjustments till you get cerebellum, then just see what happens with the surfaces given remaining skull, and edit out skull in brainmask.mgz if it hurts it.

For the command line below, try it with and without the -no-wgcaatlas flag. Generally the -wsthresh only needs to be varied.

  • recon-all -skullstrip -wsthresh 35 -clean-bm -no-wsgcaatlas -subjid subjid

If that still doesn't work, try using the multistrip command with the watershed method. This will give an output of 4 sets of different thresholds each for the orig, nu, and T1 volume. You can choose the best one from the set and copy it to brainmask.auto.mgz and run the last step of -skullstrip. More info can be found here: http://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/SkullStripFix


Common Error messages

Q. Help! I got this error message: "mri_watershed error: GLOBAL region of the brain empty!" - what should I do?

A: Run this:
recon-all -skullstrip -no-wsgcaatlas -s <subjid>

If that goes through without error, you can finish processing your data by running:
recon-all -autorecon2 -autorecon3 -s <subjid>

Q. I get an error message from the Talairach Failure Detection. What does this mean?

A: In certain versions of FreeSurfer, the talairach failure detection is too conservative so this may not be a problem. First, you will want to check the talairach transform to make sure it looks okay. Directions on how to do that are here: http://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/Talairach

Essentially, you want to use the command:

tkregister2 --mgz --s <subjid> --fstal

and see if the green lines line up with the anatomy of the blurry brain image. If so, then you can run this subject as you did before, just add -notal-check to your command. For example, recon-all -all -s subjid -notal-check. If the green lines do not line up well with the anatomy, you will want to follow directions on the wiki page mentioned above to fix it.

Q. I get an error during the mri_ca_label step while running recon-all. The last thing it says is: "saving intensity scales to aseg.auto_noCCseg.label_intensities.txt". What's wrong?

A: This is a bug in v.4.5. A fixed mri_ca_label can be downloaded from here:
ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/misc/linux-centos4_x86_64/

copy it your $FREESURFER_HOME/bin

We would advise rerunning all subjects with this fixed version.

Q. I get an error during the Talairach transform step when running recon-all on ANALYZE images. Why is this happening?

A: Images in the ANALYZE format do not retain orientation information (left/right). You can bypass the Talairach check by including the '-notal-check' flag in your recon-all command. Alternatively, you can specify the orientation (neurological or radiological) using mri_convert. Run 'mri_convert --help' to get info on specifying volume orientation in the description section. Lastly, you can manually register your brain volume in Talairach space by following this tutorial.


FreeSurfer Output Questions

Q. The surfaces near the medial wall, hippocampus, and amygdala aren't accurately following the structures there. How can I fix this?

A: The good news is you don't have to! These areas are generally unreliable for a thickness study so you would want to exclude them from your analysis. If you use glmfit, it calls the ?h.cortex.label file in order to determine thickness. This file automatically has set these areas to zero so they will not be included in your analysis. To see what area ?h.cortex.label excludes you can load it in tksurfer on top of the inflated surface. If you have tkmedit open at the same time for the same subject, you can use the Go To Saved Point function to make sure areas of concern are in this excluded section. *Note: If you are using a FreeSurfer version older than 4.3.0, the excluded region includes the insula. If you are using an analysis program other than glmfit, just be sure to use the ?h.cortex.label file to get your thickness measurements.

The picture below shows the ?h.cortex.label (outlined in yellow) over the ?h.aparc.annot. Notice how the ?h.cortex.label includes some of the ?h.unknown.label:
cortex_label_over_aparc.jpeg

As always, use the example subject bert that comes with the FreeSurfer installation to see what we define as acceptable surfaces.

Q: It seems that there is a 5mm thickness upper limit in my volumes, is it normal? How can I change this?

A: We did this to prevent noncortical regions such as the basal ganglia from corrupting the thickness measure through averaging. With the ?h.cortex.label it is probably no longer needed, however you can use mris_thickness -max <max thick> to generate a thickness with a different max. Take a look in the example below:

mris_thickness -max 10 bert lh newlh.thickness

The file newlh.thickness will be created inside the surf directory of your subject. But we don't think the true thickness is ever that much except in pathological cases like dysplasia and other disorders of cortical development.

Q. Why in many subjects the insular cortical surface seems so thick? Is the convoluted nature of the Insula that causes that?

A: It's not the convoluted nature of the Insula. It's the fact that extreme capsule is so thin that it frequently isn't very apparent on MR, and so there appears to be continuous gray matter from the basal ganglia into the cortex. We think version 4.0 fixes this.

Q. What are the sulc and curv overlays (in QDEC) showing us?

A: The 'sulc' conveys information on how far removed a particular vertex point on a surface is from a hypothetical "mid-surface" that exists between the gyri and sulci. This surface is chosen so that the "mean" of all these displacements is zero. The 'sulc' gives a indication then of linear distance and displacements: how "deep" and how "high" are brain folds

In FreeSurfer, gyri have negative 'sulc' values, are colored green, and indicate how far "down" a point has to travel to reach this "mid-surface". Sulci have positive 'sulc' values, are colored red, and indicate how far "up" a point needs to travel to reach the mid-surface.

The 'curv' conveys information on the curvature (not distance) at a specific vertex point. The color conveys the sign, and is just an arbitrary choice. The sharper the curve, the higher the value (positive or negative). Areas with positive curvature, are colored red, and correspond to curvatures in sulci, i.e. curving "up". Areas with negative curvature are colored green, and correspond to curves pointing "down", i.e. gyri.

So, in a nutshell, the difference is that the 'curv' files contain information about curvatures, and the 'sulc' files contain information about displacement.

Q. How would I put a FreeSurfer output volume and/or segmentation back into the same space as my original anatomical input (native space)?

A: Please see directions on how to do this here, and also on this page http://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems

Q. How do I transform coordinates in one space to those in another space (eg, a point on the surface to MNI305 space or to the col, row, slice of a functional volume)?

A: Directions on how to do this are on this page: http://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems

Q. The pial surface includes some cerebellum. How can I fix this?

A: This fix only works for v4.3 and up. If you are using an earlier version, please contact us for help.

In order to fix this problem, you will have to edit the brain.finalsurfs.mgz (and not the brainmask.mgz). Remove the parts of the cerebellum that are affecting the surfaces. Save your changes and then run:
recon-all -make all -s subjid

Q. How do I get the cortical thickness maps for several subjects into the same template space (fsaverage)?

A: Include the '-qcache -measure thickness' flags in your recon-all command for each subject. This will create files in the /surf directory which sample the thickness data at different smoothing levels onto the fsaverage subject space. If the '-measure' flag is not included, all cortical measurements will be sampled onto fsaverage and smoothed (thickness, sulc, area, curv, etc.).

Q. Where can I find V1 labels?

A: V1 labeling is produced by default in recon-all as part of the Brodmann area set (located in ../fsaverage/label/?h.V1.label). Those labels are described here. The Hind's V1 labeling method must be run seperately by adding the '-label-v1' flag to your recon-all command:

recon-all -all -s bert -label-v1

The accuracy of the Hinds and Fischl V1 labeling method compared to retinotopy depends under what conditions the retinotopy is carried out (field strength, # of coils elements, voxel size, etc.). In our comparision, the folding patterns predict the border location to about 2.5mm, which is probably better than you can get with retinotopy.


Analysis of FreeSurfer Data

Q. I am trying to measure the cortical thickness of specific ROI how can I do this?

A: You can save the ROI to a label file and then use:

  • mris_anatomical_stats -l <label file>

Q. I am using QDEC to examine the anatomical differences between two groups of subjects. The surface-based measures I can select are thickness, area, area.pial, sulc, curv, and jacobian_white. Could anybody tell me what anatomical features the later three (sulc, curv, and jacobian_white) actually measure?


sulc = "average convexity" from our 1999 reconII paper(https://surfer.nmr.mgh.harvard.edu/ftp/articles/fischl99b-recon2.pdf).
Essentially measures the depth/height of each point above the average surface.
curv = smoothed mean curvature.
jacobian_white = the jacobian of the spherical transform. Measures the amount of distortion needed to warp a subject into register with the atlas.
You might want to look at the slides downloadable from the top of this page:

http://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial
which contain pictures showing the meaning of 'curv' and 'sulc'.

Q: How can I get measurements of the lobes (parietal, temporal, frontal, & occipital)?

A: You can either use the PALS_B12 atlas (mapped to fsaverage in v5.0) or create your own following the directions on the CorticalParcellation wiki.

Q. How would I calculate the total CSF volume?

A: You can add up the various ventricular structures to get total ventricular volume, but we don't segment sulcal CSF, since it's not distinguishible from bone on a T1-weighted MRI.

Q. What is the unit measure of mean curvature and Gaussian curvature?

A: See these wiki pages for more info: Mean curvature, Gaussian curvature

Q. What goes into the calculation of subcortical volume? We have tried adding volumes of individual subcortical areas but the total does not equal the subcortical volume provided by aseg. Is the subcortical volume calculation accurate?

A: The aseg.stats file takes into account partial voluming which is not taken into account when you simply sum up the subcortical structures because some of those structures will be partially volumed with white matter.

Q. How would you perform a power analysis for a whole brain group comparison QDEC analysis?

A: For the power analysis, you need four things:

  1. Effect Size
  2. Number of Subjects
  3. Target False Positive Rate (alpha)
  4. Target False Negative Rate (beta)

Given any 3, you can compute the 4th. You can get the Effect Size from the output of the QDEC analysis. Each analysis creates a GLM directory, and there is a directory for each contrast in the GLM dir. In the contrast dir, you will find several files, but the important ones for this are the gamma.mgh and the gammavar.mgh. The gammavar is the square of the error bar (ie, t=gamma/sqrt(gammavar)). The gamma will not change as you add subjects (at least in expectation). The gammavar will drop linearly with the number of subjects (again in expectation). The effect size will then be gamma/sqrt(gammavar*Npilot), where Npilot is the number subjects in the pilot study. In a new study with Nnew subjects, the expected t will be tnew = gamma/sqrt(gammavar*Npilot/Nnew).


FreeSurfer & Matlab

Q. Can I load FreeSurfer output in Matlab?

A: If you write it as .mgz format then load_mgh (or MRIread) will read it

Q. How can I make a histogram of cortical thickness?

A: In Matlab you can use the read_curv() function, as in the example below.

  • thick = read_curv ('/usr/local/freesurfer/subjects/bert/surfer/lh.thickness');
    hist (thick,100);


    Notice that there are many zero values that refer to areas where there's no cortical surface. The best procedure is to create a new array without the zero values and then make the histogram.

Q. How can I obtain the thickness of each vertex, and how can you identify which structure each vertex belongs to?

A: You will need to use the read_curv() function to get the thickness estimates, and use the read_annotation() function to assign each index in the surface vector to a specific structure. You can then match up corresponding indices in the the thickness vector and the structure vector to determine the thickness and structure label for each vertex.

UserContributions/FAQ (last edited 2019-12-14 14:15:45 by DougGreve)