# -*- coding: utf-8 -*-
r"""
.. _tut-freesurfer:

======================================
FreeSurfer integration with MNE-Python
======================================

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 :ref:`source estimation <tut-inverse-methods>`. 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.
:ref:`ch_morph` for information about how to
use FreeSurfer surface representations to allow functional data to morph
between different subjects.

.. contents::
    :local:

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
    <https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall>`_ 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
<https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall>`_ 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 :class:`source space <mne.SourceSpaces>`. See
:ref:`setting_up_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 :code:`i` stands for "input" and :code:`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 :class:`mne.SourceEstimate` carry two sets of
spatial locations (vertices) for both hemispheres separately. See also
:ref:`tut-source-estimate-class`.

'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
:ref:`sample-data`.

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 :ref:`source estimate transformations <ch_morph>`.

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 :func:`mne.setup_source_space`, ``SUBJECTS_DIR`` has
to be defined either globally by setting :func:`mne.set_config` or for
each function separately, by passing the respective keyword argument
``subjects_dir='~/subjects'``. See also :ref:`setting_up_source_space` to get
an idea of how this works.
"""
