[[FreeSurferWiki|top]]

= FreeSurfer Beginners Guide =

!FreeSurfer is a freely available software package developed by investigators at the [[http://www.nmr.mgh.harvard.edu:|Athinoula A. Martinos Center for Biomedical Imaging]] used for a number of procedures including:

        1.      Creation of computerized models of the brain from magnetic resonance imaging (MRI) data.

        2.      Processing of functional magnetic resonance imaging (fMRI) data.

        3.      Measuring a number of morphometric properties of the brain including cortical thickness and regional volumes.

        4.      Intersubject averaging of structural and functional data using a procedure that aligns individuals based on their cortical folding patterns for optimal alignment of homologous neural regions.

'''Machine Requirements'''

        To run FreeSurfer, you will need either a PC running Linux or a Macintosh running OS X.

        FreeSurfer consumes a lot of processor time, memory resources and disk space, so it is recommended to run FreeSurfer on as powerful a machine as you have available.  For example, at MGH we typically run Linux CentOS 5 on 2.5GHz quad processor Intel Xeon with 4 to 8 GB of DDR SDRAM, and 500GB of disk space.

        See SystemRequirements for more info.

'''Data Requirements'''

        The processing procedures for the creation of cortical models require good quality T1 weighted MRI data, such as a Siemens MPRAGE ([[http://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferWiki?action=AttachFile&do=get&target=FreeSurfer_Suggested_Morphometry_Protocols.pdf|examples of appropriate Siemens scanner protocols]]) or GE SPGR sequence with approximately 1mm^3^ resolution (although a variety of quality data sets can be processed with additional manual intervention).  Thickness should not exceed 1.5mm (~1mm^3 is ideal). [[http://adni.loni.ucla.edu/methods/documents/mri-protocols/|The protocols specified for the ADNI project are excellent examples to follow.]] The best FreeSurfer processing results come from scans having excellent gray/white matter contrast.

{{attachment:example_scan_A.jpg}}
{{attachment:example_scan_B.jpg}}
{{attachment:example_scan_C.jpg}}

            * '''A''' - excellent GM/WM contrast, acquired with MP-RAGE pulse-sequence protocol
            * '''B''' - very good GM/WM contrast, acquired with MP-RAGE pulse-sequence protocol
            * '''C''' - good GM/WM contrast, acquired with SPGR pulse-sequence protocol; not as good GM/WM contrast as the MP-RAGE acquisitions; low bandwidth causes some temporal lobe artifacts (brightening of the gray matter)

        These example scans, captured from FreeSurfer's tkmedit display, are slices from the brainmask.mgz file, created by the -autorecon1 stage of FreeSurfer (requiring about 20 minutes of processing time).  This means that some amount of intensity normalization has occurred, but the contrast differences between image examples are easier to see, compared to the original (orig.mgz) volume.  Refer to the tutorial sections [[FsTutorial/ControlPoints|'Using Control Points to Fix Intensity Normalization']] and [[FsTutorial/WhiteMatterEdits|'Fixing Common Geometric Inaccuracies in White Matter Surfaces']] for examples of problem areas resulting from scan deficiencies.

'''Getting Started'''

        There is a variety of documentation about the use of FreeSurfer contained in the FreeSurfer wiki including [[TeachYourselfFreeSurfer|a collection of talks and tutorials to teach yourself how to use FreeSurfer]], [[DownloadAndInstall|installation of the software]], [[FsTutorial|tutorials]], [[FsTutorial/Data|sample data]], and [[WorkFlows|work flows]] providing step by step guides to performing specific tasks.

        To get started, we suggest you:

            1.      Read the links to slides marked as type 'talk' in the tutorials: [[FsTutorial|click here]]

            2.      Read the background material: [[https://www.zotero.org/freesurfer|click here]]

            3.      Install FreeSurfer: [[DownloadAndInstall|click here]]

            4.      Download the sample data set: [[FsTutorial/Data|click here]]

            5.      Follow the cortical reconstruction tutorial to create cortical models: [[FsTutorial|click here]]

            6.      Follow the reconstruction workflow page: [[RecommendedReconstruction|click here]]

            7.      Peruse the wiki to get a fuller knowledge of all of the available processing procedures in the FreeSurfer software package
            8.      Process your own data with a command such as this:
                    {{{
recon-all \
  -i  <one slice in the anatomical dicom series> \
  -s  <subject id that you make up> \
  -sd <directory to put the subject folder in> \
  -all
   }}}
where the input (-i) file is a single file representing a T1-weighted data set. If you have DICOM images, you must find a file in the T1 series to pass. You can do this with the dcmunack command. 

An active [[FreeSurferSupport|e-mail list]] is available to answer specific questions about processing procedures.

There is also a [[UserContributions/FAQ|FAQ]]