FreeSurfer MRI reconstruction

FreeSurfer is an open source analysis toolbox for MRI data. It contains several command line tools and graphical user interfaces. FreeSurfer can be obtained from https://surfer.nmr.mgh.harvard.edu/

In MNE, FreeSurfer is used to provide structural information of various kinds, for source estimation. Thereby a subject specific structural MRI will be used to obtain various structural representations like spherical or inflated brain surfaces. Furthermore features like curvature as well as various labels for areas of interest (such as V1) are computed.

Thus FreeSurfer provides an easy way to shift anatomically related data between different representations and spaces. See e.g. Morphing and averaging source estimates for information about how to use FreeSurfer surface representations to allow functional data to morph between different subjects.

First steps

After downloading and installing, the environment needs to be set up correctly. This can be done by setting the FreeSurfer’s root directory correctly and sourcing the setup file:

$ export FREESURFER_HOME=/path/to/FreeSurfer
$ source $FREESURFER_HOME/SetUpFreeSurfer.sh

Note

The FreeSurfer home directory might vary depending on your operating system. See the FreeSurfer installation guide for more.

Another important step is to define the subject directory correctly. SUBJECTS_DIR must be defined such, that it contains the individual subject’s reconstructions in separate sub-folders. Those sub-folders will be created upon the reconstruction of the anatomical data. Nevertheless the parent directory has to be set beforehand:

$ export SUBJECTS_DIR=~/subjects

Again see the FreeSurfer installation guide for more.

Once setup correctly, FreeSurfer will create a new subject folder in $SUBJECTS_DIR.

Anatomical reconstruction

MNE-Python works together with FreeSurfer in order to compute the forward model and setting up the corresponding source space. See Setting up the source space for more information. Usually a full FreeSurfer reconstruction is obtained by prompting the following command to a bash console (e.g. Linux or MacOS Terminal):

$ my_subject=sample
$ my_NIfTI=/path/to/NIfTI.nii.gz
$ recon-all -i $my_NIfTI -s $my_subject -all

where i stands for “input” and s for “subject”. Executing this, will create the folder “~/subjects/sample”, where all results are stored.

Note

This compution takes often several hours. Please be patient.

Within a single subject all the files MNE-Python uses (and some more) are grouped into meaningful sub-folders (such that “surf” contains surface representations, “mri” volumetric files, etc.).

FreeSurfer performs a hemispheric separation and most results are present in a left and right hemisphere version. This is often indicated by the prefix lh or rh to refer to the aforementioned. For that reason data representations such as mne.SourceEstimate carry two sets of spatial locations (vertices) for both hemispheres separately. See also The SourceEstimate data structure.

import mne
subjects_dir = mne.datasets.sample.data_path() + '/subjects'
Brain = mne.viz.get_brain_class()
brain = Brain('sample', hemi='lh', surf='pial',
              subjects_dir=subjects_dir, size=(800, 600))
brain.add_annotation('aparc.a2009s', borders=False)

‘fsaverage’

During installation, FreeSurfer copies a “default” subject, called 'fsaverage' to $FREESURFER_HOME/subjects/fsaverage. It contains all data types that a subject reconstruction would yield and is required by MNE-Python.

See https://surfer.nmr.mgh.harvard.edu/fswiki/FsAverage for more information. Furthermore a copy of ‘fsaverage’ can be found in Writing examples.

When using 'fsaverage' as value for the definition of a subject when calling a function, the corresponding data will be read (e.g., subject='fsaverage') from ‘~/subjects/fsaverage’. This becomes especially handy, when attempting statistical analyses on group level, based on individual’s brain space data. In that case 'fsaverage' will by default act as reference space for source estimate transformations.

For example, to reproduce a typical header image used by FreeSurfer, we can plot the aparc parcellation:

Use with MNE-Python

For source localization analyses to work properly, it is important that the FreeSurfer reconstruction has completed beforehand. Furthermore, when using related functions, such as mne.setup_source_space(), SUBJECTS_DIR has to be defined either globally by setting mne.set_config() or for each function separately, by passing the respective keyword argument subjects_dir='~/subjects'.

See also Setting up the source space to get an idea of how this works for one particular function, and How MNE uses FreeSurfer’s outputs for how the two are integrated.

Estimated memory usage: 12 MB