{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# FreeSurfer MRI reconstruction\n\nThis tutorial covers how to use FreeSurfer alongside MNE-Python, to handle the\nstructural MRI data that we use to build subject-specific anatomical models of\nthe scalp, inner/outer skull, and cortical surface.\n\nFreeSurfer is an open source analysis toolbox for MRI data, available from\nhttps://surfer.nmr.mgh.harvard.edu/. FreeSurfer provides graphical interfaces\nfor visualizing MRI data, several anatomical parcellations useful for creating\nregion-of-interest (ROI) labels, template brains such as ``fsaverage``, and\nseveral command-line tools for tasks like finding tissue boundaries or morphing\nbrains to align analogous anatomical regions across subjects.\n\nThese FreeSurfer capabilities are necessary for MNE-Python to compute the\n:term:`forward model <forward>` and set up the corresponding `source space\n<mne.SourceSpaces>` (a grid of dipoles located on the cortical surface or\nwithin the brain volume).\n\n\n## First steps\n\nAfter downloading and installing FreeSurfer, there are a few steps to set up\nthe environment. First is to define an environment variable ``FREESURFER_HOME``\nand then run the FreeSurfer setup script:\n\n```console\n$ export FREESURFER_HOME=/path/to/FreeSurfer\n$ source $FREESURFER_HOME/SetUpFreeSurfer.sh\n```\n<div class=\"alert alert-info\"><h4>Note</h4><p>The FreeSurfer home directory will vary depending on your operating\n    system and choices you made during installation. See the `FreeSurfer\n    installation guide`_ for more info.</p></div>\n\n\nAnother important step is to tell FreeSurfer where to put the anatomical\nreconstructions of your research subjects. This is done with an environment\nvariable called ``SUBJECTS_DIR``, which will contain the individual subjects'\nreconstructions in separate sub-folders.\n\n```console\n$ export SUBJECTS_DIR=/path/to/your/subjects_dir\n```\nAgain see the `FreeSurfer installation guide`_ for more info.\n\n\n## Anatomical reconstruction\n\nThe first processing stage is the creation of various surface reconstructions.\nUsually a full FreeSurfer reconstruction is obtained by the following commands:\n\n```console\n$ my_subject=sample\n$ my_NIfTI=/path/to/NIfTI.nii.gz\n$ recon-all -i $my_NIfTI -s $my_subject -all\n```\nwhere ``i`` stands for \"input\" and ``s`` for \"subject\". Executing this will\ncreate the folder :file:`$SUBJECTS_DIR/sample` and populate it\nwith several subfolders (``bem``, ``label``, ``mri``, etc). See also the\nFreeSurfer wiki's `recommended reconstruction workflow`_ for more detailed\nexplanation.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>Anatomical reconstruction can take several hours, even on a fast computer.</p></div>\n\nFreeSurfer performs a hemispheric separation so most resulting files have\nseparate left and right hemisphere versions, indicated by the prefix\n``lh`` or ``rh``. This hemispheric separation is preserved by MNE-Python (e.g.,\n`mne.SourceEstimate` objects store spatial locations (vertices) for the two\nhemispheres separately; cf. `tut-source-estimate-class`).\n\nBelow we show an example of the results of a FreeSurfer reconstruction for the\nleft hemisphere of the `sample-dataset` dataset subject, including an\noverlay of an anatomical parcellation (in this case, the parcellation from\n:footcite:`DestrieuxEtAl2010`).\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Authors: The MNE-Python contributors.\n# License: BSD-3-Clause\n# Copyright the MNE-Python contributors."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import mne\n\nsample_data_folder = mne.datasets.sample.data_path()\nsubjects_dir = sample_data_folder / \"subjects\"\nBrain = mne.viz.get_brain_class()\nbrain = Brain(\n    \"sample\", hemi=\"lh\", surf=\"pial\", subjects_dir=subjects_dir, size=(800, 600)\n)\nbrain.add_annotation(\"aparc.a2009s\", borders=False)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Use with MNE-Python\n\nFor source localization analysis to work properly, it is important that the\nFreeSurfer reconstruction has completed beforehand. Furthermore, for many\nMNE-Python functions related to inverse imaging (such as\n`mne.setup_source_space`), ``SUBJECTS_DIR`` has to be defined globally (as an\nenvironment variable or through a call to `mne.set_config`), or specified\nseparately in each function call by passing the keyword argument\n``subjects_dir='/path/to/your/subjects_dir'``.\n\nSee `setting_up_source_space` to get an idea of how this works for one\nparticular function, and `tut-freesurfer-mne` for more details on how\nMNE-Python and FreeSurfer are integrated.\n\n\n## 'fsaverage'\n\nDuring installation, FreeSurfer copies a subject called ``'fsaverage'`` to\n``$FREESURFER_HOME/subjects/fsaverage``. ``fsaverage`` is a template brain\nbased on a combination of 40 MRI scans of real brains. The ``fsaverage``\nsubject folder contains all the files that a normal subject reconstruction\nwould yield. See https://surfer.nmr.mgh.harvard.edu/fswiki/FsAverage for an\noverview, and https://surfer.nmr.mgh.harvard.edu/fswiki/Buckner40Notes for\ndetails about the subjects used to create ``fsaverage``. A copy of\n``fsaverage`` is also provided as part of the `sample-dataset` dataset\nand is also distributed as a `standalone dataset <fsaverage>`.\n\nOne of the most common uses of ``fsaverage`` is as a destination space for\ncortical morphing / `source estimate transformations <ch_morph>`. In\nother words, it is common to morph each individual subject's estimated brain\nactivity onto the ``fsaverage`` brain, so that group-level statistical\ncomparisons can be made.\n\n\n## References\n\n.. footbibliography::\n\n   https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall\n   https://surfer.nmr.mgh.harvard.edu/fswiki/RecommendedReconstruction\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.12.2"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}