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.
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
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
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
i stands for “input” and
s for “subject”. Executing
this, will create the folder “~/subjects/sample”, where all
results are stored.
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
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.
During installation, FreeSurfer copies a “default” subject, called
$FREESURFER_HOME/subjects/fsaverage. It contains all
data types that a subject reconstruction would yield and is required by
See https://surfer.nmr.mgh.harvard.edu/fswiki/FsAverage for more information. Furthermore a copy of ‘fsaverage’ can be found in Writing examples.
'fsaverage' as value for the definition
of a subject when calling a function, the corresponding data will be read
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
For source localization analyses to work properly, it is important that the
FreeSurfer reconstruction has completed beforehand. Furthermore, when using
related functions, such as
has to be defined either globally by setting
mne.set_config() or for
each function separately, by passing the respective keyword argument
Total running time of the script: ( 0 minutes 2.154 seconds)
Estimated memory usage: 12 MB