diff -Nru python-mne-0.18.1+dfsg/azure-pipelines.yml python-mne-0.19.1+dfsg/azure-pipelines.yml --- python-mne-0.18.1+dfsg/azure-pipelines.yml 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/azure-pipelines.yml 2019-10-25 14:42:45.000000000 +0000 @@ -13,23 +13,22 @@ variables: MNE_LOGGING_LEVEL: 'warning' MNE_FORCE_SERIAL: 'true' - PIP_DEPENDENCIES: 'codecov' OPENBLAS_NUM_THREADS: 1 AZURE_CI_WINDOWS: 'true' + PYTHON_VERSION: '3.7' + CONDA_VERSION: '>=4.3.27' strategy: maxParallel: 4 matrix: # Eventually we should test x86 (32-bit), but it was a nightmare # to get it to download 32-bit Anaconda properly, and VTK does not ship # 32-bit Windows binaries via pip. - Python36-64bit-full-conda: - PYTHON_VERSION: '3.6' + Python37-64bit-full-conda: PLATFORM: 'x86-64' TEST_MODE: 'conda' - CONDA_ENVIRONMENT: 'environment.yml' + CONDA_ENV: 'environment.yml' PIP_NO_UPGRADE: 'True' Python37-64bit-full-pip: - PYTHON_VERSION: '3.7' PYTHON_ARCH: 'x64' TEST_MODE: 'pip' steps: @@ -52,8 +51,7 @@ $PSDefaultParameterValues['*:ErrorAction']='Stop' pip install --upgrade numpy scipy vtk pip install --upgrade -r requirements.txt - pip install $env:PIP_DEPENDENCIES - pip install pylsl + pip install codecov condition: eq(variables['TEST_MODE'], 'pip') displayName: 'Install dependencies with pip' - powershell: | @@ -62,13 +60,13 @@ $PSDefaultParameterValues['*:ErrorAction']='Stop' $env:PYTHON = '$(System.DefaultWorkingDirectory)' + '\conda' git clone git://github.com/astropy/ci-helpers.git - cd ci-helpers - git checkout nopip - cd .. powershell ci-helpers/appveyor/install-miniconda.ps1 - $env:PATH = $env:PYTHON + "\envs\test;" + $env:PYTHON + "\envs\test\Scripts;" + $env:PYTHON + ";" + $env:PYTHON + "\Scripts;" + $env:PATH + $env:PATH = $env:PYTHON + ";" + $env:PYTHON + "\Scripts;" + $env:PYTHON + "\Library\bin;" + $env:PATH + conda env list + conda install numpy scipy matplotlib scikit-learn + conda env update --file $env:CONDA_ENV pip uninstall -yq mne - pip install pylsl + pip install codecov Write-Host ("##vso[task.setvariable variable=PATH]" + $env:PATH) condition: eq(variables['TEST_MODE'], 'conda') displayName: 'Install dependencies with conda' @@ -78,7 +76,7 @@ displayName: 'Print config' - script: python -c "import mne; mne.datasets.testing.data_path(verbose=True)" displayName: 'Get test data' - - script: pytest -m "not ultraslowtest" mne --cov=mne + - script: pytest -m "not ultraslowtest" --cov=mne mne displayName: 'Run tests' - script: codecov --root %BUILD_REPOSITORY_LOCALPATH% -t %CODECOV_TOKEN% displayName: 'Codecov' diff -Nru python-mne-0.18.1+dfsg/bin/mne python-mne-0.19.1+dfsg/bin/mne --- python-mne-0.18.1+dfsg/bin/mne 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/bin/mne 2019-10-25 14:42:45.000000000 +0000 @@ -1,40 +1,5 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- -import sys -import glob -import subprocess -import os.path as op - import mne - -mne_bin_dir = op.dirname(mne.__file__) -valid_commands = sorted(glob.glob(op.join(mne_bin_dir, - 'commands', 'mne_*.py'))) -valid_commands = [c.split(op.sep)[-1][4:-3] for c in valid_commands] - - -def print_help(): - print("Usage : mne command options\n") - print("Accepted commands :\n") - for c in valid_commands: - print("\t- %s" % c) - print("\nExample : mne browse_raw --raw sample_audvis_raw.fif") - print("\nGetting help example : mne compute_proj_eog -h") - sys.exit(0) - - -if len(sys.argv) == 1: - print_help() -elif ("help" in sys.argv[1] or "-h" in sys.argv[1]): - print_help() -elif sys.argv[1] == "--version": - print("MNE %s" % mne.__version__) -elif sys.argv[1] not in valid_commands: - print('Invalid command: "%s"\n' % sys.argv[1]) - print_help() - sys.exit(0) -else: - cmd = sys.argv[1] - cmd_path = op.join(mne_bin_dir, 'commands', 'mne_%s.py' % cmd) - sys.exit(subprocess.call([sys.executable, cmd_path] + sys.argv[2:])) +mne.commands.utils.main() diff -Nru python-mne-0.18.1+dfsg/.circleci/artifact_path python-mne-0.19.1+dfsg/.circleci/artifact_path --- python-mne-0.18.1+dfsg/.circleci/artifact_path 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/.circleci/artifact_path 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1 @@ +0/dev/index.html diff -Nru python-mne-0.18.1+dfsg/.circleci/config.yml python-mne-0.19.1+dfsg/.circleci/config.yml --- python-mne-0.18.1+dfsg/.circleci/config.yml 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/.circleci/config.yml 2019-10-25 14:42:45.000000000 +0000 @@ -66,8 +66,16 @@ sudo apt-get install qt5-default - run: + name: Install graphviz and fonts needed for diagrams + command: | + sudo apt-get install graphviz + mkdir -p $HOME/.fonts + curl https://codeload.github.com/adobe-fonts/source-code-pro/tar.gz/2.030R-ro/1.050R-it | tar xz -C $HOME/.fonts + curl https://codeload.github.com/adobe-fonts/source-sans-pro/tar.gz/2.045R-ro/1.095R-it | tar xz -C $HOME/.fonts + fc-cache -f + + - run: name: Get Python running - # pip install --user --upgrade --progress-bar off https://api.github.com/repos/larsoner/numpydoc/zipball/xref-param-type command: | pip install --user --upgrade --progress-bar off pip numpy vtk pip install --user --upgrade --progress-bar off -r requirements.txt @@ -85,6 +93,7 @@ which python python -c "import mne; mne.sys_info()" LIBGL_DEBUG=verbose python -c "from mayavi import mlab; import matplotlib.pyplot as plt; mlab.figure(); plt.figure()" + python -c "import mne; mne.set_config('MNE_USE_CUDA', 'false')" # this is needed for the config tutorial python -c "import mne; mne.set_config('MNE_LOGGING_LEVEL', 'info')" python -c "import mne; level = mne.get_config('MNE_LOGGING_LEVEL'); assert level.lower() == 'info', repr(level)" @@ -101,7 +110,7 @@ if [ "$CIRCLE_BRANCH" == "master" ] || [[ $(cat gitlog.txt) == *"[circle full]"* ]]; then echo html_dev > build.txt; python -c "import mne; mne.datasets._download_all_example_data()"; - elif [ "$CIRCLE_BRANCH" == "maint/0.18" ]; then + elif [ "$CIRCLE_BRANCH" == "maint/0.19" ]; then echo html_stable > build.txt; python -c "import mne; mne.datasets._download_all_example_data()"; else @@ -128,7 +137,10 @@ python -c "import mne; print(mne.datasets.somato.data_path(update_path=True))"; fi; if [[ $(cat $FNAME | grep -x ".*datasets.*eegbci.*" | wc -l) -gt 0 ]]; then - python -c "import mne; print(mne.datasets.eegbci.load_data(1, [6, 10, 14], update_path=True))"; + python -c "import mne; print(mne.datasets.eegbci.load_data(1, [3, 6, 10, 14], update_path=True))"; + python -c "import mne; print(mne.datasets.eegbci.load_data(2, [3], update_path=True))"; + python -c "import mne; print(mne.datasets.eegbci.load_data(3, [3], update_path=True))"; + python -c "import mne; print(mne.datasets.eegbci.load_data(4, [3], update_path=True))"; fi; if [[ $(cat $FNAME | grep -x ".*datasets.*sleep_physionet.*" | wc -l) -gt 0 ]]; then python -c "import mne; print(mne.datasets.sleep_physionet.age.fetch_data([0, 1], recording=[1], update_path=True))"; @@ -151,10 +163,6 @@ if [[ $(cat $FNAME | grep -x ".*brainstorm.*bst_phantom_elekta.*" | wc -l) -gt 0 ]]; then python -c "import mne; print(mne.datasets.brainstorm.bst_phantom_elekta.data_path(update_path=True))" --accept-brainstorm-license; fi; - if [[ $(cat $FNAME | grep -x ".*datasets.*megsim.*" | wc -l) -gt 0 ]]; then - python -c "import mne; print(mne.datasets.megsim.load_data(condition='visual', data_format='single-trial', data_type='simulation', update_path=True))"; - python -c "import mne; print(mne.datasets.megsim.load_data(condition='visual', data_format='raw', data_type='experimental', update_path=True))"; - fi; if [[ $(cat $FNAME | grep -x ".*datasets.*hcp_mmp_parcellation.*" | wc -l) -gt 0 ]]; then python -c "import mne; print(mne.datasets.sample.data_path(update_path=True))"; python -c "import mne; print(mne.datasets.fetch_hcp_mmp_parcellation())" --accept-hcpmmp-license; @@ -183,6 +191,9 @@ if [[ $(cat $FNAME | grep -x ".*datasets.*phantom_4dbti.*" | wc -l) -gt 0 ]]; then python -c "import mne; print(mne.datasets.phantom_4dbti.data_path(update_path=True))"; fi; + if [[ $(cat $FNAME | grep -x ".*datasets.*limo.*" | wc -l) -gt 0 ]]; then + python -c "import mne; print(mne.datasets.limo.data_path(subject=2, update_path=True))"; + fi; fi; done; echo PATTERN="$PATTERN"; @@ -222,6 +233,15 @@ command: | python -c "import mne; level = mne.get_config('MNE_LOGGING_LEVEL'); assert level.lower() == 'info', repr(level)" + # Reduce upload time of artifacts we will (almost) never look at + - run: + name: Reduce artifact upload time + command: | + if grep -q html_dev-pattern build.txt || grep -q html_dev-noplot build.txt; then + tar czf doc/_build/html/_downloads.tgz doc/_build/html/_downloads + rm -Rf doc/_build/html/_downloads + fi + # Save the JUnit file - store_test_results: path: doc/_build/test-results @@ -286,6 +306,7 @@ key: data-cache-8 paths: - ~/mne_data/MNE-visual_92_categories-data + - ~/mne_data/MNE-limo-data linkcheck: @@ -341,7 +362,7 @@ name: Deploy docs command: | set -e; - if [ "${CIRCLE_BRANCH}" == "master" ] || [ "${CIRCLE_BRANCH}" == "maint/0.18" ]; then + if [ "${CIRCLE_BRANCH}" == "master" ] || [ "${CIRCLE_BRANCH}" == "maint/0.19" ]; then git config --global user.email "circle@mne.com"; git config --global user.name "Circle CI"; cd ~/mne-tools.github.io; @@ -385,7 +406,7 @@ branches: only: - master - - maint/0.18 + - maint/0.19 weekly: jobs: diff -Nru python-mne-0.18.1+dfsg/CONTRIBUTING.rst python-mne-0.19.1+dfsg/CONTRIBUTING.rst --- python-mne-0.18.1+dfsg/CONTRIBUTING.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/CONTRIBUTING.rst 2019-10-25 14:42:45.000000000 +0000 @@ -31,4 +31,4 @@ .. _`pull request`: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork .. _`code of conduct`: https://github.com/mne-tools/mne-python/blob/master/CODE_OF_CONDUCT.md -.. _`contributing guide`: https://mne-tools.github.io/dev/contributing.html +.. _`contributing guide`: https://mne-tools.github.io/dev/install/contributing.html diff -Nru python-mne-0.18.1+dfsg/.coveragerc python-mne-0.19.1+dfsg/.coveragerc --- python-mne-0.18.1+dfsg/.coveragerc 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/.coveragerc 2019-10-25 14:42:45.000000000 +0000 @@ -7,3 +7,9 @@ */bin/* */setup.py */mne/fixes* + */mne/utils/linalg.py + +[report] +exclude_lines = + pragma: no cover + if __name__ == .__main__.: diff -Nru python-mne-0.18.1+dfsg/debian/changelog python-mne-0.19.1+dfsg/debian/changelog --- python-mne-0.18.1+dfsg/debian/changelog 2019-09-01 12:38:58.000000000 +0000 +++ python-mne-0.19.1+dfsg/debian/changelog 2019-12-03 08:52:14.000000000 +0000 @@ -1,3 +1,17 @@ +python-mne (0.19.1+dfsg-1) unstable; urgency=medium + + * Team upload. + * Breaks+Replaces: python-mne + Closes: #939623 + * debhelper-compat 12 + * Standards-Version: 4.4.1 + * Replace Build-Depends forcing Python2 to mayavi2 (python-vtk6 | python-vtk) + by python3-vtk7 + * Recommends: s/mayavi2/python3-vtk7/ + Suggests: mayavi2 + + -- Andreas Tille Tue, 03 Dec 2019 09:52:14 +0100 + python-mne (0.18.1+dfsg-0.1) unstable; urgency=medium * Non-maintainer upload (with team approval). diff -Nru python-mne-0.18.1+dfsg/debian/compat python-mne-0.19.1+dfsg/debian/compat --- python-mne-0.18.1+dfsg/debian/compat 2019-09-01 12:38:58.000000000 +0000 +++ python-mne-0.19.1+dfsg/debian/compat 1970-01-01 00:00:00.000000000 +0000 @@ -1 +0,0 @@ -12 diff -Nru python-mne-0.18.1+dfsg/debian/control python-mne-0.19.1+dfsg/debian/control --- python-mne-0.18.1+dfsg/debian/control 2019-09-01 12:38:58.000000000 +0000 +++ python-mne-0.19.1+dfsg/debian/control 2019-12-03 08:52:14.000000000 +0000 @@ -1,69 +1,66 @@ Source: python-mne Maintainer: Debian Med Packaging Team -Uploaders: - Yaroslav Halchenko , - Michael Hanke , +Uploaders: Yaroslav Halchenko , + Michael Hanke Section: python Testsuite: autopkgtest-pkg-python Priority: optional -Build-Depends: - debhelper (>= 12~), - dh-python, - libgl1-mesa-dri, - libjs-jquery, - libjs-jquery-ui, - mayavi2 (>= 4.4.3~) | python-vtk6 | python-vtk, - python3-all, - python3-coverage, - python3-joblib, - python3-matplotlib, - python3-nibabel, - python3-nose, - python3-numpy, - python3-pytest, - python3-pytest-cov, - python3-scipy, - python3-setuptools, - python3-sklearn, - python3-tk, - python3-sphinx, - xauth, - xvfb, - yui-compressor, -Standards-Version: 4.3.0 +Build-Depends: debhelper-compat (= 12), + dh-python, + libgl1-mesa-dri, + libjs-jquery, + libjs-jquery-ui, + python3-vtk7, + python3-all, + python3-coverage, + python3-joblib, + python3-matplotlib, + python3-nibabel, + python3-nose, + python3-numpy, + python3-pytest, + python3-pytest-cov, + python3-scipy, + python3-setuptools, + python3-sklearn, + python3-tk, + python3-sphinx, + xauth, + xvfb, + yui-compressor +Standards-Version: 4.4.1 Vcs-Browser: https://salsa.debian.org/med-team/python-mne Vcs-Git: https://salsa.debian.org/med-team/python-mne.git Homepage: http://martinos.org/mne Package: python3-mne Architecture: all -Depends: - help2man, - libgl1-mesa-dri, - libjs-bootstrap, - libjs-d3, - libjs-jquery, - libjs-jquery-ui, - python3-joblib, - python3-matplotlib, - python3-numpy, - python3-scipy, - python3-sklearn, - xauth, - xvfb, - ${misc:Depends}, - ${python3:Depends}, -Recommends: - mayavi2, - python3-nibabel, - python3-nose, - python3-pytest, -Suggests: - ipython, - python3-dap, - python3-pycuda, -Provides: - ${python3:Provides}, +Depends: help2man, + libgl1-mesa-dri, + libjs-bootstrap, + libjs-d3, + libjs-jquery, + libjs-jquery-ui, + python3-joblib, + python3-matplotlib, + python3-numpy, + python3-scipy, + python3-sklearn, + xauth, + xvfb, + ${misc:Depends}, + ${python3:Depends} +Recommends: python3-vtk7, + python3-nibabel, + python3-nose, + python3-pytest +Suggests: mayavi2, + ipython, + python3-dap, + python3-pycuda +Breaks: python-mne +Provides: ${python3:Provides} +Replaces: python-mne Description: Python modules for MEG and EEG data analysis This package is designed for sensor- and source-space analysis of MEG and EEG data, including frequency-domain and time-frequency analyses diff -Nru python-mne-0.18.1+dfsg/debian/copyright python-mne-0.19.1+dfsg/debian/copyright --- python-mne-0.18.1+dfsg/debian/copyright 2019-09-01 12:38:58.000000000 +0000 +++ python-mne-0.19.1+dfsg/debian/copyright 2019-12-03 08:52:14.000000000 +0000 @@ -2,7 +2,8 @@ Upstream-Name: MNE-Python Upstream-Contact: Alexandre Gramfort Source: http://github.com/mne-tools/mne-python -Files-Excluded: mne/html/*.min.js +Files-Excluded: mne/html/jquery.js + mne/html/*.min.js mne/html/*.min.css Comment: File AppEULA.rst refers to code that is documented in this package but not shipped with it. @@ -33,18 +34,10 @@ Copyright: 2010, Prasanth Nair, License: BSD-2-Clause -Files: mne/externals/six.py -Copyright: 2010-2013 Benjamin Peterson -License: Expat - Files: mne/externals/tempita/* Copyright: 2008 Ian Bicking and Contributors License: Expat -Files: mne/html/mpld3* -Copyright: 2013, Jake Vanderplas -License: BSD-3-Clause - License: BSD-2-Clause Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are diff -Nru python-mne-0.18.1+dfsg/debian/patches/deb_paths python-mne-0.19.1+dfsg/debian/patches/deb_paths --- python-mne-0.18.1+dfsg/debian/patches/deb_paths 2019-09-01 12:38:58.000000000 +0000 +++ python-mne-0.19.1+dfsg/debian/patches/deb_paths 2019-12-03 08:52:14.000000000 +0000 @@ -7,29 +7,12 @@ --- a/mne/report.py +++ b/mne/report.py -@@ -1359,16 +1359,21 @@ +@@ -1368,7 +1368,7 @@ class Report(object): @verbose def _init_render(self, verbose=None): """Initialize the renderer.""" -- inc_fnames = ['jquery-1.10.2.min.js', 'jquery-ui.min.js', -+ inc_fnames = ['/usr/share/javascript/jquery/jquery.min.js', -+ '/usr/share/javascript/jquery-ui/jquery-ui.min.js', +- inc_fnames = ['jquery.js', 'jquery-ui.min.js', ++ inc_fnames = ['/usr/share/javascript/jquery/jquery.min.js', '/usr/share/javascript/jquery-ui/jquery-ui.min.js', 'bootstrap.min.js', 'jquery-ui.min.css', 'bootstrap.min.css'] - include = list() - for inc_fname in inc_fnames: - logger.info('Embedding : %s' % inc_fname) -- fname = op.join(op.dirname(__file__), 'html', inc_fname) -- with open(fname, 'rb') as fid: -- file_content = fid.read().decode('utf-8') -+ if not os.path.isabs(inc_fname): -+ inc_fname = op.join(op.dirname(__file__), 'html', inc_fname) -+ f = open(inc_fname, 'r') -+ if PY3: -+ file_content = f.read() -+ else: -+ file_content = f.read().decode('UTF-8') - if inc_fname.endswith('.js'): - include.append(u'') diff -Nru python-mne-0.18.1+dfsg/debian/patches/python3.patch python-mne-0.19.1+dfsg/debian/patches/python3.patch --- python-mne-0.18.1+dfsg/debian/patches/python3.patch 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/debian/patches/python3.patch 2019-12-03 08:52:14.000000000 +0000 @@ -0,0 +1,24 @@ +Description: Fix Python 3 issue +Author: Thomas Goirand , + Jaakko Leppakangas +Last-Update: Sun, 01 Sep 2019 14:38:58 +0200 + +--- a/mne/report.py ++++ b/mne/report.py +@@ -1375,9 +1375,13 @@ class Report(object): + include = list() + for inc_fname in inc_fnames: + logger.info('Embedding : %s' % inc_fname) +- fname = op.join(op.dirname(__file__), 'html', inc_fname) +- with open(fname, 'rb') as fid: +- file_content = fid.read().decode('utf-8') ++ if not os.path.isabs(inc_fname): ++ inc_fname = op.join(op.dirname(__file__), 'html', inc_fname) ++ f = open(inc_fname, 'r') ++ if PY3: ++ file_content = f.read() ++ else: ++ file_content = f.read().decode('UTF-8') + if inc_fname.endswith('.js'): + include.append(u'') diff -Nru python-mne-0.18.1+dfsg/debian/patches/series python-mne-0.19.1+dfsg/debian/patches/series --- python-mne-0.18.1+dfsg/debian/patches/series 2019-09-01 12:38:58.000000000 +0000 +++ python-mne-0.19.1+dfsg/debian/patches/series 2019-12-03 08:52:14.000000000 +0000 @@ -1,3 +1,4 @@ deb_skip_segfaultingtests deb_paths +python3.patch up_check_numpy diff -Nru python-mne-0.18.1+dfsg/debian/patches/up_check_numpy python-mne-0.19.1+dfsg/debian/patches/up_check_numpy --- python-mne-0.18.1+dfsg/debian/patches/up_check_numpy 2019-09-01 12:38:58.000000000 +0000 +++ python-mne-0.19.1+dfsg/debian/patches/up_check_numpy 2019-12-03 08:52:14.000000000 +0000 @@ -6,16 +6,16 @@ --- a/mne/decoding/tests/test_receptive_field.py +++ b/mne/decoding/tests/test_receptive_field.py -@@ -10,7 +10,7 @@ +@@ -10,7 +10,7 @@ from numpy.testing import assert_array_e from mne import io, pick_types - from mne.fixes import einsum + from mne.fixes import einsum, rfft, irfft -from mne.utils import requires_version, requires_sklearn, run_tests_if_main +from mne.utils import requires_version, requires_sklearn, run_tests_if_main, check_version from mne.decoding import ReceptiveField, TimeDelayingRidge from mne.decoding.receptive_field import (_delay_time_series, _SCORERS, _times_to_delays, _delays_to_slice) -@@ -521,6 +521,9 @@ +@@ -521,6 +521,9 @@ def test_inverse_coef(): rf = ReceptiveField(tmin, tmax, 1., estimator=estimator, patterns=True) rf.fit(X, y) diff -Nru python-mne-0.18.1+dfsg/doc/advanced_setup.rst python-mne-0.19.1+dfsg/doc/advanced_setup.rst --- python-mne-0.18.1+dfsg/doc/advanced_setup.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/advanced_setup.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,174 +0,0 @@ -.. include:: links.inc - -.. _advanced_setup: - -Advanced setup of MNE-Python -============================ - -.. contents:: - :local: - :depth: 1 - -Using MNE-Python with IPython / Jupyter notebooks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When using MNE-Python within IPython or a Jupyter notebook, we strongly -recommend using the Qt matplotlib backend for fast and correct rendering. On -Linux, for example, Qt is the only matplotlib backend for which 3D rendering -will work correctly. On macOS, certain matplotlib functions might not work as -expected on backends other than Qt. Enabling Qt can be accomplished when -starting IPython from a terminal: - -.. code-block:: console - - $ ipython --matplotlib=qt - -or in a Jupyter Notebook, you can use the "magic" command: - -.. code-block:: ipython - - In [1]: %matplotlib qt - -This will create separate pop-up windows for each figure, and has the advantage -that the 3D plots will retain rich interactivity (so, for example, you can -click-and-drag to rotate cortical surface activation maps). - -If you are creating a static notebook or simply prefer Jupyter's inline plot -display, MNE-Python will work with the standard "inline" magic: - -.. code-block:: ipython - - In [1]: %matplotlib inline - -but some functionality will be lost. For example, mayavi scenes will still -pop-up a separate window, but only one window at a time is possible, and -interactivity within the scene is limited in non-blocking plot calls. - -.. admonition:: |windows| Windows - :class: note - - If you are using MNE-Python on Windows through IPython or Jupyter, you might - also have to use the IPython magic command ``%gui qt`` after importing - MNE-Python, Mayavi or PySurfer (see `here - `_). For example: - - .. code-block:: ipython - - In [1]: from mayavi import mlab - In [2]: %gui qt - -If you use another Python setup and you encounter some difficulties please -report them on the `MNE mailing list`_ or on the `GitHub issues page`_ to get -assistance. - -.. _installing_master: - -Using the development version of MNE-Python (latest master) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you want access to the latest features and bugfixes, you can easily switch -from the stable version of MNE-Python to the current development version. - -.. warning:: In between releases, function and class APIs can change without - warning. - -For a one-time update to latest master, make sure you're in the ``mne`` conda -environment (``conda activate mne``), and use ``pip``: - -.. code-block:: console - - $ pip install --upgrade --no-deps git+https://github.com/mne-tools/mne-python.git - -If you plan to contribute to MNE-Python, or just prefer to use git rather than -pip to make frequent updates, check out the :ref:`contributing guide -`. - -.. _other-py-distros: - -Using MNE-Python with other Python distributions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -While the `Anaconda`_ Python distribution provides many conveniences, other -distributions of Python should also work with MNE-Python. In particular, -`Miniconda`_ is a lightweight alternative to Anaconda that is fully compatible; -like Anaconda, Miniconda includes the ``conda`` command line tool for -installing new packages and managing environments; unlike Anaconda, Miniconda -starts off with a minimal set of around 30 packages instead of Anaconda's -hundreds. See the `installation instructions for Miniconda`_ for more info. - -It is also possible to use a system-level installation of Python (version 3.5 -or higher) and use ``pip`` to install MNE-Python and its dependencies, using -the provided `requirements file`_: - -.. code-block:: console - - curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/requirements.txt - pip install --user requirements.txt - -Other configurations will probably also work, but we may be unable to offer -support if you encounter difficulties related to your particular Python -installation choices. - -.. _CUDA: - -Using MNE-Python with CUDA (NVIDIA GPU acceleration) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Some operations in MNE-Python can utilize `NVIDIA CUDA GPU processing`_ to -speed up some operations (e.g. FIR filtering) by roughly an order of magnitude. -To use CUDA, first ensure that you are running the `NVIDIA proprietary -drivers`_ on your operating system, and then do: - -.. code-block:: console - - $ conda install cupy - $ MNE_USE_CUDA=true python -c "import mne; mne.cuda.init_cuda(verbose=True)" - Enabling CUDA with 1.55 GB available memory - -If you receive a message reporting the GPU's available memory, CuPy_ -is working properly. To permanently enable CUDA in MNE, you can do:: - - >>> mne.utils.set_config('MNE_USE_CUDA', 'true') # doctest: +SKIP - -You can then test MNE CUDA support by running the associated test: - -.. code-block:: console - - $ pytest mne/tests/test_filter.py -k cuda - -If the tests pass, then CUDA should work in MNE. You can use CUDA in methods -that state that they allow passing ``n_jobs='cuda'``, such as -:meth:`mne.io.Raw.filter` and :meth:`mne.io.Raw.resample`, -and they should run faster than the CPU-based multithreading such as -``n_jobs=8``. - -Off-screen rendering in MNE-Python on Linux with MESA -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -On remote systems, it might be possible to use MESA software rendering -(such as ``llvmpipe`` or ``swr``) for 3D visualization (with some tweaks). -For example, on CentOS 7.5 you might be able to use an environment variable -to force MESA to use modern OpenGL by using this before executing -``spyder`` or ``python``: - -.. code-block:: console - - $ export MESA_GL_VERSION_OVERRIDE=3.3 - -Also, it's possible that different software rending backends might perform -better than others, such as using the ``llvmpipe`` backend rather than ``swr``. - -Troubleshooting 3D plots in MNE-Python -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you run into trouble when visualizing source estimates (or anything else -using mayavi), you can try setting a couple of environment variables at the -beginning of your script, session, or notebook:: - - >>> import os - >>> os.environ['ETS_TOOLKIT'] = 'qt4' - >>> os.environ['QT_API'] = 'pyqt5' - -This will tell mayavi to use Qt backend with PyQt bindings, instead of the -default PySide. For more information, see -http://docs.enthought.com/mayavi/mayavi/building_applications.html#integrating-in-a-qt-application. diff -Nru python-mne-0.18.1+dfsg/doc/carousel.inc python-mne-0.19.1+dfsg/doc/carousel.inc --- python-mne-0.18.1+dfsg/doc/carousel.inc 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/carousel.inc 2019-10-25 14:42:45.000000000 +0000 @@ -19,7 +19,7 @@

Source estimation

Distributed, sparse, mixed-norm, beamformers, dipole fitting, and more.

-

Check it out

+

Check it out

@@ -30,7 +30,7 @@

Statistics

Parametric and non-parametric, permutation tests and clustering.

-

Check it out

+

Check it out

@@ -41,7 +41,7 @@

Machine learning

Advanced decoding models including time generalization.

-

Check it out

+

Check it out

@@ -52,7 +52,7 @@

Encoding models

Receptive field estimation with optional smoothness priors.

-

Check it out

+

Check it out

@@ -74,7 +74,7 @@

Data visualization.

Explore your data from multiple perspectives.

-

Check it out

+

Check it out

diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.10.inc python-mne-0.19.1+dfsg/doc/changes/0.10.inc --- python-mne-0.18.1+dfsg/doc/changes/0.10.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.10.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,148 @@ +.. _changes_0_10: + +Version 0.10 +------------ + +Changelog +~~~~~~~~~ + +- Add support for generalized M-way repeated measures ANOVA for fully balanced designs with :func:`mne.stats.f_mway_rm` by `Denis Engemann`_ + +- Add epochs browser to interactively view and manipulate epochs with :func:`mne.viz.plot_epochs` by `Jaakko Leppakangas`_ + +- Speed up TF-MxNE inverse solver with block coordinate descent by `Daniel Strohmeier`_ and `Yousra Bekhti`_ + +- Speed up zero-phase overlap-add (default) filtering by a factor of up to 2 using linearity by `Ross Maddox`_ and `Eric Larson`_ + +- Add support for scaling and adjusting the number of channels/time per view by `Jaakko Leppakangas`_ + +- Add support to toggle the show/hide state of all sections with a single keypress ('t') in :class:`mne.Report` by `Mainak Jas`_ + +- Add support for BEM model creation :func:`mne.make_bem_model` by `Eric Larson`_ + +- Add support for BEM solution computation :func:`mne.make_bem_solution` by `Eric Larson`_ + +- Add ICA plotters for raw and epoch components by `Jaakko Leppakangas`_ + +- Add new object ``mne.decoding.TimeDecoding`` for decoding sensors' evoked response across time by `Jean-Remi King`_ + +- Add command ``mne freeview_bem_surfaces`` to quickly check BEM surfaces with Freeview by `Alex Gramfort`_. + +- Add support for splitting epochs into multiple files in :func:`mne.Epochs.save` by `Mainak Jas`_ and `Alex Gramfort`_ + +- Add support for jointly resampling a raw object and event matrix to avoid issues with resampling status channels by `Marijn van Vliet`_ + +- Add new method :class:`mne.preprocessing.Xdawn` for denoising and decoding of ERP/ERF by `Alexandre Barachant`_ + +- Add support for plotting patterns/filters in :class:`mne.decoding.CSP` and :class:`mne.decoding.LinearModel` by `Romain Trachel`_ + +- Add new object :class:`mne.decoding.LinearModel` for decoding M/EEG data and interpreting coefficients of linear models with patterns attribute by `Romain Trachel`_ and `Alex Gramfort`_ + +- Add support to append new channels to an object from a list of other objects by `Chris Holdgraf`_ + +- Add interactive plotting of topomap from time-frequency representation by `Jaakko Leppakangas`_ + +- Add ``plot_topo`` method to ``Evoked`` object by `Jaakko Leppakangas`_ + +- Add fetcher :mod:`mne.datasets.brainstorm ` for datasets used by Brainstorm in their tutorials by `Mainak Jas`_ + +- Add interactive plotting of single trials by right clicking on channel name in epochs browser by `Jaakko Leppakangas`_ + +- New logos and logo generation script by `Daniel McCloy`_ + +- Add ability to plot topomap with a "skirt" (channels outside of the head circle) by `Marijn van Vliet`_ + +- Add multiple options to ICA infomax and extended infomax algorithms (number of subgaussian components, computation of bias, iteration status printing), enabling equivalent computations to those performed by EEGLAB by `Jair Montoya Martinez`_ + +- Add :func:`mne.Epochs.apply_baseline` method to ``Epochs`` objects by `Teon Brooks`_ + +- Add ``preload`` argument to :func:`mne.read_epochs` to enable on-demand reads from disk by `Eric Larson`_ + +- Big rewrite of simulation module by `Yousra Bekhti`_, `Mark Wronkiewicz`_, `Eric Larson`_ and `Alex Gramfort`_. Allows to simulate raw with artifacts (ECG, EOG) and evoked data, exploiting the forward solution. See :func:`mne.simulation.simulate_raw`, :func:`mne.simulation.simulate_evoked` and :func:`mne.simulation.simulate_sparse_stc` + +- Add :func:`mne.Epochs.load_data` method to :class:`mne.Epochs` by `Teon Brooks`_ + +- Add support for drawing topomaps by selecting an area in :func:`mne.Evoked.plot` by `Jaakko Leppakangas`_ + +- Add support for finding peaks in evoked data in :func:`mne.Evoked.plot_topomap` by `Jona Sassenhagen`_ and `Jaakko Leppakangas`_ + +- Add source space morphing in :func:`morph_source_spaces` and :func:`SourceEstimate.to_original_src` by `Eric Larson`_ and `Denis Engemann`_ + +- Adapt ``corrmap`` function (Viola et al. 2009) to semi-automatically detect similar ICs across data sets by `Jona Sassenhagen`_ and `Denis Engemann`_ and `Eric Larson`_ + +- Clarify docstring for :class:`mne.preprocessing.ICA` by `jeythekey`_ + +- New ``mne flash_bem`` command to compute BEM surfaces from Flash MRI images by `Lorenzo Desantis`_, `Alex Gramfort`_ and `Eric Larson`_. See :func:`mne.bem.make_flash_bem`. + +- New gfp parameter in :func:`mne.Evoked.plot` method to display Global Field Power (GFP) by `Eric Larson`_. + +- Add :meth:`mne.Report.add_slider_to_section` methods to :class:`mne.Report` by `Teon Brooks`_ + +BUG +~~~ + +- Fix ``mne.io.add_reference_channels`` not setting ``info[nchan]`` correctly by `Federico Raimondo`_ + +- Fix ``mne.stats.bonferroni_correction`` reject mask output to use corrected p-values by `Denis Engemann`_ + +- Fix FFT filter artifacts when using short windows in overlap-add by `Eric Larson`_ + +- Fix picking channels from forward operator could return a channel ordering different from ``info['chs']`` by `Chris Bailey`_ + +- Fix dropping of events after downsampling stim channels by `Marijn van Vliet`_ + +- Fix scaling in :func:``mne.viz.utils._setup_vmin_vmax`` by `Jaakko Leppakangas`_ + +- Fix order of component selection in :class:`mne.decoding.CSP` by `Clemens Brunner`_ + +API +~~~ + +- Rename and deprecate ``mne.viz.plot_topo`` for ``mne.viz.plot_evoked_topo`` by `Jaakko Leppakangas`_ + +- Deprecated :class: `mne.decoding.transformer.ConcatenateChannels` and replaced by :class: `mne.decoding.transformer.EpochsVectorizer` by `Romain Trachel`_ + +- Deprecated `lws` and renamed `ledoit_wolf` for the ``reg`` argument in :class:`mne.decoding.CSP` by `Romain Trachel`_ + +- Redesigned and rewrote :meth:`mne.Epochs.plot` (no backwards compatibility) during the GSOC 2015 by `Jaakko Leppakangas`_, `Mainak Jas`_, `Federico Raimondo`_ and `Denis Engemann`_ + +- Deprecated and renamed ``mne.viz.plot_image_epochs`` for ``mne.plot.plot_epochs_image`` by `Teon Brooks`_ + +- ``picks`` argument has been added to :func:`mne.time_frequency.tfr_morlet`, :func:`mne.time_frequency.tfr_multitaper` by `Teon Brooks`_ + +- ``mne.io.Raw.preload_data`` has been deprecated for :func:`mne.io.Raw.load_data` by `Teon Brooks`_ + +- ``RawBrainVision`` objects now always have event channel ``'STI 014'``, and recordings with no events will have this channel set to zero by `Eric Larson`_ + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number of commits): + +* 273 Eric Larson +* 270 Jaakko Leppakangas +* 194 Alexandre Gramfort +* 128 Denis A. Engemann +* 114 Jona Sassenhagen +* 107 Mark Wronkiewicz +* 97 Teon Brooks +* 81 Lorenzo De Santis +* 55 Yousra Bekhti +* 54 Jean-Remi King +* 48 Romain Trachel +* 45 Mainak Jas +* 40 Alexandre Barachant +* 32 Marijn van Vliet +* 26 Jair Montoya +* 22 Chris Holdgraf +* 16 Christopher J. Bailey +* 7 Christian Brodbeck +* 5 Natalie Klein +* 5 Fede Raimondo +* 5 Alan Leggitt +* 5 Roan LaPlante +* 5 Ross Maddox +* 4 Dan G. Wakeman +* 3 Daniel McCloy +* 3 Daniel Strohmeier +* 1 Jussi Nurminen diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.11.inc python-mne-0.19.1+dfsg/doc/changes/0.11.inc --- python-mne-0.18.1+dfsg/doc/changes/0.11.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.11.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,92 @@ +.. _changes_0_11: + +Version 0.11 +------------ + +Changelog +~~~~~~~~~ + +- Maxwell filtering (SSS) implemented in :func:`mne.preprocessing.maxwell_filter` by `Mark Wronkiewicz`_ as part of Google Summer of Code, with help from `Samu Taulu`_, `Jukka Nenonen`_, and `Jussi Nurminen`_. Our implementation includes support for: + + - Fine calibration + + - Cross-talk correction + + - Temporal SSS (tSSS) + + - Head position translation + + - Internal component regularization + +- Compensation for movements using Maxwell filtering on epoched data in :func:`mne.epochs.average_movements` by `Eric Larson`_ and `Samu Taulu`_ + +- Add reader for Nicolet files in :func:`mne.io.read_raw_nicolet` by `Jaakko Leppakangas`_ + +- Add FIFF persistence for ICA labels by `Denis Engemann`_ + +- Display ICA labels in :func:`mne.viz.plot_ica_scores` and :func:`mne.viz.plot_ica_sources` (for evoked objects) by `Denis Engemann`_ + +- Plot spatially color coded lines in :func:`mne.Evoked.plot` by `Jona Sassenhagen`_ and `Jaakko Leppakangas`_ + +- Add reader for CTF data in :func:`mne.io.read_raw_ctf` by `Eric Larson`_ + +- Add support for Brainvision v2 in :func:`mne.io.read_raw_brainvision` by `Teon Brooks`_ + +- Improve speed of generalization across time ``mne.decoding.GeneralizationAcrossTime`` decoding up to a factor of seven by `Jean-Remi King`_ and `Federico Raimondo`_ and `Denis Engemann`_. + +- Add the explained variance for each principal component, ``explained_var``, key to the :class:`mne.Projection` by `Teon Brooks`_ + +- Added methods ``mne.Epochs.add_eeg_average_proj``, ``mne.io.Raw.add_eeg_average_proj``, and ``mne.Evoked.add_eeg_average_proj`` to add an average EEG reference. + +- Add reader for EEGLAB data in :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab` by `Mainak Jas`_ + +BUG +~~~ + +- Fix bug that prevented homogeneous bem surfaces to be displayed in HTML reports by `Denis Engemann`_ + +- Added safeguards against ``None`` and negative values in reject and flat parameters in :class:`mne.Epochs` by `Eric Larson`_ + +- Fix train and test time window-length in ``mne.decoding.GeneralizationAcrossTime`` by `Jean-Remi King`_ + +- Added lower bound in :func:`mne.stats.linear_regression` on p-values ``p_val`` (and resulting ``mlog10_p_val``) using double floating point arithmetic limits by `Eric Larson`_ + +- Fix channel name pick in :func:`mne.Evoked.get_peak` method by `Alex Gramfort`_ + +- Fix drop percentages to take into account ``ignore`` option in :func:`mne.viz.plot_drop_log` and :func:`mne.Epochs.plot_drop_log` by `Eric Larson`_. + +- :class:`mne.EpochsArray` no longer has an average EEG reference silently added (but not applied to the data) by default. Use ``mne.EpochsArray.add_eeg_ref`` to properly add one. + +- Fix :func:`mne.io.read_raw_ctf` to read ``n_samp_tot`` instead of ``n_samp`` by `Jaakko Leppakangas`_ + +API +~~~ + +- :func:`mne.io.read_raw_brainvision` now has ``event_id`` argument to assign non-standard trigger events to a trigger value by `Teon Brooks`_ + +- :func:`mne.read_epochs` now has ``add_eeg_ref=False`` by default, since average EEG reference can be added before writing or after reading using the method ``mne.Epochs.add_eeg_ref``. + +- :class:`mne.EpochsArray` no longer has an average EEG reference silently added (but not applied to the data) by default. Use ``mne.EpochsArray.add_eeg_average_proj`` to properly add one. + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number of commits): + +* 171 Eric Larson +* 117 Jaakko Leppakangas +* 58 Jona Sassenhagen +* 52 Mainak Jas +* 46 Alexandre Gramfort +* 33 Denis A. Engemann +* 28 Teon Brooks +* 24 Clemens Brunner +* 23 Christian Brodbeck +* 15 Mark Wronkiewicz +* 10 Jean-Remi King +* 5 Marijn van Vliet +* 3 Fede Raimondo +* 2 Alexander Rudiuk +* 2 emilyps14 +* 2 lennyvarghese +* 1 Marian Dovgialo diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.12.inc python-mne-0.19.1+dfsg/doc/changes/0.12.inc --- python-mne-0.18.1+dfsg/doc/changes/0.12.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.12.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,211 @@ +.. _changes_0_12: + +Version 0.12 +------------ + +Changelog +~~~~~~~~~ + +- Add ``overlay_times`` parameter to :func:`mne.viz.plot_epochs_image` to be able to display for example reaction times on top of the images, by `Alex Gramfort`_ + +- Animation for evoked topomap in :func:`mne.Evoked.animate_topomap` by `Jaakko Leppakangas`_ + +- Make :func:`mne.channels.find_layout` more robust for KIT systems in the presence of bad or missing channels by `Jaakko Leppakangas`_ + +- Add raw movement compensation to :func:`mne.preprocessing.maxwell_filter` by `Eric Larson`_ + +- Add :class:`mne.Annotations` for for annotating segments of raw data by `Jaakko Leppakangas`_ + +- Add reading of .fif file montages by `Eric Larson`_ + +- Add system config utility :func:`mne.sys_info` by `Eric Larson`_ + +- Automatic cross-validation and scoring metrics in ``mne.decoding.GeneralizationAcrossTime``, by `Jean-Remi King`_ + +- ``mne.decoding.GeneralizationAcrossTime`` accepts non-deterministic cross-validations, by `Jean-Remi King`_ + +- Add plotting RMS of gradiometer pairs in :func:`mne.viz.plot_evoked_topo` by `Jaakko Leppakangas`_ + +- Add regularization methods to :func:`mne.compute_raw_covariance` by `Eric Larson`_. + +- Add command ``mne show_info`` to quickly show the measurement info from a .fif file from the terminal by `Alex Gramfort`_. + +- Add creating forward operator for dipole object :func:`mne.make_forward_dipole` by `Chris Bailey`_ + +- Add reading and estimation of fixed-position dipole time courses (similar to Elekta ``xfit``) using :func:`mne.read_dipole` and :func:`mne.fit_dipole` by `Eric Larson`_. + +- Accept ``mne.decoding.GeneralizationAcrossTime``'s ``scorer`` parameter to be a string that refers to a scikit-learn_ metric scorer by `Asish Panda`_. + +- Add method :func:`mne.Epochs.plot_image` calling :func:`mne.viz.plot_epochs_image` for better usability by `Asish Panda`_. + +- Add :func:`mne.io.read_raw_cnt` for reading Neuroscan CNT files by `Jaakko Leppakangas`_ + +- Add ``decim`` parameter to ``mne.time_frequency.cwt_morlet``, by `Jean-Remi King`_ + +- Add method :func:`mne.Epochs.plot_topo_image` by `Jaakko Leppakangas`_ + +- Add the ability to read events when importing raw EEGLAB files, by `Jona Sassenhagen`_. + +- Add function :func:`mne.viz.plot_sensors` and methods :func:`mne.Epochs.plot_sensors`, :func:`mne.io.Raw.plot_sensors` and :func:`mne.Evoked.plot_sensors` for plotting sensor positions and :func:`mne.viz.plot_layout` and :func:`mne.channels.Layout.plot` for plotting layouts by `Jaakko Leppakangas`_ + +- Add epoch rejection based on annotated segments by `Jaakko Leppakangas`_ + +- Add option to use new-style MEG channel names in :func:`mne.read_selection` by `Eric Larson`_ + +- Add option for ``proj`` in :class:`mne.EpochsArray` by `Eric Larson`_ + +- Enable the usage of :func:`mne.viz.plot_topomap` with an :class:`mne.Info` instance for location information, by `Jona Sassenhagen`_. + +- Add support for electrocorticography (ECoG) channel type by `Eric Larson`_ + +- Add option for ``first_samp`` in :func:`mne.make_fixed_length_events` by `Jon Houck`_ + +- Add ability to auto-scale channel types for :func:`mne.viz.plot_raw` and :func:`mne.viz.plot_epochs` and corresponding object plotting methods by `Chris Holdgraf`_ + +BUG +~~~ + +- ``mne.time_frequency.compute_raw_psd``, ``mne.time_frequency.compute_epochs_psd``, :func:`mne.time_frequency.psd_multitaper`, and :func:`mne.time_frequency.psd_welch` no longer remove rows/columns of the SSP matrix before applying SSP projectors when picks are provided by `Chris Holdgraf`_. + +- :func:`mne.Epochs.plot_psd` no longer calls a Welch PSD, and instead uses a Multitaper method which is more appropriate for epochs. Flags for this function are passed to :func:`mne.time_frequency.psd_multitaper` by `Chris Holdgraf`_ + +- Time-cropping functions (e.g., :func:`mne.Epochs.crop`, :func:`mne.Evoked.crop`, :func:`mne.io.Raw.crop`, :func:`mne.SourceEstimate.crop`) made consistent with behavior of ``tmin`` and ``tmax`` of :class:`mne.Epochs`, where nearest sample is kept. For example, for MGH data acquired with ``sfreq=600.614990234``, constructing ``Epochs(..., tmin=-1, tmax=1)`` has bounds ``+/-1.00064103``, and now ``epochs.crop(-1, 1)`` will also have these bounds (previously they would have been ``+/-0.99897607``). Time cropping functions also no longer use relative tolerances when determining the boundaries. These changes have minor effects on functions that use cropping under the hood, such as :func:`mne.compute_covariance` and :func:`mne.connectivity.spectral_connectivity`. Changes by `Jaakko Leppakangas`_ and `Eric Larson`_ + +- Fix EEG spherical spline interpolation code to account for average reference by `Mainak Jas`_ + +- MEG projectors are removed after Maxwell filtering by `Eric Larson`_ + +- Fix ``mne.decoding.TimeDecoding`` to allow specifying ``clf`` by `Jean-Remi King`_ + +- Fix bug with units (uV) in 'Brain Vision Data Exchange Header File Version 1.0' by `Federico Raimondo`_ + +- Fix bug where :func:`mne.preprocessing.maxwell_filter` ``destination`` parameter did not properly set device-to-head transform by `Eric Larson`_ + +- Fix bug in rank calculation of ``mne.utils.estimate_rank``, :func:`mne.io.Raw.estimate_rank`, and covariance functions where the tolerance was set to slightly too small a value, new 'auto' mode uses values from ``scipy.linalg.orth`` by `Eric Larson`_. + +- Fix bug when specifying irregular ``train_times['slices']`` in ``mne.decoding.GeneralizationAcrossTime``, by `Jean-Remi King`_ + +- Fix colorbar range on norm data by `Jaakko Leppakangas`_ + +- Fix bug in :func:`mne.preprocessing.run_ica`, which used the ``ecg_criterion`` parameter for the EOG criterion instead of ``eog_criterion`` by `Christian Brodbeck`_ + +- Fix normals in CTF data reader by `Eric Larson`_ + +- Fix bug in :func:`mne.io.read_raw_ctf`, when omitting samples at the end by `Jaakko Leppakangas`_ + +- Fix ``info['lowpass']`` value for downsampled raw data by `Eric Larson`_ + +- Remove measurement date from :class:`mne.Info` in :func:`mne.io.Raw.anonymize` by `Eric Larson`_ + +- Fix bug that caused synthetic ecg channel creation even if channel was specified for ECG peak detection in :func:`mne.preprocessing.create_ecg_epochs` by `Jaakko Leppakangas`_ + +- Fix bug with vmin and vmax when None is passed in :func:`mne.viz.plot_topo_image_epochs` by `Jaakko Leppakangas`_ + +- Fix bug with :func:`mne.label_sign_flip` (and :func:`mne.extract_label_time_course`) by `Natalie Klein`_ and `Eric Larson`_ + +- Add copy parameter in :func:`mne.Epochs.apply_baseline` and :func:`mne.io.Raw.filter` methods by `Jona Sassenhagen`_ and `Alex Gramfort`_ + +- Fix bug in :func:`mne.merge_events` when using ``replace_events=False`` by `Alex Gramfort`_ + +- Fix bug in :class:`mne.Evoked` type setting in :func:`mne.stats.linear_regression_raw` by `Eric Larson`_ + +- Fix bug in :class: `mne.io.edf.RawEDF` highpass filter setting to take max highpass to match warning message by `Teon Brooks`_ + +- Fix bugs with coordinane frame adjustments in ``mne.viz.plot_trans`` by `Eric Larson`_ + +- Fix bug in colormap selection in :func:`mne.Evoked.plot_projs_topomap` by `Jaakko Leppakangas`_ + +- Fix bug in source normal adjustment that occurred when 1) patch information is available (e.g., when distances have been calculated) and 2) points are excluded from the source space (by inner skull distance) by `Eric Larson`_ + +- Fix bug when merging info that has a field with list of dicts by `Jaakko Leppakangas`_ + +- The BTi/4D reader now considers user defined channel labels instead of the hard-ware names, however only for channels other than MEG. By `Denis Engemann`_ and `Alex Gramfort`_. + +- The BTi reader :func:`mne.io.read_raw_bti` can now read 2500 system data, by `Eric Larson`_ + +- Fix bug in :func:`mne.compute_raw_covariance` where rejection by non-data channels (e.g. EOG) was not done properly by `Eric Larson`_. + +- Change default scoring method of ``mne.decoding.GeneralizationAcrossTime`` and ``mne.decoding.TimeDecoding`` to estimate the scores within the cross-validation as in scikit-learn_ as opposed to across all cross-validated ``y_pred``. The method can be changed with the ``score_mode`` parameter by `Jean-Remi King`_ + +- Fix bug in :func:`mne.io.Raw.save` where, in rare cases, automatically split files could end up writing an extra empty file that wouldn't be read properly by `Eric Larson`_ + +- Fix :class:``mne.realtime.StimServer`` by removing superfluous argument ``ip`` used while initializing the object by `Mainak Jas`_. + +- Fix removal of projectors in :func:`mne.preprocessing.maxwell_filter` in ``st_only=True`` mode by `Eric Larson`_ + +API +~~~ + +- The default `picks=None` in :func:`mne.viz.plot_epochs_image` now only plots the first 5 channels, not all channels, by `Jona Sassenhagen`_ + +- The ``mesh_color`` parameter in :func:`mne.viz.plot_dipole_locations` has been removed (use `brain_color` instead), by `Marijn van Vliet`_ + +- Deprecated functions ``mne.time_frequency.compute_raw_psd`` and ``mne.time_frequency.compute_epochs_psd``, replaced by :func:`mne.time_frequency.psd_welch` by `Chris Holdgraf`_ + +- Deprecated function ``mne.time_frequency.multitaper_psd`` and replaced by :func:`mne.time_frequency.psd_multitaper` by `Chris Holdgraf`_ + +- The ``y_pred`` attribute in ``mne.decoding.GeneralizationAcrossTime`` and ``mne.decoding.TimeDecoding`` is now a numpy array, by `Jean-Remi King`_ + +- The :func:`mne.bem.fit_sphere_to_headshape` function now default to ``dig_kinds='auto'`` which will use extra digitization points, falling back to extra plus eeg digitization points if there not enough extra points are available. + +- The :func:`mne.bem.fit_sphere_to_headshape` now has a ``units`` argument that should be set explicitly. This will default to ``units='mm'`` in 0.12 for backward compatibility but change to ``units='m'`` in 0.13. + +- Added default parameters in Epochs class namely ``event_id=None``, ``tmin=-0.2`` and ``tmax=0.5``. + +- To unify and extend the behavior of :func:`mne.compute_raw_covariance` relative to :func:`mne.compute_covariance`, the default parameter ``tstep=0.2`` now discards any epochs at the end of the :class:`mne.io.Raw` instance that are not the full ``tstep`` duration. This will slightly change the computation of :func:`mne.compute_raw_covariance`, but should only potentially have a big impact if the :class:`mne.io.Raw` instance is short relative to ``tstep`` and the last, too short (now discarded) epoch contained data inconsistent with the epochs that preceded it. + +- The default ``picks=None`` in :func:`mne.io.Raw.filter` now picks eeg, meg, seeg, and ecog channels, by `Jean-Remi King`_ and `Eric Larson`_ + +- EOG, ECG and EMG channels are now plotted by default (if present in data) when using :func:`mne.viz.plot_evoked` by `Marijn van Vliet`_ + +- Replace pseudoinverse-based solver with much faster Cholesky solver in :func:`mne.stats.linear_regression_raw`, by `Jona Sassenhagen`_. + +- CTF data reader now reads EEG locations from .pos file as HPI points by `Jaakko Leppakangas`_ + +- Subselecting channels can now emit a warning if many channels have been subselected from projection vectors. We recommend only computing projection vertors for and applying projectors to channels that will be used in the final analysis. However, after picking a subset of channels, projection vectors can be renormalized with :func:`mne.Info.normalize_proj` if necessary to avoid warnings about subselection. Changes by `Eric Larson`_ and `Alex Gramfort`_. + +- Rename and deprecate ``mne.Epochs.drop_bad_epochs`` to :func:`mne.Epochs.drop_bad`, and `mne.Epochs.drop_epochs`` to :func:`mne.Epochs.drop` by `Alex Gramfort`_. + +- The C wrapper ``mne.do_forward_solution`` has been deprecated in favor of the native Python version :func:`mne.make_forward_solution` by `Eric Larson`_ + +- The ``events`` parameter of :func:`mne.EpochsArray` is set by default to chronological time-samples and event values to 1, by `Jean-Remi King`_ + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number of commits): + +* 348 Eric Larson +* 347 Jaakko Leppakangas +* 157 Alexandre Gramfort +* 139 Jona Sassenhagen +* 67 Jean-Remi King +* 32 Chris Holdgraf +* 31 Denis A. Engemann +* 30 Mainak Jas +* 16 Christopher J. Bailey +* 13 Marijn van Vliet +* 10 Mark Wronkiewicz +* 9 Teon Brooks +* 9 kaichogami +* 8 Clément Moutard +* 5 Camilo Lamus +* 5 mmagnuski +* 4 Christian Brodbeck +* 4 Daniel McCloy +* 4 Yousra Bekhti +* 3 Fede Raimondo +* 1 Jussi Nurminen +* 1 MartinBaBer +* 1 Mikolaj Magnuski +* 1 Natalie Klein +* 1 Niklas Wilming +* 1 Richard Höchenberger +* 1 Sagun Pai +* 1 Sourav Singh +* 1 Tom Dupré la Tour +* 1 jona-sassenhagen@ +* 1 kambysese +* 1 pbnsilva +* 1 sviter +* 1 zuxfoucault diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.13.inc python-mne-0.19.1+dfsg/doc/changes/0.13.inc --- python-mne-0.18.1+dfsg/doc/changes/0.13.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.13.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,248 @@ +.. _changes_0_13: + +Version 0.13 +------------ + +Changelog +~~~~~~~~~ + +- Add new class :class:`AcqParserFIF` to parse Elekta/Neuromag MEG acquisition info, allowing e.g. collecting epochs according to acquisition-defined averaging categories by `Jussi Nurminen`_ + +- Adds automatic determination of FIR filter parameters ``filter_length``, ``l_trans_bandwidth``, and ``h_trans_bandwidth`` and adds ``phase`` argument in e.g. in :meth:`mne.io.Raw.filter` by `Eric Larson`_ + +- Adds faster ``n_fft='auto'`` option to :meth:`mne.io.Raw.apply_hilbert` by `Eric Larson`_ + +- Adds new function ``mne.time_frequency.csd_array`` to compute the cross-spectral density of multivariate signals stored in an array, by `Nick Foti`_ + +- Add order params 'selection' and 'position' for :func:`mne.viz.plot_raw` to allow plotting of specific brain regions by `Jaakko Leppakangas`_ + +- Added the ability to decimate :class:`mne.Evoked` objects with :func:`mne.Evoked.decimate` by `Eric Larson`_ + +- Add generic array-filtering function :func:`mne.filter.filter_data` by `Eric Larson`_ + +- ``mne.viz.plot_trans`` now also shows head position indicators by `Christian Brodbeck`_ + +- Add label center of mass function :func:`mne.Label.center_of_mass` by `Eric Larson`_ + +- Added :func:`mne.viz.plot_ica_properties` that allows plotting of independent component properties similar to ``pop_prop`` in EEGLAB. Also :class:`mne.preprocessing.ICA` has :func:`mne.preprocessing.ICA.plot_properties` method now. Added by `Mikołaj Magnuski`_ + +- Add second-order sections (instead of ``(b, a)`` form) IIR filtering for reduced numerical error by `Eric Larson`_ + +- Add interactive colormap option to image plotting functions by `Jaakko Leppakangas`_ + +- Add support for the University of Maryland KIT system by `Christian Brodbeck`_ + +- Add support for \*.elp and \*.hsp files to the KIT2FIFF converter and ``mne.channels.read_dig_montage`` by `Teon Brooks`_ and `Christian Brodbeck`_ + +- Add option to preview events in the KIT2FIFF GUI by `Christian Brodbeck`_ + +- Add approximation of size of :class:`io.Raw`, :class:`Epochs`, and :class:`Evoked` in :func:`repr` by `Eric Larson`_ + +- Add possibility to select a subset of sensors by lasso selector to :func:`mne.viz.plot_sensors` and :func:`mne.viz.plot_raw` when using order='selection' or order='position' by `Jaakko Leppakangas`_ + +- Add the option to plot brain surfaces and source spaces to :func:`viz.plot_bem` by `Christian Brodbeck`_ + +- Add the ``--filterchpi`` option to :ref:`mne browse_raw `, by `Felix Raimundo`_ + +- Add the ``--no-decimate`` option to :ref:`mne make_scalp_surfaces ` to skip the high-resolution surface decimation step, by `Eric Larson`_ + +- Add new class :class:`mne.decoding.EMS` to transform epochs with the event-matched spatial filters and add 'cv' parameter to :func:`mne.decoding.compute_ems`, by `Jean-Remi King`_ + +- Added :class:`mne.time_frequency.EpochsTFR` and average parameter in :func:`mne.time_frequency.tfr_morlet` and :func:`mne.time_frequency.tfr_multitaper` to compute time-frequency transforms on single trial epochs without averaging, by `Jean-Remi King`_ and `Alex Gramfort`_ + +- Added :class:`mne.decoding.TimeFrequency` to transform signals in scikit-learn pipelines, by `Jean-Remi King`_ + +- Added :class:`mne.decoding.UnsupervisedSpatialFilter` providing interface for scikit-learn decomposition algorithms to be used with MNE data, by `Jean-Remi King`_ and `Asish Panda`_ + +- Added support for multiclass decoding in :class:`mne.decoding.CSP`, by `Jean-Remi King`_ and `Alexandre Barachant`_ + +- Components obtained from :class:`mne.preprocessing.ICA` are now sorted by explained variance, by `Mikołaj Magnuski`_ + +- Adding an EEG reference channel using :func:`mne.add_reference_channels` will now use its digitized location from the FIFF file, if present, by `Chris Bailey`_ + +- Added interactivity to :func:`mne.preprocessing.ICA.plot_components` - passing an instance of :class:`io.Raw` or :class:`Epochs` in ``inst`` argument allows to open component properties by clicking on component topomaps, by `Mikołaj Magnuski`_ + +- Adds new function :func:`mne.viz.plot_compare_evokeds` to show multiple evoked time courses at a single location, or the mean over a ROI, or the GFP, automatically averaging and calculating a CI if multiple subjects are given, by `Jona Sassenhagen`_ + +- Added `transform_into` parameter into :class:`mne.decoding.CSP` to retrieve the average power of each source or the time course of each source, by `Jean-Remi King`_ + +- Added support for reading MaxShield (IAS) evoked data (e.g., from the acquisition machine) in :func:`mne.read_evokeds` by `Eric Larson`_ + +- Added support for functional near-infrared spectroscopy (fNIRS) channels by `Jaakko Leppakangas`_ + +- Added :attr:`mne.io.Raw.acqparser` convenience attribute for :class:`mne.AcqParserFIF` by `Eric Larson`_ + +- Added example of Representational Similarity Analysis, by `Jean-Remi King`_ + +BUG +~~~ + +- Fixed a bug where selecting epochs using hierarchical event IDs (HIDs) was *and*-like instead of *or*-like. When doing e.g. ``epochs[('Auditory', 'Left')]``, previously all trials that contain ``'Auditory'`` *and* ``'Left'`` (like ``'Auditory/Left'``) would be selected, but now any conditions matching ``'Auditory'`` *or* ``'Left'`` will be selected (like ``'Auditory/Left'``, ``'Auditory/Right'``, and ``'Visual/Left'``). This is now consistent with how epoch selection was done without HID tags, e.g. ``epochs[['a', 'b']]`` would select all epochs of type ``'a'`` and type ``'b'``. By `Eric Larson`_ + +- Fixed Infomax/Extended Infomax when the user provides an initial weights matrix by `Jair Montoya Martinez`_ + +- Fixed the default raw FIF writing buffer size to be 1 second instead of 10 seconds by `Eric Larson`_ + +- Fixed channel selection order when MEG channels do not come first in :func:`mne.preprocessing.maxwell_filter` by `Eric Larson`_ + +- Fixed color ranges to correspond to the colorbar when plotting several time instances with :func:`mne.viz.plot_evoked_topomap` by `Jaakko Leppakangas`_ + +- Added units to :func:`mne.io.read_raw_brainvision` for reading non-data channels and enable default behavior of inferring channel type by unit by `Jaakko Leppakangas`_ and `Pablo-Arias`_ + +- Fixed minor bugs with :func:`mne.Epochs.resample` and :func:`mne.Epochs.decimate` by `Eric Larson`_ + +- Fixed a bug where duplicate vertices were not strictly checked by :func:`mne.simulation.simulate_stc` by `Eric Larson`_ + +- Fixed a bug where some FIF files could not be read with :func:`mne.io.show_fiff` by `Christian Brodbeck`_ and `Eric Larson`_ + +- Fixed a bug where ``merge_grads=True`` causes :func:`mne.viz.plot_evoked_topo` to fail when plotting a list of evokeds by `Jaakko Leppakangas`_ + +- Fixed a bug when setting multiple bipolar references with :func:`set_bipolar_reference` by `Marijn van Vliet`_. + +- Fixed image scaling in :func:`mne.viz.plot_epochs_image` when plotting more than one channel by `Jaakko Leppakangas`_ + +- Fixed :class:`mne.preprocessing.Xdawn` to fit shuffled epochs by `Jean-Remi King`_ + +- Fixed a bug with channel order determination that could lead to an ``AssertionError`` when using :class:`mne.Covariance` matrices by `Eric Larson`_ + +- Fixed the check for CTF gradient compensation in :func:`mne.preprocessing.maxwell_filter` by `Eric Larson`_ + +- Fixed the import of EDF files with encoding characters in :func:`mne.io.read_raw_edf` by `Guillaume Dumas`_ + +- Fixed :class:`mne.Epochs` to ensure that detrend parameter is not a boolean by `Jean-Remi King`_ + +- Fixed bug with ``mne.realtime.FieldTripClient.get_data_as_epoch`` when ``picks=None`` which crashed the function by `Mainak Jas`_ + +- Fixed reading of units in ``.elc`` montage files (from ``UnitsPosition`` field) so that ``mne.channels.Montage`` objects are now returned with the ``pos`` attribute correctly in meters, by `Chris Mullins`_ + +- Fixed reading of BrainVision files by `Phillip Alday`_: + +- Greater support for BVA files, especially older ones: alternate text coding schemes with fallback to Latin-1 as well as units in column headers + +- Use online software filter information when present + +- Fix comparisons of filter settings for determining "strictest"/"weakest" filter + +- Weakest filter is now used for heterogeneous channel filter settings, leading to more consistent behavior with filtering methods applied to a subset of channels (e.g. ``Raw.filter`` with ``picks != None``). + +- Fixed plotting and timing of :class:`Annotations` and restricted addition of annotations outside data range to prevent problems with cropping and concatenating data by `Jaakko Leppakangas`_ + +- Fixed ICA plotting functions to refer to IC index instead of component number by `Andreas Hojlund`_ and `Jaakko Leppakangas`_ + +- Fixed bug with ``picks`` when interpolating MEG channels by `Mainak Jas`_. + +- Fixed bug in padding of Stockwell transform for signal of length a power of 2 by `Johannes Niediek`_ + +API +~~~ + +- The ``add_eeg_ref`` argument in core functions like :func:`mne.io.read_raw_fif` and :class:`mne.Epochs` has been deprecated in favor of using :func:`mne.set_eeg_reference` and equivalent instance methods like :meth:`raw.set_eeg_reference() `. In functions like :func:`mne.io.read_raw_fif` where the default in 0.13 and older versions is ``add_eeg_ref=True``, the default will change to ``add_eeg_ref=False`` in 0.14, and the argument will be removed in 0.15. + +- Multiple aspects of FIR filtering in MNE-Python has been refactored: + + 1. New recommended defaults for ``l_trans_bandwidth='auto'``, ``h_trans_bandwidth='auto'``, and ``filter_length='auto'``. This should generally reduce filter artifacts at the expense of slight decrease in effective filter stop-band attenuation. For details see :ref:`tut_filtering_in_python`. The default values of ``l_trans_bandwidth=h_trans_bandwidth=0.5`` and ``filter_length='10s'`` will change to ``'auto'`` in 0.14. + + 2. The ``filter_length=None`` option (i.e. use ``len(x)``) has been deprecated. + + 3. An improved ``phase='zero'`` zero-phase FIR filtering has been added. Instead of running the designed filter forward and backward, the filter is applied once and we compensate for the linear phase of the filter. The previous ``phase='zero-double'`` default will change to ``phase='zero'`` in 0.14. + + 4. A warning is provided when the filter is longer than the signal of interest, as this is unlikely to produce desired results. + + 5. Previously, if the filter was as long or longer than the signal of interest, direct FFT-based computations were used. Now a single code path (overlap-add filtering) is used for all FIR filters. This could cause minor changes in how short signals are filtered. + +- Support for Python 2.6 has been dropped, and the minimum supported dependencies are NumPy_ 1.8, SciPy_ 0.12, and Matplotlib_ 1.3 by `Eric Larson`_ + +- When CTF gradient compensation is applied to raw data, it is no longer reverted on save of :meth:`mne.io.Raw.save` by `Eric Larson`_ + +- Adds ``mne.time_frequency.csd_epochs`` to replace ``mne.time_frequency.csd_compute_epochs`` for naming consistency. ``mne.time_frequency.csd_compute_epochs`` is now deprecated and will be removed in mne 0.14, by `Nick Foti`_ + +- Weighted addition and subtraction of :class:`Evoked` as ``ev1 + ev2`` and ``ev1 - ev2`` have been deprecated, use explicit :func:`mne.combine_evoked(..., weights='nave') ` instead by `Eric Larson`_ + +- Deprecated support for passing a list of filenames to :class:`mne.io.Raw` constructor, use :func:`mne.io.read_raw_fif` and :func:`mne.concatenate_raws` instead by `Eric Larson`_ + +- Added options for setting data and date formats manually in :func:`mne.io.read_raw_cnt` by `Jaakko Leppakangas`_ + +- Now channels with units of 'C', 'µS', 'uS', 'ARU' and 'S' will be turned to misc by default in :func:`mne.io.read_raw_brainvision` by `Jaakko Leppakangas`_ + +- Add :func:`mne.io.anonymize_info` function to anonymize measurements and add methods to :class:`mne.io.Raw`, :class:`mne.Epochs` and :class:`mne.Evoked`, by `Jean-Remi King`_ + +- Now it is possible to plot only a subselection of channels in :func:`mne.viz.plot_raw` by using an array for order parameter by `Jaakko Leppakangas`_ + +- EOG channels can now be included when calling :func:`mne.preprocessing.ICA.fit` and a proper error is raised when trying to include unsupported channels by `Alexander Rudiuk`_ + +- :func:`mne.concatenate_epochs` and :func:`mne.compute_covariance` now check to see if all :class:`Epochs` instances have the same MEG-to-Head transformation, and errors by default if they do not by `Eric Larson`_ + +- Added option to pass a list of axes to :func:`mne.viz.plot_epochs_image` by `Mikołaj Magnuski`_ + +- Constructing IIR filters in :func:`mne.filter.construct_iir_filter` defaults to ``output='ba'`` in 0.13 but this will be changed to ``output='sos'`` by `Eric Larson`_ + +- Add ``zorder`` parameter to :func:`mne.Evoked.plot` and derived functions to sort allow sorting channels by e.g. standard deviation, by `Jona Sassenhagen`_ + +- The ``baseline`` parameter of :func:`mne.Epochs.apply_baseline` is set by default (None, 0), by `Felix Raimundo`_ + +- Adds :func:`mne.Evoked.apply_baseline` to be consistent with :func:`mne.Epochs.apply_baseline`, by `Felix Raimundo`_ + +- Deprecated the ``baseline`` parameter in :class:`mne.Evoked`, by `Felix Raimundo`_ + +- The API of :meth:`mne.SourceEstimate.plot` and :func:`mne.viz.plot_source_estimates` has been updated to reflect current PySurfer 0.6 API. The ``config_opts`` parameter is now deprecated and will be removed in mne 0.14, and the default representation for time will change from ``ms`` to ``s`` in mne 0.14. By `Christian Brodbeck`_ + +- The default dataset location has been changed from ``examples/`` in the MNE-Python root directory to ``~/mne_data`` in the user's home directory, by `Eric Larson`_ + +- A new option ``set_env`` has been added to :func:`mne.set_config` that defaults to ``False`` in 0.13 but will change to ``True`` in 0.14, by `Eric Larson`_ + +- The ``compensation`` parameter in :func:`mne.io.read_raw_fif` has been deprecated in favor of the method :meth:`mne.io.Raw.apply_gradient_compensation` by `Eric Larson`_ + +- ``mne.decoding.EpochsVectorizer`` has been deprecated in favor of :class:`mne.decoding.Vectorizer` by `Asish Panda`_ + +- The `epochs_data` parameter has been deprecated in :class:`mne.decoding.CSP`, in favour of the ``X`` parameter to comply to scikit-learn API, by `Jean-Remi King`_ + +- Deprecated ``mne.time_frequency.cwt_morlet`` and ``mne.time_frequency.single_trial_power`` in favour of :func:`mne.time_frequency.tfr_morlet` with parameter average=False, by `Jean-Remi King`_ and `Alex Gramfort`_ + +- Add argument ``mask_type`` to func:`mne.read_events` and func:`mne.find_events` to support MNE-C style of trigger masking by `Teon Brooks`_ and `Eric Larson`_ + +- Extended Infomax is now the new default in :func:`mne.preprocessing.infomax` (``extended=True``), by `Clemens Brunner`_ + +- :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab` now take additional argument ``uint16_codec`` that allows to define the encoding of character arrays in set file. This helps in rare cases when reading a set file fails with ``TypeError: buffer is too small for requested array``. By `Mikołaj Magnuski`_ + +- Added :class:`mne.decoding.TemporalFilter` to filter data in scikit-learn pipelines, by `Asish Panda`_ + +- :func:`mne.preprocessing.create_ecg_epochs` now includes all the channels when ``picks=None`` by `Jaakko Leppakangas`_ + +- :func:`mne.set_eeg_reference` now allows moving from a custom to an average EEG reference by `Marijn van Vliet`_ + +Authors +~~~~~~~ + +The committer list for this release is the following (sorted by alphabetical order): + +* Alexander Rudiuk +* Alexandre Barachant +* Alexandre Gramfort +* Asish Panda +* Camilo Lamus +* Chris Holdgraf +* Christian Brodbeck +* Christopher J. Bailey +* Christopher Mullins +* Clemens Brunner +* Denis A. Engemann +* Eric Larson +* Federico Raimondo +* Félix Raimundo +* Guillaume Dumas +* Jaakko Leppakangas +* Jair Montoya +* Jean-Remi King +* Johannes Niediek +* Jona Sassenhagen +* Jussi Nurminen +* Keith Doelling +* Mainak Jas +* Marijn van Vliet +* Michael Krause +* Mikolaj Magnuski +* Nick Foti +* Phillip Alday +* Simon-Shlomo Poil +* Teon Brooks +* Yaroslav Halchenko diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.14.inc python-mne-0.19.1+dfsg/doc/changes/0.14.inc --- python-mne-0.18.1+dfsg/doc/changes/0.14.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.14.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,250 @@ +.. _changes_0_14: + +Version 0.14 +------------ + +Changelog +~~~~~~~~~ + +- Add example of time-frequency decoding with CSP by `Laura Gwilliams`_ + +- Automatically create a legend in :func:`mne.viz.plot_evoked_topo` by `Jussi Nurminen`_ + +- Add I/O support for Artemis123 infant/toddler MEG data by `Luke Bloy`_ + +- Add filter plotting functions :func:`mne.viz.plot_filter` and :func:`mne.viz.plot_ideal_filter` as well as filter creation function :func:`mne.filter.create_filter` by `Eric Larson`_ + +- Add HCP-MMP1.0 parcellation dataset downloader by `Eric Larson`_ + +- Add option to project EEG electrodes onto the scalp in ``mne.viz.plot_trans`` by `Eric Larson`_ + +- Add option to plot individual sensors in :meth:`mne.io.Raw.plot_psd` by `Alex Gramfort`_ and `Eric Larson`_ + +- Add option to plot ECoG electrodes in ``mne.viz.plot_trans`` by `Eric Larson`_ + +- Add convenient default values to :meth:`mne.io.Raw.apply_hilbert` and :meth:`mne.io.Raw.apply_function` by `Denis Engemann`_ + +- Remove MNE-C requirement for :ref:`mne make_scalp_surfaces ` by `Eric Larson`_ + +- Add support for FastTrack Polhemus ``.mat`` file outputs in ``hsp`` argument of ``mne.channels.read_dig_montage`` by `Eric Larson`_ + +- Add option to convert 3d electrode plots to a snapshot with 2d electrode positions with :func:`mne.viz.snapshot_brain_montage` by `Chris Holdgraf`_ + +- Add skull surface plotting option to ``mne.viz.plot_trans`` by `Jaakko Leppakangas`_ + +- Add minimum-phase filtering option in :meth:`mne.io.Raw.filter` by `Eric Larson`_ + +- Add support for reading ASCII BrainVision files in :func:`mne.io.read_raw_brainvision` by `Eric Larson`_ + +- Add method of ICA objects for retrieving the component maps :meth:`mne.preprocessing.ICA.get_components` by `Jona Sassenhagen`_ + +- Add option to plot events in :func:`mne.viz.plot_epochs` by `Jaakko Leppakangas`_ + +- Add dipole definitions for older phantom at Otaniemi in :func:`mne.dipole.get_phantom_dipoles` by `Eric Larson`_ + +- Add spatial colors option for :func:`mne.viz.plot_raw_psd` by `Jaakko Leppakangas`_ + +- Add functions like :func:`get_volume_labels_from_src` to handle mixed source spaces by `Annalisa Pascarella`_ + +- Add convenience function for opening MNE documentation :func:`open_docs` by `Eric Larson`_ + +- Add option in :meth:`mne.io.Raw.plot` to display the time axis relative to ``raw.first_samp`` by `Mainak Jas`_ + +- Add new :mod:`mne.datasets.visual_92_categories ` dataset by `Jaakko Leppakangas`_ + +- Add option in :func:`mne.io.read_raw_edf` to allow channel exclusion by `Jaakko Leppakangas`_ + +- Allow integer event codes in :func:`mne.read_epochs_eeglab` by `Jaakko Leppakangas`_ + +- Add ability to match channel names in a case insensitive manner when applying a ``mne.channels.Montage`` by `Marijn van Vliet`_ + +- Add ``yscale`` keyword argument to :meth:`mne.time_frequency.AverageTFR.plot` that allows specifying whether to present the frequency axis in linear (``'linear'``) or log (``'log'``) scale. The default value is ``'auto'`` which detects whether frequencies are log-spaced and sets yscale to log. Added by `Mikołaj Magnuski`_ + +- Add :ref:`Representational Similarity Analysis (RSA) ` example on :mod:`mne.datasets.visual_92_categories.data_path` dataset by `Jaakko Leppakangas`_, `Jean-Remi King`_ and `Alex Gramfort`_ + +- Add support for NeuroScan files with event type 3 in :func:`mne.io.read_raw_cnt` by `Marijn van Vliet`_ + +- Add interactive annotation mode to :meth:`mne.io.Raw.plot` (accessed by pressing 'a') by `Jaakko Leppakangas`_ + +- Add support for deleting all projectors or a list of indices in :meth:`mne.io.Raw.del_proj` by `Eric Larson`_ + +- Add source space plotting with :meth:`mne.SourceSpaces.plot` using ``mne.viz.plot_trans`` by `Eric Larson`_ + +- Add :func:`mne.decoding.get_coef` to retrieve and inverse the coefficients of a linear model - typically a spatial filter or pattern, by `Jean-Remi King`_ + +- Add support for reading in EGI MFF digitization coordinate files in ``mne.channels.read_dig_montage`` by `Matt Boggess`_ + +- Add ``n_per_seg`` keyword argument to :func:`mne.time_frequency.psd_welch` and :func:`mne.time_frequency.psd_array_welch` that allows to control segment length independently of ``n_fft`` and use zero-padding when ``n_fft > n_per_seg`` by `Mikołaj Magnuski`_ + +- Add annotation aware data getter :meth:`mne.io.Raw.get_data` by `Jaakko Leppakangas`_ + +- Add support of dipole location visualization with MRI slice overlay with matplotlib to :func:`mne.viz.plot_dipole_locations` via mode='orthoview' parameter by `Jaakko Leppakangas`_ and `Alex Gramfort`_ + +- Add plotting of head positions as a function of time in :func:`mne.viz.plot_head_positions` by `Eric Larson`_ + +- Add ``real_filter`` option to ``mne.beamformer.dics``, ``mne.beamformer.dics_source_power``, ``mne.beamformer.tf_dics`` and ``mne.beamformer.dics_epochs`` by `Eric Larson`_, `Alex Gramfort`_ and `Andrea Brovelli`_. + +- Add a demo script showing how to use a custom inverse solver with MNE by `Alex Gramfort`_ + +- Functions :func:`mne.preprocessing.create_ecg_epochs`, :func:`mne.preprocessing.create_eog_epochs`, :func:`mne.compute_raw_covariance` and ICA methods :meth:`mne.preprocessing.ICA.score_sources`, :meth:`mne.preprocessing.ICA.find_bads_ecg`, :meth:`mne.preprocessing.ICA.find_bads_eog` are now annotation aware by `Jaakko Leppakangas`_ + +- Allow using ``spatial_colors`` for non-standard layouts by creating custom layouts from channel locations and add ``to_sphere`` keyword to :func:`mne.viz.plot_sensors` to allow plotting sensors that are not on the head surface by `Jaakko Leppakangas`_ + +- Concatenating raws with :func:`mne.concatenate_raws` now creates boundary annotations automatically by `Jaakko Leppakangas`_ + +- :func:`mne.viz.plot_projs_topomap` now supports plotting EEG topomaps by passing in :class:`mne.Info` by `Eric Larson`_ + +BUG +~~~ + +- Fix bug with DICS and LCMV (e.g., ``mne.beamformer.lcmv``, ``mne.beamformer.dics``) where regularization was done improperly. The default ``reg=0.01`` has been changed to ``reg=0.05``, by `Andrea Brovelli`_, `Alex Gramfort`_, and `Eric Larson`_ + +- Fix callback function call in ``mne.viz.topo._plot_topo_onpick`` by `Erkka Heinila`_ + +- Fix reading multi-file CTF recordings in :func:`mne.io.read_raw_ctf` by `Niklas Wilming`_ + +- Fix computation of AR coefficients across channels in :func:`mne.time_frequency.fit_iir_model_raw` by `Eric Larson`_ + +- Fix maxfilter channel names extra space bug in :func:`mne.preprocessing.maxwell_filter` by `Sheraz Khan`_ + +- :func:`mne.channels.find_layout` now leaves out the excluded channels by `Jaakko Leppakangas`_ + +- Array data constructors :class:`mne.io.RawArray` and :class:`EvokedArray` now make a copy of the info structure by `Jaakko Leppakangas`_ + +- Fix bug with finding layouts in :func:`mne.viz.plot_projs_topomap` by `Eric Larson`_ + +- Fix bug :func:`mne.io.anonymize_info` when Info does not contain 'file_id' or 'meas_id' fields by `Jean-Remi King`_ + +- Fix colormap selection in :func:`mne.viz.plot_evoked_topomap` when using positive vmin with negative data by `Jaakko Leppakangas`_ + +- Fix channel name comparison in ``mne.channels.read_montage`` so that if ``ch_names`` is provided, the returned montage will have channel names in the same letter case by `Jaakko Leppakangas`_ + +- Fix :meth:`inst.set_montage(montage) ` to only set ``inst.info['dev_head_t']`` if ``dev_head_t=True`` in ``mne.channels.read_dig_montage`` by `Eric Larson`_ + +- Fix handling of events in ``mne.realtime.RtEpochs`` when the triggers were split between two buffers resulting in missing and/or duplicate epochs by `Mainak Jas`_ and `Antti Rantala`_ + +- Fix bug with automatic decimation in :func:`mne.io.read_raw_kit` by `Keith Doelling`_ + +- Fix bug with :func:`setup_volume_source_space` where arguments ``subject`` and ``subjects_dir`` were ignored by `Jaakko Leppakangas`_ + +- Fix sanity check for incompatible ``threshold`` and ``tail`` values in clustering functions like :func:`mne.stats.spatio_temporal_cluster_1samp_test` by `Eric Larson`_ + +- Fix ``_bad_dropped`` not being set when loading eeglab epoched files via :func:`mne.read_epochs_eeglab` which resulted in :func:`len` not working by `Mikołaj Magnuski`_ + +- Fix a bug in :meth:`mne.time_frequency.AverageTFR.plot` when plotting without a colorbar by `Jaakko Leppakangas`_ + +- Fix ``_filenames`` attribute in creation of :class:`mne.io.RawArray` with :meth:`mne.preprocessing.ICA.get_sources` by `Paul Pasler`_ + +- Fix contour levels in :func:`mne.viz.plot_evoked_topomap` to be uniform across topomaps by `Jaakko Leppakangas`_ + +- Fix bug in :func:`mne.preprocessing.maxwell_filter` where fine calibration indices were mismatched leading to an ``AssertionError`` by `Eric Larson`_ + +- Fix bug in :func:`mne.preprocessing.fix_stim_artifact` where non-data channels were interpolated by `Eric Larson`_ + +- :class:`mne.decoding.Scaler` now scales each channel independently using data from all time points (epochs and times) instead of scaling all channels for each time point. It also now accepts parameter ``scalings`` to determine the data scaling method (default is ``None`` to use static channel-type-based scaling), by `Asish Panda`_, `Jean-Remi King`_, and `Eric Larson`_ + +- Raise error if the cv parameter of ``mne.decoding.GeneralizationAcrossTime`` and ``mne.decoding.TimeDecoding`` is not a partition and the predict_mode is "cross-validation" by `Jean-Remi King`_ + +- Fix bug in :func:`mne.io.read_raw_edf` when ``preload=False`` and channels have different sampling rates by `Jaakko Leppakangas`_ + +- Fix :func:`mne.read_labels_from_annot` to set ``label.values[:]=1`` rather than 0 for consistency with the :class:`Label` class by `Jon Houck`_ + +- Fix plotting non-uniform freqs (for example log-spaced) in :meth:`mne.time_frequency.AverageTFR.plot` by `Mikołaj Magnuski`_ + +- Fix :func:`mne.minimum_norm.compute_source_psd` when used with ``pick_ori=None`` by `Annalisa Pascarella`_ and `Alex Gramfort`_ + +- Fix bug in :class:`mne.Annotations` where concatenating two raws where ``orig_time`` of the second run is ``None`` by `Jaakko Leppakangas`_ + +- Fix reading channel location from eeglab ``.set`` files when some of the channels do not provide this information. Previously all channel locations were ignored in such case, now they are read - unless a montage is provided by the user in which case only channel names are read from set file. By `Mikołaj Magnuski`_ + +- Fix reading eeglab ``.set`` files when ``.chanlocs`` structure does not contain ``X``, ``Y`` or ``Z`` fields by `Mikołaj Magnuski`_ + +- Fix bug with :func:`mne.simulation.simulate_raw` when ``interp != 'zero'`` by `Eric Larson`_ + +- Fix :func:`mne.fit_dipole` to handle sphere model rank deficiency properly by `Alex Gramfort`_ + +- Raise error in :func:`mne.concatenate_epochs` when concatenated epochs have conflicting event_id by `Mikołaj Magnuski`_ + +- Fix handling of ``n_components=None`` in :class:`mne.preprocessing.ICA` by `Richard Höchenberger`_ + +- Fix reading of fiducials correctly from CTF data in :func:`mne.io.read_raw_ctf` by `Jaakko Leppakangas`_ + +- Fix :func:`mne.beamformer.rap_music` to return dipoles with amplitudes in Am instead of nAm by `Jaakko Leppakangas`_ + +- Fix computation of duality gap in ``mne.inverse_sparse.mxne_optim.dgap_l21`` by `Mathurin Massias`_ + +API +~~~ + +- The filtering functions ``band_pass_filter``, ``band_stop_filter``, ``low_pass_filter``, and ``high_pass_filter`` have been deprecated in favor of :func:`mne.filter.filter_data` by `Eric Larson`_ + +- :class:`EvokedArray` now has default value ``tmin=0.`` by `Jaakko Leppakangas`_ + +- The ``ch_type`` argument for ``mne.viz.plot_trans`` has been deprecated, use ``eeg_sensors`` and ``meg_sensors`` instead, by `Eric Larson`_ + +- The default ``tmax=60.`` in :meth:`mne.io.Raw.plot_psd` will change to ``tmax=np.inf`` in 0.15, by `Eric Larson`_ + +- Base classes :class:`mne.io.BaseRaw` and :class:`mne.BaseEpochs` are now public to allow easier typechecking, by `Daniel McCloy`_ + +- :func:`mne.io.read_raw_edf` now combines triggers from multiple tal channels to 'STI 014' by `Jaakko Leppakangas`_ + +- The measurement info :class:`Info` no longer contains a potentially misleading ``info['filename']`` entry. Use class properties like :attr:`mne.io.Raw.filenames` or :attr:`mne.Epochs.filename` instead by `Eric Larson`_ + +- Default fiducial name change from 'nz' to 'nasion' in ``mne.channels.read_montage``, so that it is the same for both ``mne.channels.Montage`` and :class: `mne.channels.DigMontage` by `Leonardo Barbosa`_ + +- MNE's additional files for the ``fsaverage`` head/brain model are now included in MNE-Python, and the now superfluous ``mne_root`` parameter to :func:`create_default_subject` has been deprecated by `Christian Brodbeck`_ + +- An ``overwrite=False`` default parameter has been added to :func:`write_source_spaces` to protect against accidental overwrites, by `Eric Larson`_ + +- The :class:`mne.decoding.LinearModel` class will no longer support `plot_filters` and `plot_patterns`, use :class:`mne.EvokedArray` with :func:`mne.decoding.get_coef` instead, by `Jean-Remi King`_ + +- Made functions :func:`mne.time_frequency.tfr_array_multitaper`, :func:`mne.time_frequency.tfr_array_morlet`, :func:`mne.time_frequency.tfr_array_stockwell`, :func:`mne.time_frequency.psd_array_multitaper` and :func:`mne.time_frequency.psd_array_welch` public to allow computing TFRs and PSDs on numpy arrays by `Jaakko Leppakangas`_ + +- :meth:`mne.preprocessing.ICA.fit` now rejects data annotated bad by default. Turn off with ``reject_by_annotation=False``, by `Jaakko Leppakangas`_ + +- :func:`mne.io.read_raw_egi` now names channels with pattern 'E'. This behavior can be changed with parameter ``channel_naming`` by `Jaakko Leppakangas`_ + +- the `name`` parameter in :class:`mne.Epochs` is deprecated, by `Jaakko Leppakangas`_ + +Authors +~~~~~~~ + +People who contributed to this release (in alphabetical order): + +* Alexander Rudiuk +* Alexandre Gramfort +* Annalisa Pascarella +* Antti Rantala +* Asish Panda +* Burkhard Maess +* Chris Holdgraf +* Christian Brodbeck +* Cristóbal Moënne-Loccoz +* Daniel McCloy +* Denis A. Engemann +* Eric Larson +* Erkka Heinila +* Hermann Sonntag +* Jaakko Leppakangas +* Jakub Kaczmarzyk +* Jean-Remi King +* Jon Houck +* Jona Sassenhagen +* Jussi Nurminen +* Keith Doelling +* Leonardo S. Barbosa +* Lorenz Esch +* Lorenzo Alfine +* Luke Bloy +* Mainak Jas +* Marijn van Vliet +* Matt Boggess +* Matteo Visconti +* Mikolaj Magnuski +* Niklas Wilming +* Paul Pasler +* Richard Höchenberger +* Sheraz Khan +* Stefan Repplinger +* Teon Brooks +* Yaroslav Halchenko diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.15.inc python-mne-0.19.1+dfsg/doc/changes/0.15.inc --- python-mne-0.18.1+dfsg/doc/changes/0.15.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.15.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,329 @@ +.. _changes_0_15: + +Version 0.15 +------------ + +Changelog +~~~~~~~~~ + +- :meth:`mne.channels.Layout.plot` and :func:`mne.viz.plot_layout` now allows plotting a subset of channels with ``picks`` argument by `Jaakko Leppakangas`_ + +- Add .bvef extension (BrainVision Electrodes File) to ``mne.channels.read_montage`` by `Jean-Baptiste Schiratti`_ + +- Add :func:`mne.decoding.cross_val_multiscore` to allow scoring of multiple tasks, typically used with :class:`mne.decoding.SlidingEstimator`, by `Jean-Remi King`_ + +- Add :class:`mne.decoding.ReceptiveField` module for modeling electrode response to input features by `Chris Holdgraf`_ + +- Add :class:`mne.decoding.TimeDelayingRidge` class, used by default by :class:`mne.decoding.ReceptiveField`, to speed up auto- and cross-correlation computations and enable Laplacian regularization by `Ross Maddox`_ and `Eric Larson`_ + +- Add new :mod:`mne.datasets.mtrf ` dataset by `Chris Holdgraf`_ + +- Add example of time-frequency decoding with CSP by `Laura Gwilliams`_ + +- Add :class:`mne.decoding.SPoC` to fit and apply spatial filters based on continuous target variables, by `Jean-Remi King`_ and `Alexandre Barachant`_ + +- Add Fieldtrip's electromyogram dataset, by `Alexandre Barachant`_ + +- Add ``reject_by_annotation`` option to :func:`mne.preprocessing.find_eog_events` (which is also utilised by :func:`mne.preprocessing.create_eog_epochs`) to omit data that is annotated as bad by `Jaakko Leppakangas`_ + +- Add example for fast screening of event-related dynamics in frequency bands by `Denis Engemann`_ + +- Add :meth:`mne.time_frequency.EpochsTFR.save` by `Jaakko Leppakangas`_ + +- Add butterfly mode (toggled with 'b' key) to :meth:`mne.io.Raw.plot` by `Jaakko Leppakangas`_ + +- Add ``axes`` parameter to plot_topo functions by `Jaakko Leppakangas`_ + +- Add options to change time windowing in :func:`mne.chpi.filter_chpi` by `Eric Larson`_ + +- ``mne.channels.Montage.plot``, :meth:`mne.channels.DigMontage.plot`, and :func:`mne.viz.plot_montage` now allow plotting channel locations as a topomap by `Clemens Brunner`_ + +- Add ``background_color`` parameter to :meth:`mne.Evoked.plot_topo` and :func:`mne.viz.plot_evoked_topo` and improve axes rendering as done in :func:`mne.viz.plot_compare_evokeds` by `Alex Gramfort`_ + +- Add support for GDF files in :func:`mne.io.read_raw_edf` by `Nicolas Barascud`_ + +- Add ``mne.io.find_edf_events`` for getting the events as they are in the EDF/GDF header by `Jaakko Leppakangas`_ + +- Speed up :meth:`mne.io.Raw.plot` and :meth:`mne.Epochs.plot` using (automatic) decimation based on low-passing with ``decim='auto'`` parameter by `Eric Larson`_ and `Jaakko Leppakangas`_ + +- Add ``mne.inverse_sparse.mxne_optim.dgap_l21l1`` for computing the duality gap for TF-MxNE as the new stopping criterion by `Daniel Strohmeier`_ + +- Add option to return a list of :class:`Dipole` objects in sparse source imaging methods by `Daniel Strohmeier`_ + +- Add :func:`mne.inverse_sparse.make_stc_from_dipoles` to generate stc objects from lists of dipoles by `Daniel Strohmeier`_ + +- Add :func:`mne.channels.find_ch_connectivity` that tries to infer the correct connectivity template using channel info. If no template is found, it computes the connectivity matrix using :class:`Delaunay ` triangulation of the 2d projected channel positions by `Jaakko Leppakangas`_ + +- Add IO support for EGI MFF format by `Jaakko Leppakangas`_ and `ramonapariciog`_ + +- Add option to use matplotlib backend when plotting with :func:`mne.viz.plot_source_estimates` by `Jaakko Leppakangas`_ + +- Add ``mne.channels.Montage.get_pos2d`` to get the 2D positions of channels in a montage by `Clemens Brunner`_ + +- Add MGH 60- and 70-channel standard montages to ``mne.channels.read_montage`` by `Eric Larson`_ + +- Add option for embedding SVG instead of PNG in HTML for :class:`mne.Report` by `Eric Larson`_ + +- Add confidence intervals, number of free parameters, and χ² to :func:`mne.fit_dipole` and :func:`mne.read_dipole` by `Eric Larson`_ + +- :attr:`mne.SourceEstimate.data` is now writable, writing to it will also update :attr:`mne.SourceEstimate.times` by `Marijn van Vliet`_ + +- :meth:`mne.io.Raw.plot` and :meth:`mne.Epochs.plot` now use anti-aliasing to draw signals by `Clemens Brunner`_ + +- Allow using saved ``DigMontage`` to import digitization to :func:`mne.gui.coregistration` by `Jaakko Leppakangas`_ + +- Add function :func:`mne.channels.get_builtin_montages` to list all built-in montages by `Clemens Brunner`_ + +- :class:`mne.decoding.SlidingEstimator` and :class:`mne.decoding.GeneralizingEstimator` now accept ``**fit_params`` at fitting by `Jean-Remi King`_ + +- Add :class:`mne.VectorSourceEstimate` class which enables working with both source power and dipole orientations by `Marijn van Vliet`_ + +- Add option ``pick_ori='vector'`` to :func:`mne.minimum_norm.apply_inverse` to produce :class:`mne.VectorSourceEstimate` by `Marijn van Vliet`_ + +- Add support for :class:`numpy.random.RandomState` argument to ``seed`` in :mod:`statistical clustering functions ` and better documentation of exact 1-sample tests by `Eric Larson`_ + +- Extend :func:`mne.viz.plot_epochs_image`/:meth:`mne.Epochs.plot_image` with regards to grouping by or aggregating over channels. See the new example at `examples/visualization/plot_roi_erpimage_by_rt.py` by `Jona Sassenhagen`_ + +- Add bootstrapped confidence intervals to :func:`mne.viz.plot_compare_evokeds` by `Jona Sassenhagen`_ and `Denis Engemann`_ + +- Add example on how to plot ERDS maps (also known as ERSP) by `Clemens Brunner`_ + +- Add support for volume source spaces to :func:`spatial_src_connectivity` and :func:`spatio_temporal_src_connectivity` by `Alex Gramfort`_ + +- Plotting raw data (:func:`mne.viz.plot_raw` or :meth:`mne.io.Raw.plot`) with events now includes event numbers (if there are not more than 50 events on a page) by `Clemens Brunner`_ + +- Add filtering functions :meth:`mne.Epochs.filter` and :meth:`mne.Evoked.filter`, as well as ``pad`` argument to :meth:`mne.io.Raw.filter` by `Eric Larson`_ + +- Add high frequency somatosensory MEG dataset by `Jussi Nurminen`_ + +- Add reduced set of labels for HCPMMP-1.0 parcellation in :func:`mne.datasets.fetch_hcp_mmp_parcellation` by `Eric Larson`_ + +- Enable morphing between hemispheres with ``mne.compute_morph_matrix`` by `Christian Brodbeck`_ + +- Add ``return_residual`` to :func:`mne.minimum_norm.apply_inverse` by `Eric Larson`_ + +- Add ``return_drop_log`` to :func:`mne.preprocessing.compute_proj_eog` and :func:`mne.preprocessing.compute_proj_ecg` by `Eric Larson`_ + +- Add time cursor and category/amplitude status message into the single-channel evoked plot by `Jussi Nurminen`_ + +BUG +~~~ +- Fixed a bug when creating spherical volumetric grid source spaces in :func:`setup_volume_source_space` by improving the minimum-distance computations, which in general will decrease the number of used source space points by `Eric Larson`_ + +- Fix bug in :meth:`mne.io.read_raw_brainvision` read .vhdr files with ANSI codepage by `Okba Bekhelifi`_ and `Alex Gramfort`_ + +- Fix unit scaling when reading in EGI digitization files using ``mne.channels.read_dig_montage`` by `Matt Boggess`_ + +- Fix ``picks`` default in :meth:`mne.io.Raw.filter` to include ``ref_meg`` channels by default by `Eric Larson`_ + +- Fix :class:`mne.decoding.CSP` order of spatial filter in ``patterns_`` by `Alexandre Barachant`_ + +- :meth:`mne.concatenate_epochs` now maintains the relative position of events during concatenation by `Alexandre Barachant`_ + +- Fix bug in script `mne make_scalp_surfaces` by `Denis Engemann`_ (this bug prevented creation of high-resolution meshes when they were absent in the first place.) + +- Fix writing of raw files with empty set of annotations by `Jaakko Leppakangas`_ + +- Fix bug in :meth:`mne.preprocessing.ICA.plot_properties` where merging gradiometers would fail by `Jaakko Leppakangas`_ + +- Fix :func:`mne.viz.plot_sensors` to maintain proper aspect ratio by `Eric Larson`_ + +- Fix :func:`mne.viz.plot_topomap` to allow 0 contours by `Jaakko Leppakangas`_ + +- Fix :class:`mne.preprocessing.ICA` source-picking to increase threshold for rank estimation to 1e-14 by `Jesper Duemose Nielsen`_ + +- Fix :func:`mne.set_bipolar_reference` to support duplicates in anodes by `Jean-Baptiste Schiratti`_ and `Alex Gramfort`_ + +- Fix visuals of :func:`mne.viz.plot_evoked` and a bug where ylim changes when using interactive topomap plotting by `Jaakko Leppakangas`_ + +- Fix :meth:`mne.Evoked.plot_topomap` when using the ``mask`` argument with paired gradiometers by `Eric Larson`_ + +- Fix bug in :meth:`mne.Label.fill` where an empty label raised an error, by `Eric Larson`_ + +- Fix :func:`mne.io.read_raw_ctf` to also include the samples in the last block by `Jaakko Leppakangas`_ + +- Fix :meth:`mne.preprocessing.ICA.save` to close file before attempting to delete it when write fails by `Jesper Duemose Nielsen`_ + +- Fix :func:`mne.simulation.simulate_evoked` to use nave parameter instead of snr, by `Yousra Bekhti`_ + +- Fix :func:`mne.read_bem_surfaces` for BEM files missing normals by `Christian Brodbeck`_ + +- Fix :func:`mne.transform_surface_to` to actually copy when ``copy=True`` by `Eric Larson`_ + +- Fix :func:`mne.io.read_raw_brainvision` to read vectorized data correctly by `Jaakko Leppakangas`_ and `Phillip Alday`_ + +- Fix :func:`mne.connectivity.spectral_connectivity` so that if ``n_jobs > 1`` it does not ignore last ``n_epochs % n_jobs`` epochs by `Mikołaj Magnuski`_ + +- Fix :func:`mne.io.read_raw_edf` to infer sampling rate correctly when reading EDF+ files where tal-channel has a higher sampling frequency by `Jaakko Leppakangas`_ + +- Fix default value of ``kind='topomap'`` in ``mne.channels.Montage.plot`` to be consistent with :func:`mne.viz.plot_montage` by `Clemens Brunner`_ + +- Fix bug in :meth:`to_data_frame ` where non-consecutive picks would make the function crash by `Jaakko Leppakangas`_ + +- Fix channel picking and drop in :class:`mne.time_frequency.EpochsTFR` by `Lukáš Hejtmánek`_ + +- Fix :func:`mne.SourceEstimate.transform` to properly update :attr:`mne.SourceEstimate.times` by `Marijn van Vliet`_ + +- Fix :func:`mne.viz.plot_evoked_joint` to allow custom titles without appending information about the channels by `Jaakko Leppakangas`_ + +- Fix writing a forward solution after being processed by :func:`mne.forward.restrict_forward_to_label` or :func:`mne.forward.restrict_forward_to_stc` by `Marijn van Vliet`_ + +- Fix bug in :func:`mne.viz.plot_compare_evokeds` where ``truncate_yaxis`` was ignored (default is now ``False``), by `Jona Sassenhagen`_ + +- Fix bug in :func:`mne.viz.plot_evoked` where all xlabels were removed when using ``spatial_colors=True``, by `Jesper Duemose Nielsen`_ + +- Fix field mapping :func:`mne.make_field_map` and MEG bad channel interpolation functions (e.g., :meth:`mne.Evoked.interpolate_bads`) to choose a better number of components during pseudoinversion when few channels are available, by `Eric Larson`_ + +- Fix bug in :func:`mne.io.read_raw_brainvision`, changed default to read coordinate information if available and added test, by `Jesper Duemose Nielsen`_ + +- Fix bug in :meth:`mne.SourceEstimate.to_original_src` where morphing failed if two vertices map to the same target vertex, by `Marijn van Vliet`_ + +- Fix :class:`mne.preprocessing.Xdawn` to give verbose error messages about rank deficiency and handle transforming :class:`mne.Evoked`, by `Eric Larson`_ + +- Fix bug in DC and Nyquist frequency multitaper PSD computations, e.g. in :func:`mne.time_frequency.psd_multitaper`, by `Eric Larson`_ + +- Fix default padding type for :meth:`mne.Epochs.resample` and :meth:`mne.Evoked.resample` to be ``'edge'`` by default, by `Eric Larson`_ + +- Fix :func:`mne.inverse_sparse.mixed_norm`, :func:`mne.inverse_sparse.tf_mixed_norm` and :func:`mne.inverse_sparse.gamma_map` to work with volume source space and sphere head models in MEG by `Alex Gramfort`_ and `Yousra Bekhti`_ + +- Fix :meth:`mne.Evoked.as_type` channel renaming to append ``'_v'`` instead of ``'_virtual'`` to channel names to comply with shorter naming (15 char) requirements, by `Eric Larson`_ + +- Fix treatment of CTF HPI coils as fiducial points in :func:`mne.gui.coregistration` by `Eric Larson`_ + +- Fix resampling of events along with raw in :func:`mne.io.Raw` to now take into consideration the value of ``first_samp`` by `Chris Bailey`_ + +- Fix labels of PSD plots in :func:`mne.viz.plot_raw_psd` by `Alejandro Weinstein`_ + +- Fix depth weighting of sparse solvers (:func:`mne.inverse_sparse.mixed_norm`, :func:`mne.inverse_sparse.tf_mixed_norm` and :func:`mne.inverse_sparse.gamma_map`) with free orientation source spaces to improve orientation estimation by `Alex Gramfort`_ and `Yousra Bekhti`_ + +- Fix the threshold in :func:`mne.beamformer.rap_music` to properly estimate the rank by `Yousra Bekhti`_ + +- Fix treatment of vector inverse in :func:`mne.minimum_norm.apply_inverse_epochs` by `Emily Stephen`_ + +- Fix :func:`mne.find_events` when passing a list as stim_channel parameter by `Alex Gramfort`_ + +- Fix parallel processing when computing covariance with shrinkage estimators by `Denis Engemann`_ + +API +~~~ +- Removed the ``mne.datasets.megsim`` dataset because it was taken down by its host (MRN). Use the :mod:`mne.simulation` functions instead, by `Eric Larson`_ + +- Add ``skip_by_annotation`` to :meth:`mne.io.Raw.filter` to process data concatenated with e.g. :func:`mne.concatenate_raws` separately. This parameter will default to the old behavior (treating all data as a single block) in 0.15 but will change to ``skip_by_annotation='edge'``, which will separately filter the concatenated chunks separately, in 0.16. This should help prevent potential problems with filter-induced ringing in concatenated files, by `Eric Larson`_ + +- ICA channel names have now been reformatted to start from zero, e.g. ``"ICA000"``, to match indexing schemes in :class:`mne.preprocessing.ICA` and related functions, by `Stefan Repplinger`_ and `Eric Larson`_ + +- Add :func:`mne.beamformer.make_lcmv` and :func:`mne.beamformer.apply_lcmv`, :func:`mne.beamformer.apply_lcmv_epochs`, and :func:`mne.beamformer.apply_lcmv_raw` to enable the separate computation and application of LCMV beamformer weights by `Britta Westner`_, `Alex Gramfort`_, and `Denis Engemann`_. + +- Add ``weight_norm`` parameter to enable both unit-noise-gain beamformer and neural activity index (weight normalization) and make whitening optional by allowing ``noise_cov=None`` in ``mne.beamformer.lcmv``, ``mne.beamformer.lcmv_epochs``, and ``mne.beamformer.lcmv_raw``, by `Britta Westner`_, `Alex Gramfort`_, and `Denis Engemann`_. + +- Add new filtering mode ``fir_design='firwin'`` (default in the next 0.16 release) that gets improved attenuation using fewer samples compared to ``fir_design='firwin2'`` (default in the current 0.15 release) by `Eric Larson`_ + +- Make the goodness of fit (GOF) of the dipoles returned by :func:`mne.beamformer.rap_music` consistent with the GOF of dipoles returned by :func:`mne.fit_dipole` by `Alex Gramfort`_. + +- :class:`mne.decoding.SlidingEstimator` will now replace ``mne.decoding.TimeDecoding`` to make it generic and fully compatible with scikit-learn, by `Jean-Remi King`_ and `Alex Gramfort`_ + +- :class:`mne.decoding.GeneralizingEstimator` will now replace ``mne.decoding.GeneralizationAcrossTime`` to make it generic and fully compatible with scikit-learn, by `Jean-Remi King`_ and `Alex Gramfort`_ + +- ``mne.viz.decoding.plot_gat_times``, ``mne.viz.decoding.plot_gat_matrix`` are now deprecated. Use matplotlib instead as shown in the examples, by `Jean-Remi King`_ and `Alex Gramfort`_ + +- Add ``norm_trace`` parameter to control single-epoch covariance normalization in :class:mne.decoding.CSP, by `Jean-Remi King`_ + +- Allow passing a list of channel names as ``show_names`` in function :func:`mne.viz.plot_sensors` and methods :meth:`mne.Evoked.plot_sensors`, :meth:`mne.Epochs.plot_sensors` and :meth:`mne.io.Raw.plot_sensors` to show only a subset of channel names by `Jaakko Leppakangas`_ + +- Make function ``mne.io.eeglab.read_events_eeglab`` public to allow loading overlapping events from EEGLAB files, by `Jona Sassenhagen`_. + +- :func:`mne.find_events` ``mask_type`` parameter will change from ``'not_and'`` to ``'and'`` in 0.16. + +- Instead of raising an error, duplicate channel names in the data file are now appended with a running number by `Jaakko Leppakangas`_ + +- :func:`mne.io.read_raw_edf` has now ``'auto'`` option for ``stim_channel`` (default in version 0.16) that automatically detects if EDF annotations or GDF events exist in the header and constructs the stim channel based on these events by `Jaakko Leppakangas`_ + +- :meth:`mne.io.Raw.plot_psd` now rejects data annotated bad by default. Turn off with ``reject_by_annotation=False``, by `Eric Larson`_ + +- :func:`mne.set_eeg_reference` and the related methods (e.g., :meth:`mne.io.Raw.set_eeg_reference`) have a new argument ``projection``, which if set to False directly applies an average reference instead of adding an SSP projector, by `Clemens Brunner`_ + +- Deprecate ``plot_trans`` in favor of :func:`mne.viz.plot_alignment` and add ``bem`` parameter for plotting conductor model by `Jaakko Leppakangas`_ + +- :func:`mne.beamformer.tf_lcmv` now has a ``raw`` parameter to accommodate epochs objects that already have data loaded with ``preload=True``, with :meth:`mne.Epochs.load_data`, or that are read from disk, by `Eric Larson`_ + +- :func:`mne.time_frequency.psd_welch` and :func:`mne.time_frequency.psd_array_welch` now use a Hamming window (instead of a Hann window) by `Clemens Brunner`_ + +- ``picks`` parameter in ``mne.beamformer.lcmv``, ``mne.beamformer.lcmv_epochs``, ``mne.beamformer.lcmv_raw``, :func:`mne.beamformer.tf_lcmv` and :func:`mne.beamformer.rap_music` is now deprecated and will be removed in 0.16, by `Britta Westner`_, `Alex Gramfort`_, and `Denis Engemann`_. + +- The keyword argument ``frequencies`` has been deprecated in favor of ``freqs`` in various time-frequency functions, e.g. :func:`mne.time_frequency.tfr_array_morlet`, by `Eric Larson`_ + +- Add ``patterns=False`` parameter in :class:`mne.decoding.ReceptiveField`. Turn on to compute inverse model coefficients, by `Nicolas Barascud`_ + +- The ``scale``, ``scale_time``, and ``unit`` parameters have been deprecated in favor of ``scalings``, ``scalings_time``, and ``units`` in :func:`mne.viz.plot_evoked_topomap` and related functions, by `Eric Larson`_ + +- ``loose`` parameter in inverse solvers has now a default value ``'auto'`` depending if the source space is a surface, volume, or discrete type by `Alex Gramfort`_ and `Yousra Bekhti`_ + +- The behavior of ``'mean_flip'`` label-flipping in :meth:`mne.extract_label_time_course` and related functions has been changed such that the flip, instead of having arbitrary sign, maximally aligns in the positive direction of the normals of the label, by `Eric Larson`_ + +- Deprecate force_fixed and surf_ori in :func:`mne.read_forward_solution` by `Daniel Strohmeier`_ + +- :func:`mne.convert_forward_solution` has a new argument ``use_cps``, which controls whether information on cortical patch statistics is applied while generating surface-oriented forward solutions with free and fixed orientation by `Daniel Strohmeier`_ + +- :func:`mne.write_forward_solution` writes a forward solution as a forward solution with free orientation in X/Y/Z RAS coordinates if it is derived from a forward solution with free orientation and as a forward solution with fixed orientation in surface-based local coordinates otherwise by `Daniel Strohmeier`_ + +- ``loose=None`` in inverse solvers is deprecated, use explicitly ``loose=0`` for fixed constraint and ``loose=1.0`` for free orientations by `Eric Larson`_ + +- Zero-channel-value in PSD calculation in :func:`mne.viz.plot_raw_psd` has been relaxed from error to warning by `Alejandro Weinstein`_ + +- Expose "rank" parameter in :func:`mne.viz.plot_evoked_white` to correct rank estimates on the spot during visualization by `Denis Engemann`_, `Eric Larson`_, `Alex Gramfort`_. + +- Show channel name under mouse cursor on topography plots by `Jussi Nurminen`_ + +- Return maximum response amplitude from :meth:`mne.Evoked.get_peak` + +Authors +~~~~~~~ + +People who contributed to this release (in alphabetical order): + +* akshay0724 +* Alejandro Weinstein +* Alexander Rudiuk +* Alexandre Barachant +* Alexandre Gramfort +* Andrew Dykstra +* Britta Westner +* Chris Bailey +* Chris Holdgraf +* Christian Brodbeck +* Christopher Holdgraf +* Clemens Brunner +* Cristóbal Moënne-Loccoz +* Daniel McCloy +* Daniel Strohmeier +* Denis A. Engemann +* Emily P. Stephen +* Eric Larson +* Fede Raimondo +* Jaakko Leppakangas +* Jean-Baptiste Schiratti +* Jean-Remi King +* Jesper Duemose Nielsen +* Joan Massich +* Jon Houck +* Jona Sassenhagen +* Jussi Nurminen +* Laetitia Grabot +* Laura Gwilliams +* Luke Bloy +* Lukáš Hejtmánek +* Mainak Jas +* Marijn van Vliet +* Mathurin Massias +* Matt Boggess +* Mikolaj Magnuski +* Nicolas Barascud +* Nicole Proulx +* Phillip Alday +* Ramonapariciog Apariciogarcia +* Robin Tibor Schirrmeister +* Rodrigo Hübner +* S. M. Gutstein +* Simon Kern +* Teon Brooks +* Yousra Bekhti diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.16.inc python-mne-0.19.1+dfsg/doc/changes/0.16.inc --- python-mne-0.18.1+dfsg/doc/changes/0.16.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.16.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,258 @@ +.. _changes_0_16: + +Version 0.16 +------------ + +Changelog +~~~~~~~~~ + +- Add possibility to pass dict of floats as argument to :func:`mne.make_ad_hoc_cov` by `Nathalie Gayraud`_ + +- Add support for metadata in :class:`mne.Epochs` by `Chris Holdgraf`_, `Alex Gramfort`_, `Jona Sassenhagen`_, and `Eric Larson`_ + +- Add support for plotting a dense head in :func:`mne.viz.plot_alignment` by `Eric Larson`_ + +- Allow plotting in user-created mayavi Scene in :func:`mne.viz.plot_alignment` by `Daniel McCloy`_ + +- Reduce memory consumption and do not require data to be loaded in :meth:`mne.Epochs.apply_baseline` by `Eric Larson`_ + +- Add option ``render_bem`` to :meth:`mne.Report.parse_folder` by `Eric Larson`_ + +- Add to :func:`mne.viz.plot_alignment` plotting of coordinate frame axes via ``show_axes`` and terrain-style interaction via ``interaction``, by `Eric Larson`_ + +- Add option ``initial_event`` to :func:`mne.find_events` by `Clemens Brunner`_ + +- Left and right arrow keys now scroll by 25% of the visible data, whereas Shift+left/right scroll by a whole page in :meth:`mne.io.Raw.plot` by `Clemens Brunner`_ + +- Add support for gantry tilt angle determination from Elekta FIF file header by `Chris Bailey`_ + +- Add possibility to concatenate :class:`mne.Annotations` objects with ``+`` or ``+=`` operators by `Clemens Brunner`_ + +- Add support for MaxShield raw files in :class:`mne.Report` by `Eric Larson`_ + +- Add ability to plot whitened data in :meth:`mne.io.Raw.plot`, :meth:`mne.Epochs.plot`, :meth:`mne.Evoked.plot`, and :meth:`mne.Evoked.plot_topo` by `Eric Larson`_ + +- Workaround for reading EGI MFF files with physiological signals that also present a bug from the EGI system in :func:`mne.io.read_raw_egi` by `Federico Raimondo`_ + +- Add support for reading subject height and weight in ``info['subject_info']`` by `Eric Larson`_ + +- Improve online filtering of raw data when plotting with :meth:`mne.io.Raw.plot` to filter in segments in accordance with the default ``skip_by_annotation=('edge', 'bad_acq_skip')`` of :meth:`mne.io.Raw.filter` to avoid edge ringing by `Eric Larson`_ + +- Add support for multiple head position files, plotting of sensors, and control of plotting color and axes in :func:`mne.viz.plot_head_positions` by `Eric Larson`_ + +- Add ability to read and write :class:`Annotations` separate from :class:`mne.io.Raw` instances via :meth:`Annotations.save` and :func:`read_annotations` by `Eric Larson`_ + +- Add option to unset a montage by passing `None` to :meth:`mne.io.Raw.set_montage` by `Clemens Brunner`_ + +- Add sensor denoising via :func:`mne.preprocessing.oversampled_temporal_projection` by `Eric Larson`_ + +- Add ``mne.io.pick.get_channel_types`` which returns all available channel types in MNE by `Clemens Brunner`_ + +- Use standard PCA instead of randomized PCA whitening prior to ICA to increase reproducibility by `Clemens Brunner`_ + +- Plot sEEG electrodes in :func:`mne.viz.plot_alignment` by `Alex Gramfort`_ + +- Add support for any data type like sEEG or ECoG in covariance related functions (estimation, whitening and plotting) by `Alex Gramfort`_ and `Eric Larson`_ + +- Add function ``mne.io.read_annotations_eeglab`` to allow loading annotations from EEGLAB files, by `Alex Gramfort`_ + +- :meth:`mne.io.Raw.set_montage` now accepts a string as its ``montage`` argument; this will set a builtin montage, by `Clemens Brunner`_ + +- Add 4D BTi phantom dataset :func:`mne.datasets.phantom_4dbti.data_path`, by `Alex Gramfort`_ + +- Changed the background color to grey in :func:`mne.viz.plot_alignment` to make helmet more visible, by `Alex Gramfort`_ + +- Add :meth:`mne.io.Raw.reorder_channels`, :meth:`mne.Evoked.reorder_channels`, etc. to reorder channels, by `Eric Larson`_ + +- Add to ``mne coreg`` and :func:`mne.gui.coregistration` by `Eric Larson`_: + + - Improved visibility of points inside the head + - Projection of EEG electrodes + - Orientation of extra points toward the surface + - Scaling points by distance to the head surface + - Display of HPI points + - ICP fitting with convergence criteria + - Faster display updates + - Scaling of ``mri/*.mgz`` files + - Scaling of ``mri/trainsforms/talairach.xfm`` files for conversion to MNI space + +- Add ability to exclude components interactively by clicking on their labels in :meth:`mne.preprocessing.ICA.plot_components` by `Mikołaj Magnuski`_ + +- Add reader for manual annotations of raw data produced by Brainstorm by `Anne-Sophie Dubarry`_ + +- Add eLORETA noise normalization for minimum-norm solvers by `Eric Larson`_ + +- Tighter duality gap computation in ``mne.inverse_sparse.tf_mxne_optim`` and new parametrization with ``alpha`` and ``l1_ratio`` instead of ``alpha_space`` and ``alpha_time`` by `Mathurin Massias`_ and `Daniel Strohmeier`_ + +- Add ``dgap_freq`` parameter in ``mne.inverse_sparse.mxne_optim`` solvers to control the frequency of duality gap computation by `Mathurin Massias`_ and `Daniel Strohmeier`_ + +- Add support for reading Eximia files by `Eric Larson`_ and `Federico Raimondo`_ + +- Add the Picard algorithm to perform ICA for :class:`mne.preprocessing.ICA`, by `Pierre Ablin`_ and `Alex Gramfort`_ + +- Add ability to supply a mask to the plot in :func:`mne.viz.plot_evoked_image` by `Jona Sassenhagen`_ + +- Add ``connectivity=False`` to cluster-based statistical functions to perform non-clustering stats by `Eric Larson`_ + +- Add :func:`mne.time_frequency.csd_morlet` and :func:`mne.time_frequency.csd_array_morlet` to estimate cross-spectral density using Morlet wavelets, by `Marijn van Vliet`_ + +- Add multidictionary time-frequency support to :func:`mne.inverse_sparse.tf_mixed_norm` by `Mathurin Massias`_ and `Daniel Strohmeier`_ + +- Add new DICS implementation as :func:`mne.beamformer.make_dics`, :func:`mne.beamformer.apply_dics`, :func:`mne.beamformer.apply_dics_csd` and :func:`mne.beamformer.apply_dics_epochs`, by `Marijn van Vliet`_ and `Susanna Aro`_ + +Bug +~~~ + +- Fix bug in EEG interpolation code to do nothing if there is no channel to interpolate by `Mainak Jas`_ + +- Fix bug in ``mne.preprocessing.peak_finder`` to output datatype consistently and added input check for empty vectors by `Tommy Clausner`_ + +- Fix bug in :func:`mne.io.read_raw_brainvision` to use the correct conversion for filters from time constant to frequency by `Stefan Appelhoff`_ + +- Fix bug with events when saving split files using :meth:`mne.Epochs.save` by `Eric Larson`_ + +- Fix bug in :class:`mne.decoding.SlidingEstimator` and :class:`mne.decoding.GeneralizingEstimator` to allow :func:`mne.decoding.cross_val_multiscore` to automatically detect whether the `base_estimator` is a classifier and use a `StratifiedKFold` instead of a `KFold` when `cv` is not specified, by `Jean-Remi King`_ + +- Fix bug in :func:`mne.set_eeg_reference` to remove an average reference projector when setting the reference to ``[]`` (i.e. do not change the existing reference) by `Clemens Brunner`_ + +- Fix bug in threshold-free cluster enhancement parameter validation (:func:`mne.stats.permutation_cluster_1samp_test` and :func:`mne.stats.permutation_cluster_test`) by `Clemens Brunner`_ + +- Fix bug in :meth:`mne.io.Raw.plot` to correctly display event types when annotations are present by `Clemens Brunner`_ + +- Fix bug in :func:`mne.stats.spatio_temporal_cluster_test` default value for ``threshold`` is now calculated based on the array sizes in ``X``, by `Eric Larson`_ + +- Fix bug in :func:`mne.simulation.simulate_raw` with ``use_cps=True`` where CPS was not actually used by `Eric Larson`_ + +- Fix bug in :func:`mne.simulation.simulate_raw` where 1- and 3-layer BEMs were not properly transformed using ``trans`` by `Eric Larson`_ + +- Fix bug in :func:`mne.viz.plot_alignment` where the head surface file ``-head.fif`` was not used even though present by `Chris Bailey`_ + +- Fix bug when writing compressed sparse column matrices (e.g., Maxwell filtering cross-talk matrices) by `Marijn van Vliet`_ and `Eric Larson`_ + +- Fix bug in :meth:`mne.io.Raw.plot_psd` to correctly deal with ``reject_by_annotation=False`` by `Clemens Brunner`_ + +- Fix bug in :func:`mne.make_fixed_length_events` when hitting corner case problems rounding to sample numbers by `Eric Larson`_ + +- Fix bug in :class:`mne.Epochs` when passing events as list with ``event_id=None`` by `Alex Gramfort`_ + +- Fix bug in :meth:`mne.Report.add_figs_to_section` when passing :class:`numpy.ndarray` by `Eric Larson`_ + +- Fix bug in CSS class setting in `mne.Report` BEM section by `Eric Larson`_ + +- Fix bug in :class:`Annotations` where annotations that extend to the end of a recording were not extended properly by `Eric Larson`_ + +- Fix bug in :meth:`mne.io.Raw.filter` to properly raw data with acquisition skips in separate segments by `Eric Larson`_ + +- Fix bug in :func:`mne.preprocessing.maxwell_filter` where homogeneous fields were not removed for CTF systems by `Eric Larson`_ + +- Fix computation of average quaternions in :func:`mne.preprocessing.maxwell_filter` by `Eric Larson`_ + +- Fix bug in writing ``raw.annotations`` where empty annotations could not be written to disk, by `Eric Larson`_ + +- Fix support for writing FIF files with acquisition skips by using empty buffers rather than writing zeros by `Eric Larson`_ + +- Fix bug in the ``mne make_scalp_surfaces`` command where ``--force`` (to bypass topology check failures) was ignored by `Eric Larson`_ + +- Fix bug in :func:`mne.preprocessing.maxwell_filter` when providing ``origin`` in ``'meg'`` coordinate frame for recordings with a MEG to head transform (i.e., non empty-room recordings) by `Eric Larson`_ + +- Fix bug in :func:`mne.viz.plot_cov` that ignored ``colorbar`` argument by `Nathalie Gayraud`_ + +- Fix bug when picking CTF channels that could cause data saved to disk to be unreadable by `Eric Larson`_ + +- Fix bug when reading event latencies (in samples) from eeglab files didn't translate indices to 0-based python indexing by `Mikołaj Magnuski`_ + +- Fix consistency between :class:`mne.Epochs` and :func:`mne.stats.linear_regression_raw` in converting between samples and times (:func:`mne.stats.linear_regression_raw` now rounds, instead of truncating) by `Phillip Alday`_ + +- Fix bug in ``mne coreg`` where sphere surfaces were scaled by `Eric Larson`_ + +- Fix bug in :meth:`mne.Evoked.plot_topomap` when using ``proj='interactive'`` mode by `Eric Larson`_ + +- Fix bug when passing ``show_sensors=1`` to :func:`mne.viz.plot_compare_evokeds` resulted in sensors legend placed in lower right of the figure (position 4 in matplotlib), not upper right by `Mikołaj Magnuski`_ + +- Fix handling of annotations when cropping and concatenating raw data by `Alex Gramfort`_ and `Eric Larson`_ + +- Fix bug in :func:`mne.preprocessing.create_ecg_epochs` where ``keep_ecg=False`` was ignored by `Eric Larson`_ + +- Fix bug in :meth:`mne.io.Raw.plot_psd` when ``picks is not None`` and ``picks`` spans more than one channel type by `Eric Larson`_ + +- Fix bug in :class:`mne.make_forward_solution` when passing data with compensation channels (e.g. CTF) that contain bad channels by `Alex Gramfort`_ + +- Fix bug in :meth:`mne.SourceEstimate.get_peak` and :meth:`mne.VolSourceEstimate.get_peak` when there is only a single time point by `Marijn van Vliet`_ + +- Fix bug in :func:`mne.io.read_raw_edf` when reading BDF files stimulus channels are now not scaled anymore by `Clemens Brunner`_ + +API +~~~ + +- Channels with unknown locations are now assigned position ``[np.nan, np.nan, np.nan]`` instead of ``[0., 0., 0.]``, by `Eric Larson`_ + +- Removed unused ``image_mask`` argument from :func:`mne.viz.plot_topomap` by `Eric Larson`_ + +- Unknown measurement dates are now stored as ``info['meas_date'] = None`` rather than using the current date. ``None`` is also now used when anonymizing data and when determining the machine ID for writing files, by `Mainak Jas`_ and `Eric Larson`_ + +- :meth:`mne.Evoked.plot` will now append the number of epochs averaged for the evoked data in the first plot title, by `Eric Larson`_ + +- Changed the line width in :func:`mne.viz.plot_bem` from 2.0 to 1.0 for better visibility of underlying structures, by `Eric Larson`_ + +- Changed the behavior of :meth:`mne.io.Raw.pick_channels` and similar methods to be consistent with :func:`mne.pick_channels` to treat channel list as a set (ignoring order) -- if reordering is necessary use ``inst.reorder_channels``, by `Eric Larson`_ + +- Changed the labeling of some plotting functions to use more standard capitalization and units, e.g. "Time (s)" instead of "time [sec]" by `Eric Larson`_ + +- ``mne.time_frequency.csd_epochs`` has been refactored into :func:`mne.time_frequency.csd_fourier` and :func:`mne.time_frequency.csd_multitaper`, by `Marijn van Vliet`_ + +- ``mne.time_frequency.csd_array`` has been refactored into :func:`mne.time_frequency.csd_array_fourier` and :func:`mne.time_frequency.csd_array_multitaper`, by `Marijn van Vliet`_ + +- Added ``clean_names=False`` parameter to :func:`mne.io.read_raw_ctf` for control over cleaning of main channel names and compensation channel names from CTF suffixes by `Oleh Kozynets`_ + +- The functions ``lcmv``, ``lcmv_epochs``, and ``lcmv_raw`` are now deprecated in favor of :func:`mne.beamformer.make_lcmv` and :func:`mne.beamformer.apply_lcmv`, :func:`mne.beamformer.apply_lcmv_epochs`, and :func:`mne.beamformer.apply_lcmv_raw`, by `Britta Westner`_ + +- The functions ``mne.beamformer.dics``, ``mne.beamformer.dics_epochs`` and ``mne.beamformer.dics_source_power`` are now deprecated in favor of :func:`mne.beamformer.make_dics`, :func:`mne.beamformer.apply_dics`, and :func:`mne.beamformer.apply_dics_csd`, by `Marijn van Vliet`_ + + +Authors +~~~~~~~ + +People who contributed to this release (in alphabetical order): + +* Alejandro Weinstein +* Alexandre Gramfort +* Annalisa Pascarella +* Anne-Sophie Dubarry +* Britta Westner +* Chris Bailey +* Chris Holdgraf +* Christian Brodbeck +* Claire Braboszcz +* Clemens Brunner +* Daniel McCloy +* Denis A. Engemann +* Desislava Petkova +* Dominik Krzemiński +* Eric Larson +* Erik Hornberger +* Fede Raimondo +* Henrich Kolkhorst +* Jean-Remi King +* Jen Evans +* Joan Massich +* Jon Houck +* Jona Sassenhagen +* Juergen Dammers +* Jussi Nurminen +* Kambiz Tavabi +* Katrin Leinweber +* Kostiantyn Maksymenko +* Larry Eisenman +* Luke Bloy +* Mainak Jas +* Marijn van Vliet +* Mathurin Massias +* Mikolaj Magnuski +* Nathalie Gayraud +* Oleh Kozynets +* Phillip Alday +* Pierre Ablin +* Stefan Appelhoff +* Stefan Repplinger +* Tommy Clausner +* Yaroslav Halchenko diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.17.inc python-mne-0.19.1+dfsg/doc/changes/0.17.inc --- python-mne-0.18.1+dfsg/doc/changes/0.17.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.17.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,317 @@ +.. _changes_0_17: + +Version 0.17 +------------ + +Changelog +~~~~~~~~~ + +- Add new tutorial for :class:`mne.Annotations` and ``events`` by `Joan Massich`_ and `Alex Gramfort`_ + +- Add support for saving :class:`mne.Annotations` as CSV and TXT files by `Joan Massich`_ and `Alex Gramfort`_ + +- Add :meth:`mne.Epochs.shift_time` that shifts the time axis of :class:`mne.Epochs` by `Thomas Hartmann`_ + +- Add :func:`mne.viz.plot_arrowmap` computes arrowmaps using Hosaka-Cohen transformation from magnetometer or gradiometer data, these arrows represents an estimation of the current flow underneath the MEG sensors by `Sheraz Khan`_ + +- Add :func:`mne.io.read_raw_fieldtrip`, :func:`mne.read_epochs_fieldtrip` and :func:`mne.read_evoked_fieldtrip` to import FieldTrip data. By `Thomas Hartmann`_ and `Dirk Gütlin`_. + +- Add ``rank`` parameter to :func:`mne.compute_covariance`, :func:`mne.cov.regularize` and related functions to preserve data rank and speed up computation using low-rank computations during regularization by `Eric Larson`_ and `Denis Engemann`_ + +- Add new function :func:`mne.read_annotations` that can read annotations in EEGLAB, BrainVision, EDF and Brainstorm formats by `Joan Massich`_ and `Alex Gramfort`_. + +- Add capability to read and save Epochs containing complex data (e.g. after Hilbert-transform) using :meth:`mne.Epochs.save` and :func:`mne.read_epochs`, by `Stefan Repplinger`_, `Eric Larson`_ and `Alex Gramfort`_ + +- Add optically pumped magnetometer dataset and example by `Rasmus Zetter`_ and `Eric Larson`_ + +- Add ``orgin`` parameter to :meth:`mne.io.Raw.time_as_index` to allow ``times`` to be relative to this ``origin`` by `Joan Massich`_ + +- Add ``title`` argument to :meth:`mne.SourceEstimate.plot` by `Eric Larson`_ + +- :func:`mne.io.Raw.set_annotations` now changes ``orig_time`` to match ``meas_date`` and shift ``self.annotations.onset`` accordingly. Previous behavior is deprecated and would be removed in 0.18. Work by `Joan Massich`_ + +- Add :func:`mne.compute_source_morph` which creates a :class:`mne.SourceMorph` object to unify morphing any type of source estimates (surface or volume) from one subject to another for group studies. It is now possible to do group studies when working on the volume with MNE. Work by `Tommy Clausner`_ during GSOC 2018 with the help of `Alex Gramfort`_ and `Eric Larson`_. + +- Add ability to pass threshold for EOG to :func:`mne.preprocessing.find_eog_events` and :func:`mne.preprocessing.create_eog_epochs` by `Peter Molfese`_ + +- Add possibility to save :class:`mne.VolSourceEstimate` and :class:`mne.MixedSourceEstimate` to HDF5 format (file extension .h5) with :meth:`mne.VolSourceEstimate.save` and :meth:`mne.MixedSourceEstimate.save` by `Alex Gramfort`_ + +- Add `replace` parameter to :meth:`mne.io.Raw.add_events` to allow adding events while removing the old ones on the stim channel by `Alex Gramfort`_ + +- Add ability to pass ``axes`` to ``ts_args`` and ``topomap_args`` of :meth:`mne.viz.plot_evoked_joint` by `Jona Sassenhagen`_ + +- Add ability to pass a precomputed forward solution to :func:`mne.simulation.simulate_raw` by `Eric Larson`_ + +- Add ability to read and write beamformers with :func:`mne.beamformer.read_beamformer` and :class:`mne.beamformer.Beamformer.save` by `Eric Larson`_ + +- Add resting-state source power spectral estimation example ``sphx_glr_auto_examples_datasets_plot_opm_rest_data.py`` by `Eric Larson`_, `Denis Engemann`_, and `Luke Bloy`_ + +- Add :func:`mne.channels.make_1020_channel_selections` to group 10/20-named EEG channels by location, by `Jona Sassenhagen`_ + +- Add helmet for Artemis123 for :func:`mne.viz.plot_alignment` by `Eric Larson`_ + +- Add support for reading MATLAB ``v7.3+`` files in :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab` via `pymatreader`_ by `Steven Gutstein`_, `Eric Larson`_, and `Thomas Hartmann`_ + +- Add support for raw PSD plots in :meth:`mne.Report.parse_folder` via ``raw_psd`` argument of :class:`mne.Report` by `Eric Larson`_ + +- Add `trig_shift_by_type` parameter in :func:`mne.io.read_raw_brainvision` to allow to specify offsets for arbitrary marker types by `Henrich Kolkhorst`_ + +- Add progress bar support to :class:`mne.decoding.SlidingEstimator` and :class:`mne.decoding.GeneralizingEstimator` by `Eric Larson`_ + +- Add interactive visualization of volume source estimates using :func:`mne.viz.plot_volume_source_estimates` by `Mainak Jas`_ + +- Add :func:`mne.head_to_mri` to convert positions from head coordinates to MRI RAS coordinates, by `Joan Massich`_ and `Alex Gramfort`_ + +- Add improved CTF helmet for :func:`mne.viz.plot_alignment` by `Eric Larson`_ + +- Add handling in :func:`mne.combine_evoked` and :func:`mne.grand_average` for input with the same channels in different orders, if required, by `Jona Sassenhagen`_ + +- Add `split_naming` parameter to the `Raw.save` method to allow for BIDS-compatible raw file name construction by `Teon Brooks`_ + +- Add ``origin`` parameter to :meth:`mne.Evoked.interpolate_bads` and related methods by `Eric Larson`_ + +- Add automated MEG helmet shape approximation to :func:`mne.viz.plot_alignment` by `Eric Larson`_ + +- Add capability to save a :class:`mne.Report` to an HDF5 file to :meth:`mne.Report.save` by `Marijn van Vliet`_ + +- Add :func:`mne.open_report` to read back a :class:`mne.Report` object that was saved to an HDF5 file by `Marijn van Vliet`_ + +- Add multi-taper estimation to :func:`mne.minimum_norm.compute_source_psd` by `Eric Larson`_ + +- Add support for custom, e.g. robust, averaging methods in :meth:`mne.Epochs.average` by `Jona Sassenhagen`_ + +- Add support for Neuromag 122 system by `Alex Gramfort`_ + +- Add function ``mne.io.read_annotations_brainvision`` for reading directly Brainvision marker files by `Alex Gramfort`_ + +- Add :meth:`mne.Report.remove` method to remove existing figures from a report, by `Marijn van Vliet`_ + +- Add sign to output of max-power orientation for :func:`mne.beamformer.make_dics` by `Eric Larson`_ + +- Add support for ``pick_ori='max-power'`` when ``weight_norm=None`` in :func:`mne.beamformer.make_lcmv` by `Marijn van Vliet`_ + +- Add support for ``weight_norm='nai'`` for all ``pick_ori`` options in :func:`mne.beamformer.make_lcmv` by `Marijn van Vliet`_ + +- Add support for ``weight_norm='nai'`` to :func:`mne.beamformer.make_dics` by `Marijn van Vliet`_ + +- Add parameter ``rank=None`` to :func:`mne.beamformer.make_dics` by `Marijn van Vliet`_ + +- Add parameter ``rank='full'`` to :func:`mne.beamformer.make_lcmv`, which can be set to ``None`` to auto-compute the rank of the covariance matrix before regularization by `Marijn van Vliet`_ + +- Handle different time vectors in topography plots using :func:`mne.viz.plot_evoked_topo` by `Jussi Nurminen`_ + +- Speed up :func:`mne.inverse_sparse.mixed_norm` if the :solver: parameter is set to `bcd` using :func:`scipy.linalg.get_blas_funcs` by `Quentin Bertrand`_ + +Bug +~~~ + +- Fix bug with scaling of data in ``mne.cov._compute_covariance_auto`` that was affecting the :class:`mne.decoding.SPoC` estimator by `David Sabbagh`_ + +- Fix :func:`mne.io.Raw.plot_projs_topomap` by `Joan Massich`_ + +- Fix bug in :func:`mne.minimum_norm.compute_source_psd` where the ``stc.times`` output was scaled by 1000, by `Eric Larson`_ + +- Fix default values for ``'diagonal_fixed'`` estimation method of :func:`mne.compute_covariance` to be ``0.1`` for all channel types, as in :func:`mne.cov.regularize` by `Eric Larson`_ + +- Fix reading edf file annotations by `Joan Massich`_ + +- Fix bug with reading events from BrainVision files by `Stefan Appelhoff`_ + +- Fix bug where :func:`mne.io.read_raw_eeglab` would warn when the stim channel is populated with an array of zeros by `Joan Massich`_ + +- Fix 2nd column of events in BrainVision to no longer store duration but rather be contained by ``raw.annotations`` by `Alex Gramfort`_ + +- Fix checking of the correctness of the ``prepared=True`` argument in :func:`mne.minimum_norm.apply_inverse` and related functions by `Eric Larson`_ + +- Fix bug of not showing ERD's in baseline rescaled tfr topomaps if grads are combined by `Erkka Heinila`_ + +- Fix bug with FIF I/O where strings were written in UTF-8 format instead of Latin-1 by `Eric Larson`_ + +- Fix bug with reading measurement dates from BrainVision files by `Stefan Appelhoff`_ + +- Fix bug with `mne.fit_dipole` where the residual was returned as ``ndarray`` instead of :class:`mne.Evoked` instance, by `Eric Larson`_ + +- Fix bug with ``mne flash_bem`` when ``flash30`` is not used by `Eric Larson`_ + +- Fix bug with :func:`mne.stats.permutation_cluster_test` and :func:`mne.stats.spatio_temporal_cluster_test` where ``threshold=None`` was not calculated properly for a f-oneway test by `Daniel McCloy`_ and `Eric Larson`_ + +- Fix bug with channel names in ``mgh70`` montage in ``mne.channels.read_montage`` by `Eric Larson`_ + +- Fix duplication of ``info['hpi_meas']`` and ``info['hpi_results']`` by `Sara Sommariva`_ + +- Fix bug in :func:`mne.io.read_raw_edf` when reading large files on Windows by `Marcin Koculak`_ + +- Fix check in :func:`mne.viz.plot_sensors` for invalid channel locations by `Eric Larson`_ + +- Fix bug in :func:`mne.io.read_raw_edf` where GDF files had ``info['highpass']`` and ``info['lowpass']`` set to NaN and ``info['meas_date']`` set incorrectly, by `Eric Larson`_ + +- Fix bug in :func:`mne.preprocessing.ICA.apply` to handle arrays as `exclude` property by `Joan Massich`_ + +- Fix bug in ``method='eLORETA'`` for :func:`mne.minimum_norm.apply_inverse` when using a sphere model and saved ``inv`` by `Eric Larson`_ + +- Fix bug in :class:`mne.io.Raw` where warnings were emitted when objects were deleted by `Eric Larson`_ + +- Fix vector data support for :class:`mne.VolSourceEstimate` by `Christian Brodbeck`_ + +- Fix bug with IIR filtering axis in :func:`mne.filter.filter_data` by `Eric Larson`_ + +- Fix bug with non-boxcar windows in :meth:`mne.io.Raw.resample` and :func:`mne.filter.resample` by `Eric Larson`_ + +- Fix bug in :func:`mne.minimum_norm.apply_inverse` where applying an MEG-only inverse would raise an error about needing an average EEG reference by `Eric Larson`_ + +- Fix bug in ``inst.apply_proj()`` where an average EEG reference was always added by `Eric Larson`_ + +- Fix bug in :func:`mne.time_frequency.tfr_morlet`, :func:`mne.time_frequency.tfr_multitaper`, and :func:`mne.time_frequency.tfr_stockwell` where not all data channels were picked by `Eric Larson`_ + +- Fix bug in :meth:`mne.preprocessing.ICA.plot_overlay` and :func:`mne.make_field_map` for CTF data with compensation by `Eric Larson`_ + +- Fix bug in :func:`mne.create_info` passing ``int`` as ``ch_names`` on Windows by `Eric Larson`_ + +- Fix bug in ``mne.realtime.RtEpochs`` where events during the buildup of the buffer were not correctly processed when incoming data buffers are smaller than the epochs by `Henrich Kolkhorst`_ + +- Fix bug in :func:`mne.io.read_raw_brainvision` where 1-indexed BrainVision events were not being converted into 0-indexed mne events by `Steven Bethard`_ + +- Fix bug in :func:`mne.viz.plot_snr_estimate` and :func:`mne.minimum_norm.estimate_snr` where the inverse rank was not properly utilized (especially affecting SSS'ed MEG data) by `Eric Larson`_ + +- Fix error when saving stc as nifti image when using volume source space formed by more than one label by `Alex Gramfort`_ + +- Fix error when interpolating MEG channels with compensation using reference channels (like for CTF data) by `Alex Gramfort`_ + +- Fix bug in :func:`mne.make_sphere_model` where EEG sphere model coefficients were not optimized properly by `Eric Larson`_ + +- Fix bug in :func:`mne.io.read_raw_ctf` to read bad channels and segments from CTF ds files by `Luke Bloy`_ + +- Fix problem with :meth:`mne.io.Raw.add_channels` where ``raw.info['bads']`` was replicated by `Eric Larson`_ + +- Fix bug with :class:`mne.Epochs` where an error was thrown when resizing data (e.g., during :meth:`mne.Epochs.drop_bad`) by `Eric Larson`_ + +- Fix naming of ``raw.info['buffer_size_sec']`` to be ``raw.buffer_size_sec`` as it is a writing parameter rather than a measurement parameter by `Eric Larson`_ + +- Fix EGI-MFF parser not to require ``dateutil`` package by `Eric Larson`_ + +- Fix error when running LCMV on MEG channels with compensation using reference channels (like for CTF data) by `Alex Gramfort`_ + +- Fix the use of :func:`sklearn.model_selection.cross_val_predict` with :class:`mne.decoding.SlidingEstimator` by `Alex Gramfort`_ + +- Fix event sample number increase when combining many Epochs objects with :func:`mne.concatenate_epochs` with by `Jasper van den Bosch`_ + +- Fix title of custom slider images to :class:`mne.Report` by `Marijn van Vliet`_ + +- Fix missing initialization of ``self._current`` in :class:`mne.Epochs` by `Henrich Kolkhorst`_ + +- Fix processing of data with bad segments and acquisition skips with new ``skip_by_annotation`` parameter in :func:`mne.preprocessing.maxwell_filter` by `Eric Larson`_ + +- Fix symlinking to use relative paths in ``mne flash_bem` and ``mne watershed_bem`` by `Eric Larson`_ + +- Fix error in mne coreg when saving with scaled MRI if fiducials haven't been saved by `Ezequiel Mikulan`_ + +- Fix normalization error in :func:`mne.beamformer.make_lcmv` when ``pick_ori='normal', weight_norm='unit_noise_gain'`` by `Marijn van Vliet`_ + +- Fix MNE-C installation instructions by `buildqa`_ + +- Fix computation of max-power orientation in :func:`mne.beamformer.make_dics` when ``pick_ori='max-power', weight_norm='unit_noise_gain'`` by `Marijn van Vliet`_ + +API +~~~ + +- Deprecated separate reading of annotations and synthesis of STI014 channels in readers by `Joan Massich`_: + + - Deprecated ``mne.io.read_annotations_eeglab`` + - Deprecated ``annot`` and ``annotmap`` parameters in :meth:`~mne.io.read_raw_edf` + - Deprecated ``stim_channel`` parameters in :func:`~mne.io.read_raw_edf`, :func:`~mne.io.read_raw_brainvision`, and :func:`~mne.io.read_raw_eeglab` + + Annotations are now added to ``raw`` instances directly upon reading as :attr:`raw.annotations `. + They can also be read separately with :func:`mne.read_annotations` for EEGLAB, BrainVision, EDF, and Brainstorm formats. + Use :func:`mne.events_from_annotations(raw.annotations) ` + to convert these to events instead of the old way (using STI014 channel synthesis followed by :func:`mne.find_events(raw) `). + + In 0.17 (this release) + Use ``read_raw_...(stim_channel=False)`` to disable warnings (and stim channel synthesis), but other arguments for ``stim_channel`` will still be supported. + + In 0.18 + The only supported option will be ``read_raw_...(stim_channel=False)``, and all stim-channel-synthesis arguments will be removed. At this point, ``stim_channel`` should be removed from scripts for future compatibility, but ``stim_channel=False`` will still be acceptable for backward compatibility. + + In 0.19 + The ``stim_channel`` keyword arguments will be removed from ``read_raw_...`` functions. + +- Calling :meth:``mne.io.pick.pick_info`` removing channels that are needed by compensation matrices (``info['comps']``) no longer raises ``RuntimeException`` but instead logs an info level message. By `Luke Bloy`_ + +- :meth:`mne.Epochs.save` now has the parameter `fmt` to specify the desired format (precision) saving epoched data, by `Stefan Repplinger`_, `Eric Larson`_ and `Alex Gramfort`_ + +- Deprecated ``mne.SourceEstimate.morph_precomputed``, ``mne.SourceEstimate.morph``, ``mne.compute_morph_matrix``, ``mne.morph_data_precomputed`` and ``mne.morph_data`` in favor of :func:`mne.compute_source_morph`, by `Tommy Clausner`_ + +- Prepare transition to Python 3. This release will be the last release compatible with Python 2. The next version will be Python 3 only. + +- CUDA support now relies on CuPy_ instead of ``PyCUDA`` and ``scikits-cuda``. It can be installed using ``conda install cupy``. By `Eric Larson`_ + +- Functions requiring a color cycle will now default to Matplotlib rcParams colors, by `Stefan Appelhoff`_ + +- :meth:`mne.Evoked.plot_image` has gained the ability to ``show_names``, and if a selection is provided to ``group_by``, ``axes`` can now receive a `dict`, by `Jona Sassenhagen`_ + +- Calling :meth:`mne.Epochs.decimate` with ``decim=1`` no longer copies the data by `Henrich Kolkhorst`_ + +- Removed blocking (waiting for new epochs) in ``mne.realtime.RtEpochs.get_data()`` by `Henrich Kolkhorst`_ + +- Warning messages are now only emitted as :func:`warnings.warn_explicit` rather than also being emitted as ``logging`` messages (unless a logging file is being used) to avoid duplicate warning messages, by `Eric Larson`_ + +- Deprecated save_stc_as_volume function in favor of :meth:`mne.VolSourceEstimate.as_volume` and :meth:`mne.VolSourceEstimate.save_as_volume` by `Alex Gramfort`_ + +- `src.kind` now equals to `'mixed'` (and not `'combined'`) for a mixed source space (made of surfaces and volume grids) by `Alex Gramfort`_ + +- Deprecation of :attr:`mne.io.Raw.annotations` property in favor of :meth:`mne.io.Raw.set_annotations` by `Joan Massich`_ + +- The default value of ``stop_receive_thread`` in ``mne.realtime.RtEpochs.stop`` has been changed to ``True`` by `Henrich Kolkhorst`_ + +- Using the :meth:`mne.io.Raw.add_channels` on an instance with memmapped data will now resize the memmap file to append the new channels on Windows and Linux, by `Eric Larson`_ + +- :attr:`mne.io.Raw.annotations` when missing is set to an empty :class:`mne.Annotations` rather than ``None`` by `Joan Massich`_ and `Alex Gramfort`_ + +- Mismatches in CTF compensation grade are now checked in inverse computation by `Eric Larson`_ + + +Authors +~~~~~~~ + +People who contributed to this release (in alphabetical order): + +* Alexandre Gramfort +* Antoine Gauthier +* Britta Westner +* Christian Brodbeck +* Clemens Brunner +* Daniel McCloy +* David Sabbagh +* Denis A. Engemann +* Eric Larson +* Ezequiel Mikulan +* Henrich Kolkhorst +* Hubert Banville +* Jasper J.F. van den Bosch +* Jen Evans +* Joan Massich +* Johan van der Meer +* Jona Sassenhagen +* Kambiz Tavabi +* Lorenz Esch +* Luke Bloy +* Mainak Jas +* Manu Sutela +* Marcin Koculak +* Marijn van Vliet +* Mikolaj Magnuski +* Peter J. Molfese +* Sam Perry +* Sara Sommariva +* Sergey Antopolskiy +* Sheraz Khan +* Stefan Appelhoff +* Stefan Repplinger +* Steven Bethard +* Teekuningas +* Teon Brooks +* Thomas Hartmann +* Thomas Jochmann +* Tom Dupré la Tour +* Tristan Stenner +* buildqa +* jeythekey diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.18.inc python-mne-0.19.1+dfsg/doc/changes/0.18.inc --- python-mne-0.18.1+dfsg/doc/changes/0.18.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.18.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,268 @@ +.. _changes_0_18: + +Version 0.18 +------------ + +Changelog +~~~~~~~~~ + +- Add ``event_id='auto'`` in :func:`mne.events_from_annotations` to accommodate Brainvision markers by `Jona Sassenhagen`_, `Joan Massich`_ and `Eric Larson`_ + +- Add example on how to simulate raw data using subject anatomy, by `Ivana Kojcic`_,`Eric Larson`_,`Samuel Deslauriers-Gauthier`_ and`Kostiantyn Maksymenko`_ + +- :func:`mne.beamformer.apply_lcmv_cov` returns static source power after supplying a data covariance matrix to the beamformer filter by `Britta Westner`_ and `Marijn van Vliet`_ + +- Add ``butterfly`` and ``order`` arguments to :func:`mne.viz.plot_epochs` and offer separated traces for non-meg data (seeg, eeg, ecog) in butterfly view by `Stefan Repplinger`_ and `Eric Larson`_ + +- :meth:`mne.Epochs.get_data` now takes a ``picks`` parameter by `Jona Sassenhagen`_ + +- :func:`~mne.viz.plot_compare_evokeds` will generate topo plots if ``axes='topo'`` by `Jona Sassenhagen`_ + +- ``mne.viz.iter_topography`` can yield an additional axis, e.g., for plotting legends by `Jona Sassenhagen`_ and `Daniel McCloy`_ + +- Default plot title reflects channel type when ``picks`` is a channel type in :func:`~mne.viz.plot_compare_evokeds` by `Daniel McCloy`_ + +- Color scale limits in :func:`~mne.viz.plot_topo_image_epochs` are now computed separately per channel type in combined mag/grad plots, by `Daniel McCloy`_ + +- :func:`mne.simulation.simulate_stc` now allows for label overlaps by `Nathalie Gayraud`_, and `Ivana Kojcic`_ + +- Add ``long_format`` option to the pandas dataframe exporters, e.g :meth:`mne.Epochs.to_data_frame` by `Denis Engemann`_ + +- Add example on how to load standard montage :ref:`plot_montage` by `Joan Massich`_ + +- Add new tutorial on :ref:`tut-eeg-fsaverage-source-modeling` by `Alex Gramfort`_, and `Joan Massich`_ + +- Add :meth:`mne.Epochs.apply_hilbert` and :meth:`mne.Evoked.apply_hilbert` by `Eric Larson`_ + +- Add convenience ``fsaverage`` subject dataset fetcher / updater :func:`mne.datasets.fetch_fsaverage` by `Eric Larson`_ + +- Add ``fmin`` and ``fmax`` argument to :meth:`mne.time_frequency.AverageTFR.crop` and to :meth:`mne.time_frequency.EpochsTFR.crop` to crop TFR objects along frequency axis by `Dirk Gütlin`_ + +- Add support to :func:`mne.read_annotations` to read CNT formats by `Joan Massich`_ + +- Add ``reject`` parameter to :meth:`mne.preprocessing.ICA.plot_properties` to visualize rejected epochs by `Antoine Gauthier`_ + +- Add support for picking channels using channel name and type strings to functions with ``picks`` arguments, along with a convenience :meth:`mne.io.Raw.pick`, :meth:`mne.Epochs.pick`, and :meth:`mne.Evoked.pick` method, by `Eric Larson`_ + +- Add new tutorial on :ref:`tut-sleep-stage-classif` by `Alex Gramfort`_, `Stanislas Chambon`_ and `Joan Massich`_ + +- Add data fetchers for polysomnography (PSG) recordings from Physionet (:func:`mne.datasets.sleep_physionet.age.fetch_data` and :func:`mne.datasets.sleep_physionet.temazepam.fetch_data`) by `Alex Gramfort`_ and `Joan Massich`_ + +- Add envelope correlation code in :func:`mne.connectivity.envelope_correlation` by `Denis Engemann`_, `Sheraz Khan`_, and `Eric Larson`_ + +- Add option to toggle all projectors in :meth:`mne.io.Raw.plot` and related functions by `Eric Larson`_ + +- Add support for indexing, slicing, and iterating :class:`mne.Annotations` by `Joan Massich`_ + +- :meth:`mne.io.Raw.plot` now uses the lesser of ``n_channels`` and ``raw.ch_names``, by `Joan Massich`_ + +- Add support for FIR filtering in :meth:`mne.io.Raw.plot` and :ref:`gen_mne_browse_raw` by passing ``filtorder=0`` or ``--filtorder 0``, respectively, by `Eric Larson`_ + +- Add ``chunk_duration`` parameter to :func:`mne.events_from_annotations` to allow multiple events from a single annotation by `Joan Massich`_ + +- Add :class:`mne.simulation.SourceSimulator` class to simplify simulating SourceEstimates, by `Samuel Deslauriers-Gauthier`_, `Kostiantyn Maksymenko`_, `Nathalie Gayraud`_, `Ivana Kojcic`_, `Alex Gramfort`_, and `Eric Larson`_ + +- :func:`mne.io.read_raw_edf` now detects analog stim channels labeled ``'STATUS'`` and sets them as stim channel. :func:`mne.io.read_raw_edf` no longer synthesize TAL annotations into stim channel but stores them in ``raw.annotations`` when reading by `Joan Massich`_ + +- Add `mne.simulation.add_noise` for ad-hoc noise addition to `io.Raw`, `Epochs`, and `Evoked` instances, by `Eric Larson`_ + +- Add ``drop_refs=True`` parameter to :func:`set_bipolar_reference` to drop/keep anode and cathode channels after applying the reference by `Cristóbal Moënne-Loccoz`_. + +- Add processing of reference MEG channels to :class:`mne.preprocessing.ICA` by `Jeff Hanna`_ + +- Add use of :func:`scipy.signal.windows.dpss` for faster multitaper window computations in PSD functions by `Eric Larson`_ + +- Add :func:`mne.morph_labels` to facilitate morphing label sets obtained from parcellations, by `Eric Larson`_ + +- Add :func:`mne.labels_to_stc` to facilitate working with label data, by `Eric Larson`_ + +- Add :func:`mne.label.select_sources` to simplify the selection of sources within a label, by `Samuel Deslauriers-Gauthier`_ + +- Add support for using :class:`mne.Info` in :func:`mne.simulation.simulate_raw` instead of :class:`mne.io.Raw` by `Eric Larson`_ + +- Add support for passing an iterable and stim channel values using ``stc`` parameter of :func:`mne.simulation.simulate_raw` by `Eric Larson`_ + +- Add ``overlap`` argument to :func:`mne.make_fixed_length_events` by `Eric Larson`_ + +- Add approximate distance-based ``spacing`` source space decimation algorithm to :func:`mne.setup_source_space` by `Eric Larson`_ + +- Add 448-labels subdivided aparc cortical parcellation by `Denis Engemann`_ and `Sheraz Khan`_ + +- Add option to improve rendering in :ref:`gen_mne_coreg` for modern graphics cards by `Eric Larson`_ + +- Add :func:`mne.preprocessing.mark_flat` to automate marking of flat channels and segments of raw data by `Eric Larson`_ + +- Add support for CUDA-based correlation computations and progress bars in :class:`mne.decoding.ReceptiveField` by `Eric Larson`_ + +- Add support for file-like objects in :func:`mne.io.read_raw_fif` as long as preloading is used by `Eric Larson`_ + +- Add keyboard shortcuts to nativate volume source estimates in time using (shift+)left/right arrow keys by `Mainak Jas`_ + +- Add option to SSP preprocessing functions (e.g., :func:`mne.preprocessing.compute_proj_eog` and :func:`mne.compute_proj_epochs`) to process MEG channels jointly with ``meg='combined'`` by `Eric Larson`_ + +- Add Epoch selection and metadata functionality to :class:`mne.time_frequency.EpochsTFR` using new mixin class by `Keith Doelling`_ + +- Add ``reject_by_annotation`` argument to :func:`mne.preprocessing.find_ecg_events` by `Eric Larson`_ + +- Add ``pca`` argument to return the rank-reduced whitener in :func:`mne.cov.compute_whitener` by `Eric Larson`_ + +- Add ``extrapolate`` argument to :func:`mne.viz.plot_topomap` for better control of extrapolation points placement by `Mikołaj Magnuski`_ + +- Add ``channel_wise`` argument to :func:`mne.io.Raw.apply_function` to allow applying a function on multiple channels at once by `Hubert Banville`_ + +- Add option ``copy='auto'`` to control data copying in :class:`mne.io.RawArray` by `Eric Larson`_ + +- The ``mri`` parameter in :func:`mne.setup_volume_source_space` is now automatically set to ``T1.mgz`` if ``subject`` is provided. This allows to get a :class:`mne.SourceSpaces` of kind ``volume`` more automatically. By `Alex Gramfort`_ + +- Add better ``__repr__`` for constants, and :class:`info['dig'] ` entries via ``DigPoint`` by `Eric Larson`_ + +- Allow string argument in :meth:`mne.io.Raw.drop_channels` to remove a single channel by `Clemens Brunner`_ + +- Add additional depth weighting options for inverse solvers (e.g., :func:`mne.inverse_sparse.gamma_map` and :func:`mne.inverse_sparse.mixed_norm`) by `Eric Larson`_ + +- Add depth weighting to LCMV beamformers via ``depth`` argument in :func:`mne.beamformer.make_lcmv` by `Eric Larson`_ + +- Allow toggling of DC removal in :meth:`mne.io.Raw.plot` by pressing the 'd' key by `Clemens Brunner`_ + +- Improved clicking in :meth:`mne.io.Raw.plot` (left click on trace toggles bad, left click on background sets green line, right click anywhere removes green line) by `Clemens Brunner`_ + +- Add ``mne.realtime.LSLClient`` for realtime data acquisition with LSL streams of data by `Teon Brooks`_ and `Mainak Jas`_ + +- Add partial support for PyVista as a 3D backend using :func:`mne.viz.use_3d_backend` by `Guillaume Favelier`_ + +- Add option ``ids = None`` in :func:`mne.event.shift_time_events` for considering all events by `Nikolas Chalas`_ and `Joan Massich`_ + +- Add ``mne.realtime.MockLSLStream`` to simulate an LSL stream for testing and examples by `Teon Brooks`_ + +- Add support for file-like objects in :func:`mne.read_epochs` as long as preloading is used by `Paul Roujansky`_ + +Bug +~~~ + +- Fix annotations in split fif files :func:`mne.io.read_raw_fif` by `Joan Massich`_ + +- Fix :meth:`mne.Epochs.plot` with ``scalings='auto'`` to properly compute channel-wise scalings by `Stefan Repplinger`_ + +- Fix :func:`mne.gui.coregistration` and :ref:`mne coreg ` crashing with segmentation fault when switching subjects by `Eric Larson`_ + +- Fix :func:`mne.io.read_raw_brainvision` to accommodate vmrk files which do not have any annotations by `Alexander Kovrig`_ + +- Fix :meth:`mne.io.Raw.plot` and :meth:`mne.Epochs.plot` to auto-scale ``misc`` channel types by default by `Eric Larson`_ + +- Fix filtering functions (e.g., :meth:`mne.io.Raw.filter`) to properly take into account the two elements in ``n_pad`` parameter by `Bruno Nicenboim`_ + +- Fix `feature_names` parameter change after fitting in :class:`mne.decoding.ReceptiveField` by `Jean-Remi King`_ + +- Fix index error in :func:`mne.io.read_raw_cnt` when creating stim_channel manually by `Joan Massich`_ + +- Fix bug with ``weight_norm='unit-gain'`` in :func:`mne.beamformer.make_lcmv` and :func:`mne.beamformer.make_dics` by `Britta Westner`_ + +- Fix 32bits annotations in :func:`mne.io.read_raw_cnt` by `Joan Massich`_ + +- Fix :func:`mne.events_from_annotations` to ignore ``'BAD_'` and ``'EDGE_'`` annotations by default using a new default ``regexp`` by `Eric Larson`_ + +- Fix bug in :func:`mne.preprocessing.mark_flat` where ``raw.first_samp`` was not taken into account by `kalenkovich`_ + +- Fix date parsing in :func:`mne.io.read_raw_cnt` by `Joan Massich`_ + +- Fix topological checks and error messages for BEM surfaces in :func:`mne.make_bem_model` by `Eric Larson`_ + +- Fix default HTML language of :class:`mne.Report` to be ``"en-us"`` instead of ``"fr"`` and allow setting via ``report.lang`` property by `Eric Larson`_ + +- Fix bug where loading epochs with ``preload=True`` and subsequently using :meth:`mne.Epochs.drop_bad` with new ``reject`` or ``flat`` entries leads to improper data (and ``epochs.selection``) since v0.16.0 by `Eric Larson`_. + If your code uses ``Epochs(..., preload=True).drop_bad(reject=..., flat=...)``, we recommend regenerating these data. + +- Fix :ref:`gen_mne_flash_bem` to properly utilize ``flash30`` images when conversion from DICOM images is used, and to properly deal with non-standard acquisition affines by `Eric Larson`_ + +- Fix :meth:`mne.io.Raw.set_annotations` with ``annotations=None`` to create an empty annotations object with ``orig_time`` that matches the :class:`mne.io.Raw` instance by `Eric Larson`_ + +- Fix :func:`mne.io.read_raw_edf` returning all the annotations with the same name in GDF files by `Joan Massich`_ + +- Fix boundaries during plotting of raw data with :func:`mne.io.Raw.plot` and :ref:`gen_mne_browse_raw` on scaled displays (e.g., macOS with HiDPI/Retina screens) by `Clemens Brunner`_ + +- Fix bug where filtering was not performed with ``lowpass`` or ``highpass`` in :meth:`mne.io.Raw.plot` and :ref:`gen_mne_browse_raw` by `Eric Larson`_ + +- Fix :func:`mne.simulation.simulate_evoked` that was failing to simulate the noise with heterogeneous sensor types due to poor conditioning of the noise covariance and make sure the projections from the noise covariance are taken into account `Alex Gramfort`_ + +- Fix checking of ``data`` dimensionality in :class:`mne.SourceEstimate` and related constructors by `Eric Larson`_ + +- Fix :meth:`mne.io.Raw.append` annotations miss-alignment by `Joan Massich`_ + +- Fix hash bug in the ``mne.io.edf`` module when installing on Windows by `Eric Larson`_ + +- Fix :func:`mne.io.read_raw_edf` reading duplicate channel names by `Larry Eisenman`_ + +- Fix :func:`set_bipolar_reference` in the case of generating all bipolar combinations and also in the case of repeated channels in both lists (anode and cathode) by `Cristóbal Moënne-Loccoz`_ + +- Fix missing code for computing the median when ``method='median'`` in :meth:`mne.Epochs.average` by `Cristóbal Moënne-Loccoz`_ + +- Fix CTF helmet plotting in :func:`mne.viz.plot_evoked_field` by `Eric Larson`_ + +- Fix saving of rejection parameters in :meth:`mne.Epochs.save` by `Eric Larson`_ + +- Fix orientations returned by :func:`mne.dipole.get_phantom_dipoles` (half were flipped 180 degrees) by `Eric Larson`_ + +- Fix bug in :func:`mne.viz.plot_compare_evokeds` when ``evoked.times[0] >= 0`` would cause a problem with ``vlines='auto'`` mode by `Eric Larson`_ + +- Fix path bugs in :func:`mne.bem.make_flash_bem` and :ref:`gen_mne_flash_bem` by `Eric Larson`_ + +- Fix :meth:`mne.time_frequency.AverageTFR.plot_joint` mishandling bad channels, by `David Haslacher`_ and `Jona Sassenhagen`_ + +- Fix :func:`mne.beamformer.make_lcmv` failing when full rank data is used (i.e., when no projection is done) with ``reg=0.``, by `Eric Larson`_ + +- Fix issue with bad channels ignored in :func:`mne.beamformer.make_lcmv` and :func:`mne.beamformer.make_dics` by `Alex Gramfort`_ + +- Fix :func:`mne.compute_proj_raw` when ``duration != None`` not to apply existing proj and to avoid using duplicate raw data samples by `Eric Larson`_ + +- Fix ``reject_by_annotation`` not being passed internally by :func:`mne.preprocessing.create_ecg_epochs` and :ref:`mne clean_eog_ecg ` to :func:`mne.preprocessing.find_ecg_events` by `Eric Larson`_ + +- Fix :func:`mne.io.read_raw_edf` failing when EDF header fields (such as patient name) contained special characters, by `Clemens Brunner`_ + +- Fix :func:`mne.io.read_raw_eeglab` incorrectly parsing event durations by `Clemens Brunner`_ + +- Fix :func:`mne.io.read_raw_egi` when cropping non-preloaded EGI MFF data by `Alex Gramfort`_ + +- Fix :meth:`mne.io.Raw.interpolate_bads` for interpolating CTF MEG channels when reference sensors are present by `jeythekey`_ + +- Fix a bug in :meth:`mne.io.Raw.resample`, where resampling events could result in indices > n_times-1, by `jeythekey`_ + +- Fix :meth:`mne.preprocessing.ICA.score_sources` to use the ``sfreq`` of the raw data to filter rather than the ``sfreq`` when the ICA was fit, by `jeythekey`_ + +- Fix a bug in :class:`mne.preprocessing.ICA`, where manually setting the attribute ``ICA.exclude`` to an np.array resulted in the removal of random components when later also providing the ``exclude`` argument to any ``apply...``-method, by `jeythekey`_ + +- Ascending changed to descending sorting of scores for integer ``..._criterion`` arguments in :func:`mne.preprocessing.ICA.detect_artifacts` and :func:`mne.preprocessing.run_ica`, as it used to be documented; the docstring in these functions was corrected for float ``..._criterion`` arguments, by `jeythekey`_ + +API +~~~ + +- Deprecate ``cov, iir_params, blink, ecg, chpi, random_state`` and support for :class:`mne.io.Raw` instance inputs in :func:`mne.simulation.simulate_raw`; use :func:`mne.simulation.add_noise`, :func:`mne.simulation.add_ecg`, :func:`mne.simulation.add_eog`, and :func:`mne.simulation.add_chpi` by `Eric Larson`_ + +- Add ``overwrite`` parameter in :func:`mne.Epochs.save` by `Katarina Slama`_ + +- Add ``stim_channel`` parameter in :func:`mne.io.read_raw_cnt` to toggle stim channel synthesis by `Joan Massich`_ + +- Python 2 is no longer supported; MNE-Python now requires Python 3.5+, by `Eric Larson`_ + +- A new class :class:`mne.VolVectorSourceEstimate` is returned by :func:`mne.minimum_norm.apply_inverse` (and related functions) when a volume source space and ``pick_ori='vector'`` is used, by `Eric Larson`_ + +- Converting a forward solution with a volume source space to fixed orientation using :func:`mne.convert_forward_solution` now raises an error, by `Eric Larson`_ + +- ``raw.estimate_rank`` has been deprecated and will be removed in 0.19 in favor of :func:`mne.compute_rank` by `Eric Larson`_ + +- :class:`Annotations` are now kept sorted (by onset time) during instantiation and :meth:`~Annotations.append` operations, by `Eric Larson`_ + +- Deprecate ``mne.io.find_edf_events`` by `Joan Massich`_ + +- Deprecate ``limit_depth_chs`` in :func:`mne.minimum_norm.make_inverse_operator` in favor of ``depth=dict(limit_depth_chs=...)`` by `Eric Larson`_ + +- Reading BDF and GDF files with :func:`mne.io.read_raw_edf` is deprecated and replaced by :func:`mne.io.read_raw_bdf` and :func:`mne.io.read_raw_gdf`, by `Clemens Brunner`_ + +- :func:`mne.forward.compute_depth_prior` has been reworked to operate directly on :class:`Forward` instance as ``forward`` rather than a representation scattered across the parameters ``G, is_fixed_ori, patch_info``, by `Eric Larson`_ + +- Deprecate ``method='extended-infomax'`` in :class:`mne.preprocessing.ICA`; Extended Infomax can now be computed with ``method='infomax'`` and ``fit_params=dict(extended=True)`` by `Clemens Brunner`_ + +- Fix support for supplying ``extrapolate`` via :meth:`ica.plot_properties(..., topomap_args=dict(extrapolate=...)) ` by `Sebastian Castano`_ + +- The peak finder that was formerly accessible via ``from mne.preprocessing.peak_finder import peak_finder`` should now be imported directly from the enclosing namespace as ``from mne.preprocessing import peak_finder`` by `Eric Larson`_ + +- Deprecate ``mne.realtime`` module to make a standalone module `mne-realtime` that will live outside of this package by `Teon Brooks`_ diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.19.inc python-mne-0.19.1+dfsg/doc/changes/0.19.inc --- python-mne-0.18.1+dfsg/doc/changes/0.19.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.19.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,268 @@ +.. NOTE: we are now using links to highlight new functions and classes. + Please follow the examples below like :func:`mne.stats.f_mway_rm`, so the + whats_new page will have a link to the function/class documentation. + +.. NOTE: there are 3 separate sections for changes, based on type: + - "Changelog" for new features + - "Bug" for bug fixes + - "API" for backward-incompatible changes + +.. _changes_0_19: + +Version 0.19.1 +-------------- + +Bug +~~~ + +- Fix plotting of TFRs with linear y-scale (misaligned frequency bins), by `Stefan Repplinger`_ and `Eric Larson`_ + +- Fix bug in :class:`~mne.preprocessing.ICA` where requesting extended infomax via ``fit_params={'extended': True}`` was overridden, by `Daniel McCloy`_. + +- Fix handling of repeated events in :class:`mne.Epochs` by `Fahimeh Mamashli`_ and `Alex Gramfort`_ + +- Fix reading of cardinals in .htps files (identifier are int not strings) by `Alex Gramfort`_ + +- Fix handling in cases where no components are found in :func:`mne.preprocessing.corrmap` by `Eric Larson`_ + +- Fix bug in :func:`mne.write_evokeds` where ``evoked.nave`` was not saved properly when multiple :class:`~mne.Evoked` instances were written to a single file, by `Eric Larson`_ + +- Fix TAL channel parsing (annotations) for EDF-D files by `Clemens Brunner`_ + +- Fix ``info['sfreq']`` when decimating in :func:`mne.time_frequency.tfr_multitaper` and :func:`mne.time_frequency.tfr_morlet` and make sure an error is raised when exceed Nyquist frequency by `Adonay Nunes`_ + +- Fix IO of TFRs when event_id contain a / in one of the keys by `Alex Gramfort`_ + +Changelog +~~~~~~~~~ + +Version 0.19 +------------ + +Changelog +~~~~~~~~~ + +- Add :func:`mne.cuda.set_cuda_device` and config variable ``MNE_CUDA_DEVICE`` to select among multiple GPUs (by numeric device ID) by `Daniel McCloy`_. + +- Add :func:`mne.channels.make_standard_montage` to create :class:`mne.channels.DigMontage` from templates by `Joan Massich`_ and `Alex Gramfort`_. + +- Add :func:`mne.channels.compute_dev_head_t` to compute Device-to-Head transformation from a montage by `Joan Massich`_ and `Alex Gramfort`_. + +- Add :func:`mne.channels.read_dig_fif` to read digitization coordinates from ``.fif`` files by `Joan Massich`_ and `Alex Gramfort`_. + +- Add :func:`mne.channels.read_dig_egi` to read digitization coordinates from EGI ``.xml`` files by `Joan Massich`_ and `Alex Gramfort`_. + +- Add :func:`mne.channels.read_dig_polhemus_isotrak` and :func:`mne.channels.read_polhemus_fastscan` to read Polhemus data by `Joan Massich`_ + +- Add :func:`mne.channels.read_dig_captrack` to read BrainVision CapTrak (BVCT) digitization coordinate files by `Stefan Appelhoff`_ and `Joan Massich`_ + +- Add :func:`mne.channels.make_dig_montage` to create :class:`mne.channels.DigMontage` objects out of np.arrays by `Joan Massich`_ + +- Add :func:`mne.channels.read_custom_montage` to read various EEG electrode locations files by `Joan Massich`_ and `Alex Gramfort`_. + +- Add support for making epochs with duplicated events, by allowing three policies: "error" (default), "drop", or "merge" in :class:`mne.Epochs` by `Stefan Appelhoff`_ + +- Allow :meth:`mne.Annotations.crop` to support negative ``tmin`` and ``tmax`` by `Joan Massich`_ + +- Unknown events code in GDF are now visible in the ``event_id`` by `Theodore Papadopoulo`_ + +- Now :func:`mne.io.read_raw_ctf` populates ``raw.annotations`` with the markers in ``MarkerFile.mrk`` if any by `Joan Massich`_ + +- Add options for controlling the use of the ``-T1`` flag and the location of the brainmask output in :ref:`mne watershed_bem ` by `Eric Larson`_ + +- Add support to :func:`mne.read_annotations` to read CTF marker files by `Joan Massich`_ + +- Do not convert effective number of averages (``nave`` attribute of :class:`mne.Evoked`) to integer except when saving to FIFF file by `Daniel McCloy`_. + +- Add automatic fiducial position estimation in :ref:`mne coreg ` using MNI Talairach fiducial locations in :func:`mne.coreg.get_mni_fiducials` by `Jon Houck`_ and `Eric Larson`_ + +- Add support for :ref:`mne coreg ` scaling surrogate subjects without surface reconstructions, such as those created for volumetric analyses only (e.g., with ``recon-all -autorecon1``) by `Eric Larson`_ + +- Add reader for Curry data in :func:`mne.io.read_raw_curry` by `Dirk Gütlin`_ + +- Butterfly channel plots now possible for :meth:`mne.Epochs.plot_psd` with ``average=False``. Infrastructure for this function now shared with analogous Raw function, found in ``mne.viz.utils`` by `Jeff Hanna` _ + +- Add option not to orthogonalize power envelopes with ``orthogonalize=False`` in :func:`mne.connectivity.envelope_correlation` by `Denis Engemann`_ + +- Accept filenames of raw .fif files that end in ``_meg.fif`` to enable complicance with the Brain Imaging Data Structure by `Stefan Appelhoff`_ + +- Add function to check the type of a FIF file using :func:`mne.what` and `mne what ` by `Eric Larson`_ + +- Add support for specifying the initial time and/or position and providing a :class:`mne.SourceMorph` instead of :class:`mne.SourceSpaces` in :func:`mne.viz.plot_volume_source_estimates` by `Eric Larson`_ + +- Speed up morph map generation in :func:`mne.read_morph_map` by ~5-10x by using :func:`numba.jit` by `Eric Larson`_ + +- Speed up :func:`mne.setup_volume_source_space`, especially when ``volume_label is not None`` by `Eric Larson`_ + +- Speed up :ref:`mne coreg ` interactive and automated (ICP) alignment by using nearest-neighbor calculations in the MRI coordinate frame, by `Eric Larson`_ + +- Add :func:`mne.dig_mri_distances` to compute the distances between digitized head points and the MRI head surface by `Alex Gramfort`_ and `Eric Larson`_ + +- Add scale bars for data channels in :func:`mne.io.Raw.plot` by `Eric Larson`_ + +- Add :func:`mne.viz.plot_brain_colorbar` to plot a colorbar appropriately matched to a :func:`mne.viz.plot_source_estimates` plot by `Eric Larson`_ + +- Add support for showing head surface (to visualize digitization fit) while showing a single-layer BEM to :func:`mne.viz.plot_alignment` by `Eric Larson`_ + +- Add option ``include_tmax=True`` to cropping methods :meth:`mne.io.Raw.crop`, :meth:`mne.Epochs.crop`, :meth:`mne.Evoked.crop`, :meth:`mne.SourceEstimate.crop`, :meth:`mne.Dipole.crop`, and :meth:`mne.time_frequency.AverageTFR.crop` by `Eric Larson`_ + +- Change the behavior of :meth:`mne.io.Raw.plot` for ``scalings='auto'`` and ``remove_dc=True`` to compute the scalings on the data with DC removed by `Clemens Brunner`_ + +- Allow creating annotations within existing annotations in :func:`mne.io.Raw.plot` by default (the old snapping behavior can be toggled by pressing 'p') by `Clemens Brunner`_ + +- Add plotting of rank estimates in :func:`mne.viz.plot_cov` by `Eric Larson`_ + +- Add a new :func:`mne.viz.plot_sensors_connectivity` function to visualize the sensor connectivity in 3D by `Guillaume Favelier`_ and `Alex Gramfort`_ + +- Add support for ``info['utc_offset']``, ``info['device_info']``, and ``info['helium_info']`` components of :class:`mne.Info` by `Eric Larson`_ + +- Add control over dipole colors in :func:`mne.viz.plot_dipole_locations` when using orthoview mode by `Eric Larson`_ + +- Use second-order-sections filtering in :meth:`mne.io.Raw.plot` and :ref:`mne browse_raw ` by `Eric Larson`_ + +- Add re-referencing functionality for ecog and seeg channel types in :func:`mne.set_eeg_reference` by `Keith Doelling`_ + +- Add support for median averaging and for returning unaggregated segments in :func:`mne.time_frequency.psd_welch` by `Richard Höchenberger`_ + +- :func:`io.read_raw_kit`: add support for NYU New York 2019 system update, by `Christian Brodbeck`_ + + +Bug +~~~ + +- Fix setting montage eeg ref position for captrack by `Joan Massich`_ + +- Fix saving raw read from BDF file using ``tmin`` and ``tmax`` using ``preload=False`` by `Alex Gramfort`_ + +- Fix :func:`mne.grand_average` to use equal sum-to-one weights (like it used to, before changes to underlying :func:`mne.combine_evoked`) by `Daniel McCloy`_ + +- Fix :meth:`mne.io.Raw.filter` to deal with instances with no data channels properly by `Eric Larson`_ + +- Fix one-sample baseline issue in :class:`mne.BaseEpochs` when using `tmin=0` by `Milan Rybář`_ + +- Fix bug in :func:`mne.viz.plot_volume_source_estimates` where ``'glass_brain'`` MRIs were not transformed to MNI space, by `Eric Larson`_ + +- Fix bug in :func:`mne.viz.plot_volume_source_estimates` where MRIs with voxels not in RAS orientation could not be browsed properly, by `Eric Larson`_ + +- Fix bug in :meth:`mne.SourceMorph.apply` where output STCs had ``stc.vertices`` defined improperly, by `Eric Larson`_ + +- Fix bug in :meth:`mne.SourceMorph.apply` where the default was errantly ``mri_space=False`` instead of ``mri_space=None`` (as documented), by `Eric Larson`_ + +- Fix :meth:`mne.VolVectorSourceEstimate.normal` and :func:`mne.minimum_norm.apply_inverse` to only allow normal extraction/orientation for surface and discrete source spaces by `Eric Larson`_ + +- Fix :meth:`mne.io.Raw.set_annotations` for ``meas_date`` previous to 1970 by `Joan Massich`_ + +- Fix horizontal spacing issues in :meth:`mne.io.Raw.plot_psd` by `Jeff Hanna`_ + +- Fix reading of dates in BrainVision files if no "New Segment" marker is specified, no date is given, or data is missing, by `Stefan Appelhoff`_ + +- Fix bug with reading one-channel GDF files by `Abram Hindle`_ + +- Fix bug with y-axis labeling in :meth:`mne.io.Raw.plot_psd` by `Eric Larson`_ + +- Fix side-effect where :func:`mne.viz.plot_ica_sources` and :meth:`mne.preprocessing.ICA.plot_sources` changed the ``ICA.exclude`` attribute even when users didn't interact with the plot by `Daniel McCloy`_. + +- Fix scaling of sources in :meth:`ica.plot_sources(epochs) ` by `Eric Larson`_ + +- Fix wrong assumptions about units in BrainVision montages and add test asserting units in "mm" or "auto", by `Stefan Appelhoff`_ + +- Fix scaling issue with signals in mV in EDF files read with :func:`mne.io.read_raw_edf` by `Alex Gramfort`_ + +- Fix :func:`mne.extract_label_time_course` behavior when using STCs generated with ``apply_inverse(..., label=label)`` or ``stc.in_label`` by `Eric Larson`_ + +- Fix bug in :func:`mne.io.read_raw_brainvision` so that recording date timestamps are also recognized if channel reference data is negative, by `Stefan Appelhoff`_ + +- Fix order of ``info['dig']`` that was alphabetical based on channel names and not following the channel order when using :meth:`mne.io.Raw.set_montage` and a ``mne.channels.Montage`` object by `Joan Massich`_ and `Alex Gramfort`_. + +- Fix reading CNT files larger than 2Gb by `Joan Massich`_ + +- Fix reading of 4D/BTi data with different channel names and onsets in :func:`mne.io.read_raw_bti` by `Joshua Bear`_ and `Eberhard Eich`_ + +- Fix formula for effective number of averages in :func:`mne.combine_evoked` when ``weights='equal'`` by `Daniel McCloy`_. + +- Fix bug in :func:`mne.simulation.simulate_stc` to avoid empty stc if label vertices and source space do not intersect, by `Kostiantyn Maksymenko`_ + +- Fix ``event_id='auto'`` in :func:`mne.events_from_annotations` to recover Brainvision markers after saving it in ``.fif`` by `Joan Massich`_ + +- Fix :func:`mne.read_epochs_eeglab` when epochs are stored as float. By `Thomas Radman`_ + +- Fix :func:`mne.Evoked.resample` and :func:`mne.Epochs.resample` not setting ``inst.info['lowpass']`` properly by `Eric Larson`_ + +- Fix checks when constructing volumetric and surface source spaces with :func:`mne.setup_volume_source_space` and :func:`mne.setup_source_space`, respectively, by `Eric Larson`_ + +- Fix bug in handling of :class:`mne.Evoked` types that were not produced by MNE-Python (e.g., alternating average) by `Eric Larson`_ + +- Fix bug in :func:`mne.read_source_estimate` where vector volumetric source estimates could not be read by `Eric Larson`_ + +- Fix bug in :func:`mne.inverse_sparse.mixed_norm` and :func:`mne.inverse_sparse.tf_mixed_norm` where ``weights`` was supplied but ``weights_min`` was not, by `Eric Larson`_ + +- Fix bug in :func:`mne.set_eeg_reference` where non-EEG channels could be re-referenced by default if there were no EEG channels present, by `Eric Larson`_ + +- Fix bug in :func:`mne.io.Raw.plot` when using HiDPI displays and the MacOSX backend of matplotlib by `Eric Larson`_ + +- Fix bug in :func:`mne.viz.plot_compare_evokeds` when using Neuromag 122 system by `Eric Larson`_ + +- Fix bug in :func:`mne.Epochs.plot_psd` when some channels had zero/infinite ``psd`` values causing erroneous error messages by `Luke Bloy`_ + +- Fix :func:`mne.Evoked.decimate` not setting ``inst.first`` and ``inst.last`` properly by `Marijn van Vliet`_ + +- Fix :func:`mne.io.read_raw_brainvision` not handling ``Event`` markers created by PyCorder correctly by `Richard Höchenberger`_ + +- Fix support for string-like objects (such as :class:`python:pathlib.Path`) by `Eric Larson`_ + +- Fix :class:`mne.Report` silently suppressing exceptions when used as a context manager by `Marijn van Vliet`_ + +API +~~~ + +- Deprecate ``mne.channels.Montage`` class, ``mne.channels.read_montage`` and ``mne.channels.read_dig_montage`` function by `Joan Massich`_. + +- Deprecate passing ``Montage``, ``str`` as montage parameter in :meth:`mne.io.Raw.set_montage` by `Joan Massich`_. + +- Deprecate ``set_dig`` parameter in :meth:`mne.io.Raw.set_montage` and ``update_ch_names`` in ``mne.io.RawEEGLAB.set_montage`` when using :class:`mne.channels.DigMontage` as by `Joan Massich`_. + +- Now :meth:`mne.io.Raw.set_montage` raises an error when :class:`mne.channels.DigMontage` contains only a subset of the channels in ``raw.info``. It also adds ``raise_if_subset`` parameter to ensure backward compatibility (defaults to False in 0.19, to True in 0.20, and will be removed in 0.21) by `Joan Massich`_. + +- Minimum dependency versions for the following libraries have been bumped up (by `Eric Larson`_): + + - NumPy: 1.12.1 + - SciPy: 0.18.1 + - matplotlib: 2.0.2 + - scikit-learn: 0.18.2 + - pandas 0.19.2 + +- New boolean parameter ``show_scrollbars`` for :meth:`mne.io.Raw.plot`, :meth:`mne.Epochs.plot`, and :meth:`mne.preprocessing.ICA.plot_sources` (and associated functions) that allows hiding the scrollbars and buttons for a "zen mode" data browsing experience. When the plot window has focus, zen mode can be toggled by pressing :kbd:`z`, by `Daniel McCloy`_. + +- Deprecate ``mne.evoked.grand_average`` in favor of :func:`mne.grand_average` (which works on both :class:`~mne.Evoked` and :class:`~mne.time_frequency.AverageTFR`) by `Daniel McCloy`_ + +- Deprecate ``exclude`` parameter in :func:`mne.viz.plot_ica_sources` and :meth:`mne.preprocessing.ICA.plot_sources`, instead always use the ``exclude`` attribute of the ICA object by `Daniel McCloy`_. + +- Deprecate ``montage`` parameter in favor of the ``set_montage`` method in all EEG data readers :func:`mne.io.read_raw_cnt`, :func:`mne.io.read_raw_egi`, :func:`mne.io.read_raw_edf`, :func:`mne.io.read_raw_gdf`, :func:`mne.io.read_raw_nicolet`, :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab` by `Alex Gramfort`_ + +- New parameter ``clear`` in :func:`mne.viz.plot_epochs_image` for clearing pre-existing axes before plotting into them by `Daniel McCloy`_ + +- :func:`mne.viz.plot_epochs_image` no longer supports ``group_by='type'`` — combining by channel type is now the default when ``picks`` is a channel type string; to get individual plots for each channel, pass ``picks`` as a list of channel names or indices by `Daniel McCloy`_ + +- New parameter ``combine`` in :func:`mne.viz.plot_compare_evokeds` for specifying method to combine information across channels by `Daniel McCloy`_ + +- FIFF constants related to SmartShield (``*_SMSH_*`` and ``*_SMARTSHIELD``) have been renamed to ``IAS`` for consistency with MEGIN, by `Eric Larson`_ + +- The ``gfp`` parameter of :func:`mne.viz.plot_compare_evokeds` is deprecated; use ``combine='gfp'`` instead by `Daniel McCloy`_ + +- The ``truncate_yaxis='max_ticks'`` parameter of :func:`mne.viz.plot_compare_evokeds` is deprecated; use ``truncate_yaxis='auto'`` instead by `Daniel McCloy`_ + +- The ``truncate_xaxis`` and ``truncate_yaxis`` parameters of :func:`mne.viz.plot_compare_evokeds` now perform one-sided truncation unless both are ``True`` by `Daniel McCloy`_ + +- The ``show_legend`` parameter of :func:`mne.viz.plot_compare_evokeds` is renamed to ``legend`` by `Daniel McCloy`_ + +- :func:`mne.viz.plot_compare_evokeds` always returns a list of figures even when a single figure is generated by `Daniel McCloy`_ + +- Deprecate ``average=True`` and ``spatial_colors=False`` for :func:`mne.Epochs.plot_psd` by `Jeff Hanna`_ + +- :func:`mne.io.read_raw_brainvision` no longer raises an error when there are inconsistencies between ``info['chs']`` and ``montage`` but warns instead by `Joan Massich`_ + +- Add ``update_ch_names`` parameter to ``mne.io.RawEEGLAB.set_montage`` to allow updating the channel names based on the montage by `Joan Massich`_ + +- Reading annotations contained in GDF files with :func:`mne.io.read_raw_gdf` now returns numeric event codes as descriptions (instead of textual descriptions) due to restrictive licensing of the GDF event code table from BioSig by `Clemens Brunner`_ + +- :func:`channels.find_ch_connectivity` now returns pre-built neighbor maps for KIT systems when available, by `Christian Brodbeck`_ diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.2.inc python-mne-0.19.1+dfsg/doc/changes/0.2.inc --- python-mne-0.18.1+dfsg/doc/changes/0.2.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.2.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,40 @@ +.. _changes_0_2: + +Version 0.2 +----------- + +Changelog +~~~~~~~~~ + +- New stats functions for FDR correction and Bonferroni by `Alex Gramfort`_. + +- Faster time-frequency using downsampling trick by `Alex Gramfort`_. + +- Support for volume source spaces by `Alex Gramfort`_ (requires next MNE release or nightly). + +- Improved Epochs handling by `Martin Luessi`_ (slicing, drop_bad_epochs). + +- Bug fix in Epochs + ECG detection by Manfred Kitzbichler. + +- New pick_types_evoked function by `Alex Gramfort`_. + +- SourceEstimate now supports algebra by `Alex Gramfort`_. + +API changes summary +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here are the code migration instructions when upgrading from mne-python +version 0.1: + +- New return values for the function find_ecg_events + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number +of commits): + +* 33 Alexandre Gramfort +* 12 Martin Luessi +* 2 Yaroslav Halchenko +* 1 Manfred Kitzbichler diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.3.inc python-mne-0.19.1+dfsg/doc/changes/0.3.inc --- python-mne-0.18.1+dfsg/doc/changes/0.3.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.3.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,40 @@ +.. _changes_0_3: + +Version 0.3 +----------- + +Changelog +~~~~~~~~~ + +- Sign flip computation for robust label average of signed values by `Alex Gramfort`_. + +- Reading and writing of .w files by `Martin Luessi`_. + +- Support for modifying Raw object and allow raw data preloading with memory mapping by `Martin Luessi`_ and `Alex Gramfort`_. + +- Support of arithmetic of Evoked data (useful to concatenate between runs and compute contrasts) by `Alex Gramfort`_. + +- Support for computing sensor space data from a source estimate using an MNE forward solution by `Martin Luessi`_. + +- Support of arithmetic of Covariance by `Alex Gramfort`_. + +- Write BEM surfaces in Python by `Alex Gramfort`_. + +- Filtering operations and apply_function interface for Raw object by `Martin Luessi`_. + +- Support for complex valued raw fiff files and computation of analytic signal for Raw object by `Martin Luessi`_. + +- Write inverse operators (surface and volume) by `Alex Gramfort`_. + +- Covariance matrix computation with multiple event types by `Martin Luessi`_. + +- New tutorial in the documentation and new classes and functions reference page by `Alex Gramfort`_. + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number +of commits): + +* 80 Alexandre Gramfort +* 51 Martin Luessi diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.4.inc python-mne-0.19.1+dfsg/doc/changes/0.4.inc --- python-mne-0.18.1+dfsg/doc/changes/0.4.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.4.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,52 @@ +.. _changes_0_4: + +Version 0.4 +----------- + +Changelog +~~~~~~~~~ + +- Add function to compute source PSD using minimum norm by `Alex Gramfort`_ + +- L21 Mixed Norm Estimates (MxNE) by `Alex Gramfort`_ and `Daniel Strohmeier`_ + +- Generation of simulated evoked responses by `Alex Gramfort`_, `Daniel Strohmeier`_, and `Martin Luessi`_ + +- Fit AR models to raw data for temporal whitening by `Alex Gramfort`_. + +- speedup + reduce memory of mne.morph_data by `Alex Gramfort`_. + +- Backporting scipy.signal.firwin2 so filtering works with old scipy by `Alex Gramfort`_. + +- LCMV Beamformer for evoked data, single trials, and raw data by `Alex Gramfort`_ and `Martin Luessi`_. + +- Add support for reading named channel selections by `Martin Luessi`_. + +- Add Raw.filter method to more easily band pass data by `Alex Gramfort`_. + +- Add tmin + tmax parameters in mne.compute_covariance to estimate noise covariance in epochs baseline without creating new epochs by `Alex Gramfort`_. + +- Add support for sLORETA in apply_inverse, apply_inverse_raw, apply_inverse_epochs (API Change) by `Alex Gramfort`_. + +- Add method to regularize a noise covariance by `Alex Gramfort`_. + +- Read and write measurement info in forward and inverse operators for interactive visualization in mne_analyze by `Alex Gramfort`_. + +- New mne_compute_proj_ecg.py and mne_compute_proj_eog.py scripts to estimate ECG/EOG PCA/SSP vectors by `Alex Gramfort`_ and `Martin Luessi`_. + +- Wrapper function and script (mne_maxfilter.py) for Elekta Neuromag MaxFilter(TM) by `Martin Luessi`_ + +- Add method to eliminate stimulation artifacts from raw data by linear interpolation or windowing by `Daniel Strohmeier`_. + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number +of commits): + +* 118 Alexandre Gramfort +* 81 Martin Luessi +* 15 Daniel Strohmeier +* 4 Christian Brodbeck +* 4 Louis Thibault +* 2 Brad Buran diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.5.inc python-mne-0.19.1+dfsg/doc/changes/0.5.inc --- python-mne-0.18.1+dfsg/doc/changes/0.5.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.5.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,125 @@ +.. _changes_0_5: + +Version 0.5 +----------- + +Changelog +~~~~~~~~~ + +- Multi-taper PSD estimation for single epochs in source space using minimum norm by `Martin Luessi`_ + +- Read and visualize .dip files obtained with xfit or mne_dipole_fit by `Alex Gramfort`_ + +- Make EEG layout by `Eric Larson`_ + +- Ability to specify SSP projectors when computing covariance from raw by `Eric Larson`_ + +- Read and write txt based event files (.eve or .txt) by `Eric Larson`_ + +- Pass qrs threshold to preprocessing functions by `Eric Larson`_ + +- Compute SSP projections from continuous raw data by `Eric Larson`_ + +- Support for applied SSP projections when loading Raw by `Eric Larson`_ and `Alex Gramfort`_ + +- Support for loading Raw stored in different fif files by `Eric Larson`_ + +- IO of many Evoked in a single fif file + compute Epochs.standard_error by `Eric Larson`_ and `Alex Gramfort`_ + +- ICA computation on Raw and Epochs with automatic component selection by `Denis Engemann`_ and `Alex Gramfort`_ + +- Saving ICA sources to fif files and creating ICA topography layouts by `Denis Engemann`_ + +- Save and restore ICA session to and from fif by `Denis Engemann`_ + +- Export raw, epochs and evoked data as data frame to the pandas library by `Denis Engemann`_ + +- Export raw, epochs and evoked data to the nitime library by `Denis Engemann`_ + +- Copy methods for raw and epochs objects by `Denis Engemann`_, `Martin Luessi`_ and `Alex Gramfort`_ + +- New raw objects method to get the time at certain indices by `Denis Engemann`_ and `Alex Gramfort`_ + +- Plot method for evoked objects by `Denis Engemann`_ + +- Enhancement of cluster-level stats (speed and memory efficiency) by `Eric Larson`_ and `Martin Luessi`_ + +- Reading of source space distances by `Eric Larson`_ + +- Support for filling / smoothing labels and speedup of morphing by `Eric Larson`_ + +- Adding options for morphing by `Eric Larson`_ + +- Plotting functions for time frequency and epochs image topographies by `Denis Engemann`_ and `Alex Gramfort`_ + +- Plotting ERP/ERF images by `Alex Gramfort`_ + +- See detailed subplot when cliking on a channel inside a topography plot by `Martin Luessi`_, `Eric Larson`_ and `Denis Engemann`_ + +- Misc channel type support plotting functions by `Denis Engemann`_ + +- Improved logging support by `Eric Larson`_ + +- Whitening of evoked data for plotting and quality checking by `Alex Gramfort`_ + +- Transparent I/O of gzipped fif files (as .fif.gz) by `Eric Larson`_ + +- Spectral connectivity estimation in sensor and source space by `Martin Luessi`_ + +- Read and write Epochs in FIF files by `Alex Gramfort`_ + +- Resampling of Raw, Epochs, and Evoked by `Eric Larson`_ + +- Creating epochs objects for different conditions and accessing conditions via user-defined name by `Denis Engemann`_ , `Eric Larson`_, `Alex Gramfort`_ and `Christian Brodbeck`_ + +- Visualizing evoked responses from different conditions in one topography plot by `Denis Engemann`_ and `Alex Gramfort`_ + +- Support for L21 MxNE solver using coordinate descent using scikit-learn by `Alex Gramfort`_ and `Daniel Strohmeier`_ + +- Support IIR filters (butterworth, chebyshev, bessel, etc.) by `Eric Larson`_ + +- Read labels from FreeSurfer parcellation by `Martin Luessi`_ + +- Combining labels in source space by `Christian Brodbeck`_ + +- Read and write source spaces, surfaces and coordinate transforms to and from files by `Christian Brodbeck`_ + +- Downsample epochs by `Christian Brodbeck`_ and `Eric Larson`_ + +- New labels class for handling source estimates by `Christian Brodbeck`_, `Martin Luessi`_ and `Alex Gramfort`_ + +- New plotting routines to easily display SourceEstimates using PySurfer by `Alex Gramfort`_ + +- Function to extract label time courses from SourceEstimate(s) by `Martin Luessi`_ + +- Function to visualize connectivity as circular graph by `Martin Luessi`_ and `Alex Gramfort`_ + +- Time-frequency Mixed Norm Estimates (TF-MxNE) by `Alex Gramfort`_ and `Daniel Strohmeier`_ + + +API +~~~ +- Added nave parameter to source_induced_power() and source_band_induced_power(), use nave=1 by default (wrong nave was used before). + +- Use mne.layout.read_layout instead of mne.layout.Layout to read a layout file (.lout) + +- Use raw.time_as_index instead of time_to_index (still works but is deprecated). + +- The artifacts module (mne.artifacts) is now merged into mne.preprocessing + +- Epochs objects now also take dicts as values for the event_id argument. They now can represent multiple conditions. + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number +of commits): + +* 313 Eric Larson +* 226 Alexandre Gramfort +* 219 Denis A. Engemann +* 104 Christian Brodbeck +* 85 Martin Luessi +* 6 Daniel Strohmeier +* 4 Teon Brooks +* 1 Dan G. Wakeman diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.6.inc python-mne-0.19.1+dfsg/doc/changes/0.6.inc --- python-mne-0.18.1+dfsg/doc/changes/0.6.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.6.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,156 @@ +.. _changes_0_6: + +Version 0.6 +----------- + +Changelog +~~~~~~~~~ + +- Linear (and zeroth-order) detrending for Epochs and Evoked by `Eric Larson`_ + +- Label morphing between subjects by `Eric Larson`_ + +- Define events based on time lag between reference and target event by `Denis Engemann`_ + +- ICA convenience function implementing an automated artifact removal workflow by `Denis Engemann`_ + +- Bad channels no longer included in epochs by default by `Eric Larson`_ + +- Support for diagonal noise covariances in inverse methods and rank computation by `Eric Larson`_ + +- Support for using CUDA in FFT-based FIR filtering (method='fft') and resampling by `Eric Larson`_ + +- Optimized FFT length selection for faster overlap-add filtering by `Martin Luessi`_ + +- Ability to exclude bad channels from evoked plots or shown them in red by `Martin Luessi`_ + +- Option to show both hemispheres when plotting SourceEstimate with PySurfer by `Martin Luessi`_ + +- Optimized Raw reading and epoching routines to limit memory copies by `Eric Larson`_ + +- Advanced options to save raw files in short or double precision by `Eric Larson`_ + +- Option to detect decreasing events using find_events by `Simon Kornblith`_ + +- Option to change default stim_channel used for finding events by `Eric Larson`_ + +- Use average patch normal from surface-oriented forward solution in inverse calculation when possible by `Eric Larson`_ + +- Function to plot drop_log from Epochs instance by `Eric Larson`_ + +- Estimate rank of Raw data by `Eric Larson`_ + +- Support reading of BTi/4D data by `Denis Engemann`_ + +- Wrapper for generating forward solutions by `Eric Larson`_ + +- Averaging forward solutions by `Eric Larson`_ + +- Events now contain the pre-event stim channel value in the middle column, by `Christian Brodbeck`_ + +- New function ``mne.find_stim_steps`` for finding all steps in a stim channel by `Christian Brodbeck`_ + +- Get information about FIFF files using mne.fiff.show_fiff() by `Eric Larson`_ + +- Compute forward fields sensitivity maps by `Alex Gramfort`_ and `Eric Larson`_ + +- Support reading of KIT data by `Teon Brooks`_ and `Christian Brodbeck`_ + +- Raw data visualization by `Eric Larson`_ + +- Smarter SourceEstimate object that contains linear inverse kernel and sensor space data for fast time-frequency transforms in source space by `Martin Luessi`_ + +- Add example of decoding/MVPA on MEG sensor data by `Alex Gramfort`_ + +- Add support for non-paired tests in spatiotemporal cluster stats by `Alex Gramfort`_ + +- Add unified SSP-projector API for Raw, Epochs and Evoked objects by `Denis Engemann`_, `Alex Gramfort`_ `Eric Larson`_ and `Martin Luessi`_ + +- Add support for delayed SSP application at evoked stage `Denis Engemann`_, `Alex Gramfort`_, `Eric Larson`_ and `Martin Luessi`_ + +- Support selective parameter updating in functions taking dicts as arguments by `Denis Engemann`_ + +- New ICA method ``sources_as_epochs`` to create Epochs in ICA space by `Denis Engemann`_ + +- New method in Evoked and Epoch classes to shift time scale by `Mainak Jas`_ + +- Added option to specify EOG channel(s) when computing PCA/SSP projections for EOG artifacts by `Mainak Jas`_ + +- Improved connectivity interface to allow combinations of signals, e.g., seed time series and source estimates, by `Martin Luessi`_ + +- Effective connectivity estimation using Phase Slope Index (PSI) by `Martin Luessi`_ + +- Support for threshold-free cluster enhancement (TFCE) by `Eric Larson`_ + +- Support for "hat" variance regularization by `Eric Larson`_ + +- Access source estimates as Pandas DataFrame by `Denis Engemann`_. + +- Add example of decoding/MVPA on MEG source space data by `Denis Engemann`_ + +- Add support for --tstart option in mne_compute_proj_eog.py by `Alex Gramfort`_ + +- Add two-way repeated measures ANOVA for mass-univariate statistics by `Denis Engemann`_, `Eric Larson`_ and `Alex Gramfort`_ + +- Add function for summarizing clusters from spatio-temporal-cluster permutation tests by `Denis Engemann`_ and `Eric Larson`_ + +- Add generator support for ``lcmv_epochs`` by `Denis Engemann`_ + +- Gamma-MAP sparse source localization method by `Martin Luessi`_ and `Alex Gramfort`_ + +- Add regular expression and substring support for selecting parcellation labels by `Denis Engemann`_ + +- New plot_evoked option for interactive and reversible selection of SSP projection vectors by `Denis Engemann`_ + +- Plot 2D flat topographies with interpolation for evoked and SSPs by `Christian Brodbeck`_ and `Alex Gramfort`_ + +- Support delayed SSP applicationon for 2D flat topographies by `Denis Engemann`_ and `Christian Brodbeck`_ and `Alex Gramfort`_ + +- Allow picking maximum power source, a.k.a. "optimal", orientation in LCMV beamformers by `Roman Goj`_, `Alex Gramfort`_, `Denis Engemann`_ and `Martin Luessi`_ + +- Add sensor type scaling parameter to plot_topo by `Andrew Dykstra`_, `Denis Engemann`_ and `Eric Larson`_ + +- Support delayed SSP application in plot_topo by `Denis Engemann`_ + +API +~~~ + +- Deprecated use of fiff.pick_types without specifying exclude -- use either [] (none), ``bads`` (bad channels), or a list of string (channel names). + +- Depth bias correction in dSPM/MNE/sLORETA make_inverse_operator is now done like in the C code using only gradiometers if present, else magnetometers, and EEG if no MEG channels are present. + +- Fixed-orientation inverse solutions need to be made using `fixed=True` option (using non-surface-oriented forward solutions if no depth weighting is used) to maintain compatibility with MNE C code. + +- Raw.save() will only overwrite the destination file, if it exists, if option overwrite=True is set. + +- mne.utils.set_config(), get_config(), get_config_path() moved to mne namespace. + +- Raw constructor argument proj_active deprecated -- use proj argument instead. + +- Functions from the mne.mixed_norm module have been moved to the mne.inverse_sparse module. + +- Deprecate CTF compensation (keep_comp and dest_comp) in Epochs and move it to Raw with a single compensation parameter. + +- Remove artifacts module. Artifacts- and preprocessing related functions can now be found in mne.preprocessing. + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number +of commits): + +* 340 Eric Larson +* 330 Denis A. Engemann +* 204 Alexandre Gramfort +* 72 Christian Brodbeck +* 66 Roman Goj +* 65 Martin Luessi +* 37 Teon Brooks +* 18 Mainak Jas +* 9 Simon Kornblith +* 7 Daniel Strohmeier +* 6 Romain Trachel +* 5 Yousra BEKHTI +* 5 Brad Buran +* 1 Andrew Dykstra +* 1 Christoph Dinh diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.7.inc python-mne-0.19.1+dfsg/doc/changes/0.7.inc --- python-mne-0.18.1+dfsg/doc/changes/0.7.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.7.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,136 @@ +.. _changes_0_7: + +Version 0.7 +----------- + +Changelog +~~~~~~~~~ + +- Add capability for real-time feedback via trigger codes using StimServer and StimClient classes by `Mainak Jas`_ + +- New decoding module for MEG analysis containing sklearn compatible transformers by `Mainak Jas`_ and `Alex Gramfort`_ + +- New realtime module containing RtEpochs, RtClient and MockRtClient class by `Martin Luessi`_, `Christopher Dinh`_, `Alex Gramfort`_, `Denis Engemann`_ and `Mainak Jas`_ + +- Allow picking normal orientation in LCMV beamformers by `Roman Goj`_, `Alex Gramfort`_, `Denis Engemann`_ and `Martin Luessi`_ + +- Add printing summary to terminal for measurement info by `Denis Engemann`_ + +- Add read and write info attribute ICA objects by `Denis Engemann`_ + +- Decoding with Common Spatial Patterns (CSP) by `Romain Trachel`_ and `Alex Gramfort`_ + +- Add ICA ``plot_topomap`` function and method for displaying the spatial sensitivity of ICA sources by `Denis Engemann`_ + +- Plotting multiple brain views at once by `Eric Larson`_ + +- Reading head positions from raw FIFF files by `Eric Larson`_ + +- Add decimation parameter to ICA.decompose* methods by `Denis Engemann`_ and `Alex Gramfort`_ + +- Add rejection buffer to ICA.decompose* methods by `Denis Engemann`_ and `Alex Gramfort`_ + +- Improve ICA computation speed and memory usage by `Denis Engemann`_ and `Alex Gramfort`_ + +- Add polygonal surface decimation function to preprocess head surfaces for coregistration by `Denis Engemann`_ and `Alex Gramfort`_ + +- DICS time-frequency beamforming for epochs, evoked and for estimating source power by `Roman Goj`_, `Alex Gramfort`_ and `Denis Engemann`_ + +- Add method for computing cross-spectral density (CSD) from epochs and class for storing CSD data by `Roman Goj`_, `Alex Gramfort`_ and `Denis Engemann`_ + +- Add trellis plot function and method for visualizing single epochs by `Denis Engemann`_ + +- Add fiducials read/write support by `Christian Brodbeck`_ and `Alex Gramfort`_ + +- Add select / drop bad channels in `plot_raw` on click by `Denis Engemann`_ + +- Add `ico` and `oct` source space creation in native Python by `Eric Larson`_ + +- Add interactive rejection of bad trials in ``plot_epochs`` by `Denis Engemann`_ + +- Add morph map calculation by `Eric Larson`_ and `Martin Luessi`_ + +- Add volume and discrete source space creation and I/O support by `Eric Larson`_ + +- Time-frequency beamforming to obtain spectrograms in source space using LCMV and DICS by `Roman Goj`_, `Alex Gramfort`_ and `Denis Engemann`_ + +- Compute epochs power spectral density function by `Denis Engemann`_ + +- Plot raw power spectral density by `Eric Larson`_ + +- Computing of distances along the cortical surface by `Eric Larson`_ + +- Add reading BEM solutions by `Eric Larson`_ + +- Add forward solution calculation in native Python by `Eric Larson`_ + +- Add (Neuro)debian license compatibility by `Eric Larson`_ + +- Automatic QRS threshold selection for ECG events by `Eric Larson`_ + +- Add Travis continuous integration service by `Denis Engemann`_ + +- Add SPM face data set by `Denis Engemann`_ `Martin Luessi`_ and `Alex Gramfort`_ + +- Support reading of EDF+,BDF data by `Teon Brooks`_ + +- Tools for scaling MRIs (mne.scale_mri) by `Christian Brodbeck`_ + +- GUI for head-MRI coregistration (mne.gui.coregistration) by `Christian Brodbeck`_ + +- GUI for ki2fiff conversion (mne.gui.kit2fiff) by `Christian Brodbeck`_ + +- Support reading of EEG BrainVision data by `Teon Brooks`_ + +- Improve CTF compensation handling by `Martin Luessi`_ and `Eric Larson`_ + +- Improve and extend automated layout guessing by `Denis Engemann`_ + +- Add Continuum Analytics Anaconda support by `Denis Engemann`_ + +- Add `subtract evoked` option to beamformers by `Andrew Dykstra`_ + +- Add new `transform` method to SourceEstimate(s) by `Andrew Dykstra`_ + +API +~~~ + +- The pick_normal parameter for minimum norm solvers has been renamed as ``pick_ori`` and normal orientation picking is now achieved by passing the value "normal" for the `pick_ori` parameter. + +- ICA objects now expose the measurement info of the object fitted. + +- Average EEG reference is now added by default to Raw instances. + +- Removed deprecated read/write_stc/w, use SourceEstimate methods instead + +- The ``chs`` argument in ``mne.layouts.find_layout`` is deprecated and will be removed in MNE-Python 0.9. Use ``info`` instead. + +- ``plot_evoked`` and ``Epochs.plot`` now open a new figure by default. To plot on an existing figure please specify the `axes` parameter. + + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number +of commits): + +* 336 Denis A. Engemann +* 202 Eric Larson +* 193 Roman Goj +* 138 Alexandre Gramfort +* 99 Mainak Jas +* 75 Christian Brodbeck +* 60 Martin Luessi +* 40 Teon Brooks +* 29 Romain Trachel +* 28 Andrew Dykstra +* 12 Mark Wronkiewicz +* 10 Christoph Dinh +* 8 Alan Leggitt +* 3 Yaroslav Halchenko +* 3 Daniel Strohmeier +* 2 Mads Jensen +* 2 Praveen Sripad +* 1 Luke Bloy +* 1 Emanuele Olivetti +* 1 Yousra BEKHTI diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.8.inc python-mne-0.19.1+dfsg/doc/changes/0.8.inc --- python-mne-0.18.1+dfsg/doc/changes/0.8.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.8.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,194 @@ +.. _changes_0_8: + +Version 0.8 +----------- + +Changelog +~~~~~~~~~ + +- Add Python3 support by `Nick Ward`_, `Alex Gramfort`_, `Denis Engemann`_, and `Eric Larson`_ + +- Add ``get_peak`` method for evoked and stc objects by `Denis Engemann`_ + +- Add ``iter_topography`` function for radically simplified custom sensor topography plotting by `Denis Engemann`_ + +- Add field line interpolation by `Eric Larson`_ + +- Add full provenance tacking for epochs and improve ``drop_log`` by `Tal Linzen`_, `Alex Gramfort`_ and `Denis Engemann`_ + +- Add systematic contains method to ``Raw``, ``Epochs`` and ``Evoked`` for channel type membership testing by `Denis Engemann`_ + +- Add fiff unicode writing and reading support by `Denis Engemann`_ + +- Add 3D MEG/EEG field plotting function and evoked method by `Denis Engemann`_ and `Alex Gramfort`_ + +- Add consistent channel-dropping methods to ``Raw``, ``Epochs`` and ``Evoked`` by `Denis Engemann`_ and `Alex Gramfort`_ + +- Add ``equalize_channnels`` function to set common channels for a list of ``Raw``, ``Epochs``, or ``Evoked`` objects by `Denis Engemann`_ + +- Add ``plot_events`` function to visually display paradigm by `Alex Gramfort`_ + +- Improved connectivity circle plot by `Martin Luessi`_ + +- Add ability to anonymize measurement info by `Eric Larson`_ + +- Add callback to connectivity circle plot to isolate connections to clicked nodes `Roan LaPlante`_ + +- Add ability to add patch information to source spaces by `Eric Larson`_ + +- Add ``split_label`` function to divide labels into multiple parts by `Christian Brodbeck`_ + +- Add ``color`` attribute to ``Label`` objects by `Christian Brodbeck`_ + +- Add ``max`` mode for ``extract_label_time_course`` by `Mads Jensen`_ + +- Add ``rename_channels`` function to change channel names and types in info object by `Dan Wakeman`_ and `Denis Engemann`_ + +- Add ``compute_ems`` function to extract the time course of experimental effects by `Denis Engemann`_, `Sébastien Marti`_ and `Alex Gramfort`_ + +- Add option to expand Labels defined in a source space to the original surface (``Label.fill()``) by `Christian Brodbeck`_ + +- GUIs can be invoked form the command line using `$ mne coreg` and `$ mne kit2fiff` by `Christian Brodbeck`_ + +- Add ``add_channels_epochs`` function to combine different recordings at the Epochs level by `Christian Brodbeck`_ and `Denis Engemann`_ + +- Add support for EGI Netstation simple binary files by `Denis Engemann`_ + +- Add support for treating arbitrary data (numpy ndarray) as a Raw instance by `Eric Larson`_ + +- Support for parsing the EDF+ annotation channel by `Martin Billinger`_ + +- Add EpochsArray constructor for creating epochs from numpy arrays by `Denis Engemann`_ and `Federico Raimondo`_ + +- Add connector to FieldTrip realtime client by `Mainak Jas`_ + +- Add color and event_id with legend options in plot_events in viz.py by `Cathy Nangini`_ + +- Add ``events_list`` parameter to ``mne.concatenate_raws`` to concatenate events corresponding to runs by `Denis Engemann`_ + +- Add ``read_ch_connectivity`` function to read FieldTrip neighbor template .mat files and obtain sensor adjacency matrices by `Denis Engemann`_ + +- Add display of head in helmet from -trans.fif file to check coregistration quality by `Mainak Jas`_ + +- Add ``raw.add_events`` to allow adding events to a raw file by `Eric Larson`_ + +- Add ``plot_image`` method to Evoked object to display data as images by `Jean-Remi King`_ and `Alex Gramfort`_ and `Denis Engemann`_ + +- Add BCI demo with CSP on motor imagery by `Martin Billinger`_ + +- New ICA API with unified methods for processing ``Raw``, ``Epochs`` and ``Evoked`` objects by `Denis Engemann`_ + +- Apply ICA at the evoked stage by `Denis Engemann`_ + +- New ICA methods for visualizing unmixing quality, artifact detection and rejection by `Denis Engemann`_ + +- Add ``pick_channels`` and ``drop_channels`` mixin class to pick and drop channels from ``Raw``, ``Epochs``, and ``Evoked`` objects by `Andrew Dykstra`_ and `Denis Engemann`_ + +- Add ``EvokedArray`` class to create an Evoked object from an array by `Andrew Dykstra`_ + +- Add ``plot_bem`` method to visualize BEM contours on MRI anatomical images by `Mainak Jas`_ and `Alex Gramfort`_ + +- Add automated ECG detection using cross-trial phase statistics by `Denis Engemann`_ and `Juergen Dammers`_ + +- Add Forward class to succintly display gain matrix info by `Andrew Dykstra`_ + +- Add reading and writing of split raw files by `Martin Luessi`_ + +- Add OLS regression function by `Tal Linzen`_, `Teon Brooks`_ and `Denis Engemann`_ + +- Add computation of point spread and cross-talk functions for MNE type solutions by `Alex Gramfort`_ and `Olaf Hauk`_ + +- Add mask parameter to `plot_evoked_topomap` and ``evoked.plot_topomap`` by `Denis Engemann`_ and `Alex Gramfort`_ + +- Add infomax and extended infomax ICA by `Denis Engemann`_, `Juergen Dammers`_ and `Lukas Breuer`_ and `Federico Raimondo`_ + +- Aesthetically redesign interpolated topography plots by `Denis Engemann`_ and `Alex Gramfort`_ + +- Simplify sensor space time-frequency analysis API with ``tfr_morlet`` function by `Alex Gramfort`_ and `Denis Engemann`_ + +- Add new somatosensory MEG dataset with nice time-frequency content by `Alex Gramfort`_ + +- Add HDF5 write/read support for SourceEstimates by `Eric Larson`_ + +- Add InverseOperator class to display inverse operator info by `Mainak Jas`_ + +- Add `$ mne report` command to generate html reports of MEG/EEG data analysis pipelines by `Mainak Jas`_, `Alex Gramfort`_ and `Denis Engemann`_ + +- Improve ICA verbosity with regard to rank reduction by `Denis Engemann`_ + +BUG +~~~ + +- Fix incorrect ``times`` attribute when stc was computed using ``apply_inverse`` after decimation at epochs stage for certain, arbitrary sample frequencies by `Denis Engemann`_ + +- Fix corner case error for step-down-in-jumps permutation test (when step-down threshold was high enough to include all clusters) by `Eric Larson`_ + +- Fix selection of total number of components via float when picking ICA sources by `Denis Engemann`_ and `Qunxi Dong`_ + +- Fix writing and reading transforms after modification in measurement info by `Denis Engemann`_ and `Martin Luessi`_ and `Eric Larson`_ + +- Fix pre-whitening / rescaling when estimating ICA on multiple channels without covariance by `Denis Engemann`_ + +- Fix ICA pre-whitening, avoid recomputation when applying ICA to new data by `Denis Engemann`_ + +API +~~~ + +- The minimum numpy version has been increased to 1.6 from 1.4. + +- Epochs object now has a selection attribute to track provenance of selected Epochs. The length of the drop_log attribute is now the same as the length of the original events passed to Epochs. In earlier versions it had the length of the events filtered by event_id. Epochs has also now a plot_drop_log method. + +- Deprecate Epochs.drop_picks in favor of a new method called drop_channels + +- Deprecate ``labels_from_parc`` and ``parc_from_labels`` in favor of ``read_labels_from_annot`` and ``write_labels_to_annot`` + +- The default of the new add_dist option of ``setup_source_space`` to add patch information will change from False to True in MNE-Python 0.9 + +- Deprecate ``read_evoked`` and ``write_evoked`` in favor of ``read_evokeds`` and ``write_evokeds``. read_evokeds will return all `Evoked` instances in a file by default. + +- Deprecate ``setno`` in favor of ``condition`` in the initialization of an Evoked instance. This affects ``mne.fiff.Evoked`` and ``read_evokeds``, but not ``read_evoked``. + +- Deprecate ``mne.fiff`` module, use ``mne.io`` instead e.g. ``mne.io.Raw`` instead of ``mne.fiff.Raw``. + +- Pick functions (e.g., ``pick_types``) are now in the mne namespace (e.g. use ``mne.pick_types``). + +- Deprecated ICA methods specific to one container type. Use ICA.fit, ICA.get_sources ICA.apply and ``ICA.plot_*`` for processing Raw, Epochs and Evoked objects. + +- The default smoothing method for ``mne.stc_to_label`` will change in v0.9, and the old method is deprecated. + +- As default, for ICA the maximum number of PCA components equals the number of channels passed. The number of PCA components used to reconstruct the sensor space signals now defaults to the maximum number of PCA components estimated. + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number of commits): + +* 418 Denis A. Engemann +* 284 Alexandre Gramfort +* 242 Eric Larson +* 155 Christian Brodbeck +* 144 Mainak Jas +* 49 Martin Billinger +* 49 Andrew Dykstra +* 44 Tal Linzen +* 37 Dan G. Wakeman +* 36 Martin Luessi +* 26 Teon Brooks +* 20 Cathy Nangini +* 15 Hari Bharadwaj +* 15 Roman Goj +* 10 Ross Maddox +* 9 Marmaduke Woodman +* 8 Praveen Sripad +* 8 Tanay +* 8 Roan LaPlante +* 5 Saket Choudhary +* 4 Nick Ward +* 4 Mads Jensen +* 3 Olaf Hauk +* 3 Brad Buran +* 2 Daniel Strohmeier +* 2 Federico Raimondo +* 2 Alan Leggitt +* 1 Jean-Remi King +* 1 Matti Hamalainen diff -Nru python-mne-0.18.1+dfsg/doc/changes/0.9.inc python-mne-0.19.1+dfsg/doc/changes/0.9.inc --- python-mne-0.18.1+dfsg/doc/changes/0.9.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/0.9.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,239 @@ +.. _changes_0_9: + +Version 0.9 +----------- + +Changelog +~~~~~~~~~ + +- Add support for mayavi figures in ``add_section`` method in Report by `Mainak Jas`_ + +- Add extract volumes of interest from freesurfer segmentation and setup as volume source space by `Alan Leggitt`_ + +- Add support to combine source spaces of different types by `Alan Leggitt`_ + +- Add support for source estimate for mixed source spaces by `Alan Leggitt`_ + +- Add ``SourceSpaces.save_as_volume`` method by `Alan Leggitt`_ + +- Automatically compute proper box sizes when generating layouts on the fly by `Marijn van Vliet`_ + +- Average evoked topographies across time points by `Denis Engemann`_ + +- Add option to Report class to save images as vector graphics (SVG) by `Denis Engemann`_ + +- Add events count to ``mne.viz.plot_events`` by `Denis Engemann`_ + +- Add support for stereotactic EEG (sEEG) channel type by `Marmaduke Woodman`_ + +- Add support for montage files by `Denis Engemann`_, `Marijn van Vliet`_, `Jona Sassenhagen`_, `Alex Gramfort`_ and `Teon Brooks`_ + +- Add support for spatiotemporal permutation clustering on sensors by `Denis Engemann`_ + +- Add support for multitaper time-frequency analysis by `Hari Bharadwaj`_ + +- Add Stockwell (S) transform for time-frequency representations by `Denis Engemann`_ and `Alex Gramfort`_ + +- Add reading and writing support for time frequency data (AverageTFR objects) by `Denis Engemann`_ + +- Add reading and writing support for digitizer data, and function for adding dig points to info by `Teon Brooks`_ + +- Add ``plot_projs_topomap`` method to ``Raw``, ``Epochs`` and ``Evoked`` objects by `Teon Brooks`_ + +- Add EEG (based on spherical splines) and MEG (based on field interpolation) bad channel interpolation method to ``Raw``, ``Epochs`` and ``Evoked`` objects by `Denis Engemann`_ and `Mainak Jas`_ + +- Add parameter to ``whiten_evoked``, ``compute_whitener`` and ``prepare_noise_cov`` to set the exact rank by `Martin Luessi`_ and `Denis Engemann`_ + +- Add fiff I/O for processing history and MaxFilter info by `Denis Engemann`_ and `Eric Larson`_ + +- Add automated regularization with support for multiple sensor types to ``compute_covariance`` by `Denis Engemann`_ and `Alex Gramfort`_ + +- Add ``Evoked.plot_white`` method to diagnose the quality of the estimated noise covariance and its impact on spatial whitening by `Denis Engemann`_ and `Alex Gramfort`_ + +- Add ``mne.evoked.grand_average`` function to compute grand average of Evoked data while interpolating bad EEG channels if necessary by `Mads Jensen`_ and `Alex Gramfort`_ + +- Improve EEG referencing support and add support for bipolar referencing by `Marijn van Vliet`_ and `Alex Gramfort`_ + +- Enable TFR calculation on Evoked objects by `Eric Larson`_ + +- Add support for combining Evoked datasets with arbitrary weights (e.g., for oddball paradigms) by `Eric Larson`_ and `Alex Gramfort`_ + +- Add support for concatenating a list of Epochs objects by `Denis Engemann`_ + +- Labels support subtraction (``label_1 - label_2``) by `Christian Brodbeck`_ + +- Add GeneralizationAcrossTime object with support for cross-condition generalization by `Jean-Remi King`_ and `Denis Engemann`_ + +- Add support for single dipole fitting by `Eric Larson`_ + +- Add support for spherical models in forward calculations by `Eric Larson`_ + +- Add support for SNR estimation by `Eric Larson`_ + +- Add support for Savitsky-Golay filtering of Evoked and Epochs by `Eric Larson`_ + +- Add support for adding an empty reference channel to data by `Teon Brooks`_ + +- Add reader function ``mne.io.read_raw_fif`` for Raw FIF files by `Teon Brooks`_ + +- Add example of creating MNE objects from arbitrary data and NEO files by `Jaakko Leppakangas`_ + +- Add ``plot_psd`` and ``plot_psd_topomap`` methods to epochs by `Yousra Bekhti`_, `Eric Larson`_ and `Denis Engemann`_ + +- ``evoked.pick_types``, ``epochs.pick_types``, and ``tfr.pick_types`` added by `Eric Larson`_ + +- ``rename_channels`` and ``set_channel_types`` added as methods to ``Raw``, ``Epochs`` and ``Evoked`` objects by `Teon Brooks`_ + +- Add RAP-MUSIC inverse method by `Yousra Bekhti`_ and `Alex Gramfort`_ + +- Add ``evoked.as_type`` to allow remapping data in MEG channels to virtual magnetometer or gradiometer channels by `Mainak Jas`_ + +- Add :meth:`mne.Report.add_bem_to_section`, :meth:`mne.Report.add_htmls_to_section` methods to :class:`mne.Report` by `Teon Brooks`_ + +- Add support for KIT epochs files with ``read_epochs_kit`` by `Teon Brooks`_ + +- Add whitening plots for evokeds to ``mne.Report`` by `Mainak Jas`_ + +- Add ``DigMontage`` class and reader to interface with digitization info by `Teon Brooks`_ and `Christian Brodbeck`_ + +- Add ``set_montage`` method to the ``Raw``, ``Epochs``, and ``Evoked`` objects by `Teon Brooks`_ and `Denis Engemann`_ + +- Add support for capturing sensor positions when clicking on an image by `Chris Holdgraf`_ + +- Add support for custom sensor positions when creating Layout objects by `Chris Holdgraf`_ + +BUG +~~~ + +- Fix energy conservation for STFT with tight frames by `Daniel Strohmeier`_ + +- Fix incorrect data matrix when tfr was plotted with parameters ``tmin``, ``tmax``, ``fmin`` and ``fmax`` by `Mainak Jas`_ + +- Fix channel names in topomaps by `Alex Gramfort`_ + +- Fix mapping of ``l_trans_bandwidth`` (to low frequency) and ``h_trans_bandwidth`` (to high frequency) in ``_BaseRaw.filter`` by `Denis Engemann`_ + +- Fix scaling source spaces when distances have to be recomputed by `Christian Brodbeck`_ + +- Fix repeated samples in client to FieldTrip buffer by `Mainak Jas`_ and `Federico Raimondo`_ + +- Fix highpass and lowpass units read from Brainvision vhdr files by `Alex Gramfort`_ + +- Add missing attributes for BrainVision and KIT systems needed for resample by `Teon Brooks`_ + +- Fix file extensions of SSP projection files written by mne commands (from _proj.fif to -prof.fif) by `Alex Gramfort`_ + +- Generating EEG layouts no longer requires digitization points by `Marijn van Vliet`_ + +- Add missing attributes to BTI, KIT, and BrainVision by `Eric Larson`_ + +- The API change to the edf, brainvision, and egi break backwards compatibility for when importing eeg data by `Teon Brooks`_ + +- Fix bug in ``mne.viz.plot_topo`` if ylim was passed for single sensor layouts by `Denis Engemann`_ + +- Average reference projections will no longer by automatically added after applying a custom EEG reference by `Marijn van Vliet`_ + +- Fix picks argument to filter in n dimensions (affects FilterEstimator), and highpass filter in FilterEstimator by `Mainak Jas`_ + +- Fix beamformer code LCMV/DICS for CTF data with reference channels by `Denis Engemann`_ and `Alex Gramfort`_ + +- Fix scalings for bad EEG channels in ``mne.viz.plot_topo`` by `Marijn van Vliet`_ + +- Fix EGI reading when no events are present by `Federico Raimondo`_ + +- Add functionality to determine plot limits automatically or by data percentiles by `Mark Wronkiewicz`_ + +- Fix bug in mne.io.edf where the channel offsets were omitted in the voltage calculations by `Teon Brooks`_ + +- Decouple section ordering in command-line from python interface for mne-report by `Mainak Jas`_ + +- Fix bug with ICA resetting by `Denis Engemann`_ + +API +~~~ + +- apply_inverse functions have a new boolean parameter ``prepared`` which saves computation time by calling ``prepare_inverse_operator`` only if it is False + +- find_events and read_events functions have a new parameter ``mask`` to set some bits to a don't care state by `Teon Brooks`_ + +- New channels module including layouts, electrode montages, and neighbor definitions of sensors which deprecates ``mne.layouts`` by `Denis Engemann`_ + +- ``read_raw_brainvision``, ``read_raw_edf``, ``read_raw_egi`` all use a standard montage import by `Teon Brooks`_ + +- Fix missing calibration factors for ``mne.io.egi.read_raw_egi`` by `Denis Engemann`_ and `Federico Raimondo`_ + +- Allow multiple filename patterns as a list (e.g., \*raw.fif and \*-eve.fif) to be parsed by mne report in ``Report.parse_folder()`` by `Mainak Jas`_ + +- ``read_hsp``, ``read_elp``, and ``write_hsp``, ``write_mrk`` were removed and made private by `Teon Brooks`_ + +- When computing the noise covariance or MNE inverse solutions, the rank is estimated empirically using more sensitive thresholds, which stabilizes results by `Denis Engemann`_ and `Eric Larson`_ and `Alex Gramfort`_ + +- Raw FIFF files can be preloaded after class instantiation using ``raw.preload_data()`` + +- Add ``label`` parameter to ``apply_inverse`` by `Teon Brooks`_ + +- Deprecated ``label_time_courses`` for ``in_label`` method in `SourceEstimate` by `Teon Brooks`_ + +- Deprecated ``as_data_frame`` for ``to_data_frame`` by `Chris Holdgraf`_ + +- Add ``transform``, ``unit`` parameters to ``read_montage`` by `Teon Brooks`_ + +- Deprecated ``fmin, fmid, fmax`` in stc.plot and added ``clim`` by `Mark Wronkiewicz`_ + +- Use ``scipy.signal.welch`` instead of matplotlib.psd inside ``compute_raw_psd`` and ``compute_epochs_psd`` by `Yousra Bekhti`_ `Eric Larson`_ and `Denis Engemann`_. As a consquence, ``Raw.plot_raw_psds`` has been deprecated. + +- ``Raw`` instances returned by ``mne.forward.apply_forward_raw`` now always have times starting from + zero to be consistent with all other ``Raw`` instances. To get the former ``start`` and ``stop`` times, + use ``raw.first_samp / raw.info['sfreq']`` and ``raw.last_samp / raw.info['sfreq']``. + +- ``pick_types_evoked`` has been deprecated in favor of ``evoked.pick_types``. + +- Deprecated changing the sensor type of channels in ``rename_channels`` by `Teon Brooks`_ + +- CUDA is no longer initialized at module import, but only when first used. + +- ``add_figs_to_section`` and ``add_images_to_section`` now have a ``textbox`` parameter to add comments to the image by `Teon Brooks`_ + +- Deprecated ``iir_filter_raw`` for ``fit_iir_model_raw``. + +- Add ``montage`` parameter to the ``create_info`` function to create the info using montages by `Teon Brooks`_ + +Authors +~~~~~~~ + +The committer list for this release is the following (preceded by number of commits): + +* 515 Eric Larson +* 343 Denis A. Engemann +* 304 Alexandre Gramfort +* 300 Teon Brooks +* 142 Mainak Jas +* 119 Jean-Remi King +* 77 Alan Leggitt +* 75 Marijn van Vliet +* 63 Chris Holdgraf +* 57 Yousra Bekhti +* 49 Mark Wronkiewicz +* 44 Christian Brodbeck +* 30 Jona Sassenhagen +* 29 Hari Bharadwaj +* 27 Clément Moutard +* 24 Ingoo Lee +* 18 Marmaduke Woodman +* 16 Martin Luessi +* 10 Jaakko Leppakangas +* 9 Andrew Dykstra +* 9 Daniel Strohmeier +* 7 kjs +* 6 Dan G. Wakeman +* 5 Federico Raimondo +* 3 Basile Pinsard +* 3 Christoph Dinh +* 3 Hafeza Anevar +* 2 Martin Billinger +* 2 Roan LaPlante +* 1 Manoj Kumar +* 1 Matt Tucker +* 1 Romain Trachel +* 1 mads jensen +* 1 sviter diff -Nru python-mne-0.18.1+dfsg/doc/changes/names.inc python-mne-0.19.1+dfsg/doc/changes/names.inc --- python-mne-0.18.1+dfsg/doc/changes/names.inc 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/changes/names.inc 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,265 @@ +.. _Alex Gramfort: http://alexandre.gramfort.net + +.. _Martin Luessi: https://www.martinos.org/user/8245 + +.. _Yaroslav Halchenko: http://www.onerussian.com/ + +.. _Daniel Strohmeier: http://www.tu-ilmenau.de/bmti/fachgebiete/biomedizinische-technik/dipl-ing-daniel-strohmeier/ + +.. _Eric Larson: http://larsoner.com + +.. _Denis Engemann: http://denis-engemann.de + +.. _Christian Brodbeck: https://github.com/christianbrodbeck + +.. _Simon Kornblith: http://simonster.com + +.. _Teon Brooks: https://teonbrooks.github.io + +.. _Mainak Jas: http://ltl.tkk.fi/wiki/Mainak_Jas + +.. _Roman Goj: http://romanmne.blogspot.co.uk + +.. _Andrew Dykstra: https://github.com/adykstra + +.. _Romain Trachel: http://www.lscp.net/braware/trachelBr.html + +.. _Christopher Dinh: https://github.com/chdinh + +.. _Nick Ward: http://www.ucl.ac.uk/ion/departments/sobell/Research/NWard + +.. _Tal Linzen: http://tallinzen.net/ + +.. _Roan LaPlante: https://github.com/aestrivex + +.. _Mads Jensen: https://github.com/MadsJensen + +.. _Dan Wakeman: https://github.com/dgwakeman + +.. _Qunxi Dong: https://github.com/dongqunxi + +.. _Martin Billinger: https://github.com/kazemakase + +.. _Federico Raimondo: https://github.com/fraimondo + +.. _Cathy Nangini: https://github.com/KatiRG + +.. _Jean-Remi King: https://github.com/kingjr + +.. _Juergen Dammers: https://github.com/jdammers + +.. _Olaf Hauk: http://www.neuroscience.cam.ac.uk/directory/profile.php?olafhauk + +.. _Lukas Breuer: http://www.researchgate.net/profile/Lukas_Breuer + +.. _Alan Leggitt: https://github.com/leggitta + +.. _Marijn van Vliet: https://github.com/wmvanvliet + +.. _Marmaduke Woodman: https://github.com/maedoc + +.. _Jona Sassenhagen: https://github.com/jona-sassenhagen + +.. _Hari Bharadwaj: http://www.haribharadwaj.com + +.. _Chris Holdgraf: http://chrisholdgraf.com + +.. _Jaakko Leppakangas: https://github.com/jaeilepp + +.. _Yousra Bekhti: https://www.linkedin.com/pub/yousra-bekhti/56/886/421 + +.. _Mark Wronkiewicz: http://ilabs.washington.edu/graduate-students/bio/i-labs-mark-wronkiewicz + +.. _Sébastien Marti: http://www.researchgate.net/profile/Sebastien_Marti + +.. _Chris Bailey: https://github.com/cjayb + +.. _Ross Maddox: https://www.urmc.rochester.edu/labs/maddox-lab.aspx + +.. _Alexandre Barachant: http://alexandre.barachant.org + +.. _Daniel McCloy: http://dan.mccloy.info + +.. _Jair Montoya Martinez: https://github.com/jmontoyam + +.. _Samu Taulu: http://ilabs.washington.edu/institute-faculty/bio/i-labs-samu-taulu-dsc + +.. _Lorenzo Desantis: https://github.com/lorenzo-desantis/ + +.. _Jukka Nenonen: https://www.linkedin.com/pub/jukka-nenonen/28/b5a/684 + +.. _Jussi Nurminen: https://scholar.google.fi/citations?user=R6CQz5wAAAAJ&hl=en + +.. _Clemens Brunner: https://github.com/cle1109 + +.. _Asish Panda: https://github.com/kaichogami + +.. _Natalie Klein: http://www.stat.cmu.edu/people/students/neklein + +.. _Jon Houck: https://scholar.google.com/citations?user=DNoS05IAAAAJ&hl=en + +.. _Pablo-Arias: https://github.com/Pablo-Arias + +.. _Alexander Rudiuk: https://github.com/ARudiuk + +.. _Mikołaj Magnuski: https://github.com/mmagnuski + +.. _Felix Raimundo: https://github.com/gamazeps + +.. _Nick Foti: http://nfoti.github.io + +.. _Guillaume Dumas: http://www.extrospection.eu + +.. _Chris Mullins: http://crmullins.com + +.. _Phillip Alday: https://palday.bitbucket.io + +.. _Andreas Hojlund: https://github.com/ahoejlund + +.. _Johannes Niediek: https://github.com/jniediek + +.. _Sheraz Khan: https://github.com/SherazKhan + +.. _Antti Rantala: https://github.com/Odingod + +.. _Keith Doelling: http://science.keithdoelling.com + +.. _Paul Pasler: https://github.com/ppasler + +.. _Niklas Wilming: https://github.com/nwilming + +.. _Annalisa Pascarella: http://www.iac.rm.cnr.it/~pasca/ + +.. _Luke Bloy: https://scholar.google.com/citations?hl=en&user=Ad_slYcAAAAJ&view_op=list_works&sortby=pubdate + +.. _Leonardo Barbosa: https://github.com/noreun + +.. _Erkka Heinila: https://github.com/Teekuningas + +.. _Andrea Brovelli: http://www.int.univ-amu.fr/_BROVELLI-Andrea_?lang=en + +.. _Richard Höchenberger: https://github.com/hoechenberger + +.. _Matt Boggess: https://github.com/mattboggess + +.. _Jean-Baptiste Schiratti: https://github.com/jbschiratti + +.. _Laura Gwilliams: http://lauragwilliams.github.io + +.. _Jesper Duemose Nielsen: https://github.com/jdue + +.. _Mathurin Massias: https://mathurinm.github.io/ + +.. _ramonapariciog: https://github.com/ramonapariciog + +.. _Britta Westner: https://github.com/britta-wstnr + +.. _Lukáš Hejtmánek: https://github.com/hejtmy + +.. _Stefan Repplinger: https://github.com/stfnrpplngr + +.. _Okba Bekhelifi: https://github.com/okbalefthanded + +.. _Nicolas Barascud: https://github.com/nbara + +.. _Alejandro Weinstein: http://ocam.cl + +.. _Emily Stephen: http://github.com/emilyps14 + +.. _Nathalie Gayraud: https://github.com/ngayraud + +.. _Anne-Sophie Dubarry: https://github.com/annesodub + +.. _Stefan Appelhoff: http://stefanappelhoff.com + +.. _Tommy Clausner: https://github.com/TommyClausner + +.. _Pierre Ablin: https://pierreablin.com + +.. _Oleh Kozynets: https://github.com/OlehKSS + +.. _Susanna Aro: https://www.linkedin.com/in/susanna-aro + +.. _Joan Massich: https://github.com/massich + +.. _Henrich Kolkhorst: https://github.com/hekolk + +.. _Steven Bethard: https://github.com/bethard + +.. _Thomas Hartmann: https://github.com/thht + +.. _Steven Gutstein: http://robust.cs.utep.edu/~gutstein + +.. _Peter Molfese: https://github.com/pmolfese + +.. _Dirk Gütlin: https://github.com/DiGyt + +.. _Jasper van den Bosch: https://github.com/ilogue + +.. _Ezequiel Mikulan: https://github.com/ezemikulan + +.. _Rasmus Zetter: https://people.aalto.fi/rasmus.zetter + +.. _Marcin Koculak: https://github.com/mkoculak + +.. _David Sabbagh: https://github.com/DavidSabbagh + +.. _Hubert Banville: https://github.com/hubertjb + +.. _buildqa: https://github.com/buildqa + +.. _jeythekey: https://github.com/jeythekey + +.. _Sara Sommariva: http://www.dima.unige.it/~sommariva/ + +.. _Cristóbal Moënne-Loccoz: https://github.com/cmmoenne + +.. _David Haslacher: https://github.com/davidhaslacher + +.. _Larry Eisenman: https://github.com/lneisenman + +.. _Stanislas Chambon: https://github.com/Slasnista + +.. _Jeff Hanna: https://github.com/jshanna100 + +.. _kalenkovich: https://github.com/kalenkovich + +.. _Antoine Gauthier: https://github.com/Okamille + +.. _Samuel Deslauriers-Gauthier: https://github.com/sdeslauriers + +.. _Sebastian Castano: https://github.com/jscastanoc + +.. _Guillaume Favelier: https://github.com/GuillaumeFavelier + +.. _Katarina Slama: https://katarinaslama.github.io + +.. _Bruno Nicenboim: http://nicenboim.org + +.. _Ivana Kojcic: https://github.com/ikojcic + +.. _Nikolas Chalas: https://github.com/Nichalas + +.. _Quentin Bertrand: https://github.com/QB3 + +.. _Alexander Kovrig: https://github.com/OpenSatori + +.. _Kostiantyn Maksymenko: https://github.com/makkostya + +.. _Thomas Radman: https://github.com/tradman + +.. _Paul Roujansky: https://github.com/paulroujansky + +.. _Theodore Papadopoulo: https://github.com/papadop + +.. _Milan Rybář: http://milanrybar.cz + +.. _Joshua Bear: https://github.com/joshbear + +.. _Eberhard Eich: https://github.com/ebeich + +.. _Abram Hindle: http://softwareprocess.es + +.. _Fahimeh Mamashli: https://github.com/fmamashli + +.. _Adonay Nunes: https://github.com/AdoNunes diff -Nru python-mne-0.18.1+dfsg/doc/conf.py python-mne-0.19.1+dfsg/doc/conf.py --- python-mne-0.18.1+dfsg/doc/conf.py 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/conf.py 2019-10-25 14:42:45.000000000 +0000 @@ -60,11 +60,13 @@ 'sphinx.ext.linkcode', 'sphinx.ext.mathjax', 'sphinx.ext.todo', + 'sphinx.ext.graphviz', + 'numpydoc', 'sphinx_gallery.gen_gallery', 'sphinx_fontawesome', - 'numpydoc', 'gen_commands', 'sphinx_bootstrap_theme', + 'sphinx_bootstrap_divs', ] linkcheck_ignore = [ @@ -82,6 +84,11 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_includes'] + # The suffix of source filenames. source_suffix = '.rst' @@ -169,14 +176,15 @@ 'navbar_class': "navbar", 'bootstrap_version': "3", # default 'navbar_links': [ - ("Install", "getting_started"), - ("Documentation", "documentation"), - ("API", "python_reference"), - ("Glossary", "glossary"), + ("Install", "install/index"), + ("Overview", "overview/index"), + ("Tutorials", "auto_tutorials/index"), ("Examples", "auto_examples/index"), - ("Contribute", "contributing"), + ("Glossary", "glossary"), + ("API", "python_reference"), + ("Contribute", "install/contributing"), ], - } +} # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -202,7 +210,12 @@ # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. -#html_extra_path = [] +html_extra_path = [ + 'contributing.html', + 'documentation.html', + 'getting_started.html', + 'install_mne_python.html', +] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -294,10 +307,11 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), - 'numpy': ('https://www.numpy.org/devdocs', None), + 'numpy': ('https://numpy.org/devdocs', None), 'scipy': ('https://scipy.github.io/devdocs', None), 'matplotlib': ('https://matplotlib.org', None), 'sklearn': ('https://scikit-learn.org/stable', None), + 'numba': ('https://numba.pydata.org/numba-doc/latest', None), 'joblib': ('https://joblib.readthedocs.io/en/latest', None), 'mayavi': ('http://docs.enthought.com/mayavi/mayavi', None), 'nibabel': ('https://nipy.org/nibabel', None), @@ -305,8 +319,12 @@ 'surfer': ('https://pysurfer.github.io/', None), 'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None), 'statsmodels': ('http://www.statsmodels.org/stable/', None), - 'dipy': ('http://nipy.org/dipy', None), - 'mne_realtime': ('https://mne-tools.github.io/mne-realtime', None), + # There are some problems with dipy's redirect: + # https://github.com/nipy/dipy/issues/1955 + 'dipy': ('https://dipy.org/documentation/latest', + 'https://dipy.org/documentation/1.0.0./objects.inv/'), + 'mne_realtime': ('https://mne.tools/mne-realtime', None), + 'picard': ('https://pierreablin.github.io/picard/', None), } ############################################################################## @@ -314,19 +332,67 @@ examples_dirs = ['../examples', '../tutorials'] gallery_dirs = ['auto_examples', 'auto_tutorials'] +os.environ['_MNE_BUILDING_DOC'] = 'true' +scrapers = ('matplotlib',) try: mlab = mne.utils._import_mlab() # Do not pop up any mayavi windows while running the # examples. These are very annoying since they steal the focus. mlab.options.offscreen = True - scrapers = ('matplotlib', 'mayavi') + # hack to initialize the Mayavi Engine + mlab.test_plot3d() + mlab.close() +except Exception: + pass +else: + scrapers += ('mayavi',) +try: + with warnings.catch_warnings(): + warnings.filterwarnings("ignore", category=DeprecationWarning) + import pyvista + pyvista.OFF_SCREEN = True except Exception: - scrapers = ('matplotlib',) + pass else: - # Let's do the same thing we do in tests: reraise traits exceptions + scrapers += ('pyvista',) +if any(x in scrapers for x in ('pyvista', 'mayavi')): from traits.api import push_exception_handler push_exception_handler(reraise_exceptions=True) + report_scraper = mne.report._ReportScraper() + scrapers += (report_scraper,) +else: + report_scraper = None + + +def append_attr_meth_examples(app, what, name, obj, options, lines): + """Append SG examples backreferences to method and attr docstrings.""" + # NumpyDoc nicely embeds method and attribute docstrings for us, but it + # does not respect the autodoc templates that would otherwise insert + # the .. include:: lines, so we need to do it. + # Eventually this could perhaps live in SG. + if what in ('attribute', 'method'): + size = os.path.getsize(op.join( + op.dirname(__file__), 'generated', '%s.examples' % (name,))) + if size > 0: + lines += """ +.. rubric:: Examples using ``{0}``: + +.. include:: {1}.examples + :start-line: 5 + +.. raw:: html + +
+""".format(name.split('.')[-1], name).split('\n') + + +def setup(app): + """Set up the Sphinx app.""" + app.connect('autodoc-process-docstring', append_attr_meth_examples) + if report_scraper is not None: + report_scraper.app = app + app.connect('build-finished', report_scraper.copyfiles) class Resetter(object): @@ -356,6 +422,8 @@ # restrict warnings.filterwarnings('error') # allow these, but show them + warnings.filterwarnings('always', '.*non-standard config type: "foo".*') + warnings.filterwarnings('always', '.*config type: "MNEE_USE_CUUDAA".*') warnings.filterwarnings('always', '.*cannot make axes width small.*') warnings.filterwarnings('always', '.*Axes that are not compatible.*') warnings.filterwarnings('always', '.*FastICA did not converge.*') @@ -380,6 +448,7 @@ "DocumenterBridge requires a state object", # sphinx dev "'U' mode is deprecated", # sphinx io r"joblib is deprecated in 0\.21", # nilearn + 'The usage of `cmp` is deprecated and will', # sklearn/pytest ): warnings.filterwarnings( # deal with other modules having bad imports 'ignore', message=".*%s.*" % key, category=DeprecationWarning) @@ -416,6 +485,7 @@ '../examples/realtime/', '../examples/datasets/', '../tutorials/intro/', + '../tutorials/io/', '../tutorials/raw/', '../tutorials/preprocessing/', '../tutorials/epochs/', @@ -435,6 +505,7 @@ 'plot_gallery': 'True', # Avoid annoying Unicode/bool default warning 'download_section_examples': False, 'thumbnail_size': (160, 112), + 'remove_config_comments': True, 'min_reported_time': 1., 'abort_on_example_error': False, 'reset_modules': ('matplotlib', Resetter()), # called w/each script @@ -442,6 +513,7 @@ 'show_memory': True, 'line_numbers': False, # XXX currently (0.3.dev0) messes with style 'within_subsection_order': FileNameSortKey, + 'capture_repr': (), 'junit': op.join('..', 'test-results', 'sphinx-gallery', 'junit.xml'), } @@ -451,7 +523,7 @@ # XXX This hack defines what extra methods numpydoc will document docscrape.ClassDoc.extra_public_methods = mne.utils._doc_special_members numpydoc_class_members_toctree = False -numpydoc_attributes_as_param_list = False +numpydoc_attributes_as_param_list = True numpydoc_xref_param_type = True numpydoc_xref_aliases = { 'Popen': 'python:subprocess.Popen', @@ -463,6 +535,7 @@ 'Axes': 'matplotlib.axes.Axes', 'Figure': 'matplotlib.figure.Figure', 'Axes3D': 'mpl_toolkits.mplot3d.axes3d.Axes3D', + 'ColorbarBase': 'matplotlib.colorbar.ColorbarBase', # Mayavi 'mayavi.mlab.Figure': 'mayavi.core.api.Scene', 'mlab.Figure': 'mayavi.core.api.Scene', @@ -473,9 +546,11 @@ # nibabel 'Nifti1Image': 'nibabel.nifti1.Nifti1Image', 'Nifti2Image': 'nibabel.nifti2.Nifti2Image', + 'SpatialImage': 'nibabel.spatialimages.SpatialImage', # MNE 'Label': 'mne.Label', 'Forward': 'mne.Forward', 'Evoked': 'mne.Evoked', 'Info': 'mne.Info', 'SourceSpaces': 'mne.SourceSpaces', + 'SourceMorph': 'mne.SourceMorph', 'Epochs': 'mne.Epochs', 'Layout': 'mne.channels.Layout', 'EvokedArray': 'mne.EvokedArray', 'BiHemiLabel': 'mne.BiHemiLabel', 'AverageTFR': 'mne.time_frequency.AverageTFR', @@ -493,7 +568,6 @@ 'Dipole': 'mne.Dipole', 'DipoleFixed': 'mne.DipoleFixed', 'InverseOperator': 'mne.minimum_norm.InverseOperator', 'CrossSpectralDensity': 'mne.time_frequency.CrossSpectralDensity', - 'RtEpochs': 'mne.realtime.RtEpochs', 'SourceMorph': 'mne.SourceMorph', 'Xdawn': 'mne.preprocessing.Xdawn', 'Report': 'mne.Report', 'Forward': 'mne.Forward', @@ -507,6 +581,7 @@ 'FilterEstimator': 'mne.decoding.FilterEstimator', 'EMS': 'mne.decoding.EMS', 'CSP': 'mne.decoding.CSP', 'Beamformer': 'mne.beamformer.Beamformer', + 'Transform': 'mne.transforms.Transform', } numpydoc_xref_ignore = { # words @@ -524,9 +599,10 @@ 'n_splits', 'n_scores', 'n_outputs', 'n_trials', 'n_estimators', 'n_tasks', 'nd_features', 'n_classes', 'n_targets', 'n_slices', 'n_hpi', 'n_fids', 'n_elp', 'n_pts', 'n_tris', 'n_nodes', 'n_nonzero', 'n_events_out', + 'n_segments', # Undocumented (on purpose) 'RawKIT', 'RawEximia', 'RawEGI', 'RawEEGLAB', 'RawEDF', 'RawCTF', 'RawBTi', - 'RawBrainVision', + 'RawBrainVision', 'RawCurry', # sklearn subclasses 'mapping', 'to', 'any', # unlinkable diff -Nru python-mne-0.18.1+dfsg/doc/conftest.py python-mne-0.19.1+dfsg/doc/conftest.py --- python-mne-0.18.1+dfsg/doc/conftest.py 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/conftest.py 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1 @@ +from mne.conftest import * diff -Nru python-mne-0.18.1+dfsg/doc/contributing.html python-mne-0.19.1+dfsg/doc/contributing.html --- python-mne-0.18.1+dfsg/doc/contributing.html 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/contributing.html 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,9 @@ + + + + + + +

Please follow this link.

+ + diff -Nru python-mne-0.18.1+dfsg/doc/contributing.rst python-mne-0.19.1+dfsg/doc/contributing.rst --- python-mne-0.18.1+dfsg/doc/contributing.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/contributing.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,841 +0,0 @@ -.. contents:: Page contents - :local: - :depth: 2 - -.. _contributing: - -Contributing to MNE-Python -========================== - -.. NOTE: this first section (up until "overview of contribution process") is - basically a copy/paste of CONTRIBUTING.rst from the repository root, with - one sentence deleted to avoid self-referential linking. Changes made here - should be mirrored there, and vice-versa. - -MNE-Python is maintained by a community of scientists and research labs, and -accepts contributions in the form of bug reports, fixes, feature additions, and -documentation improvements (even just typo corrections). The best way to start -contributing is by `opening an issue`_ on our GitHub page to tell us about -errors you are encountering or to discuss your ideas for changes. For general -troubleshooting, you can also write to the `MNE mailing list`_ or chat with -developers on the `MNE gitter channel`_. - -Changes are typically made by `forking`_ the MNE-Python repository, making -changes to your fork (usually by `cloning`_ it to your personal computer, -making the changes, and then `pushing`_ the local changes up to your fork), and -finally creating a `pull request`_ to incorporate your changes back into the -shared "upstream" version of the codebase. - -Users and contributors to MNE-Python are expected to follow our `code of -conduct`_. - -.. _`opening an issue`: https://github.com/mne-tools/mne-python/issues/new/choose -.. _`MNE mailing list`: http://mail.nmr.mgh.harvard.edu/mailman/listinfo/mne_analysis -.. _`MNE gitter channel`: https://gitter.im/mne-tools/mne-python - -.. _`forking`: https://help.github.com/en/articles/fork-a-repo -.. _`cloning`: https://help.github.com/en/articles/cloning-a-repository -.. _`pushing`: https://help.github.com/en/articles/pushing-to-a-remote -.. _`pull request`: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork - -.. _`code of conduct`: https://github.com/mne-tools/mne-python/blob/master/CODE_OF_CONDUCT.md - - -Overview of contribution process -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In general you'll be working with three different copies of the MNE-Python -codebase: the official remote copy at https://github.com/mne-tools/mne-python -(usually called ``upstream``), your remote `fork`_ of the upstream repository -(similar URL, but with your username in place of ``mne-tools``, and usually -called ``origin``), and the local copy of the codebase on your computer. The -typical contribution process is to: - -1. synchronize your local copy with ``upstream`` - -2. make changes to your local copy - -3. `push`_ your changes to ``origin`` (your remote fork of the upstream) - -4. submit a `pull request`_ from your fork into ``upstream`` - -The sections :ref:`basic-git` and :ref:`github-workflow` (below) describe this -process in more detail. - - -Setting up your local environment for MNE-Python development -============================================================ - -Configuring git -^^^^^^^^^^^^^^^ - -.. sidebar:: Git GUI alternative - - `GitHub desktop`_ is a GUI alternative to command line git that some users - appreciate; it is available for |windows| Windows and |apple| MacOS. - -To get set up for contributing, make sure you have git installed on your local -computer: - -- On Linux, the command ``sudo apt install git`` is usually sufficient; see the - `official Linux instructions`_ for more options. - -- On MacOS, download `the .dmg installer`_; Atlassian also provides `more - detailed instructions and alternatives`_ such as using MacPorts or Homebrew. - -- On Windows, we recommend `git Bash`_ rather than the `official Windows - version of git`_, because git Bash provides its own shell that includes many - Linux-equivalent command line programs that are useful for development. - Windows 10 also offers the `Windows subsystem for Linux`_ that offers similar - functionality to git Bash, but has not been widely tested by MNE-Python - developers yet. - - -Once git is installed, the only absolutely necessary configuration step is -identifying yourself and your contact info: - -.. code-block:: console - - $ git config --global user.name "Your Name" - $ git config --global user.email you@yourdomain.example.com - -Make sure that the same email address is associated with your GitHub account -and with your local git configuration. It is possible to associate multiple -emails with a GitHub account, so if you initially set them up with different -emails, just add the local email to the GitHub account. - -Sooner or later, git is going to ask you what text editor you want it to use -when writing commit messages, so you might as well configure that now too: - -.. code-block:: console - - $ git config --global core.editor emacs # or vim, or nano, or subl, or... - -There are many other ways to customize git's behavior; see `configuring git`_ -for more information. Once you have git installed and configured, and before -creating your local copy of the codebase, go to the `MNE-Python GitHub`_ page -and create a `fork`_ into your GitHub user account. - - -Setting up the development environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. sidebar:: Supported Python environments - - We strongly recommend the `Anaconda`_ or `Miniconda`_ environment managers - for Python. Other setups are possible but are not officially supported by - the MNE-Python development team; see discussion :ref:`here - `. These instructions use ``conda`` where possible; - experts may replace those lines with some combination of ``git`` and - ``pip``. - -These instructions will set up a Python environment that is separated from your -system-level Python and any other managed Python environments on your computer. -This lets you switch between different versions of Python (MNE-Python requires -version 3.5 or higher) and also switch between the stable and development -versions of MNE-Python (so you can, for example, use the same computer to -analyze your data with the stable release, and also work with the latest -development version to fix bugs or add new features). If you've already -followed the :ref:`installation instructions ` for the stable -version of MNE-Python, after this you'll end up with two environments: ``mne`` -(stable version) and ``mnedev`` (development version). - -Once you have a working Python environment, the first step is to `clone`_ the -MNE-Python repository from your remote fork, and also connect the local copy to -the ``upstream`` version of the codebase, so you can stay up-to-date with -changes from other contributors. First, edit these two variables for your -situation: - -.. code-block:: console - - $ INSTALL_LOCATION="/opt" - $ GITHUB_USERNAME="new_mne_contributor" - -Then make a local clone of your remote fork (``origin``): - -.. code-block:: console - - $ cd $INSTALL_LOCATION - $ git clone https://github.com/$GITHUB_USERNAME/mne-python.git - -Finally, set up a link between your local clone and the official repository -(``upstream``): - -.. sidebar:: Remote URLs in git - - Here we use ``git://`` instead of ``https://`` in the URL for the - ``upstream`` remote repository. ``git://`` URLs are read-only, so you can - *pull* changes from ``upstream`` into your local copy (to stay up-to-date - with changes from other contributors) but you cannot *push* changes from - your computer into the ``upstream`` remote. Instead, you must push your - changes to your own remote fork (``origin``) first, and then create a pull - request from your remote into the upstream remote. In :ref:`a later section - ` you'll see a third kind of remote URL for connecting to - GitHub using SSH. - -.. code-block:: console - - $ cd mne-python - $ git remote add upstream git://github.com/mne-tools/mne-python.git - $ git fetch --all - -Next, use the `environment file`_ provided in the root of the MNE-Python -repository to set up your local development environment. This will install all -of the dependencies needed for running MNE-Python. The environment name "mne" -is built-in to the environment file, so we'll override that on the command line -by passing our preferred name ("mnedev") after the ``-n`` flag. See ``conda env -create --help`` for more info. - -.. code-block:: console - - $ conda env create -n mnedev -f environment.yml - $ conda activate mnedev - -The environment file installed the *stable* version of MNE-Python, so next -we'll remove that and replace it with the *development* version (the clone we -just created with git): - -.. code-block:: console - - $ cd $INSTALL_LOCATION/mne-python # make sure we're in the right folder - $ pip uninstall -y mne # or: conda remove --force mne - $ pip install -e . - -The command ``pip install -e .`` installs a python module into the current -environment by creating a link to the source code directory (instead of -copying the code to pip's ``site_packages`` directory, which is what normally -happens). This means that any edits you make to the MNE-Python source code will -be reflected the next time you open a Python interpreter and ``import mne`` -(the ``-e`` flag of ``pip`` stands for an "editable" installation). - -Finally, we'll add a few dependencies that are not needed for running -MNE-Python, but are needed for locally running our test suite or building our -documentation: - -.. code-block:: console - - $ pip install sphinx sphinx-gallery sphinx_bootstrap_theme sphinx_fontawesome memory_profiler - $ conda install sphinx-autobuild doc8 # linter packages for reStructuredText (optional) - -.. TODO: add this if sphinx-mermaid is officially adopted - Our documentation includes diagrams that are built automatically from text - using a tool called `mermaid`_. Originally a javascript tool, there is now - a command-line interface ``mermaid.cli`` as well as a plugin for ``sphinx`` - (our documentation build tool) that allows mermaid blocks in the - documentation to be rendered into diagrams automatically. - . - $ wget -O - "https://dl.yarnpkg.com/debian/pubkey.gpg" | sudo apt-key add - - $ echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list > /dev/null - $ sudo apt update - $ sudo apt install yarn - Once yarn is installed, you can use it to install mermaid - $ cd $INSTALL_LOCATION - $ yarn add mermaid - $ yarn add mermaid.cli - $ pip install sphinxcontrib-mermaid - - -.. _basic-git: - -Basic git commands -^^^^^^^^^^^^^^^^^^ - -Learning to work with git can take a long time, because it is a complex and -powerful tool for managing versions of files across multiple users, each of -whom have multiple copies of the codebase. We've already seen in the setup -commands above a few of the basic git commands useful to an MNE-Python -developer: - -- :samp:`git clone {}` (make a local copy of a repository) - -- :samp:`git remote add {} {}` (connect - a local copy to an additional remote) - -- ``git fetch --all`` (get the current state of connected remote repos) - -Other commands that you will undoubtedly need relate to `branches`_. Branches -represent multiple copies of the codebase *within a local clone or remote -repo*. Branches are typically used to experiment with new features while still -keeping a clean, working copy of the original codebase that you can switch back -to at any time. The default branch of any repo is always called ``master``, and -it is recommended that you reserve the ``master`` branch to be that clean copy -of the working ``upstream`` codebase. Therefore, if you want to add a new -feature, you should first synchronize your local ``master`` branch with the -``upstream`` repository, then create a new branch based off of ``master`` and -`check it out`_ so that any changes you make will exist on that new branch -(instead of on ``master``): - -.. code-block:: console - - $ git checkout master # switch to local master branch - $ git fetch upstream # get the current state of the remote upstream repo - $ git merge upstream/master # synchronize local master branch with remote upstream master branch - $ git checkout -b new-feature-x # create local branch "new-feature-x" and check it out - -.. sidebar:: Alternative - - You can save some typing by using ``git pull upstream/master`` to replace - the ``fetch`` and ``merge`` lines above. - -Now that you're on a new branch, you can fix a bug or add a new feature, add a -test, update the documentation, etc. When you're done, it's time to organize -your changes into a series of `commits`_. Commits are like snapshots of the -repository — actually, more like a description of what has to change to get -from the most recent snapshot to the current snapshot. - -Git knows that people often work on multiple changes in multiple files all at -once, but that ultimately they should separate those changes into sets of -related changes that are grouped together based on common goals (so that it's -easier for their colleagues to understand and review the changes). For example, -you might want to group all the code changes together in one commit, put new -unit tests in another commit, and changes to the documentation in a third -commit. Git makes this easy(ish) with something called the `stage`_ (or -*staging area*). After you've made some changes to the codebase, you'll have -what git calls "unstaged changes", which will show up with the `status`_ -command: - -.. code-block:: console - - $ git status # see what state the local copy of the codebase is in - -Those unstaged changes can be `added`_ to the stage one by one, by either -adding a whole file's worth of changes, or by adding only certain lines -interactively: - -.. code-block:: console - - $ git add mne/some_file.py # add all the changes you made to this file - $ git add mne/some_new_file.py # add a completely new file in its entirety - $ # enter interactive staging mode, to add only portions of a file: - $ git add -p mne/viz/some_other_file.py - -Once you've collected all the related changes together on the stage, the ``git -status`` command will now refer to them as "changes staged for commit". You can -commit them to the current branch with the `commit`_ command. If you just type -``git commit`` by itself, git will open the text editor you configured it to -use so that you can write a *commit message* — a short description of the -changes you've grouped together in this commit. You can bypass the text editor -by passing a commit message on the command line with the ``-m`` flag. For -example, if your first commit adds a new feature, your commit message might be: - -.. code-block:: console - - $ git commit -m 'ENH: adds feature X to the Epochs class' - -Once you've made the commit, the stage is now empty, and you can repeat the -cycle, adding the unit tests and documentation changes: - -.. code-block:: console - - $ git add mne/tests/some_testing_file.py - $ git commit -m 'add test of new feature X of the Epochs class' - $ git add -p mne/some_file.py mne/viz/some_other_file.py - $ git commit -m 'DOC: update Epochs and BaseEpochs docstrings' - $ git add tutorials/new_tutorial_file.py - $ git commit -m 'DOC: adds new tutorial about feature X' - -When you're done, it's time to run the test suite to make sure your changes -haven't broken any existing functionality, and to make sure your new test -covers the lines of code you've added (see :ref:`run-tests` and -:ref:`build-docs`, below). Once everything looks good, it's time to push your -changes to your fork: - -.. code-block:: console - - $ # push local changes to remote branch origin/new-feature-x - $ # (this will create the remote branch if it doesn't already exist) - $ git push origin new-feature-x - -Finally, go to the `MNE-Python GitHub`_ page, click on the pull requests tab, -click the "new pull request" button, and choose "compare across forks" to -select your new branch (``new-feature-x``) as the "head repository". See the -GitHub help page on `creating a PR from a fork`_ for more information about -opening pull requests. - -If any of the tests failed before you pushed your changes, try to fix them, -then add and commit the changes that fixed the tests, and push to your fork. If -you're stuck and can't figure out how to fix the tests, go ahead and push your -commits to your fork anyway and open a pull request (as described above), then -in the pull request you should describe how the tests are failing and ask for -advice about how to fix them. - -To learn more about git, check out the `GitHub help`_ website, the `GitHub -Learning Lab`_ tutorial series, and the `pro git book`_. - - -.. _github-ssh: - -Connecting to GitHub with SSH (optional) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -One easy way to speed up development is to reduce the number of times you have -to type your password. SSH (secure shell) allows authentication with pre-shared -key pairs. The private half of your key pair is kept secret on your computer, -while the public half of your key pair is added to your GitHub account; when -you connect to GitHub from your computer, the local git client checks the -remote (public) key against your local (private) key, and grants access your -account only if the keys fit. GitHub has `several help pages`_ that guide you -through the process. - -Once you have set up GitHub to use SSH authentication, you should change the -addresses of your MNE-Python GitHub remotes, from ``https://`` addresses to -``git@`` addresses, so that git knows to connect via SSH instead of HTTPS. For -example: - -.. code-block:: console - - $ git remote -v # show existing remote addresses - $ git remote set-url origin git@github.com:$GITHUB_USERNAME/mne-python.git - $ git remote set-url upstream git@github.com:mne-tools/mne-python.git - - -MNE-Python coding conventions -============================= - -General requirements -^^^^^^^^^^^^^^^^^^^^ - -All new functionality must have test coverage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For example, a new :class:`mne.Evoked` method in :file:`mne/evoked.py` should -have a corresponding test in :file:`mne/tests/test_evoked.py`. - - -All new functionality must be documented -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This includes thorough docstring descriptions for all public API changes, as -well as how-to examples or longer tutorials for major contributions. Docstrings -for private functions may be more sparse, but should not be omitted. - - -Avoid API changes when possible -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Changes to the public API (e.g., class/function/method names and signatures) -should not be made lightly, as they can break existing user scripts. Changes to -the API require a deprecation cycle (with warnings) so that users have time to -adapt their code before API changes become default behavior. See -:class:`mne.utils.deprecated` for usage. Bug fixes (when something isn't doing -what it says it will do) do not require a deprecation cycle. - -Note that any new API elements should be added to the master reference; -classes, functions, methods, and attributes cannot be cross-referenced unless -they are included in the :doc:`python_reference` -(:file:`doc/python_reference.rst`). - - -Describe your changes in the changelog -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Include in your changeset a brief description of the change in the -:doc:`changelog ` (:file:`doc/whats_new.rst`; this can be skipped -for very minor changes like correcting typos in the documentation). Note that -there are sections of the changelog for each release, and separate subsections -for bugfixes, new features, and changes to the public API. It is usually best -to wait to add a line to the changelog until your PR is finalized, to avoid -merge conflicts (since the changelog is updated with almost every PR). - - -Test locally before opening pull requests (PRs) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -MNE-Python uses `continuous integration`_ (CI) to ensure code quality and -test across multiple installation targets. However, the CIs are often slower -than testing locally, especially when other contributors also have open PRs -(which is basically always the case). Therefore, do not rely on the CIs to -catch bugs and style errors for you; :ref:`run the tests locally ` -instead before opening a new PR and before each time you push additional -changes to an already-open PR. - - -Make tests fast and thorough -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Whenever possible, use the testing dataset rather than one of the sample -datasets when writing tests; it includes small versions of most MNE-Python -objects (e.g., :class:`~mne.io.Raw` objects with short durations and few -channels). You can also check which lines are missed by the tests, then modify -existing tests (or write new ones) to target the missed lines. Here's an -example that reports which lines within ``mne.viz`` are missed when running -``test_evoked.py`` and ``test_topo.py``: - -.. code-block:: console - - $ pytest --cov=mne.viz --cov-report=term-missing mne/viz/tests/test_evoked.py mne/viz/tests/test_topo.py - -You can also use ``pytest --durations=5`` to ensure new or modified tests will -not slow down the test suite too much. - - -Code style -^^^^^^^^^^ - -Adhere to standard Python style guidelines -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All contributions to MNE-Python are checked against style guidelines described -in `PEP 8`_. We also check for common coding errors (such as variables that are -defined but never used). We allow very few exceptions to these guidelines, and -use tools such as pep8_, pyflakes_, and flake8_ to check code style -automatically. From the :file:`mne-python` root directory, you can check for -style violations by running: - -.. code-block:: console - - $ make flake - -in the shell. Several text editors or IDEs also have Python style checking, -which can highlight style errors while you code (and train you to make those -errors less frequently). This functionality is built-in to the Spyder_ IDE, but -most editors have plug-ins that provide similar functionality. Search for -:samp:`python linter ` to learn more. - - -Use consistent variable naming -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Classes should be named using ``CamelCase``. Functions and instances/variables -should use ``snake_case`` (``n_samples`` rather than ``nsamples``). Avoid -single-character variable names, unless inside a :term:`comprehension ` or :ref:`generator `. - - -Follow NumPy style for docstrings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In most cases imitating existing docstrings will be sufficient, but consult the -`Numpy docstring style guidelines`_ for more complicated formatting such as -embedding example code, citing references, or including rendered mathematics. -Private function/method docstrings may be brief for simple functions/methods, -but complete docstrings are appropriate when private functions/methods are -relatively complex. To run some basic tests on documentation, you can use: - -.. code-block:: console - - $ pytest mne/tests/test_docstring_parameters.py - $ make docstyle - - -Cross-reference everywhere -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Both the docstrings and dedicated documentation pages (tutorials, how-to -examples, discussions, and glossary) should include cross-references to any -mentioned module, class, function, method, attribute, or documentation page. -There are sphinx directives for all of these (``:mod:``, ``:class:``, -``:func:``, ``:meth:``, ``:attr:``, ``:doc:``) as well as a generic -cross-reference directive (``:ref:``) for linking to specific sections of a -documentation page. MNE-Python also uses Intersphinx_, so you can (and should) -cross-reference to Python built-in classes and functions as well as API -elements in :mod:`NumPy `, :mod:`SciPy `, etc. See the Sphinx -configuration file (:file:`doc/conf.py`) for the list of Intersphinx projects -we link to. - -.. warning:: - - Some API elements have multiple exposure points (for example, - ``mne.set_config`` and ``mne.utils.set_config``). For cross-references to - work, they must match an entry in :file:`doc/python_reference.rst` (thus - ``:func:`mne.set_config``` will work but ``:func:`mne.utils.set_config``` - will not). - - -Other style guidance -~~~~~~~~~~~~~~~~~~~~ - -- Use single quotes whenever possible. - -- Prefer :ref:`generators ` or - :term:`comprehensions ` over :func:`filter`, :func:`map` - and other functional idioms. - -- Use explicit functional constructors for builtin containers to improve - readability (e.g., :ref:`list() `, :ref:`dict() `, - :ref:`set() `). - -- Avoid nested functions or class methods if possible — use private functions - instead. - -- Avoid ``*args`` and ``**kwargs`` in function/method signatures. - - -Code organization -^^^^^^^^^^^^^^^^^ - -Importing -~~~~~~~~~ - -Import modules in this order: - -1. Python built-in (``os``, ``copy``, ``functools``, etc) -2. standard scientific (``numpy as np``, ``scipy.signal``, etc) -3. others -4. MNE-Python imports (e.g., ``from .pick import pick_types``) - -When importing from other parts of MNE-Python, use relative imports in the main -codebase and absolute imports in tests, tutorials, and how-to examples. Imports -for ``matplotlib`` and optional modules (``sklearn``, ``pandas``, etc.) should -be nested (i.e., within a function or method, not at the top of a file). - - -Return types -~~~~~~~~~~~~ - -Methods should modify inplace and return ``self``, functions should return -copies (where applicable). Docstrings should always give an informative name -for the return value, even if the function or method's return value is never -stored under that name in the code. - - -Vizualization -~~~~~~~~~~~~~ - -Visualization capabilities should be made available in both function and method -forms. Add public visualization functions to the :mod:`mne.viz` submodule, and -call those functions from the corresponding object methods. For example, the -method :meth:`mne.Epochs.plot` internally calls the function -:func:`mne.viz.plot_epochs`. - -All visualization functions must accept a boolean ``show`` parameter and -typically return a :class:`matplotlib.figure.Figure` (or a list of -:class:`~matplotlib.figure.Figure` objects). 3D visualization functions return -a :class:`mayavi.core.api.Scene`, :class:`surfer.Brain`, or other return type -as appropriate. - -Visualization functions should default to the colormap ``RdBu_r`` for signed -data with a meaningful middle (zero-point) and ``Reds`` otherwise. This applies -to both visualization functions and tutorials/examples. - - -.. _run_tests: - -Running the test suite -^^^^^^^^^^^^^^^^^^^^^^ - -Running the full test suite is as simple as running - -.. code-block:: console - - $ make test - -.. sidebar:: pytest flags - - The ``-x`` flag exits the pytest run as soon as the first test fails; this - can save some time if you are running an entire file's or module's worth of - tests instead of selecting just a single test as shown here. - - The ``--pdb`` flag will automatically start the python debugger upon test - failure. - -from the ``mne-python`` root folder. Testing the entire module can be quite -slow, however, so to run individual tests while working on a new feature, you -can run, e.g.: - -.. code-block:: console - - $ pytest mne/tests/test_evoked.py:test_io_evoked --verbose - -Or alternatively: - -.. code-block:: console - - $ pytest mne/tests/test_evoked.py -k test_io_evoked --verbose - -Make sure you have the testing dataset, which you can get by running this in -a Python interpreter:: - - >>> mne.datasets.testing.data_path(verbose=True) # doctest: +SKIP - - -.. _build-docs: - -Building the documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Our documentation (including docstrings in code files) is in -reStructuredText_ format and is built using Sphinx_ and `Sphinx-Gallery`_. -The easiest way to ensure that your contributions to the documentation are -properly formatted is to follow the style guidelines on this page, imitate -existing documentation examples, refer to the Sphinx and Sphinx-Gallery -reference materials when unsure how to format your contributions, and build the -docs locally to confirm that everything looks correct before submitting the -changes in a pull request. - -You can build the documentation locally using `GNU Make`_ with -:file:`doc/Makefile`. From within the :file:`doc` directory, you can test -formatting and linking by running: - -.. code-block:: console - - $ make html_dev-noplot - -This will build the documentation *except* it will format (but not execute) the -tutorial and example files. If you have created or modified an example or -tutorial, you should instead run -:samp:`PATTERN={} make html_dev-pattern` to render -all the documentation and additionally execute just your example or tutorial -(so you can make sure it runs successfully and generates the output / figures -you expect). - -After either of these commands completes, ``make show`` will open the -locally-rendered documentation site in your browser. Additional ``make`` -recipes are available; run ``make help`` from the :file:`doc` directory or -consult the `Sphinx-Gallery`_ documentation for additional details. - - -.. _`github-workflow`: - -GitHub workflow -^^^^^^^^^^^^^^^ - -Nearly everyone in the community of MNE-Python contributors and maintainers is -a working scientist, engineer, or student who contributes to MNE-Python in -their spare time. For that reason, a set of best practices have been adopted to -streamline the collaboration and review process. Most of these practices are -common to many open-source software projects, so learning to follow them while -working on MNE-Python will bear fruit when you contribute to other projects -down the road. Here are the guidelines: - -- Search the `MNE-Python issues page`_ (both open and closed issues) in case - someone else has already started work on the same bugfix or feature. If you - don't find anything, `open a new issue`_ to discuss changes with maintainers - before starting work on your proposed changes. - -- Implement only one new feature or bugfix per pull request (PR). Occasionally - it may make sense to fix a few related bugs at once, but this makes PRs - harder to review and test, so check with MNE-Python maintainers first before - doing this. Avoid purely cosmetic changes to the code; they make PRs harder - to review. - -- It is usually better to make PRs *from* branches other than your master - branch, so that you can use your master branch to easily get back to a - working state of the code if needed (e.g., if you're working on multiple - changes at once, or need to pull in recent changes from someone else to get - your new feature to work properly). - -- In most cases you should make PRs *into* the upstream's master branch, unless - you are specifically asked by a maintainer to PR into another branch (e.g., - for backports or maintenance bugfixes to the current stable version). - -- Don't forget to include in your PR a brief description of the change in the - :doc:`changelog ` (:file:`doc/whats_new.rst`). - -- Our community uses the following commit tags and conventions: - - - Work-in-progress PRs should be created as `draft PRs`_ and the PR title - should begin with ``WIP``. - - - When you believe a PR is ready to be reviewed and merged, `convert it - from a draft PR to a normal PR`_, change its title to begin with ``MRG``, - and add a comment to the PR asking for reviews (changing the title does not - automatically notify maintainers). - - - PRs that only affect documentation should additionally be labelled - ``DOC``, bugfixes should be labelled ``FIX``, and new features should be - labelled ``ENH`` (for "enhancement"). ``STY`` is used for style changes - (i.e., improving docstring consistency or formatting without changing its - content). - - - the following commit tags are used to interact with our - `continuous integration`_ (CI) providers. Use them judiciously; *do not - skip tests simply because they are failing*: - - - ``[skip circle]`` Skip `circle`_, which tests successful building of our - documentation. - - - ``[skip travis]`` Skip `travis`_, which tests installation and execution - on Linux and macOS systems. - - - ``[skip azp]`` Skip `azure`_ which tests installation and execution on - Windows systems. - - - ``[ci skip]`` is an alias for ``[skip travis][skip azp][skip circle]``. - Notice that ``[skip ci]`` is not a valid tag. - - - ``[circle full]`` triggers a "full" documentation build, i.e., all code - in tutorials and how-to examples will be *executed* (instead of just - nicely formatted) and the resulting output and figures will be rendered - as part of the tutorial/example. - -`This sample pull request`_ exemplifies many of the conventions listed above: -it addresses only one problem; it started with an issue to discuss the problem -and some possible solutions; it is a PR from the user's non-master branch into -the upstream master branch; it separates different kinds of changes into -separate commits and uses labels like ``DOC``, ``FIX``, and ``STY`` to make it -easier for maintainers to review the changeset; etc. If you are new to GitHub -it can serve as a useful example of what to expect from the PR review process. - -.. MNE - -.. _MNE-Python GitHub: https://github.com/mne-tools/mne-python -.. _MNE-Python issues page: https://github.com/mne-tools/mne-python/issues -.. _open a new issue: https://github.com/mne-tools/mne-python/issues/new/choose -.. _environment file: https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml -.. _This sample pull request: https://github.com/mne-tools/mne-python/pull/6230 - -.. git installation - -.. _the .dmg installer: https://git-scm.com/download/mac -.. _official Windows version of git: https://git-scm.com/download/win -.. _official Linux instructions: https://git-scm.com/download/linux -.. _more detailed instructions and alternatives: https://www.atlassian.com/git/tutorials/install-git -.. _Windows subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/about -.. _git bash: https://gitforwindows.org/ -.. _GitHub desktop: https://desktop.github.com/ - -.. github help pages - -.. _GitHub Help: https://help.github.com -.. _GitHub learning lab: https://lab.github.com/ -.. _fork: https://help.github.com/en/articles/fork-a-repo -.. _clone: https://help.github.com/en/articles/cloning-a-repository -.. _push: https://help.github.com/en/articles/pushing-to-a-remote -.. _branches: https://help.github.com/en/articles/about-branches -.. _several help pages: https://help.github.com/en/articles/connecting-to-github-with-ssh -.. _draft PRs: https://help.github.com/en/articles/about-pull-requests#draft-pull-requests -.. _convert it from a draft PR to a normal PR: https://help.github.com/en/articles/changing-the-stage-of-a-pull-request -.. _pull request: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork -.. _creating a PR from a fork: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork - -.. git docs - -.. _check it out: https://git-scm.com/docs/git-checkout -.. _added: https://git-scm.com/docs/git-add -.. _commits: https://git-scm.com/docs/git-commit -.. _commit: https://git-scm.com/docs/git-commit -.. _status: https://git-scm.com/docs/git-status - -.. git book - -.. _pro git book: https://git-scm.com/book/ -.. _stage: https://git-scm.com/book/en/v2/Git-Tools-Interactive-Staging -.. _configuring git: https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration - -.. sphinx - -.. _sphinx: http://www.sphinx-doc.org -.. _sphinx-gallery: https://sphinx-gallery.github.io -.. _reStructuredText: http://sphinx-doc.org/rest.html -.. _intersphinx: http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html - -.. linting - -.. _NumPy docstring style guidelines: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt -.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ -.. _pep8: https://pypi.org/project/pep8 -.. _pyflakes: https://pypi.org/project/pyflakes -.. _Flake8: http://flake8.pycqa.org/ - -.. misc - -.. _anaconda: https://www.anaconda.com/distribution/ -.. _miniconda: https://conda.io/en/latest/miniconda.html -.. _Spyder: https://www.spyder-ide.org/ -.. _GNU Make: https://www.gnu.org/software/make/ -.. _continuous integration: https://en.wikipedia.org/wiki/Continuous_integration -.. _matplotlib: https://matplotlib.org/ -.. _travis: https://travis-ci.org/mne-tools/mne-python/branches -.. _azure: https://dev.azure.com/mne-tools/mne-python/_build/latest?definitionId=1&branchName=master -.. _circle: https://circleci.com/gh/mne-tools/mne-python diff -Nru python-mne-0.18.1+dfsg/doc/documentation.html python-mne-0.19.1+dfsg/doc/documentation.html --- python-mne-0.18.1+dfsg/doc/documentation.html 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/documentation.html 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,9 @@ + + + + + + +

Please follow this link.

+ + diff -Nru python-mne-0.18.1+dfsg/doc/documentation.rst python-mne-0.19.1+dfsg/doc/documentation.rst --- python-mne-0.18.1+dfsg/doc/documentation.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/documentation.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,728 +0,0 @@ -:orphan: - -.. _documentation: - -Documentation -============= - -.. raw:: html - - - - - -This is where you can learn about all the things you can do with MNE. It -contains **background information** and **tutorials** for taking a deep-dive -into the techniques that MNE-python covers. You'll find practical information -on how to use these methods with your data, and in many cases some high-level -concepts underlying these methods. - -There are also **examples**, which contain a short use-case to highlight -MNE-functionality and provide inspiration for the many things you can do with -this package. You can also find a gallery of these examples in the -:ref:`examples gallery `. - -**See the links below for an introduction to MNE-python, or click one of the sections on this page to see more.** - -.. raw:: html - -
-
-
-

- Introduction to MNE and Python -

-
- -
-
- -**Getting started** - -.. toctree:: - :maxdepth: 1 - - getting_started - advanced_setup - -**MNE basics** - -.. toctree:: - :maxdepth: 1 - - tutorials/philosophy.rst - manual/cookbook.rst - whats_new.rst - python_reference.rst - glossary.rst - auto_examples/index.rst - generated/commands.rst - auto_tutorials/misc/plot_configuration.rst - cited.rst - faq.rst - -**More help** - -- :ref:`Cite MNE ` -- `Mailing list `_ for analysis talk -- `GitHub issues `_ for - requests and bug reports -- `Gitter `_ to chat with devs - -.. raw:: html - -
-
-
- - -
-
-

- Data structures and containers -

-
- -
-
- -.. toctree:: - :maxdepth: 1 - - auto_tutorials/raw/plot_object_raw.rst - auto_tutorials/epochs/plot_object_epochs.rst - auto_tutorials/evoked/plot_object_evoked.rst - auto_tutorials/source-modeling/plot_object_source_estimate.rst - auto_tutorials/intro/plot_info.rst - auto_tutorials/intro/plot_object_annotations.rst - - -.. raw:: html - -
-
-
- - -
-
-

- Data I/O and datasets -

-
-
-
- -**Getting your data into MNE** - -.. toctree:: - :maxdepth: 1 - - manual/io.rst - auto_tutorials/simulation/plot_creating_data_structures.rst - auto_tutorials/epochs/plot_metadata_epochs.rst - auto_tutorials/misc/plot_modifying_data_inplace.rst - auto_tutorials/misc/plot_ecog.rst - manual/memory.rst - manual/migrating.rst - -.. raw:: html - -
- Examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/io/plot_elekta_epochs.rst - auto_examples/io/plot_objects_from_arrays.rst - auto_examples/io/plot_read_and_write_raw_data.rst - auto_examples/io/plot_read_epochs.rst - auto_examples/io/plot_read_events.rst - auto_examples/io/plot_read_evoked.rst - auto_examples/io/plot_read_noise_covariance_matrix.rst - -.. raw:: html - -
- -**Working with public datasets** - -.. toctree:: - :maxdepth: 1 - - manual/datasets_index.rst - auto_tutorials/sample-datasets/plot_brainstorm_auditory.rst - auto_tutorials/sample-datasets/plot_brainstorm_phantom_ctf.rst - auto_tutorials/sample-datasets/plot_brainstorm_phantom_elekta.rst - auto_tutorials/sample-datasets/plot_phantom_4DBTi.rst - auto_tutorials/sample-datasets/plot_sleep.rst - auto_examples/datasets/plot_brainstorm_data.rst - auto_examples/datasets/plot_opm_data.rst - auto_examples/datasets/plot_megsim_data.rst - auto_examples/datasets/plot_megsim_data_single_trial.rst - auto_examples/datasets/spm_faces_dataset.rst - -.. raw:: html - -
-
-
- - -
-
-

- - Preprocessing (filtering, SSP, ICA, Maxwell filtering, ...) -

-
-
-
- -**Background** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/discussions/plot_background_filtering.rst - manual/preprocessing/ssp.rst - manual/preprocessing/ica.rst - manual/preprocessing/maxwell.rst - manual/channel_interpolation.rst - -**Preprocessing your data** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/preprocessing/plot_artifacts_detection.rst - auto_tutorials/preprocessing/plot_artifacts_correction_filtering.rst - auto_tutorials/preprocessing/plot_artifacts_correction_rejection.rst - auto_tutorials/preprocessing/plot_artifacts_correction_ssp.rst - auto_tutorials/preprocessing/plot_artifacts_correction_ica.rst - auto_tutorials/preprocessing/plot_artifacts_correction_maxwell_filtering.rst - -.. raw:: html - -
- Examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/preprocessing/plot_define_target_events.rst - auto_examples/preprocessing/plot_eog_artifact_histogram.rst - auto_examples/preprocessing/plot_find_ecg_artifacts.rst - auto_examples/preprocessing/plot_find_eog_artifacts.rst - auto_examples/preprocessing/plot_head_positions.rst - auto_examples/preprocessing/plot_ica_comparison.rst - auto_examples/preprocessing/plot_interpolate_bad_channels.rst - auto_examples/preprocessing/plot_movement_compensation.rst - auto_examples/preprocessing/plot_rereference_eeg.rst - auto_examples/preprocessing/plot_resample.rst - auto_examples/preprocessing/plot_run_ica.rst - auto_examples/preprocessing/plot_shift_evoked.rst - auto_examples/preprocessing/plot_virtual_evoked.rst - auto_examples/preprocessing/plot_xdawn_denoising.rst - -.. raw:: html - -
- -.. raw:: html - -
-
-
- - -
-
-

- - Visualization -

-
-
-
- -.. toctree:: - :maxdepth: 1 - - auto_tutorials/raw/plot_visualize_raw.rst - auto_tutorials/epochs/plot_visualize_epochs.rst - auto_tutorials/evoked/plot_visualize_evoked.rst - auto_tutorials/source-modeling/plot_visualize_stc.rst - auto_tutorials/evoked/plot_whitened.rst - tutorials/report.rst - -.. raw:: html - -
- Examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/visualization/make_report.rst - auto_examples/visualization/plot_3d_to_2d.rst - auto_examples/visualization/plot_channel_epochs_image.rst - auto_examples/visualization/plot_eeg_on_scalp.rst - auto_examples/visualization/plot_evoked_topomap.rst - auto_examples/visualization/plot_evoked_whitening.rst - auto_examples/visualization/plot_meg_sensors.rst - auto_examples/visualization/plot_parcellation.rst - auto_examples/visualization/plot_sensor_noise_level.rst - auto_examples/visualization/plot_ssp_projs_sensitivity_map.rst - auto_examples/visualization/plot_topo_compare_conditions.rst - auto_examples/visualization/plot_topo_customized.rst - auto_examples/visualization/plot_xhemi.rst - -.. raw:: html - -
-.. raw:: html - -
-
-
- - -
-
-

- - Time- and frequency-domain analyses -

-
-
-
- -**Tutorials** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/intro/plot_introduction.rst - auto_tutorials/intro/plot_epoching_and_averaging.rst - auto_tutorials/evoked/plot_eeg_erp.rst - auto_tutorials/time-freq/plot_sensors_time_frequency.rst - manual/time_frequency.rst - -.. raw:: html - -
- Examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/time_frequency/plot_compute_raw_data_spectrum.rst - auto_examples/time_frequency/plot_compute_source_psd_epochs.rst - auto_examples/time_frequency/plot_source_label_time_frequency.rst - auto_examples/time_frequency/plot_source_power_spectrum.rst - auto_examples/time_frequency/plot_source_space_time_frequency.rst - auto_examples/time_frequency/plot_temporal_whitening.rst - auto_examples/time_frequency/plot_time_frequency_global_field_power.rst - auto_examples/time_frequency/plot_time_frequency_simulated.rst - auto_examples/time_frequency/plot_compute_csd.rst - -.. raw:: html - -
- -.. raw:: html - -
-
-
- - -
-
-

- - Source-level analysis -

-
-
-
- -**Background** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/source-modeling/plot_background_freesurfer.rst - manual/source_localization/forward.rst - manual/source_localization/inverse.rst - manual/source_localization/morph_stc.rst - -**Getting data to source space** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/source-modeling/plot_source_alignment.rst - auto_tutorials/source-modeling/plot_forward.rst - auto_tutorials/source-modeling/plot_compute_covariance.rst - auto_tutorials/source-modeling/plot_eeg_no_mri.rst - auto_tutorials/source-modeling/plot_mne_dspm_source_localization.rst - auto_tutorials/source-modeling/plot_mne_solutions.rst - auto_tutorials/source-modeling/plot_dipole_fit.rst - auto_tutorials/simulation/plot_point_spread.rst - auto_tutorials/source-modeling/plot_dipole_orientations.rst - auto_tutorials/simulation/plot_dics.rst - - -.. raw:: html - -
- Forward examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/forward/plot_decimate_head_surface.rst - auto_examples/forward/plot_forward_sensitivity_maps.rst - auto_examples/forward/plot_left_cerebellum_volume_source.rst - auto_examples/forward/plot_source_space_morphing.rst - -.. raw:: html - -
- -.. raw:: html - -
- Inverse examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/datasets/plot_opm_rest_data.rst - auto_examples/inverse/plot_compute_mne_inverse_epochs_in_label.rst - auto_examples/inverse/plot_compute_mne_inverse_raw_in_label.rst - auto_examples/inverse/plot_compute_mne_inverse_volume.rst - auto_examples/inverse/plot_covariance_whitening_dspm.rst - auto_examples/inverse/plot_custom_inverse_solver.rst - auto_examples/inverse/plot_dics_source_power.rst - auto_examples/inverse/plot_gamma_map_inverse.rst - auto_examples/inverse/plot_label_activation_from_stc.rst - auto_examples/inverse/plot_label_from_stc.rst - auto_examples/inverse/plot_label_source_activations.rst - auto_examples/inverse/plot_lcmv_beamformer.rst - auto_examples/inverse/plot_lcmv_beamformer_volume.rst - auto_examples/inverse/plot_mixed_source_space_inverse.rst - auto_examples/inverse/plot_mixed_norm_inverse.rst - auto_examples/inverse/plot_mne_crosstalk_function.rst - auto_examples/inverse/plot_mne_point_spread_function.rst - auto_examples/inverse/plot_morph_surface_stc.rst - auto_examples/inverse/plot_morph_volume_stc.rst - auto_examples/inverse/plot_rap_music.rst - auto_examples/inverse/plot_read_stc.rst - auto_examples/inverse/plot_read_inverse.rst - auto_examples/inverse/plot_read_source_space.rst - auto_examples/inverse/plot_snr_estimate.rst - auto_examples/inverse/plot_tf_dics.rst - auto_examples/inverse/plot_tf_lcmv.rst - auto_examples/inverse/plot_time_frequency_mixed_norm_inverse.rst - auto_examples/inverse/plot_vector_mne_solution.rst - -.. raw:: html - -
- -.. raw:: html - -
- Simulation examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/simulation/plot_simulate_evoked_data.rst - auto_examples/simulation/plot_simulate_raw_data.rst - auto_examples/simulation/plot_simulated_raw_data_using_subject_anatomy.rst - -.. raw:: html - -
- -.. raw:: html - -
-
-
- - -
-
-

- Statistics -

-
-
-
- - -**Background** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/discussions/plot_background_statistics.rst - -**Sensor Space** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/stats-sensor-space/plot_stats_spatio_temporal_cluster_sensors.rst - auto_tutorials/stats-sensor-space/plot_stats_cluster_1samp_test_time_frequency.rst - auto_tutorials/stats-sensor-space/plot_stats_cluster_time_frequency.rst - auto_tutorials/stats-sensor-space/plot_stats_cluster_erp.rst - -.. raw:: html - -
- Examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/stats/plot_fdr_stats_evoked.rst - auto_examples/stats/plot_cluster_stats_evoked.rst - auto_examples/stats/plot_sensor_permutation_test.rst - auto_examples/stats/plot_sensor_regression.rst - auto_examples/stats/plot_linear_regression_raw.rst - -.. raw:: html - -
- -**Source Space** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/stats-source-space/plot_stats_cluster_time_frequency_repeated_measures_anova.rst - auto_tutorials/stats-source-space/plot_stats_cluster_spatio_temporal_2samp.rst - auto_tutorials/stats-source-space/plot_stats_cluster_spatio_temporal_repeated_measures_anova.rst - auto_tutorials/stats-source-space/plot_stats_cluster_spatio_temporal.rst - -.. raw:: html - -
-
-
- - -
-
-

- - Machine learning (decoding, encoding, MVPA) -

-
-
-
- -**Decoding** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/machine-learning/plot_sensors_decoding.rst - -.. raw:: html - -
- Examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/decoding/decoding_rsa.rst - auto_examples/decoding/plot_decoding_csp_eeg.rst - auto_examples/decoding/plot_decoding_csp_timefreq.rst - auto_examples/decoding/plot_decoding_spatio_temporal_source.rst - auto_examples/decoding/plot_decoding_spoc_CMC.rst - auto_examples/decoding/plot_decoding_time_generalization_conditions.rst - auto_examples/decoding/plot_decoding_unsupervised_spatial_filter.rst - auto_examples/decoding/plot_decoding_xdawn_eeg.rst - auto_examples/decoding/plot_ems_filtering.rst - auto_examples/decoding/plot_linear_model_patterns.rst - -.. raw:: html - -
- -**Encoding** - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/machine-learning/plot_receptive_field.rst - -.. raw:: html - -
- Examples - -.. toctree:: - :maxdepth: 1 - - auto_examples/decoding/plot_receptive_field_mtrf.rst - -.. raw:: html - -
- -.. raw:: html - -
-
-
- - -
-
-

- - Connectivity -

-
-
-
- -**Examples** - -.. toctree:: - :maxdepth: 1 - - auto_examples/connectivity/plot_cwt_sensor_connectivity.rst - auto_examples/connectivity/plot_mixed_source_space_connectivity.rst - auto_examples/connectivity/plot_mne_inverse_coherence_epochs.rst - auto_examples/connectivity/plot_mne_inverse_envelope_correlation.rst - auto_examples/connectivity/plot_mne_inverse_envelope_correlation_volume.rst - auto_examples/connectivity/plot_mne_inverse_connectivity_spectrum.rst - auto_examples/connectivity/plot_mne_inverse_label_connectivity.rst - auto_examples/connectivity/plot_mne_inverse_psi_visual.rst - auto_examples/connectivity/plot_sensor_connectivity.rst - -.. raw:: html - -
-
-
- - -
-
-

- Realtime -

-
-
-
- -**All realtime functionality has migrated to** :mod:`mne_realtime`. - -.. raw:: html - -
-
-
- -
-
-

- MNE-C and MNE-MATLAB -

-
-
-
- -**MNE-C** - -.. toctree:: - :maxdepth: 1 - - tutorials/command_line.rst - manual/c_reference.rst - manual/gui/analyze.rst - manual/gui/browse.rst - manual/source_localization/c_forward.rst - manual/source_localization/c_inverse.rst - manual/source_localization/c_morph.rst - manual/appendix/bem_model.rst - manual/appendix/c_misc.rst - manual/appendix/c_release_notes.rst - manual/appendix/c_EULA.rst - manual/appendix/martinos.rst - -**MNE-MATLAB** - -.. toctree:: - :maxdepth: 1 - - manual/matlab.rst - - -.. raw:: html - -
-
-
- - -
-
-

- Contributing -

-
- -
-
- -.. toctree:: - :maxdepth: 1 - - contributing.rst - -.. raw:: html - -
-
-
-
diff -Nru python-mne-0.18.1+dfsg/doc/faq.rst python-mne-0.19.1+dfsg/doc/faq.rst --- python-mne-0.18.1+dfsg/doc/faq.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/faq.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,280 +0,0 @@ -:orphan: - -.. include:: links.inc - -.. _faq: - -================================ -Frequently Asked Questions (FAQ) -================================ - -.. contents:: Contents - :local: - - -General MNE-Python issues -========================= - -Help! I can't get Python and MNE-Python working! ------------------------------------------------- - -Check out our section on how to get Anaconda up and running over at the -:ref:`getting started page `. - -I still can't get it to work! ------------------------------ -For analysis talk, join the `MNE mailing list`_. File specific feature -requests or bug reports `on GitHub `_. -You can also chat with developers `on Gitter `_. - -I can't get Mayavi/3D plotting to work under Windows. ------------------------------------------------------ -If Mayavi plotting in Jupyter Notebooks doesn't work -well, using the IPython magic ``%gui qt`` after importing MNE/Mayavi/PySurfer -should `help `_. - -.. code:: ipython - - from mayavi import mlab - %gui qt - - -.. _cite: - -How do I cite MNE? ------------------- -If you use the implementations provided by the MNE software in your research, -you should cite: - - - A. Gramfort, M. Luessi, E. Larson, D. Engemann, D. Strohmeier, C. Brodbeck, L. Parkkonen, M. Hämäläinen, `MNE software for processing MEG and EEG data `_, NeuroImage, Volume 86, 1 February 2014, Pages 446-460, ISSN 1053-8119, `[DOI] `__ - -If you use the Python code you should cite as well: - - - A. Gramfort, M. Luessi, E. Larson, D. Engemann, D. Strohmeier, C. Brodbeck, R. Goj, M. Jas, T. Brooks, L. Parkkonen, M. Hämäläinen, `MEG and EEG data analysis with MNE-Python `_, Frontiers in Neuroscience, Volume 7, 2013, ISSN 1662-453X, `[DOI] `__ - -To cite specific versions of the software, you can use the DOIs provided by -`Zenodo `_. - -You should as well cite the related method papers, some of which are listed in :ref:`ch_reading`. - -I'm not sure how to do *X* analysis step with my *Y* data... ------------------------------------------------------------- - -Knowing "the right thing" to do with EEG and MEG data is challenging. -We use the `MNE mailing list`_ to discuss -how to deal with different bits of data. It's worth searching the archives -to see if there have been relevant discussions before. - -I think I found a bug, what do I do? ------------------------------------- - -Please report any problems you find while using MNE-Python to the -`GitHub issues page`_. -Try :ref:`using the latest master version ` to -see if the problem persists before reporting the bug, as it may have -been fixed since the latest release. - -Why is it dangerous to "pickle" my MNE-Python objects and data for later use? ------------------------------------------------------------------------------ -`Pickling `_ data and -MNE-Python objects for later use can be tempting due to its simplicity -and generality, but it is usually not the best option. Pickling is not -designed for stable persistence, and it is likely that you will not be -able to read your data in the not-too-distant future. For details, see: - -- http://www.benfrederickson.com/dont-pickle-your-data/ -- https://stackoverflow.com/questions/21752259/python-why-pickle - -MNE-Python is designed to provide its own file saving formats -(often based on the FIF standard) for its objects usually via a -``save`` method or ``write_*`` method, e.g. :func:`mne.io.Raw.save`, -:func:`mne.Epochs.save`, :func:`mne.write_evokeds`, -:func:`mne.SourceEstimate.save`. If you have some data that you -want to save but can't figure out how, shoot an email to the -`MNE mailing list`_ or post it to the `GitHub issues page`_. - -If you want to write your own data to disk (e.g., subject behavioral -scores), we strongly recommend using `h5io `_, -which is based on the -`HDF5 format `_ and -h5py_, to save data in a fast, future-compatible, standard format. - - -I downloaded a dataset once, but MNE-Python is asking to download it again. Why? --------------------------------------------------------------------------------- -The default location for the MNE-sample data is ``~/mne_data``. -If you downloaded data and an example asks you whether to download it again, -make sure the data reside in the examples directory and that you run the -script from its current directory: - -.. code-block:: console - - $ cd examples/preprocessing - -Then in Python you can do:: - - In [1]: %run plot_find_ecg_artifacts.py - -See :ref:`datasets` for a list of all available datasets and some advanced -configuration options, e.g. to specify a custom location for storing the -datasets. - -.. _faq_cpu: - -A function uses multiple CPU cores even though I didn't tell it to. Why? ------------------------------------------------------------------------- -Ordinarily in MNE-python the ``parallel`` module is used to deploy multiple -cores via the ``n_jobs`` variable. However, functions like -:func:`mne.preprocessing.maxwell_filter` that use :mod:`scipy.linalg` do not have an -``n_jobs`` flag but may still use multiple cores. This is because :mod:`scipy.linalg` -is built with linear algebra libraries that natively support multithreading: - -* `OpenBLAS `_ -* `Intel Math Kernel Library (MKL) `_, - which uses `OpenMP `_ - -To control how many cores are used for linear-algebra-heavy functions like -:func:`mne.preprocessing.maxwell_filter`, you can set the -``OMP_NUM_THREADS`` or ``OPENBLAS_NUM_THREADS`` environment variable to the -desired number of cores for MKL or OpenBLAS, respectively. This can be done -before running Python, or inside Python you can achieve the same effect by, -e.g.:: - - >>> import os - >>> num_cpu = '4' # Set as a string - >>> os.environ['OMP_NUM_THREADS'] = num_cpu - -This must be done *before* running linear algebra functions; subsequent -changes in the same Python session will have no effect. - - -Resampling and decimating data -============================== - -What are all these options for resampling, decimating, and binning data? ------------------------------------------------------------------------- - -There are many functions in MNE-Python for changing the effective sampling -rate of data. We'll discuss some major ones here, with some of their -implications: - -- :func:`mne.io.Raw.resample` is used to resample (typically downsample) raw - data. Resampling is the two-step process of applying a low-pass FIR filter - and subselecting samples from the data. - - Using this function to resample data before forming :class:`mne.Epochs` - for final analysis is generally discouraged because doing so effectively - loses precision of (and jitters) the event timings, see - `this gist `_ as - a demonstration. However, resampling raw data can be useful for - (at least): - - - Computing projectors in low- or band-passed data - - Exploring data - -- :func:`mne.preprocessing.ICA.fit` decimates data without low-passing, - but is only used for fitting a statistical model to the data. - -- :func:`mne.Epochs.decimate`, which does the same thing as the - ``decim`` parameter in the :class:`mne.Epochs` constructor, sub-selects every - :math:`N^{th}` sample before and after each event. This should only be - used when the raw data have been sufficiently low-passed e.g. by - :func:`mne.io.Raw.filter` to avoid aliasing artifacts. - -- :func:`mne.Epochs.resample`, :func:`mne.Evoked.resample`, and - :func:`mne.SourceEstimate.resample` all resample data. - This process avoids potential aliasing artifacts because the - resampling process applies a low-pass filter. However, this filtering - introduces edge artifacts. Edge artifacts also exist when using - :func:`mne.io.Raw.resample`, but there the edge artifacts are constrained - to two times: the start and end of the recording. With these three methods, - edge artifacts are introduced to the start and end of every epoch - of data (or the start and end of the :class:`mne.Evoked` or - :class:`mne.SourceEstimate` data), which often has a more pronounced - effect on the data. - -- :func:`mne.SourceEstimate.bin` can be used to decimate, with or without - "binning" (averaging across data points). This is equivalent to applying - a moving-average (boxcar) filter to the data and decimating. A boxcar in - time is a `sinc `_ in - frequency, so this acts as a simplistic, non-ideal low-pass filter; - this will reduce but not eliminate aliasing if data were not sufficiently - low-passed. In the case where the "filter" or bin-width is a single sample - (i.e., an impulse) this operation simplifies to decimation without filtering. - -Resampling raw data is taking forever! What do I do? ----------------------------------------------------- - -:func:`mne.io.Raw.resample` was significantly sped up for version 0.12 by -using the parameter ``npad=='auto'``. Try it, it might help! - -If you have an NVIDIA GPU you could also try using :ref:`CUDA`, which can -sometimes speed up filtering and resampling operations by an order of -magnitude. - - -Inverse Solution -================ - -How should I regularize the covariance matrix? ----------------------------------------------- - -The estimated covariance can be numerically -unstable and tends to induce correlations between estimated source amplitudes -and the number of samples available. The MNE manual therefore suggests to regularize the noise covariance matrix (see -:ref:`cov_regularization`), especially if only few samples are available. Unfortunately -it is not easy to tell the effective number of samples, hence, to choose the appropriate regularization. -In MNE-Python, regularization is done using advanced regularization methods -described in [1]_. For this the 'auto' option can be used. With this -option cross-validation will be used to learn the optimal regularization:: - - >>> import mne - >>> epochs = mne.read_epochs(epochs_path) # doctest: +SKIP - >>> cov = mne.compute_covariance(epochs, tmax=0., method='auto') # doctest: +SKIP - -This procedure evaluates the noise covariance quantitatively by how well it whitens the data using the -negative log-likelihood of unseen data. The final result can also be visually inspected. -Under the assumption that the baseline does not contain a systematic signal -(time-locked to the event of interest), the whitened baseline signal should be -follow a multivariate Gaussian distribution, i.e., -whitened baseline signals should be between -1.96 and 1.96 at a given time sample. -Based on the same reasoning, the expected value for the global field power (GFP) -is 1 (calculation of the GFP should take into account the true degrees of -freedom, e.g. ``ddof=3`` with 2 active SSP vectors):: - - >>> evoked = epochs.average() # doctest: +SKIP - >>> evoked.plot_white(cov) # doctest: +SKIP - -This plot displays both, the whitened evoked signals for each channels and -the whitened GFP. The numbers in the GFP panel represent the estimated rank of -the data, which amounts to the effective degrees of freedom by which the -squared sum across sensors is divided when computing the whitened GFP. -The whitened GFP also helps detecting spurious late evoked components which -can be the consequence of over- or under-regularization. - -Note that if data have been processed using signal space separation (SSS) [2]_, -gradiometers and magnetometers will be displayed jointly because both are -reconstructed from the same SSS basis vectors with the same numerical rank. -This also implies that both sensor types are not any longer linearly independent. - -These methods for evaluation can be used to assess model violations. Additional -introductory materials can be found `here `_. - -For expert use cases or debugging the alternative estimators can also be compared:: - - >>> covs = mne.compute_covariance(epochs, tmax=0., method='auto', return_estimators=True) # doctest: +SKIP - >>> evoked = epochs.average() # doctest: +SKIP - >>> evoked.plot_white(covs) # doctest: +SKIP - -This will plot the whitened evoked for the optimal estimator and display the GFPs -for all estimators as separate lines in the related panel. - -References ----------- - -.. [1] Engemann D. and Gramfort A. (2015) Automated model selection in - covariance estimation and spatial whitening of MEG and EEG signals, - vol. 108, 328-342, NeuroImage. - -.. [2] Taulu, S., Simola, J., Kajola, M., 2005. Applications of the signal - space separation method. IEEE Trans. Signal Proc. 53, 3359–3372. diff -Nru python-mne-0.18.1+dfsg/doc/getting_started.html python-mne-0.19.1+dfsg/doc/getting_started.html --- python-mne-0.18.1+dfsg/doc/getting_started.html 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/getting_started.html 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,9 @@ + + + + + + +

Please follow this link.

+ + diff -Nru python-mne-0.18.1+dfsg/doc/getting_started.rst python-mne-0.19.1+dfsg/doc/getting_started.rst --- python-mne-0.18.1+dfsg/doc/getting_started.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/getting_started.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,19 +0,0 @@ -:orphan: - -.. include:: links.inc - -Installation — overview -========================= - -The MNE software products are open-source tools for processing, analysis, and -visualization of functional neuroimaging data (EEG, MEG, sEEG, ECoG, and -fNIRS). Pages describing the installation procedure are listed below. - -.. toctree:: - :maxdepth: 2 - - pre_install - install_mne_python - install_freesurfer - install_mne_c - advanced_setup diff -Nru python-mne-0.18.1+dfsg/doc/git_links.inc python-mne-0.19.1+dfsg/doc/git_links.inc --- python-mne-0.18.1+dfsg/doc/git_links.inc 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/git_links.inc 1970-01-01 00:00:00.000000000 +0000 @@ -1,99 +0,0 @@ -.. This (-*- rst -*-) format file contains commonly used link targets - and name substitutions. It may be included in many files, - therefore it should only contain link targets and name - substitutions. Try grepping for "^\.\. _" to find plausible - candidates for this list. - -.. NOTE: reST targets are - __not_case_sensitive__, so only one target definition is needed for - nipy, NIPY, Nipy, etc... - -.. git stuff -.. _git: https://git-scm.com/ -.. _github: https://github.com -.. _GitHub Help: https://help.github.com -.. _msysgit: http://code.google.com/p/msysgit/downloads/list -.. _git-osx-installer: http://code.google.com/p/git-osx-installer/downloads/list -.. _subversion: http://subversion.tigris.org/ -.. _git cheat sheet: http://github.com/guides/git-cheat-sheet -.. _pro git book: http://progit.org/ -.. _git svn crash course: http://git-scm.com/course/svn.html -.. _learn.github: http://learn.github.com/ -.. _network graph visualizer: https://github.com/blog/39-say-hello-to-the-network-graph-visualizer -.. _git user manual: https://schacon.github.io/git/user-manual.html -.. _git tutorial: https://schacon.github.io/git/gittutorial.html -.. _git community book: http://book.git-scm.com/ -.. _git ready: http://www.gitready.com/ -.. _git casts: http://www.gitcasts.com/ -.. _Fernando's git page: http://www.fperez.org/py4science/git.html -.. _git magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html -.. _git concepts: http://www.eecs.harvard.edu/~cduan/technical/git/ -.. _git clone: http://schacon.github.com/git/git-clone.html -.. _git checkout: https://schacon.github.io/git/git-checkout.html -.. _git commit: https://schacon.github.io/git/git-commit.html -.. _git push: https://schacon.github.io/git/git-push.html -.. _git pull: https://schacon.github.io/git/git-pull.html -.. _git add: https://schacon.github.io/git/git-add.html -.. _git status: https://schacon.github.io/git/git-status.html -.. _git diff: https://schacon.github.io/git/git-diff.html -.. _git log: https://schacon.github.io/git/git-log.html -.. _git branch: https://schacon.github.io/git/git-branch.html -.. _git remote: https://schacon.github.io/git/git-remote.html -.. _git rebase: https://schacon.github.io/git/git-rebase.html -.. _git config: https://schacon.github.io/git/git-config.html -.. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html -.. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html -.. _tangled working copy problem: http://tomayko.com/writings/the-thing-about-git -.. _git management: http://kerneltrap.org/Linux/Git_Management -.. _linux git workflow: http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html -.. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html -.. _git foundation: http://matthew-brett.github.io/pydagogue/foundation.html -.. _deleting master on github: http://matthew-brett.github.io/pydagogue/gh_delete_master.html -.. _rebase without tears: http://matthew-brett.github.io/pydagogue/rebase_without_tears.html -.. _resolving a merge: https://schacon.github.io/git/user-manual.html#resolving-a-merge -.. _ipython git workflow: https://web.archive.org/web/*/http://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html - -.. other stuff -.. _python: http://www.python.org -.. _travis: https://travis-ci.org/ -.. _linterflake8: https://atom.io/packages/linter-flake8 - -.. python packages -.. _pep8: https://pypi.org/project/pep8/ -.. _pyflakes: https://pypi.org/project/pyflakes -.. _coverage: https://pypi.python.org/pypi/coverage -.. _mayavi: http://https//docs.enthought.com/mayavi/mayavi/ -.. _nitime: http://nipy.org/nitime/ -.. _joblib: https://pypi.python.org/pypi/joblib -.. _scikit-learn: https://scikit-learn.org/stable/ -.. _pysurfer: https://pysurfer.github.io/ -.. _pyDICOM: https://pypi.python.org/pypi/pydicom/ -.. _matplotlib: https://matplotlib.org/ -.. _sphinx: http://sphinx-doc.org/ -.. _pandas: http://pandas.pydata.org/ -.. _PIL: https://pypi.python.org/pypi/PIL - -.. python editors -.. _atom: https://atom.io/ -.. _Spyder: https://www.spyder-ide.org/ -.. _anaconda: https://www.anaconda.com/distribution/ -.. _miniconda: https://conda.io/en/latest/miniconda.html -.. _installation instructions for Anaconda: http://docs.continuum.io/anaconda/install -.. _installation instructions for Miniconda: https://conda.io/projects/conda/en/latest/user-guide/install/index.html -.. _EPD: https://www.enthought.com/products/epd/ -.. _sublime text: http://www.sublimetext.com/ - -.. installation links -.. _FreeSurfer: https://surfer.nmr.mgh.harvard.edu/fswiki/ -.. _FreeSurfer download page: https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall -.. _environment file: https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml -.. _requirements file: https://raw.githubusercontent.com/mne-tools/mne-python/master/requirements.txt -.. _NVIDIA CUDA GPU processing: https://developer.nvidia.com/cuda-zone -.. _NVIDIA proprietary drivers: https://www.geforce.com/drivers - -.. _Sphinx documentation: http://sphinx-doc.org/rest.html -.. _sphinx gallery documentation: https://sphinx-gallery.github.io -.. _NumPy docstring standard: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt -.. _Stack Overflow: https://stackoverflow.com/ - -.. vim: ft=rst diff -Nru python-mne-0.18.1+dfsg/doc/glossary.rst python-mne-0.19.1+dfsg/doc/glossary.rst --- python-mne-0.18.1+dfsg/doc/glossary.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/glossary.rst 2019-10-25 14:42:45.000000000 +0000 @@ -1,21 +1,15 @@ :orphan: -.. include:: links.inc - .. _glossary: -========================== Glossary -========================== - -.. .. contents:: Contents -.. :local: - +======== .. currentmodule:: mne -MNE-Python core terminology and general concepts -================================================ +The Glossary provides short definitions of MNE-Python-specific vocabulary and +general neuroimaging concepts. If you think a term is missing, please consider +`creating a new issue`_ or `opening a pull request`_ to add it. .. glossary:: @@ -30,25 +24,34 @@ object class and :ref:`tut-annotations` for a tutorial on how to manipulate such objects. - channels - Channels refer to MEG sensors, EEG electrodes or any extra electrode - or sensor such as EOG, ECG or sEEG, ECoG etc. Channels have typically - a type, such as gradiometer, and a unit, such as Tesla/Meter that - is used in the code base, e.g. for plotting. - BEM BEM is the acronym for boundary element method or boundary element model. Both are related to the forward model computation and more specifically the definion of the conductor model. The boundary element model consists of surfaces such as the inner skull, - outer skull and outer skiln (a.k.a. scalp) that define compartments + outer skull and outer skin (a.k.a. scalp) that define compartments of tissues of the head. You can compute the BEM surfaces with :func:`mne.bem.make_watershed_bem` or :func:`mne.bem.make_flash_bem`. See :ref:`tut-forward` for usage demo. + channels + Channels refer to MEG sensors, EEG electrodes or any extra electrode + or sensor such as EOG, ECG or sEEG, ECoG etc. Channels usually have + a type, such as gradiometer, and a unit, such as Tesla/Meter that + is used in the code base, e.g. for plotting. + dipole See :term:`equivalent current dipole`. + epochs + Epochs (sometimes called "trials" in other software packages) are + equal-length spans of data extracted from raw continuous data. Usually, + epochs are extracted around stimulus events or subject responses, + though sometimes sequential or overlapping epochs are extracted (e.g., + for analysis of resting-state activity). See :class:`Epochs` for the + API of the corresponding object class, and :ref:`tut-epochs-class` for + a narrative overview. + equivalent current dipole An equivalent current dipole (ECD) is an approximate representation of post-synaptic activity in a small region of cortex. The intracellular @@ -57,14 +60,15 @@ perpendicularly to the cortical surface. Because the length of such current sources is very small relative to the distance between the cortex and the EEG/MEG sensors, the fields measured by the techniques - are well-approximated by (i.e., "equivalent" to) fields generated by + are well-approximated by (i.e., "equivalent" to) fields generated by idealized point sources (dipoles) located on the cortical surface. - epochs - Epochs are chunks of data extracted from raw continuous data. Typically, - they correspond to the trials of an experimental design. - See :class:`Epochs` for the API of the corresponding - object class, and :ref:`tut-epochs-class` for a narrative overview. + events + Events correspond to specific time points in raw data; e.g., + triggers, experimental condition events, etc. MNE represents events with + integers that are stored in numpy arrays of shape (n_events, 3). Such arrays + are classically obtained from a trigger channel, also referred to as + stim channel. evoked Evoked data are obtained by averaging epochs. Typically, an evoked object @@ -73,22 +77,21 @@ See :class:`EvokedArray` for the API of the corresponding object class, and :ref:`tut-evoked-class` for a narrative overview. - events - Events correspond to specific time points in raw data; e.g., - triggers, experimental condition events, etc. MNE represents events with - integers that are stored in numpy arrays of shape (n_events, 3). Such arrays - are classically obtained from a trigger channel, also referred to as - stim channel. + fiducial point + There are three fiducial (a.k.a. cardinal) points: the left + preauricular point (LPA), the right preauricular point (RPA) + and the nasion. first_samp - The attribute of raw objects called ``first_samp`` is an integer that - refers to the number of time samples passed between the onset of the - acquisition system and the time when data started to be written - on disk. This is a specificity of the Vectorview MEG systems (fif files) - but for consistency it is available for all file formats in MNE. - One benefit of this system is that croppping data only boils - down to a change of the ``first_samp`` attribute to know when cropped data - was acquired. + The :attr:`~mne.io.Raw.first_samp` attribute of :class:`~mne.io.Raw` + objects is an integer representing the number of time samples that + passed between the onset of the hardware acquisition system and the + time when data started to be recorded to disk. This approach to sample + numbering is a peculiarity of VectorView MEG systems, but for + consistency it is present in all :class:`~mne.io.Raw` objects + regardless of the source of the data. In other words, + :attr:`~mne.io.Raw.first_samp` will be ``0`` in :class:`~mne.io.Raw` + objects loaded from non-VectorView data files. forward solution The forward solution (abbr. ``fwd``) is a linear operator capturing the @@ -100,6 +103,23 @@ :term:`boundary element model ` and :class:`mne.bem.ConductorModel`). + GFP + Global Field Power (abbr. ``GFP``) is a measure of the (non-)uniformity + of the electromagnetic field at the sensors. It is typically calculated + as the standard deviation of the sensor values at each time point; thus + it is a one-dimensional time series capturing the spatial variability + of the signal across sensor locations. + + HPI + Head position indicators (abbr. ``HPI``, or sometimes ``cHPI`` for + *continuous* head position indicators) are small coils attached to a + subject's head during MEG acquisition. Each coil emits a sinusoidal + signal of a different frequency, which is picked up by the MEG sensors + and can be used to infer the head position. With cHPI, the sinusoidal + signals are typically set at frequencies above any neural signal of + interest, and thus can be removed after head position correction via + low-pass filtering. + info Also called ``measurement info``, it is a collection of metadata regarding a Raw, Epochs or Evoked object; e.g., @@ -118,15 +138,26 @@ A :class:`Label` refers to a region in the cortex, also often called a region of interest (ROI) in the literature. + layout + A :class:`Layout ` gives sensor positions in 2 + dimensions (defined by ``x``, ``y``, ``width``, and ``height`` values for + each sensor). It is primarily used for illustrative purposes (i.e., making + diagrams of approximate sensor positions in top-down diagrams of the head, + so-called topographies or topomaps). + montage EEG channel names and the relative positions of the sensor w.r.t. the scalp. - See :class:`~channels.Montage` for the API of the corresponding object + While layout are 2D locations, montages give 3D locations. A montage + can also contain locations for HPI points, fiducial points, or + extra head shape points. + See :class:`~channels.DigMontage` for the API of the corresponding object class. morphing Morphing refers to the operation of transferring source estimates from one anatomy to another. It is commonly referred as realignment in fMRI - literature. This operation is necessary for group studies. + literature. This operation is necessary for group studies (to get the + data in a common space for statistical analysis). See :ref:`ch_morph` for more details. pick @@ -151,17 +182,8 @@ See :class:`~io.RawArray` for the API of the corresponding object class, and :ref:`tut-raw-class` for a narrative overview. - source space - A source space (abbr. ``src``) specifies where in the brain one wants - to estimate the - source amplitudes. It corresponds to locations of a set of - candidate equivalent current dipoles (ECD). MNE mostly works - with source spaces defined on the cortical surfaces estimated - by FreeSurfer from a T1-weighted MRI image. See - :ref:`tut-forward` to read on - how to compute a forward operator on a source space. - See :class:`SourceSpaces` for the API of the corresponding - object class. + selection (abbr. sel) + A set of picks. E.g., all sensors included in a Region of Interest. source estimates (abbr. ``stc``) Source estimates, commonly referred to as STC (Source Time Courses), @@ -176,16 +198,34 @@ :class:`VectorSourceEstimate`, :class:`MixedSourceEstimate`, for the API of the corresponding object classes. - selection (abbr. sel) - A set of picks. E.g., all sensors included in a Region of Interest. + source space + A source space (abbr. ``src``) specifies where in the brain one wants + to estimate the + source amplitudes. It corresponds to locations of a set of + candidate equivalent current dipoles (ECD). MNE mostly works + with source spaces defined on the cortical surfaces estimated + by FreeSurfer from a T1-weighted MRI image. See + :ref:`tut-forward` to read on + how to compute a forward operator on a source space. + See :class:`SourceSpaces` for the API of the corresponding + object class. stim channel - A stim channel, a.k.a. trigger channel, is a channel that encodes events - during the recording. It is typically a channel that is always zero and that - takes positive values when something happens such as the onset of a stimulus. - Classical names for stim channels is ``STI 014`` or ``STI 101``. - So-called events arrays are obtained from stim channels. + A stim channel, a.k.a. trigger channel, is a channel that encodes + events during the recording. It is typically a channel that is usually + zero and takes positive values when something happens (such as the + onset of a stimulus, or a subject response). Stim channels are often + prefixed with ``STI`` to distinguish them from other channel types. See + :ref:`stim-channel-defined` for more details. trans A coordinate frame affine transformation, usually between the Neuromag head coordinate frame and the MRI Surface RAS coordinate frame used by Freesurfer. + + +.. LINKS + +.. _`creating a new issue`: + https://github.com/mne-tools/mne-python/issues/new?template=glossary.md +.. _`opening a pull request`: + https://github.com/mne-tools/mne-python/pull/new/master Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_images/CoordinateSystems.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_images/CoordinateSystems.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_images/HeadCS.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_images/HeadCS.png differ diff -Nru python-mne-0.18.1+dfsg/doc/_includes/bem_model.rst python-mne-0.19.1+dfsg/doc/_includes/bem_model.rst --- python-mne-0.18.1+dfsg/doc/_includes/bem_model.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/bem_model.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,166 @@ +:orphan: + +Creating the BEM meshes +======================= + +.. contents:: Page contents + :local: + :depth: 2 + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`bem-model` to link to that section of the implementation.rst page. + The next line is a target for :start-after: so we can omit the title from + the include: + bem-begin-content + +.. _bem_watershed_algorithm: + +Using the watershed algorithm +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The watershed algorithm [Segonne *et al.*, +2004] is part of the FreeSurfer software. +The name of the program is mri_watershed . +Its use in the MNE environment is facilitated by the script +:ref:`gen_mne_watershed_bem`. + +After ``mne watershed_bem`` has completed, the following files appear in the +subject's :file:`bem/watershed` directory: + +- :file:`{}_brain_surface` contains the brain surface triangulation. + +- :file:`{}_inner_skull_surface` contains the inner skull + triangulation. + +- :file:`{}_outer_skull_surface` contains the outer skull + triangulation. + +- :file:`{}_outer_skin_surface` contains the scalp triangulation. + +All of these surfaces are in the FreeSurfer format. In addition, there will be +a directory called :file:`bem/watershed/ws` which contains the brain MRI +volume. Furthermore, ``mne watershed_bem`` script converts the scalp surface to +fif format and saves the result to :file:`bem/{}-head.fif`. + + +Using FLASH images +~~~~~~~~~~~~~~~~~~ + +This method depends on the availablily of MRI data acquired with a multi-echo +FLASH sequence at two flip angles (5 and 30 degrees). These data can be +acquired separately from the MPRAGE data employed in FreeSurfer cortical +reconstructions but it is strongly recommended that they are collected at the +same time with the MPRAGEs or at least with the same scanner. For easy +co-registration, the images should have FOV, matrix, slice thickness, gap, and +slice orientation as the MPRAGE data. For information on suitable pulse +sequences, see reference [B. Fischl *et al.* and J. Jovicich *et al.*, 2006] in +:ref:`CEGEGDEI`. + +Creation of the BEM meshes using this method involves the following steps: + +- Creating a synthetic 5-degree flip angle FLASH volume, register + it with the MPRAGE data, and run the segmentation and meshing program. + This step is accomplished by running the script :ref:`gen_mne_flash_bem`. + +- Inspecting the meshes with tkmedit, see :ref:`inspecting-meshes`. + +.. note:: Different methods can be employed for the creation of the + individual surfaces. For example, it may turn out that the + watershed algorithm produces are better quality skin surface than + the segmentation approach based on the FLASH images. If this is + the case, ``outer_skin.surf`` can set to point to the corresponding + watershed output file while the other surfaces can be picked from + the FLASH segmentation data. + + +Organizing MRI data into directories +------------------------------------ + +Since all images comprising the multi-echo FLASH data are contained in a single +series, it is necessary to organize the images according to the echoes before +proceeding to the BEM surface reconstruction. This can be accomplished by using +`dcm2niix `__ +or the MNE-C tool ``mne_organize_dicom`` if necessary, then use +:func:`mne.bem.convert_flash_mris`. + +Creating the surface tessellations +---------------------------------- + +The BEM surface segmentation and tessellation is automated with the script +:ref:`gen_mne_flash_bem`. It assumes that a FreeSurfer reconstruction for this +subject is already in place. + +Before running :ref:`gen_mne_flash_bem` do the following: + +- Create symbolic links from the directories containing the 5-degree and + 30-degree flip angle FLASH series to ``flash05`` and ``flash30``, + respectively: + + - :samp:`ln -s {} flash05` + + - :samp:`ln -s {} flash30` + +- Some partition formats (e.g. FAT32) do not support symbolic links. In this + case, copy the file to the appropriate series: + + - :samp:`cp {} flash05` + + - :samp:`cp {} flash30` + +- Set the ``SUBJECTS_DIR`` and ``SUBJECT`` environment variables or pass + the ``--subjects-dir`` and ``--subject`` options to ``mne flash_bem`` + +.. note:: If ``mne flash_bem`` is run with the ``--noflash30`` option, the + :file:`flash30` directory is not needed, *i.e.*, only the 5-degree flip + angle flash data are employed. + +It may take a while for ``mne flash_bem`` to complete. It uses the FreeSurfer +directory structure under ``$SUBJECTS_DIR/$SUBJECT``. The script encapsulates +the following processing steps: + +- It creates an mgz file corresponding to each of the eight echoes in each of + the FLASH directories in ``mri/flash``. The files will be called + :file:`mef {}_{}.mgz`. + +- If the ``unwarp=True`` option is specified, run grad_unwarp and produce + files :file:`mef {}_{}u.mgz`. These files will be + then used in the following steps. + +- It creates parameter maps in :file:`mri/flash/parameter_maps` using + ``mri_ms_fitparms``. + +- It creates a synthetic 5-degree flip angle volume in + :file:`mri/flash/parameter_maps/flash5.mgz` using ``mri_synthesize``. + +- Using ``fsl_rigid_register``, it creates a registered 5-degree flip angle + volume ``mri/flash/parameter_maps/flash5_reg.mgz`` by registering + :file:`mri/flash/parameter_maps/flash5.mgz` to the *T1* volume under ``mri``. + +- Using ``mri_convert``, it converts the flash5_reg volume to COR format under + ``mri/flash5``. If necessary, the T1 and brain volumes are also converted + into the COR format. + +- It runs ``mri_make_bem_surfaces`` to create the BEM surface tessellations. + +- It creates the directory :file:`bem/flash`, moves the tri-format + tringulations there and creates the corresponding FreeSurfer surface files + in the same directory. + +- The COR format volumes created by ``mne flash_bem`` are removed. + +If the ``--noflash30`` option is specified to ``mne flash_bem``, +steps 3 and 4 in the above are replaced by averaging over the different +echo times in 5-degree flip angle data. + +.. _inspecting-meshes: + +Inspecting the meshes +--------------------- + +It is advisable to check the validity of the BEM meshes before +using them. This can be done with: + +- the ``--view`` option of :ref:`gen_mne_flash_bem` +- calling :func:`mne.viz.plot_bem` directly +- Using FreeSurfer tools ``tkmedit`` or ``freeview`` diff -Nru python-mne-0.18.1+dfsg/doc/_includes/channel_interpolation.rst python-mne-0.19.1+dfsg/doc/_includes/channel_interpolation.rst --- python-mne-0.18.1+dfsg/doc/_includes/channel_interpolation.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/channel_interpolation.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,79 @@ +:orphan: + +Bad channel repair via interpolation +==================================== + +Spherical spline interpolation (EEG) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`channel-interpolation` to link to that section of the + implementation.rst page. The next line is a target for :start-after: so we + can omit the title from the include: + channel-interpolation-begin-content + +In short, data repair using spherical spline interpolation [1]_ consists of the following steps: + +* Project the good and bad electrodes onto a unit sphere +* Compute a mapping matrix that maps :math:`N` good channels to :math:`M` bad channels +* Use this mapping matrix to compute interpolated data in the bad channels + +Spherical splines assume that the potential :math:`V(\boldsymbol{r_i})` at any point :math:`\boldsymbol{r_i}` on the surface of the sphere can be represented by: + +.. math:: V(\boldsymbol{r_i}) = c_0 + \sum_{j=1}^{N}c_{i}g_{m}(cos(\boldsymbol{r_i}, \boldsymbol{r_{j}})) + :label: model + +where the :math:`C = (c_{1}, ..., c_{N})^{T}` are constants which must be estimated. The function :math:`g_{m}(\cdot)` of order :math:`m` is given by: + +.. math:: g_{m}(x) = \frac{1}{4 \pi}\sum_{n=1}^{\infty} \frac{2n + 1}{(n(n + 1))^m}P_{n}(x) + :label: legendre + +where :math:`P_{n}(x)` are `Legendre polynomials`_ of order `n`. + +.. _Legendre polynomials: https://en.wikipedia.org/wiki/Legendre_polynomials + +To estimate the constants :math:`C`, we must solve the following two equations simultaneously: + +.. math:: G_{ss}C + T_{s}c_0 = X + :label: matrix_form + +.. math:: {T_s}^{T}C = 0 + :label: constraint + +where :math:`G_{ss} \in R^{N \times N}` is a matrix whose entries are :math:`G_{ss}[i, j] = g_{m}(cos(\boldsymbol{r_i}, \boldsymbol{r_j}))` and :math:`X \in R^{N \times 1}` are the potentials :math:`V(\boldsymbol{r_i})` measured at the good channels. :math:`T_{s} = (1, 1, ..., 1)^T` is a column vector of dimension :math:`N`. Equation :eq:`matrix_form` is the matrix formulation of Equation :eq:`model` and equation :eq:`constraint` is like applying an average reference to the data. From equation :eq:`matrix_form` and :eq:`constraint`, we get: + +.. math:: \begin{bmatrix} c_0 \\ C \end{bmatrix} = {\begin{bmatrix} {T_s}^{T} && 0 \\ T_s && G_{ss} \end{bmatrix}}^{-1} \begin{bmatrix} 0 \\ X \end{bmatrix} = C_{i}X + :label: estimate_constant + +:math:`C_{i}` is the same as matrix :math:`{\begin{bmatrix} {T_s}^{T} && 0 \\ T_s && G_{ss} \end{bmatrix}}^{-1}` but with its first column deleted, therefore giving a matrix of dimension :math:`(N + 1) \times N`. + +Now, to estimate the potentials :math:`\hat{X} \in R^{M \times 1}` at the bad channels, we have to do: + +.. math:: \hat{X} = G_{ds}C + T_{d}c_0 + :label: estimate_data + +where :math:`G_{ds} \in R^{M \times N}` computes :math:`g_{m}(\boldsymbol{r_i}, \boldsymbol{r_j})` between the bad and good channels. :math:`T_{d} = (1, 1, ..., 1)^T` is a column vector of dimension :math:`M`. Plugging in equation :eq:`estimate_constant` in :eq:`estimate_data`, we get + +.. math:: \hat{X} = \begin{bmatrix} T_d && G_{ds} \end{bmatrix} \begin{bmatrix} c_0 \\ C \end{bmatrix} = \underbrace{\begin{bmatrix} T_d && G_{ds} \end{bmatrix} C_{i}}_\text{mapping matrix}X + + +To interpolate bad channels, one can simply do: + + >>> evoked.interpolate_bads(reset_bads=False) # doctest: +SKIP + +and the bad channel will be fixed. + +.. target for :end-before: channel-interpolation-end-content + +.. topic:: Examples: + + * :ref:`sphx_glr_auto_examples_preprocessing_plot_interpolate_bad_channels.py` + + +References +~~~~~~~~~~ + +.. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989). + Spherical splines for scalp potential and current density mapping. + *Electroencephalography Clinical Neurophysiology* 72(2), 184-187. diff -Nru python-mne-0.18.1+dfsg/doc/_includes/channel_types.rst python-mne-0.19.1+dfsg/doc/_includes/channel_types.rst --- python-mne-0.18.1+dfsg/doc/_includes/channel_types.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/channel_types.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,66 @@ +:orphan: + +Supported channel types +======================= + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`channel-types` to link to that section of the implementation.rst + page. The next line is a target for :start-after: so we can omit the title + from the include: + channel-types-begin-content + +Channel types are represented in MNE-Python with shortened or abbreviated +names. This page lists all supported channel types, their abbreviated names, +and the measurement unit used to represent data of that type. Where channel +types occur in two or more sub-types, the sub-type abbreviations are given in +parentheses. More information about measurement units is given in the +:ref:`units` section. + +.. NOTE: To include only the table, here's a different target for :start-after: + channel-types-begin-table + +.. cssclass:: table-bordered +.. rst-class:: midvalign + +============= ========================================= ================= +Channel type Description Measurement unit +============= ========================================= ================= +eeg scalp electroencephalography (EEG) Volts + +meg (mag) Magnetoencephalography (magnetometers) Teslas + +meg (grad) Magnetoencephalography (gradiometers) Teslas/meter + +ecg Electrocardiography (ECG) Volts + +seeg Stereotactic EEG channels Volts + +ecog Electrocorticography (ECoG) Volts + +fnirs (hbo) Functional near-infrared spectroscopy Moles/liter + (oxyhemoglobin) + +fnirs (hbr) Functional near-infrared spectroscopy Moles/liter + (deoxyhemoglobin) + +emg Electromyography (EMG) Volts + +bio Miscellaneous biological channels (e.g., Arbitrary units + skin conductance) + +stim stimulus (a.k.a. trigger) channels Arbitrary units + +resp response-trigger channel Arbitrary units + +chpi continuous head position indicator Teslas + (HPI) coil channels + +exci Flux excitation channel + +ias Internal Active Shielding data + (Triux systems only?) + +syst System status channel information + (Triux systems only) +============= ========================================= ================= diff -Nru python-mne-0.18.1+dfsg/doc/_includes/data_formats.rst python-mne-0.19.1+dfsg/doc/_includes/data_formats.rst --- python-mne-0.18.1+dfsg/doc/_includes/data_formats.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/data_formats.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,73 @@ +:orphan: + +Supported data formats +====================== + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, + link to :ref:`data-formats`. The next line is + a target for :start-after: so we can omit the title above: + data-formats-begin-content + +When MNE-Python loads sensor data, the data are stored in a Python object of +type :class:`mne.io.Raw`. Specialized loading functions are provided for the +raw data file formats from a variety of equipment manufacturers. All raw data +input/output functions in MNE-Python are found in :mod:`mne.io` and start +with :samp:`read_raw_{*}`; see the documentation for each reader function for +more info on reading specific file types. + +As seen in the table below, there are also a few formats defined by other +neuroimaging analysis software packages that are supported (EEGLAB, +FieldTrip). Like the equipment-specific loading functions, these will also +return an object of class :class:`~mne.io.Raw`; additional functions are +available for reading data that has already been epoched or averaged (see +table). + +.. NOTE: To include only the table, here's a different target for :start-after: + data-formats-begin-table + +.. cssclass:: table-bordered +.. rst-class:: midvalign + +============ ============================================ ========= =================================== +Data type File format Extension MNE-Python function +============ ============================================ ========= =================================== +MEG :ref:`Artemis123 ` .bin :func:`mne.io.read_raw_artemis123` + +MEG :ref:`4-D Neuroimaging / BTi ` :func:`mne.io.read_raw_bti` + +MEG :ref:`CTF ` :func:`mne.io.read_raw_ctf` + +MEG and EEG :ref:`Elekta Neuromag ` .fif :func:`mne.io.read_raw_fif` + +MEG :ref:`KIT ` .sqd :func:`mne.io.read_raw_kit`, + :func:`mne.read_epochs_kit` + +MEG and EEG :ref:`FieldTrip ` .mat :func:`mne.io.read_raw_fieldtrip`, + :func:`mne.read_epochs_fieldtrip`, + :func:`mne.read_evoked_fieldtrip` + +EEG :ref:`Brainvision ` .vhdr :func:`mne.io.read_raw_brainvision` + +EEG :ref:`Biosemi data format ` .bdf :func:`mne.io.read_raw_bdf` + +EEG :ref:`Neuroscan CNT ` .cnt :func:`mne.io.read_raw_cnt` + +EEG :ref:`European data format ` .edf :func:`mne.io.read_raw_edf` + +EEG :ref:`EEGLAB ` .set :func:`mne.io.read_raw_eeglab`, + :func:`mne.read_epochs_eeglab` + +EEG :ref:`EGI simple binary ` .egi :func:`mne.io.read_raw_egi` + +EEG :ref:`EGI MFF format ` .mff :func:`mne.io.read_raw_egi` + +EEG :ref:`eXimia ` .nxe :func:`mne.io.read_raw_eximia` + +EEG :ref:`General data format ` .gdf :func:`mne.io.read_raw_gdf` + +EEG :ref:`Nicolet ` .data :func:`mne.io.read_raw_nicolet` +============ ============================================ ========= =================================== + +More details are provided in the tutorials in the :ref:`tut-data-formats` +section. diff -Nru python-mne-0.18.1+dfsg/doc/_includes/dig_formats.rst python-mne-0.19.1+dfsg/doc/_includes/dig_formats.rst --- python-mne-0.18.1+dfsg/doc/_includes/dig_formats.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/dig_formats.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,41 @@ +:orphan: + +Supported formats for digitized 3D locations +============================================ + +.. NOTE: If you want to link to this content, link to :ref:`dig-formats` + for the implementation page. The next line is + a target for :start-after: so we can omit the title above: + dig-formats-begin-content + +MNE-Python can load 3D point locations obtained by digitization systems. +Such files allow to obtain a :class:`montage ` +that can then be added to :class:`~mne.io.Raw` objects with the +:meth:`~mne.io.Raw.set_montage`. See the documentation for each reader +function for more info on reading specific file types. + +.. NOTE: To include only the table, here's a different target for :start-after: + dig-formats-begin-table + +.. cssclass:: table-bordered +.. rst-class:: midvalign + +================= ================ ============================================== +Vendor Extension(s) MNE-Python function +================= ================ ============================================== +Neuromag .fif :func:`mne.channels.read_dig_fif` + +Polhemus ISOTRAK .hsp, .elp, .eeg :func:`mne.channels.read_dig_polhemus_isotrak` + +EGI .xml :func:`mne.channels.read_dig_egi` + +MNE-C .hpts :func:`mne.channels.read_dig_hpts` + +Brain Products .bvct :func:`mne.channels.read_dig_captrack` +================= ================ ============================================== + +To load Polhemus FastSCAN files you can use +:func:`montage `. + +It is also possible to make a :class:`montage ` +from arrays with :func:`mne.channels.make_dig_montage`. diff -Nru python-mne-0.18.1+dfsg/doc/_includes/forward.rst python-mne-0.19.1+dfsg/doc/_includes/forward.rst --- python-mne-0.18.1+dfsg/doc/_includes/forward.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/forward.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,725 @@ +:orphan: + +The forward solution +==================== + +This page covers the definitions of different coordinate systems employed in +MNE software and FreeSurfer, the details of the computation of the forward +solutions, and the associated low-level utilities. + +.. contents:: Page contents + :local: + :depth: 2 + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`ch_forward` to link to that section of the implementation.rst page. + The next line is a target for :start-after: so we can omit the title from + the include: + forward-begin-content + + +.. _coordinate_systems: + +MEG/EEG and MRI coordinate systems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. sidebar:: Coordinate systems in MNE-Python + + In some MNE-Python objects (e.g., :class:`~mne.Forward`, + :class:`~mne.SourceSpaces`, etc), information about the coordinate frame is + encoded as a constant integer value. The meaning of those integers is + determined `in the source code + `__. + +The coordinate systems used in MNE software (and FreeSurfer) and their +relationships are depicted in :ref:`coordinate_system_figure`. Except for the +*sensor coordinates*, all of the coordinate systems are Cartesian and have the +"RAS" (Right-Anterior-Superior) orientation, *i.e.*, the :math:`x` axis points +to the right, the :math:`y` axis to the front, and the :math:`z` axis up. + +.. _coordinate_system_figure: + +.. figure:: ../_images/CoordinateSystems.png + :alt: MEG/EEG and MRI coordinate systems + + MEG/EEG and MRI coordinate systems + + The coordinate transforms present in the fif files in MNE and the + FreeSurfer files as well as those set to fixed values are indicated with + :math:`T_x`, where :math:`x` identifies the transformation. + +The coordinate systems related to MEG/EEG data are: + +**Head coordinates** + + This is a coordinate system defined with help of the fiducial landmarks + (nasion and the two auricular points). In fif files, EEG electrode + locations are given in this coordinate system. In addition, the head + digitization data acquired in the beginning of an MEG, MEG/EEG, or EEG + acquisition are expressed in head coordinates. For details, see + :ref:`coordinate_systems`. + +**Device coordinates** + + This is a coordinate system tied to the MEG device. The relationship of the + Device and Head coordinates is determined during an MEG measurement by + feeding current to three to five head-position indicator (HPI) coils and by + determining their locations with respect to the MEG sensor array from the + magnetic fields they generate. + +**Sensor coordinates** + + Each MEG sensor has a local coordinate system defining the orientation and + location of the sensor. With help of this coordinate system, the numerical + integration data needed for the computation of the magnetic field can be + expressed conveniently as discussed in :ref:`coil_geometry_information`. + The channel information data in the fif files contain the information to + specify the coordinate transformation between the coordinates of each + sensor and the MEG device coordinates. + +The coordinate systems related to MRI data are: + +**Surface RAS coordinates** + + The FreeSurfer surface data are expressed in this coordinate system. The + origin of this coordinate system is at the center of the conformed + FreeSurfer MRI volumes (usually 256 x 256 x 256 isotropic 1-mm3 voxels) + and the axes are oriented along the axes of this volume. The BEM surface + and the locations of the sources in the source space are usually expressed + in this coordinate system in the fif files. In this manual, the *Surface + RAS coordinates* are usually referred to as *MRI coordinates* unless there + is need to specifically discuss the different MRI-related coordinate + systems. + +**RAS coordinates** + + This coordinate system has axes identical to the Surface RAS coordinates + but the location of the origin is different and defined by the original MRI + data, i.e. , the origin is in a scanner-dependent location. There is hardly + any need to refer to this coordinate system explicitly in the analysis with + the MNE software. However, since the Talairach coordinates, discussed + below, are defined with respect to *RAS coordinates* rather than the + *Surface RAS coordinates*, the RAS coordinate system is implicitly involved + in the transformation between Surface RAS coordinates and the two + *Talairach* coordinate systems. + +**MNI Talairach coordinates** + + The definition of this coordinate system is discussed, e.g., in + http://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach. This transformation + is determined during the FreeSurfer reconstruction process. These + coordinates are in MNI305 space. + +**FreeSurfer Talairach coordinates** + + The problem with the MNI Talairach coordinates is that the linear MNI + Talairach transform does not match the brains completely to the Talairach + brain. This is probably because the Talairach atlas brain is a rather odd + shape, and as a result, it is difficult to match a standard brain to the + atlas brain using an affine transform. As a result, the MNI brains are + slightly larger (in particular higher, deeper and longer) than the + Talairach brain. The differences are larger as you get further from the + middle of the brain, towards the outside. The FreeSurfer Talairach + coordinates mitigate this problem by additing a an additional + transformation, defined separately for negatice and positive MNI Talairach + :math:`z` coordinates. These two transformations, denoted by :math:`T_-` + and :math:`T_+` in :ref:`coordinate_system_figure`, are fixed as discussed in + http://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach (*Approach 2*). + +The different coordinate systems are related by coordinate transformations +depicted in :ref:`coordinate_system_figure`. The arrows and coordinate +transformation symbols (:math:`T_x`) indicate the transformations actually +present in the FreeSurfer files. Generally, + +.. math:: \begin{bmatrix} + x_2 \\ + y_2 \\ + z_2 \\ + 1 + \end{bmatrix} = T_{12} \begin{bmatrix} + x_1 \\ + y_1 \\ + z_1 \\ + 1 + \end{bmatrix} = \begin{bmatrix} + R_{11} & R_{12} & R_{13} & x_0 \\ + R_{21} & R_{22} & R_{23} & y_0 \\ + R_{31} & R_{32} & R_{33} & z_0 \\ + 0 & 0 & 0 & 1 + \end{bmatrix} \begin{bmatrix} + x_1 \\ + y_1 \\ + z_1 \\ + 1 + \end{bmatrix}\ , + +where :math:`x_k`, :math:`y_k`,and :math:`z_k` are the location coordinates in +two coordinate systems, :math:`T_{12}` is the coordinate transformation from +coordinate system "1" to "2", :math:`x_0`, :math:`y_0`, and :math:`z_0` is the +location of the origin of coordinate system "1" in coordinate system "2", and +:math:`R_{jk}` are the elements of the rotation matrix relating the two +coordinate systems. The coordinate transformations are present in different +files produced by FreeSurfer and MNE. +The fixed transformations :math:`T_-` and :math:`T_+` are: + +.. math:: T_{-} = \begin{bmatrix} + 0.99 & 0 & 0 & 0 \\ + 0 & 0.9688 & 0.042 & 0 \\ + 0 & -0.0485 & 0.839 & 0 \\ + 0 & 0 & 0 & 1 + \end{bmatrix} + +and + +.. math:: T_{+} = \begin{bmatrix} + 0.99 & 0 & 0 & 0 \\ + 0 & 0.9688 & 0.046 & 0 \\ + 0 & -0.0485 & 0.9189 & 0 \\ + 0 & 0 & 0 & 1 + \end{bmatrix} + +.. note:: + This section does not discuss the transformation between the MRI voxel + indices and the different MRI coordinates. However, it is important to note + that in FreeSurfer, MNE, as well as in Neuromag software an integer voxel + coordinate corresponds to the location of the center of a voxel. Detailed + information on the FreeSurfer MRI systems can be found at + https://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems. + The symbols :math:`T_x` are defined in :ref:`coordinate_system_figure`. + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.3\linewidth}|p{0.5\linewidth}| +.. table:: Coordinate transformations in FreeSurfer and MNE software packages. + + +------------------------------+-------------------------------+-------------------------------------------------+ + | Transformation | FreeSurfer | MNE | + +------------------------------+-------------------------------+-------------------------------------------------+ + | :math:`T_1` | Not present | | Measurement data files | + | | | | Forward solution files (`*fwd.fif`) | + | | | | Inverse operator files (`*inv.fif`) | + +------------------------------+-------------------------------+-------------------------------------------------+ + | :math:`T_{s_1}\dots T_{s_n}` | Not present | Channel information in files | + | | | containing :math:`T_1`. | + +------------------------------+-------------------------------+-------------------------------------------------+ + | :math:`T_2` | Not present | | MRI description filesSeparate | + | | | | Separate ``-trans.fif`` files | + | | | | from :ref:`gen_mne_coreg` | + | | | | Forward solution files | + | | | | Inverse operator files | + +------------------------------+-------------------------------+-------------------------------------------------+ + | :math:`T_3` | `mri/*mgz` files | :class:`nibabel.freesurfer.mghformat.MGHImage` | + +------------------------------+-------------------------------+-------------------------------------------------+ + | :math:`T_4` | mri/transforms/talairach.xfm | Internal reading | + +------------------------------+-------------------------------+-------------------------------------------------+ + | :math:`T_-` | Hardcoded in software | Hardcoded in software. | + +------------------------------+-------------------------------+-------------------------------------------------+ + | :math:`T_+` | Hardcoded in software | Hardcoded in software. | + +------------------------------+-------------------------------+-------------------------------------------------+ + +.. _head_device_coords: + +The head and device coordinate systems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: ../_images/HeadCS.png + :alt: Head coordinate system + + The head coordinate system + +The MEG/EEG head coordinate system employed in the MNE software is a +right-handed Cartesian coordinate system. The direction of :math:`x` axis is +from left to right, that of :math:`y` axis to the front, and the :math:`z` axis +thus points up. + +The :math:`x` axis of the head coordinate system passes through the two +periauricular or preauricular points digitized before acquiring the data with +positive direction to the right. The :math:`y` axis passes through the nasion +and is normal to the :math:`x` axis. The :math:`z` axis points up according to +the right-hand rule and is normal to the :math:`xy` plane. + +The origin of the MEG device coordinate system is device dependent. Its origin +is located approximately at the center of a sphere which fits the occipital +section of the MEG helmet best with :math:`x` axis axis going from left to +right and :math:`y` axis pointing front. The :math:`z` axis is, again, normal +to the :math:`xy` plane with positive direction up. + +.. note:: + The above definition is identical to that of the Neuromag MEG/EEG (head) + coordinate system. However, in 4-D Neuroimaging and CTF MEG systems the head + coordinate frame definition is different. The origin of the coordinate + system is at the midpoint of the left and right auricular points. The + :math:`x` axis passes through the nasion and the origin with positive + direction to the front. The :math:`y` axis is perpendicular to the :math:`x` + axis on the and lies in the plane defined by the three fiducial landmarks, + positive direction from right to left. The :math:`z` axis is normal to the + plane of the landmarks, pointing up. Note that in this convention the + auricular points are not necessarily located on :math:`y` coordinate axis. + The file conversion utilities take care of these idiosyncrasies and convert + all coordinate information to the MNE software head coordinate frame. + +Creating a surface-based source space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The fif format source space files containing the dipole locations and +orientations are created with :func:`mne.setup_source_space`. + +Creating a volumetric or discrete source space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to source spaces confined to a surface, the MNE software provides +some support for three-dimensional source spaces bounded by a surface as well +as source spaces comprised of discrete, arbitrarily located source points. The +:func:`mne.setup_volume_source_space` utility assists in generating such source +spaces. + +Creating the BEM meshes +~~~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`bem-model`. + +Topology checks +--------------- + +The following topology checks are performed during the creation of BEM models: + +- The completeness of each surface is confirmed by calculating the total solid + angle subtended by all triangles from a point inside the triangulation. The + result should be very close to :math:`4 \pi`. If the result is :math:`-4 \pi` + instead, it is conceivable that the ordering of the triangle vertices is + incorrect and the ``--swap`` option should be specified. + +- The correct ordering of the surfaces is verified by checking that the + surfaces are inside each other as expected. This is accomplished by checking + that the sum solid angles subtended by triangles of a surface :math:`S_k` at + all vertices of another surface :math:`S_p` which is supposed to be inside it + equals :math:`4 \pi`. Naturally, this check is applied only if the model has + more than one surface. Since the surface relations are transitive, it is + enough to check that the outer skull surface is inside the skin surface and + that the inner skull surface is inside the outer skull one. + +- The extent of each of the triangulated volumes is checked. If the extent is + smaller than 50mm, an error is reported. This may indicate that the vertex + coordinates have been specified in meters instead of millimeters. + + +Computing the BEM geometry data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The utility :func:`mne.make_bem_solution` computes the geometry information for +BEM. + +.. _coil_geometry_information: + +Coil geometry information +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This Section explains the presentation of MEG detection coil geometry +information the approximations used for different detection coils in MNE +software. Two pieces of information are needed to characterize the detectors: + +- The location and orientation a local coordinate system for each detector. + +- A unique identifier, which has an one-to-one correspondence to the + geometrical description of the coil. + +.. note:: MNE ships with several coil geometry configurations. They can be + found in ``mne/data``. See :ref:`ex-plot-meg-sensors` for a + comparison between different coil geometries, and + :ref:`implemented_coil_geometries` for detailed information regarding + the files describing Neuromag coil geometries. + + +The sensor coordinate system +---------------------------- + +The sensor coordinate system is completely characterized by the location of its +origin and the direction cosines of three orthogonal unit vectors pointing to +the directions of the x, y, and z axis. In fact, the unit vectors contain +redundant information because the orientation can be uniquely defined with +three angles. The measurement fif files list these data in MEG device +coordinates. Transformation to the MEG head coordinate frame can be easily +accomplished by applying the device-to-head coordinate transformation matrix +available in the data files provided that the head-position indicator was used. +Optionally, the MNE software forward calculation applies another coordinate +transformation to the head-coordinate data to bring the coil locations and +orientations to the MRI coordinate system. + +If :math:`r_0` is a row vector for the origin of the local sensor coordinate +system and :math:`e_x`, :math:`e_y`, and :math:`e_z` are the row vectors for +the three orthogonal unit vectors, all given in device coordinates, a location +of a point :math:`r_C` in sensor coordinates is transformed to device +coordinates (:math:`r_D`) by + +.. math:: [r_D 1] = [r_C 1] T_{CD}\ , + +where + +.. math:: T = \begin{bmatrix} + e_x & 0 \\ + e_y & 0 \\ + e_z & 0 \\ + r_{0D} & 1 + \end{bmatrix}\ . + +Calculation of the magnetic field +--------------------------------- + +The forward calculation in the MNE software computes the signals detected by +each MEG sensor for three orthogonal dipoles at each source space location. +This requires specification of the conductor model, the location and +orientation of the dipoles, and the location and orientation of each MEG sensor +as well as its coil geometry. + +The output of each SQUID sensor is a weighted sum of the magnetic fluxes +threading the loops comprising the detection coil. Since the flux threading a +coil loop is an integral of the magnetic field component normal to the coil +plane, the output of the k :sup:`th` MEG channel, :math:`b_k` can be +approximated by: + +.. math:: b_k = \sum_{p = 1}^{N_k} {w_{kp} B(r_{kp}) \cdot n_{kp}} + +where :math:`r_{kp}` are a set of :math:`N_k` integration points covering the +pickup coil loops of the sensor, :math:`B(r_{kp})` is the magnetic field due to +the current sources calculated at :math:`r_{kp}`, :math:`n_{kp}` are the coil +normal directions at these points, and :math:`w_{kp}` are the weights +associated to the integration points. This formula essentially presents +numerical integration of the magnetic field over the pickup loops of sensor +:math:`k`. + +There are three accuracy levels for the numerical integration expressed above. +The *simple* accuracy means the simplest description of the coil. This accuracy +is not used in the MNE forward calculations. The *normal* or *recommended* +accuracy typically uses two integration points for planar gradiometers, one in +each half of the pickup coil and four evenly distributed integration points for +magnetometers. This is the default accuracy used by MNE. If the ``--accurate`` +option is specified, the forward calculation typically employs a total of eight +integration points for planar gradiometers and sixteen for magnetometers. +Detailed information about the integration points is given in the next section. + + +.. _implemented_coil_geometries: + +Implemented coil geometries +--------------------------- + +This section describes the coil geometries currently implemented +in MNE. The coil types fall in two general categories: + +- Axial gradiometers and planar gradiometers + and + +- Planar magnetometers. + +For axial sensors, the *z* axis of the local coordinate system is parallel to +the field component detected, *i.e.*, normal to the coil plane.For circular +coils, the orientation of the *x* and *y* axes on the plane normal to the z +axis is irrelevant. In the square coils employed in the Vectorview (TM) system +the *x* axis is chosen to be parallel to one of the sides of the magnetometer +coil. For planar sensors, the *z* axis is likewise normal to the coil plane and +the x axis passes through the centerpoints of the two coil loops so that the +detector gives a positive signal when the normal field component increases +along the *x* axis. + +:ref:`normal_coil_descriptions` lists the parameters of the *normal* coil +geometry descriptions :ref:`accurate_coil_descriptions` lists the *accurate* +descriptions. For simple accuracy, please consult the coil definition file, see +:ref:`coil_definition_file`. The columns of the tables contain the following +data: + +- The number identifying the coil id. + This number is used in the coil descriptions found in the FIF files. + +- Description of the coil. + +- Number of integration points used + +- The locations of the integration points in sensor coordinates. + +- Weights assigned to the field values at the integration points. + Some formulas are listed instead of the numerical values to demonstrate + the principle of the calculation. For example, in the normal coil + descriptions of the planar gradiometers the weights are inverses + of the baseline of the gradiometer to show that the output is in + T/m. + +.. note:: The coil geometry information is stored in the file + :file:`mne/data/coil_def.dat`, which is + automatically created by the MNE-C utility ``mne_list_coil_def``. + +.. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.1\linewidth}|p{0.25\linewidth}|p{0.2\linewidth}| +.. _normal_coil_descriptions: +.. table:: Normal coil descriptions. + + +------+-------------------------+----+----------------------------------+----------------------+ + | Id | Description | n | r/mm | w | + +======+=========================+====+==================================+======================+ + | 2 | Neuromag-122 | 2 | (+/-8.1, 0, 0) mm | +/-1 ⁄ 16.2mm | + | | planar gradiometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 2000 | A point magnetometer | 1 | (0, 0, 0)mm | 1 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3012 | Vectorview type 1 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | + | | planar gradiometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3013 | Vectorview type 2 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | + | | planar gradiometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3022 | Vectorview type 1 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3023 | Vectorview type 2 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3024 | Vectorview type 3 | 4 | (+/-5.25, +/-5.25, 0.3)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 2000 | An ideal point | 1 | (0.0, 0.0, 0.0)mm | 1 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4001 | Magnes WH | 4 | (+/-5.75, +/-5.75, 0.0)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4002 | Magnes WH 3600 | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | + | | axial gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4003 | Magnes reference | 4 | (+/-7.5, +/-7.5, 0.0)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4004 | Magnes reference | 8 | (+/-20, +/-20, 0.0)mm | 1/4 | + | | gradiometer measuring | | (+/-20, +/-20, 135)mm | -1/4 | + | | diagonal gradients | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4005 | Magnes reference | 8 | (87.5, +/-20, 0.0)mm | 1/4 | + | | gradiometer measuring | | (47.5, +/-20, 0.0)mm | -1/4 | + | | off-diagonal gradients | | (-87.5, +/-20, 0.0)mm | 1/4 | + | | | | (-47.5, +/-20, 0.0)mm | -1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 5001 | CTF 275 axial | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | + | | gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 5002 | CTF reference | 4 | (+/-4, +/-4, 0.0)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 5003 | CTF reference | 8 | (+/-8.6, +/-8.6, 0.0)mm | 1/4 | + | | gradiometer measuring | | (+/-8.6, +/-8.6, 78.6)mm | -1/4 | + | | diagonal gradients | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + +.. note:: If a plus-minus sign occurs in several coordinates, all possible + combinations have to be included. + +.. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.05\linewidth}|p{0.25\linewidth}|p{0.15\linewidth}| +.. _accurate_coil_descriptions: +.. table:: Accurate coil descriptions + + +------+-------------------------+----+----------------------------------+----------------------+ + | Id | Description | n | r/mm | w | + +======+=========================+====+==================================+======================+ + | 2 | Neuromag-122 planar | 8 | +/-(8.1, 0, 0) mm | +/-1 ⁄ 16.2mm | + | | gradiometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 2000 | A point magnetometer | 1 | (0, 0, 0) mm | 1 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3012 | Vectorview type 1 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | + | | planar gradiometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3013 | Vectorview type 2 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | + | | planar gradiometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3022 | Vectorview type 1 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3023 | Vectorview type 2 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 3024 | Vectorview type 3 | 4 | (+/-5.25, +/-5.25, 0.3)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4001 | Magnes WH magnetometer | 4 | (+/-5.75, +/-5.75, 0.0)mm | 1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4002 | Magnes WH 3600 | 4 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | + | | axial gradiometer | | (+/-4.5, +/-4.5, 0.0)mm | -1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4004 | Magnes reference | 8 | (+/-20, +/-20, 0.0)mm | 1/4 | + | | gradiometer measuring | | (+/-20, +/-20, 135)mm | -1/4 | + | | diagonal gradients | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 4005 | Magnes reference | 8 | (87.5, +/-20, 0.0)mm | 1/4 | + | | gradiometer measuring | | (47.5, +/-20, 0.0)mm | -1/4 | + | | off-diagonal gradients | | (-87.5, +/-20, 0.0)mm | 1/4 | + | | | | (-47.5, +/-20, 0.0)mm | -1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 5001 | CTF 275 axial | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | + | | gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 5002 | CTF reference | 4 | (+/-4, +/-4, 0.0)mm | 1/4 | + | | magnetometer | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 5003 | CTF 275 reference | 8 | (+/-8.6, +/-8.6, 0.0)mm | 1/4 | + | | gradiometer measuring | | (+/-8.6, +/-8.6, 78.6)mm | -1/4 | + | | diagonal gradients | | | | + +------+-------------------------+----+----------------------------------+----------------------+ + | 5004 | CTF 275 reference | 8 | (47.8, +/-8.5, 0.0)mm | 1/4 | + | | gradiometer measuring | | (30.8, +/-8.5, 0.0)mm | -1/4 | + | | off-diagonal gradients | | (-47.8, +/-8.5, 0.0)mm | 1/4 | + | | | | (-30.8, +/-8.5, 0.0)mm | -1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + | 6001 | MIT KIT system axial | 8 | (+/-3.875, +/-3.875, 0.0)mm | 1/4 | + | | gradiometer | | (+/-3.875, +/-3.875, 0.0)mm | -1/4 | + +------+-------------------------+----+----------------------------------+----------------------+ + + +.. _coil_definition_file: + +The coil definition file +------------------------ + +The coil geometry information is stored in the text file +:file:`{$MNE_ROOT}/share/mne/coil_def.dat`. In this file, any lines starting +with the pound sign (#) are comments. A coil definition starts with a +description line containing the following fields: + +- :samp:`{}`: A number indicating class of this coil. + +- :samp:`{}`: Coil ID value. This value is listed in the first column of + Tables :ref:`normal_coil_descriptions` and :ref:`accurate_coil_descriptions`. + +- :samp:`{}`: The coil representation accuracy. Possible values and + their meanings are listed in :ref:`coil_accuracies`. + +- :samp:`{}`: Number of integration points in this representation. + +- :samp:`{}`: The size of the coil. For circular coils this is the + diameter of the coil and for square ones the side length of the square. This + information is mainly included to facilitate drawing of the coil geometry. It + should not be employed to infer a coil approximation for the forward + calculations. + +- :samp:`{}`: The baseline of a this kind of a coil. This will be + zero for magnetometer coils. This information is mainly included to + facilitate drawing of the coil geometry. It should not be employed to infer + a coil approximation for the forward calculations. + +- :samp:`{}`: Short description of this kind of a coil. If the + description contains several words, it is enclosed in quotes. + + +.. tabularcolumns:: |p{0.1\linewidth}|p{0.5\linewidth}| +.. _coil_accuracies: +.. table:: Coil representation accuracies. + + ======= ==================================================================================== + Value Meaning + ======= ==================================================================================== + 1 The simplest representation available + 2 The standard or *normal* representation (see :ref:`normal_coil_descriptions`) + 3 The most *accurate* representation available (see :ref:`accurate_coil_descriptions`) + ======= ==================================================================================== + +Each coil description line is followed by one or more integration point lines, +consisting of seven numbers: + +- :samp:`{}`: Gives the weight for this integration point (last column + in Tables :ref:`normal_coil_descriptions` and + :ref:`accurate_coil_descriptions`). + +- :samp:`{} {} {}`: Indicates the location of the integration + point (fourth column in Tables :ref:`normal_coil_descriptions` and + :ref:`accurate_coil_descriptions`). + +- :samp:`{} {} {}`: Components of a unit vector indicating the + field component to be selected. Note that listing a separate unit vector for + each integration points allows the implementation of curved coils and coils + with the gradiometer loops tilted with respect to each other. + + +Computing the forward solution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Purpose +------- + +Examples on how to compute the forward solution in MNE-Python using +:func:`mne.make_forward_solution` can be found +:ref:`plot_forward_compute_forward_solution` and +:ref:`computing_the_forward_solution`. + +Implementation of software gradient compensation +------------------------------------------------ + +Accounting for noise cancellation in MNE-Python is accomplished in +:meth:`mne.io.Raw.apply_gradient_compensation`. See +:ref:`plot_brainstorm_phantom_ctf` for an example. + +CTF and 4D Neuroimaging data may have been subjected to noise cancellation +employing the data from the reference sensor array. Even though these sensor +are rather far away from the brain sources, :func:`mne.make_forward_solution` +takes them into account in the computations. If the data file has software +gradient compensation activated, it computes the field of at the reference +sensors in addition to the main MEG sensor array and computes a compensated +forward solution`. + +The EEG sphere model definition file +------------------------------------ + +In MNE-Python, different sphere models can be specified through +:func:`mne.make_sphere_model`. The default model has the following structure: + +.. tabularcolumns:: |p{0.1\linewidth}|p{0.25\linewidth}|p{0.2\linewidth}| +.. table:: Structure of the default EEG model + + ======== ======================= ======================= + Layer Relative outer radius :math:`\sigma` (S/m) + ======== ======================= ======================= + Head 1.0 0.33 + Skull 0.97 0.04 + CSF 0.92 1.0 + Brain 0.90 0.33 + ======== ======================= ======================= + +Although it is not BEM model per se the ``sphere`` structure describes the head +geometry so it can be passed as ``bem`` parameter in MNE-Python functions such +as :func:`mne.fit_dipole`, :func:`mne.viz.plot_alignment` or +:func:`mne.make_forward_solution`. + +.. _eeg_sphere_model: + +EEG forward solution in the sphere model +---------------------------------------- + +.. sidebar:: Sphere-model examples in MNE-Python + + For examples of using the sphere model when computing the forward model + (using :func:`mne.make_forward_solution`), see :ref:`Brainstorm CTF phantom + dataset tutorial `, + :ref:`Brainstorm Elekta phantom dataset tutorial + `, and + :ref:`plot_source_alignment_without_mri`. + +When the sphere model is employed, the computation of the EEG solution can be +substantially accelerated by using approximation methods described by Mosher, +Zhang, and Berg, see :ref:`CEGEGDEI` (Mosher *et al.* and references therein). +:func:`mne.make_forward_solution` approximates the solution with three dipoles +in a homogeneous sphere whose locations and amplitudes are determined by +minimizing the cost function: + +.. math:: + S(r_1,\dotsc,r_m\ ,\ \mu_1,\dotsc,\mu_m) = \int_{scalp} {(V_{true} - V_{approx})}\,dS + +where :math:`r_1,\dotsc,r_m` and :math:`\mu_1,\dotsc,\mu_m` are the locations +and amplitudes of the approximating dipoles and :math:`V_{true}` and +:math:`V_{approx}` are the potential distributions given by the true and +approximative formulas, respectively. It can be shown that this integral can be +expressed in closed form using an expansion of the potentials in spherical +harmonics. The formula is evaluated for the most superficial dipoles, *i.e.*, +those lying just inside the inner skull surface. + +Averaging forward solutions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One possibility to make a grand average over several runs of a experiment is to +average the data across runs and average the forward solutions accordingly. For +this purpose, :func:`mne.average_forward_solutions` computes a weighted average +of several forward solutions. The function averages both MEG and EEG forward +solutions. Usually the EEG forward solution is identical across runs because +the electrode locations do not change. diff -Nru python-mne-0.18.1+dfsg/doc/_includes/inverse.rst python-mne-0.19.1+dfsg/doc/_includes/inverse.rst --- python-mne-0.18.1+dfsg/doc/_includes/inverse.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/inverse.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,451 @@ +.. _ch_mne: + +The minimum-norm current estimates +================================== + +This page describes the mathematical concepts and the computation of the +minimum-norm estimates needed in order to obtain the linear inverse operator. + +.. contents:: Page contents + :local: + :depth: 2 + +Overview +~~~~~~~~ + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`ch_mne` to link to that section of the implementation.rst page. + The next line is a target for :start-after: so we can omit the title from + the include: + inverse-begin-content + + +Computing the inverse operator is accomplished using +:func:`mne.minimum_norm.make_inverse_operator` and +:func:`mne.minimum_norm.apply_inverse`. The use of these functions is presented +in the tutorial :ref:`tut-inverse-methods`. + +.. _minimum_norm_estimates: + +Minimum-norm estimates +~~~~~~~~~~~~~~~~~~~~~~ + +This section describes the mathematical details of the calculation of +minimum-norm estimates. In Bayesian sense, the ensuing current distribution is +the maximum a posteriori (MAP) estimate under the following assumptions: + +- The viable locations of the currents are constrained to the cortex. + Optionally, the current orientations can be fixed to be normal to the + cortical mantle. + +- The amplitudes of the currents have a Gaussian prior distribution with a + known source covariance matrix. + +- The measured data contain additive noise with a Gaussian distribution with a + known covariance matrix. The noise is not correlated over time. + +The linear inverse operator +--------------------------- + +The measured data in the source estimation procedure consists of MEG and EEG +data, recorded on a total of N channels. The task is to estimate a total of M +strengths of sources located on the cortical mantle. If the number of source +locations is P, M = P for fixed-orientation sources and M = 3P if the source +orientations are unconstrained. The regularized linear inverse operator +following from the Bayesian approach is given by the :math:`M \times N` matrix + +.. math:: M = R' G^T (G R' G^T + C)^{-1}\ , + +.. sidebar:: Inverse operators in MNE-Python + + For computational convenience, in MNE-Python the linear inverse operator is + not computed explicitly. See :ref:`mne_solution` for mathematical + details, and :ref:`CIHCFJEI` for a detailed example. + +where G is the gain matrix relating the source strengths to the measured +MEG/EEG data, :math:`C` is the data noise-covariance matrix and :math:`R'` is +the source covariance matrix. The dimensions of these matrices are :math:`N +\times M`, :math:`N \times N`, and :math:`M \times M`, respectively. The +:math:`M \times 1` source-strength vector is obtained by multiplying the +:math:`N \times 1` data vector by :math:`M`. + +The expected value of the current amplitudes at time *t* is then given by +:math:`\hat{j}(t) = Mx(t)`, where :math:`x(t)` is a vector containing the +measured MEG and EEG data values at time *t*. + +.. _mne_regularization: + +Regularization +-------------- + +The a priori variance of the currents is, in practise, unknown. We can express +this by writing :math:`R' = R/ \lambda^2`, which yields the inverse operator + +.. math:: M = R G^T (G R G^T + \lambda^2 C)^{-1}\ , + +where the unknown current amplitude is now interpreted in terms of the +regularization parameter :math:`\lambda^2`. Small :math:`\lambda^2` corresponds +to large current amplitudes and complex estimate current patterns while a large +:math:`\lambda^2` means the amplitude of the current is limited and a simpler, +smooth, current estimate is obtained. + +We can arrive in the regularized linear inverse operator +also by minimizing the cost function + +.. math:: S = \tilde{e}^T \tilde{e} + \lambda^2 j^T R^{-1} j\ , + +where the first term consists of the difference between the whitened measured +data (see :ref:`whitening_and_scaling`) and those predicted by the model while the +second term is a weighted-norm of the current estimate. It is seen that, with +increasing :math:`\lambda^2`, the source term receive more weight and larger +discrepancy between the measured and predicted data is tolerable. + +.. _whitening_and_scaling: + +Whitening and scaling +--------------------- + +The MNE software employs data whitening so that a 'whitened' inverse operator +assumes the form + +.. math:: \tilde{M} = R \tilde{G}^T (\tilde{G} R \tilde{G}^T + I)^{-1}\ , + +where :math:`\tilde{G} = C^{-^1/_2}G` is the spatially whitened gain matrix. +The expected current values are :math:`\hat{j} = Mx(t)`, where :math:`x(t) = +C^{-^1/_2}x(t)` is a the whitened measurement vector at *t*. The spatial +whitening operator is obtained with the help of the eigenvalue decomposition +:math:`C = U_C \Lambda_C^2 U_C^T` as :math:`C^{-^1/_2} = \Lambda_C^{-1} U_C^T`. +In the MNE software the noise-covariance matrix is stored as the one applying +to raw data. To reflect the decrease of noise due to averaging, this matrix, +:math:`C_0`, is scaled by the number of averages, :math:`L`, *i.e.*, :math:`C = +C_0 / L`. + +As shown above, regularization of the inverse solution is equivalent to a +change in the variance of the current amplitudes in the Bayesian *a priori* +distribution. + +A convenient choice for the source-covariance matrix :math:`R` is such that +:math:`\text{trace}(\tilde{G} R \tilde{G}^T) / \text{trace}(I) = 1`. With this +choice we can approximate :math:`\lambda^2 \sim 1/SNR`, where SNR is the +(power) signal-to-noise ratio of the whitened data. + +.. note:: + The definition of the signal to noise-ratio/ :math:`\lambda^2` relationship + given above works nicely for the whitened forward solution. In the + un-whitened case scaling with the trace ratio :math:`\text{trace}(GRG^T) / + \text{trace}(C)` does not make sense, since the diagonal elements summed + have, in general, different units of measure. For example, the MEG data are + expressed in T or T/m whereas the unit of EEG is Volts. + +See :ref:`tut_compute_covariance` for example of noise covariance computation +and whitening. + +.. _cov_regularization_math: + +Regularization of the noise-covariance matrix +--------------------------------------------- + +Since finite amount of data is usually available to compute an estimate of the +noise-covariance matrix :math:`C`, the smallest eigenvalues of its estimate are +usually inaccurate and smaller than the true eigenvalues. Depending on the +seriousness of this problem, the following quantities can be affected: + +- The model data predicted by the current estimate, + +- Estimates of signal-to-noise ratios, which lead to estimates of the required + regularization, see :ref:`mne_regularization`, + +- The estimated current values, and + +- The noise-normalized estimates, see :ref:`noise_normalization`. + +Fortunately, the latter two are least likely to be affected due to +regularization of the estimates. However, in some cases especially the EEG part +of the noise-covariance matrix estimate can be deficient, *i.e.*, it may +possess very small eigenvalues and thus regularization of the noise-covariance +matrix is advisable. + +Historically, the MNE software accomplishes the regularization by replacing a +noise-covariance matrix estimate :math:`C` with + +.. math:: C' = C + \sum_k {\varepsilon_k \bar{\sigma_k}^2 I^{(k)}}\ , + +where the index :math:`k` goes across the different channel groups (MEG planar +gradiometers, MEG axial gradiometers and magnetometers, and EEG), +:math:`\varepsilon_k` are the corresponding regularization factors, +:math:`\bar{\sigma_k}` are the average variances across the channel groups, and +:math:`I^{(k)}` are diagonal matrices containing ones at the positions +corresponding to the channels contained in each channel group. + +See :ref:`plot_compute_covariance_howto` for details on computing and +regularizing the channel covariance matrix. + +.. _mne_solution: + +Computation of the solution +--------------------------- + +The most straightforward approach to calculate the MNE is to employ expression +for the original or whitened inverse operator directly. However, for +computational convenience we prefer to take another route, which employs the +singular-value decomposition (SVD) of the matrix + +.. math:: A = \tilde{G} R^{^1/_2} = U \Lambda V^T + +where the superscript :math:`^1/_2` indicates a square root of :math:`R`. For a +diagonal matrix, one simply takes the square root of :math:`R` while in the +more general case one can use the Cholesky factorization :math:`R = R_C R_C^T` +and thus :math:`R^{^1/_2} = R_C`. + +With the above SVD it is easy to show that + +.. math:: \tilde{M} = R^{^1/_2} V \Gamma U^T + +where the elements of the diagonal matrix :math:`\Gamma` are + +.. math:: \gamma_k = \frac{1}{\lambda_k} \frac{\lambda_k^2}{\lambda_k^2 + \lambda^2}\ . + +With :math:`w(t) = U^T C^{-^1/_2} x(t)` the expression for the expected current +is + +.. math:: \hat{j}(t) = R^C V \Gamma w(t) = \sum_k {\bar{v_k} \gamma_k w_k(t)}\ , + +where :math:`\bar{v_k} = R^C v_k`, :math:`v_k` being the :math:`k` th column of +:math:`V`. It is thus seen that the current estimate is a weighted sum of the +'modified' eigenleads :math:`v_k`. + +It is easy to see that :math:`w(t) \propto \sqrt{L}`. To maintain the relation +:math:`(\tilde{G} R \tilde{G}^T) / \text{trace}(I) = 1` when :math:`L` changes +we must have :math:`R \propto 1/L`. With this approach, :math:`\lambda_k` is +independent of :math:`L` and, for fixed :math:`\lambda`, we see directly that +:math:`j(t)` is independent of :math:`L`. + +.. sidebar:: Computing the solution in MNE-Python + + In MNE-Python the minimum-norm estimate is computed using + :func:`mne.minimum_norm.make_inverse_operator` and its usage is illustrated + in :ref:`CIHCFJEI`. + + +.. _noise_normalization: + +Noise normalization +------------------- + +The noise-normalized linear estimates introduced by Dale et al. [2]_ require +division of the expected current amplitude by its variance. Noise normalization +serves three purposes: + +- It converts the expected current value into a dimensionless statistical test + variable. Thus the resulting time and location dependent values are often + referred to as dynamic statistical parameter maps (dSPM). + +- It reduces the location bias of the estimates. In particular, the tendency of + the MNE to prefer superficial currents is eliminated. + +- The width of the point-spread function becomes less dependent on the source + location on the cortical mantle. The point-spread is defined as the MNE + resulting from the signals coming from a point current source (a current + dipole) located at a certain point on the cortex. + +In practice, noise normalization requires the computation of the diagonal +elements of the matrix + +.. math:: M C M^T = \tilde{M} \tilde{M}^T\ . + +With help of the singular-value decomposition approach we see directly that + +.. math:: \tilde{M} \tilde{M}^T\ = \bar{V} \Gamma^2 \bar{V}^T\ . + +Under the conditions expressed at the end of :ref:`mne_solution`, it +follows that the *t*-statistic values associated with fixed-orientation +sources) are thus proportional to :math:`\sqrt{L}` while the *F*-statistic +employed with free-orientation sources is proportional to :math:`L`, +correspondingly. + +.. note:: + The MNE software usually computes the *square roots* of the F-statistic to + be displayed on the inflated cortical surfaces. These are also proportional + to :math:`\sqrt{L}`. + +Predicted data +-------------- + +Under noiseless conditions the SNR is infinite and thus leads to +:math:`\lambda^2 = 0` and the minimum-norm estimate explains the measured data +perfectly. Under realistic conditions, however, :math:`\lambda^2 > 0` and there +is a misfit between measured data and those predicted by the MNE. Comparison of +the predicted data, here denoted by :math:`x(t)`, and measured one can give +valuable insight on the correctness of the regularization applied. + +In the SVD approach we easily find + +.. math:: \hat{x}(t) = G \hat{j}(t) = C^{^1/_2} U \Pi w(t)\ , + +where the diagonal matrix :math:`\Pi` has elements :math:`\pi_k = \lambda_k +\gamma_k` The predicted data is thus expressed as the weighted sum of the +'recolored eigenfields' in :math:`C^{^1/_2} U`. + +Cortical patch statistics +------------------------- + +.. sidebar:: Cortical patch statistics in MNE-Python + + In MNE-Python, the ``use_cps`` parameter in + :func:`mne.convert_forward_solution`, and + :func:`mne.minimum_norm.make_inverse_operator` controls whether to use + cortical patch statistics (CPS) to define normal orientations or not (see + :ref:`CHDBBCEJ`). + +If the ``add_dists=True`` option was used in source space creation, +the source space file will contain +Cortical Patch Statistics (CPS) for each vertex of the cortical surface. The +CPS provide information about the source space point closest to it as well as +the distance from the vertex to this source space point. The vertices for which +a given source space point is the nearest one define the cortical patch +associated with with the source space point. Once these data are available, it +is straightforward to compute the following cortical patch statistics for each +source location :math:`d`: + +- The average over the normals of at the vertices in a patch, + :math:`\bar{n_d}`, + +- The areas of the patches, :math:`A_d`, and + +- The average deviation of the vertex normals in a patch from their average, + :math:`\sigma_d`, given in degrees. + +.. _inverse_orientation_constrains: + +The orientation constraints +--------------------------- + +.. sidebar:: Orientation constraints in MNE-Python + + In MNE-Python, rigid orientation is employed by specifying ``fixed=True`` in + :func:`mne.minimum_norm.make_inverse_operator` (forcing dipole orientation + to be orthogonal to the cortical surface, pointing outwards). If cortical + patch statistics are available the average normal over each patch, + :math:`\bar{n_d}`, are used to define the source orientation. Otherwise, the + vertex normal at the source space location is employed. See + :ref:`plot_dipole_orientations_fixed_orientations`. + + The *fLOC* is employed by specifying ``fixed=False`` and ``loose=1.0`` when + calling :func:`mne.minimum_norm.make_inverse_operator`. See + :ref:`plot_dipole_orientations_fLOC_orientations`. + + The *vLOC* is employed by specifying ``fixed=False`` and ``loose`` + parameters when calling :func:`mne.minimum_norm.make_inverse_operator`. This + is similar to *fLOC* except that the value given with the ``loose`` + parameter will be multiplied by :math:`\sigma_d`, defined above. See + :ref:`plot_dipole_orientations_vLOC_orientations`. + +The principal sources of MEG and EEG signals are generally believed to be +postsynaptic currents in the cortical pyramidal neurons. Since the net primary +current associated with these microscopic events is oriented normal to the +cortical mantle, it is reasonable to use the cortical normal orientation as a +constraint in source estimation. In addition to allowing completely free source +orientations, the MNE software implements three orientation constraints based +of the surface normal data: + +- Source orientation can be rigidly fixed to the surface normal direction (the + ``--fixed`` option). If cortical patch statistics are available the average + normal over each patch, :math:`\bar{n_d}`, are used to define the source + orientation. Otherwise, the vertex normal at the source space location is + employed. + +- A *location independent or fixed loose orientation constraint* (fLOC) can be + employed (the ``--loose`` option). In this approach, a source coordinate + system based on the local surface orientation at the source location is + employed. By default, the three columns of the gain matrix G, associated with + a given source location, are the fields of unit dipoles pointing to the + directions of the :math:`x`, :math:`y`, and :math:`z` axis of the coordinate + system employed in the forward calculation (usually the :ref:`MEG head + coordinate frame `). For LOC the orientation is changed so + that the first two source components lie in the plane normal to the surface + normal at the source location and the third component is aligned with it. + Thereafter, the variance of the source components tangential to the cortical + surface are reduced by a factor defined by the ``--loose`` option. + +- A *variable loose orientation constraint* (vLOC) can be employed (the + ``--loosevar`` option). This is similar to fLOC except that the value given + with the ``--loosevar`` option will be multiplied by :math:`\sigma_d`, + defined above. + +Depth weighting +--------------- + +.. sidebar:: Adjusting depth weighting in MNE-Python + + The maximal amount of depth weighting can be adjusted with ``depth`` + parameter in :func:`mne.minimum_norm.make_inverse_operator`. + +The minimum-norm estimates have a bias towards superficial currents. This +tendency can be alleviated by adjusting the source covariance matrix :math:`R` +to favor deeper source locations. In the depth weighting scheme employed in MNE +analyze, the elements of :math:`R` corresponding to the :math:`p` th source +location are be scaled by a factor + +.. math:: f_p = (g_{1p}^T g_{1p} + g_{2p}^T g_{2p} + g_{3p}^T g_{3p})^{-\gamma}\ , + +where :math:`g_{1p}`, :math:`g_{2p}`, and :math:`g_{3p}` are the three columns +of :math:`G` corresponding to source location :math:`p` and :math:`\gamma` is +the order of the depth weighting, which is specified via the ``depth`` option. + +Effective number of averages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is often the case that the epoch to be analyzed is a linear combination over +conditions rather than one of the original averages computed. As stated above, +the noise-covariance matrix computed is originally one corresponding to raw +data. Therefore, it has to be scaled correctly to correspond to the actual or +effective number of epochs in the condition to be analyzed. In general, we have + +.. math:: C = C_0 / L_{eff} + +where :math:`L_{eff}` is the effective number of averages. To calculate +:math:`L_{eff}` for an arbitrary linear combination of conditions + +.. math:: y(t) = \sum_{i = 1}^n {w_i x_i(t)} + +we make use of the the fact that the noise-covariance matrix + +.. math:: C_y = \sum_{i = 1}^n {w_i^2 C_{x_i}} = C_0 \sum_{i = 1}^n {w_i^2 / L_i} + +which leads to + +.. math:: 1 / L_{eff} = \sum_{i = 1}^n {w_i^2 / L_i} + +An important special case of the above is a weighted average, where + +.. math:: w_i = L_i / \sum_{i = 1}^n {L_i} + +and, therefore + +.. math:: L_{eff} = \sum_{i = 1}^n {L_i} + +Instead of a weighted average, one often computes a weighted sum, a simplest +case being a difference or sum of two categories. For a difference :math:`w_1 = +1` and :math:`w_2 = -1` and thus + +.. math:: 1 / L_{eff} = 1 / L_1 + 1 / L_2 + +or + +.. math:: L_{eff} = \frac{L_1 L_2}{L_1 + L_2} + +Interestingly, the same holds for a sum, where :math:`w_1 = w_2 = 1`. +Generalizing, for any combination of sums and differences, where :math:`w_i = +1` or :math:`w_i = -1`, :math:`i = 1 \dotso n`, we have + +.. math:: 1 / L_{eff} = \sum_{i = 1}^n {1/{L_i}} + +.. target for :end-before: inverse-end-content + +References +~~~~~~~~~~ + +.. [2] Dale AM, Fischl B, Sereno MI (1999). "Cortical surface-based analysis. + I. Segmentation and surface reconstruction." *Neuroimage* 9, 179-94. + doi: 10.1006/nimg.1998.0395 diff -Nru python-mne-0.18.1+dfsg/doc/_includes/memory.rst python-mne-0.19.1+dfsg/doc/_includes/memory.rst --- python-mne-0.18.1+dfsg/doc/_includes/memory.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/memory.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,68 @@ +:orphan: + +Memory-efficient I/O +==================== + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`memory` to link to that section of the implementation.rst + page. The next line is a target for :start-after: so we can omit the title + from the include: + memory-begin-content + + +Preloading continuous (raw) data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MNE-Python can read data on-demand using the ``preload`` option provided in +raw reading functions. For example:: + + from mne import io + from mne.datasets import sample + data_path = sample.data_path() + raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif' + raw = io.read_raw_fif(raw_fname, preload=False) + +.. note:: Filtering, resampling and dropping or selecting channels does not + work with ``preload=False``. + + +Preloading epoched data +~~~~~~~~~~~~~~~~~~~~~~~ + +Similarly, epochs can also be be read from disk on-demand. For example:: + + import mne + events = mne.find_events(raw) + event_id, tmin, tmax = 1, -0.2, 0.5 + picks = mne.pick_types(raw.info, meg=True, eeg=True, stim=False, eog=True) + epochs = mne.Epochs(raw, events, event_id, tmin, tmax, picks=picks, + baseline=(None, 0), reject=dict(eeg=80e-6, eog=150e-6), + preload=False) + +When ``preload=False``, the epochs data is loaded from the disk on-demand. Note +that ``preload=False`` for epochs will work even if the ``raw`` object has been +loaded with ``preload=True``. Preloading is also supported for +:func:`mne.read_epochs`. + +.. warning:: This comes with a caveat. When ``preload=False``, data rejection + based on peak-to-peak thresholds is executed when the data is + loaded from disk, *not* when the ``Epochs`` object is created. + +To explicitly reject artifacts with ``preload=False``, use the function :func:`mne.Epochs.drop_bad`. + + +Loading data explicitly +~~~~~~~~~~~~~~~~~~~~~~~ + +To load the data if ``preload=False`` was initially selected, use the functions :func:`mne.io.Raw.load_data` and :func:`mne.Epochs.load_data`. + + +Accessing data as NumPy arrays +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you just want your raw data as a :class:`Numpy array ` to +work with it in a different framework you can use slicing syntax:: + + first_channel_data, times = raw[0, :] + channels_3_and_4, times = raw[3:5, :] diff -Nru python-mne-0.18.1+dfsg/doc/_includes/morph.rst python-mne-0.19.1+dfsg/doc/_includes/morph.rst --- python-mne-0.18.1+dfsg/doc/_includes/morph.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/morph.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,127 @@ +:orphan: + +Morphing and averaging source estimates +======================================= + +The spherical morphing of BEM surfaces accomplished by FreeSurfer can be +employed to bring data from different subjects into a common anatomical frame. +This page describes utilities which make use of the spherical :term:`morphing` +procedure. :func:`mne.morph_labels` morphs label files between subjects +allowing the definition of labels in a one brain and transforming them to +anatomically analogous labels in another. :meth:`mne.SourceMorph.apply` offers +the capability to transform all subject data to the same space and, +e.g., compute averages of data across subjects. + +.. contents:: Page contents + :local: + :depth: 2 + + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`ch_morph` to link to that section of the implementation.rst page. + The next line is a target for :start-after: so we can omit the title from + the include: + morph-begin-content + + +Why morphing? +~~~~~~~~~~~~~ + +.. sidebar:: Morphing examples in MNE-Python + + Examples of morphing in MNE-Python include :ref:`this tutorial + ` on surface source estimation or these examples on + :ref:`surface ` and :ref:`volumetric ` + source estimation. + +Modern neuroimaging techniques, such as source reconstruction or fMRI analyses, +make use of advanced mathematical models and hardware to map brain activity +patterns into a subject-specific anatomical brain space. This enables the study +of spatio-temporal brain activity. The representation of spatio-temporal brain +data is often mapped onto the anatomical brain structure to relate functional +and anatomical maps. Thereby activity patterns are overlaid with anatomical +locations that supposedly produced the activity. Anatomical MR images are often +used as such or are transformed into an inflated surface representations to +serve as "canvas" for the visualization. + +In order to compute group-level statistics, data representations across +subjects must be morphed to a common frame, such that anatomically and +functional similar structures are represented at the same spatial location for +*all subjects equally*. Since brains vary, :term:`morphing` comes into play to +tell us how the data produced by subject A would be represented on the brain of +subject B (and vice-versa). + + +The morphing maps +~~~~~~~~~~~~~~~~~ + +The MNE software accomplishes morphing with help of morphing maps. +The morphing is performed with help of the registered +spherical surfaces (``lh.sphere.reg`` and ``rh.sphere.reg`` ) which must be +produced in FreeSurfer. A morphing map is a linear mapping from cortical +surface values in subject A (:math:`x^{(A)}`) to those in another subject B +(:math:`x^{(B)}`) + +.. math:: x^{(B)} = M^{(AB)} x^{(A)}\ , + +where :math:`M^{(AB)}` is a sparse matrix with at most three nonzero elements +on each row. These elements are determined as follows. First, using the aligned +spherical surfaces, for each vertex :math:`x_j^{(B)}`, find the triangle +:math:`T_j^{(A)}` on the spherical surface of subject A which contains the +location :math:`x_j^{(B)}`. Next, find the numbers of the vertices of this +triangle and set the corresponding elements on the *j* th row of +:math:`M^{(AB)}` so that :math:`x_j^{(B)}` will be a linear interpolation +between the triangle vertex values reflecting the location :math:`x_j^{(B)}` +within the triangle :math:`T_j^{(A)}`. + +It follows from the above definition that in general + +.. math:: M^{(AB)} \neq (M^{(BA)})^{-1}\ , + +*i.e.*, + +.. math:: x_{(A)} \neq M^{(BA)} M^{(AB)} x^{(A)}\ , + +even if + +.. math:: x^{(A)} \approx M^{(BA)} M^{(AB)} x^{(A)}\ , + +*i.e.*, the mapping is *almost* a bijection. + + +About smoothing +~~~~~~~~~~~~~~~ + +The current estimates are normally defined only in a decimated grid which is a +sparse subset of the vertices in the triangular tessellation of the cortical +surface. Therefore, any sparse set of values is distributed to neighboring +vertices to make the visualized results easily understandable. This procedure +has been traditionally called smoothing but a more appropriate name might be +smudging or blurring in accordance with similar operations in image processing +programs. + +In MNE software terms, smoothing of the vertex data is an iterative procedure, +which produces a blurred image :math:`x^{(N)}` from the original sparse image +:math:`x^{(0)}` by applying in each iteration step a sparse blurring matrix: + +.. math:: x^{(p)} = S^{(p)} x^{(p - 1)}\ . + +On each row :math:`j` of the matrix :math:`S^{(p)}` there are :math:`N_j^{(p - +1)}` nonzero entries whose values equal :math:`1/N_j^{(p - 1)}`. Here +:math:`N_j^{(p - 1)}` is the number of immediate neighbors of vertex :math:`j` +which had non-zero values at iteration step :math:`p - 1`. Matrix +:math:`S^{(p)}` thus assigns the average of the non-zero neighbors as the new +value for vertex :math:`j`. One important feature of this procedure is that it +tends to preserve the amplitudes while blurring the surface image. + +Once the indices non-zero vertices in :math:`x^{(0)}` and the topology of the +triangulation are fixed the matrices :math:`S^{(p)}` are fixed and independent +of the data. Therefore, it would be in principle possible to construct a +composite blurring matrix + +.. math:: S^{(N)} = \prod_{p = 1}^N {S^{(p)}}\ . + +However, it turns out to be computationally more effective to do blurring with +an iteration. The above formula for :math:`S^{(N)}` also shows that the +smudging (smoothing) operation is linear. diff -Nru python-mne-0.18.1+dfsg/doc/_includes/precision.rst python-mne-0.19.1+dfsg/doc/_includes/precision.rst --- python-mne-0.18.1+dfsg/doc/_includes/precision.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/precision.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,28 @@ +:orphan: + +Floating-point precision +======================== + +.. NOTE: part of this file is included in doc/manual/io.rst and + doc/overview/implementation.rst. Changes here are reflected there. If you + want to link to this content, link to :ref:`manual-precision` for the manual + or :ref:`precision` for the implementation page. The next line is a target + for :start-after: so we can omit the title above: + precision-begin-content + +MNE-Python performs all computation in memory using the double-precision 64-bit +floating point format. This means that the data is typecast into float64 format +as soon as it is read into memory. The reason for this is that operations such +as filtering and preprocessing are more accurate when using the 64-bit format. +However, for backward compatibility, MNE-Python writes :file:`.fif` files in a +32-bit format by default. This reduces file size when saving data to disk, but +beware that *saving intermediate results to disk and re-loading them from disk +later may lead to loss in precision*. If you would like to ensure 64-bit +precision, there are two possibilities: + +- Chain the operations in memory and avoid saving intermediate results. + +- Save intermediate results but change the :class:`~numpy.dtype` used for + saving, by using the ``fmt`` parameter of :meth:`mne.io.Raw.save` (or + :meth:`mne.Epochs.save`, etc). However, note that this may render the + :file:`.fif` files unreadable in software packages other than MNE-Python. diff -Nru python-mne-0.18.1+dfsg/doc/_includes/ssp.rst python-mne-0.19.1+dfsg/doc/_includes/ssp.rst --- python-mne-0.18.1+dfsg/doc/_includes/ssp.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/ssp.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,119 @@ +:orphan: + +The Signal-Space Projection (SSP) method +======================================== + +.. NOTE: part of this file is included in doc/overview/implementation.rst. + Changes here are reflected there. If you want to link to this content, link + to :ref:`ssp-method` to link to that section of the implementation.rst + page. The next line is a target for :start-after: so we can omit the title + from the include: + ssp-begin-content + +The Signal-Space Projection (SSP) is one approach to rejection of external +disturbances in software. The section presents some relevant details of this +method. For practical examples of how to use SSP for artifact rejection, see +:ref:`tut-artifact-ssp`. + +General concepts +~~~~~~~~~~~~~~~~ + +Unlike many other noise-cancellation approaches, SSP does not require +additional reference sensors to record the disturbance fields. Instead, SSP +relies on the fact that the magnetic field distributions generated by the +sources in the brain have spatial distributions sufficiently different from +those generated by external noise sources. Furthermore, it is implicitly +assumed that the linear space spanned by the significant external noise patters +has a low dimension. + +Without loss of generality we can always decompose any :math:`n`-channel +measurement :math:`b(t)` into its signal and noise components as + +.. math:: b(t) = b_s(t) + b_n(t) + :label: additive_model + +Further, if we know that :math:`b_n(t)` is well characterized by a few field +patterns :math:`b_1 \dotso b_m`, we can express the disturbance as + +.. math:: b_n(t) = Uc_n(t) + e(t)\ , + :label: pca + +where the columns of :math:`U` constitute an orthonormal basis for :math:`b_1 +\dotso b_m`, :math:`c_n(t)` is an :math:`m`-component column vector, and the +error term :math:`e(t)` is small and does not exhibit any consistent spatial +distributions over time, *i.e.*, :math:`C_e = E \{e e^T\} = I`. Subsequently, +we will call the column space of :math:`U` the noise subspace. The basic idea +of SSP is that we can actually find a small basis set :math:`b_1 \dotso b_m` +such that the conditions described above are satisfied. We can now construct +the orthogonal complement operator + +.. math:: P_{\perp} = I - UU^T + :label: projector + +and apply it to :math:`b(t)` in Equation :eq:`additive_model` yielding + +.. math:: b_{s}(t) \approx P_{\perp}b(t)\ , + :label: result + +since :math:`P_{\perp}b_n(t) = P_{\perp}(Uc_n(t) + e(t)) \approx 0` and +:math:`P_{\perp}b_{s}(t) \approx b_{s}(t)`. The projection operator +:math:`P_{\perp}` is called the **signal-space projection operator** and +generally provides considerable rejection of noise, suppressing external +disturbances by a factor of 10 or more. The effectiveness of SSP depends on two +factors: + +- The basis set :math:`b_1 \dotso b_m` should be able to characterize the + disturbance field patterns completely and + +- The angles between the noise subspace space spanned by :math:`b_1 \dotso b_m` + and the signal vectors :math:`b_s(t)` should be as close to :math:`\pi / 2` + as possible. + +If the first requirement is not satisfied, some noise will leak through because +:math:`P_{\perp}b_n(t) \neq 0`. If the any of the brain signal vectors +:math:`b_s(t)` is close to the noise subspace not only the noise but also the +signal will be attenuated by the application of :math:`P_{\perp}` and, +consequently, there might by little gain in signal-to-noise ratio. + +Since the signal-space projection modifies the signal vectors originating in +the brain, it is necessary to apply the projection to the forward solution in +the course of inverse computations. + +For more information on SSP, please consult the references listed in +:ref:`CEGIEEBB`. + +Estimation of the noise subspace +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As described above, application of SSP requires the estimation of the signal +vectors :math:`b_1 \dotso b_m` constituting the noise subspace. The most common +approach, also implemented in :func:`mne.compute_proj_raw` +is to compute a covariance matrix +of empty room data, compute its eigenvalue decomposition, and employ the +eigenvectors corresponding to the highest eigenvalues as basis for the noise +subspace. It is also customary to use a separate set of vectors for +magnetometers and gradiometers in the Vectorview system. + +EEG average electrode reference +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The EEG average reference is the mean signal over all the sensors. It is +typical in EEG analysis to subtract the average reference from all the sensor +signals :math:`b^{1}(t), ..., b^{n}(t)`. That is: + +.. math:: {b}^{j}_{s}(t) = b^{j}(t) - \frac{1}{n}\sum_{k}{b^k(t)} + :label: eeg_proj + +where the noise term :math:`b_{n}^{j}(t)` is given by + +.. math:: b_{n}^{j}(t) = \frac{1}{n}\sum_{k}{b^k(t)} + :label: noise_term + +Thus, the projector vector :math:`P_{\perp}` will be given by +:math:`P_{\perp}=\frac{1}{n}[1, 1, ..., 1]` + +.. warning:: + When applying SSP, the signal of interest can also be sometimes removed. + Therefore, it's always a good idea to check how much the effect of interest + is reduced by applying SSP. SSP might remove *both* the artifact and signal + of interest. diff -Nru python-mne-0.18.1+dfsg/doc/_includes/units.rst python-mne-0.19.1+dfsg/doc/_includes/units.rst --- python-mne-0.18.1+dfsg/doc/_includes/units.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_includes/units.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,36 @@ +:orphan: + +Internal representation (units) +=============================== + +.. NOTE: part of this file is included in doc/manual/io.rst and + doc/overview/implementation.rst. Changes here are reflected there. If you + want to link to this content, link to :ref:`manual-units` for the manual or + :ref:`units` for the implementation page. The next line is a target for + :start-after: so we can omit what's above: + units-begin-content + +Irrespective of the units used in your manufacturer's format, when importing +data, MNE-Python will always convert measurements to the same standard units. +Thus the in-memory representation of data are always in: + +- Volts (eeg, eog, seeg, emg, ecg, bio, ecog) +- Teslas (magnetometers) +- Teslas/meter (gradiometers) +- Amperes*meter (dipole fits, minimum-norm estimates, etc.) +- Moles/liter ("molar"; fNIRS data: oxyhemoglobin (hbo), deoxyhemoglobin (hbr)) +- Arbitrary units (various derived unitless quantities) + +.. NOTE: this is a target for :end-before: units-end-of-list + +Note, however, that most MNE-Python plotting functions will scale the data when +plotted to yield nice-looking axis annotations in a sensible range; for +example, :meth:`mne.io.Raw.plot_psd` will convert teslas to femtoteslas (fT) +and volts to microvolts (μV) when plotting MEG and EEG data. + +The units used in internal data representation are particularly important to +remember when extracting data from MNE-Python objects and manipulating it +outside MNE-Python (e.g., when using methods like :meth:`~mne.io.Raw.get_data` +or :meth:`~mne.Epochs.to_data_frame` to convert data to :class:`NumPy arrays +` or :class:`Pandas DataFrames ` for analysis +or plotting with other Python modules). diff -Nru python-mne-0.18.1+dfsg/doc/index.rst python-mne-0.19.1+dfsg/doc/index.rst --- python-mne-0.18.1+dfsg/doc/index.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/index.rst 2019-10-25 14:42:45.000000000 +0000 @@ -1,8 +1,5 @@ .. title:: MNE -.. include:: links.inc - - .. container:: row limitedwidth table-like .. title image and description @@ -37,28 +34,28 @@ .. raw:: html
- Data I/O + Data I/O
- Preprocessing + Preprocessing
- Visualization + Visualization
- Source estimation + Source estimation
- Time-frequency + Time-frequency
- Connectivity + Connectivity
- Machine learning + Machine learning
- Statistics + Statistics
.. container:: row limitedwidth diff -Nru python-mne-0.18.1+dfsg/doc/install/advanced.rst python-mne-0.19.1+dfsg/doc/install/advanced.rst --- python-mne-0.18.1+dfsg/doc/install/advanced.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install/advanced.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,176 @@ +.. include:: ../links.inc + +.. _advanced_setup: + +Advanced setup of MNE-Python +============================ + +.. contents:: + :local: + :depth: 1 + +Using MNE-Python with IPython / Jupyter notebooks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When using MNE-Python within IPython or a Jupyter notebook, we strongly +recommend using the Qt matplotlib backend for fast and correct rendering. On +Linux, for example, Qt is the only matplotlib backend for which 3D rendering +will work correctly. On macOS, certain matplotlib functions might not work as +expected on backends other than Qt. Enabling Qt can be accomplished when +starting IPython from a terminal: + +.. code-block:: console + + $ ipython --matplotlib=qt + +or in a Jupyter Notebook, you can use the "magic" command: + +.. code-block:: ipython + + In [1]: %matplotlib qt + +This will create separate pop-up windows for each figure, and has the advantage +that the 3D plots will retain rich interactivity (so, for example, you can +click-and-drag to rotate cortical surface activation maps). + +If you are creating a static notebook or simply prefer Jupyter's inline plot +display, MNE-Python will work with the standard "inline" magic: + +.. code-block:: ipython + + In [1]: %matplotlib inline + +but some functionality will be lost. For example, mayavi scenes will still +pop-up a separate window, but only one window at a time is possible, and +interactivity within the scene is limited in non-blocking plot calls. + +.. admonition:: |windows| Windows + :class: note + + If you are using MNE-Python on Windows through IPython or Jupyter, you might + also have to use the IPython magic command ``%gui qt`` after importing + MNE-Python, Mayavi or PySurfer (see `here + `_). For example: + + .. code-block:: ipython + + In [1]: from mayavi import mlab + In [2]: %gui qt + +If you use another Python setup and you encounter some difficulties please +report them on the `MNE mailing list`_ or on the `GitHub issues page`_ to get +assistance. + +.. _installing_master: + +Using the development version of MNE-Python (latest master) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want access to the latest features and bugfixes, you can easily switch +from the stable version of MNE-Python to the current development version. + +.. warning:: In between releases, function and class APIs can change without + warning. + +For a one-time update to latest master, make sure you're in the conda +environment where MNE-Python is installed (if you followed the default install +instructions, this will be ``base``), and use ``pip`` to upgrade: + +.. code-block:: console + + $ conda activate name_of_my_mne_environment + $ pip install --upgrade --no-deps git+https://github.com/mne-tools/mne-python.git + +If you plan to contribute to MNE-Python, or just prefer to use git rather than +pip to make frequent updates, check out the :ref:`contributing guide +`. + +.. _other-py-distros: + +Using MNE-Python with other Python distributions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +While the `Anaconda`_ Python distribution provides many conveniences, other +distributions of Python should also work with MNE-Python. In particular, +`Miniconda`_ is a lightweight alternative to Anaconda that is fully compatible; +like Anaconda, Miniconda includes the ``conda`` command line tool for +installing new packages and managing environments; unlike Anaconda, Miniconda +starts off with a minimal set of around 30 packages instead of Anaconda's +hundreds. See the `installation instructions for Miniconda`_ for more info. + +It is also possible to use a system-level installation of Python (version 3.5 +or higher) and use ``pip`` to install MNE-Python and its dependencies, using +the provided `requirements file`_: + +.. code-block:: console + + curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/requirements.txt + pip install --user requirements.txt + +Other configurations will probably also work, but we may be unable to offer +support if you encounter difficulties related to your particular Python +installation choices. + +.. _CUDA: + +Using MNE-Python with CUDA (NVIDIA GPU acceleration) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some operations in MNE-Python can utilize `NVIDIA CUDA GPU processing`_ to +speed up some operations (e.g. FIR filtering) by roughly an order of magnitude. +To use CUDA, first ensure that you are running the `NVIDIA proprietary +drivers`_ on your operating system, and then do: + +.. code-block:: console + + $ conda install cupy + $ MNE_USE_CUDA=true python -c "import mne; mne.cuda.init_cuda(verbose=True)" + Enabling CUDA with 1.55 GB available memory + +If you receive a message reporting the GPU's available memory, CuPy_ +is working properly. To permanently enable CUDA in MNE, you can do:: + + >>> mne.utils.set_config('MNE_USE_CUDA', 'true') # doctest: +SKIP + +You can then test MNE CUDA support by running the associated test: + +.. code-block:: console + + $ pytest mne/tests/test_filter.py -k cuda + +If the tests pass, then CUDA should work in MNE. You can use CUDA in methods +that state that they allow passing ``n_jobs='cuda'``, such as +:meth:`mne.io.Raw.filter` and :meth:`mne.io.Raw.resample`, +and they should run faster than the CPU-based multithreading such as +``n_jobs=8``. + +Off-screen rendering in MNE-Python on Linux with MESA +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On remote systems, it might be possible to use MESA software rendering +(such as ``llvmpipe`` or ``swr``) for 3D visualization (with some tweaks). +For example, on CentOS 7.5 you might be able to use an environment variable +to force MESA to use modern OpenGL by using this before executing +``spyder`` or ``python``: + +.. code-block:: console + + $ export MESA_GL_VERSION_OVERRIDE=3.3 + +Also, it's possible that different software rending backends might perform +better than others, such as using the ``llvmpipe`` backend rather than ``swr``. + +Troubleshooting 3D plots in MNE-Python +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you run into trouble when visualizing source estimates (or anything else +using mayavi), you can try setting a couple of environment variables at the +beginning of your script, session, or notebook:: + + >>> import os + >>> os.environ['ETS_TOOLKIT'] = 'qt4' + >>> os.environ['QT_API'] = 'pyqt5' + +This will tell mayavi to use Qt backend with PyQt bindings, instead of the +default PySide. For more information, see +http://docs.enthought.com/mayavi/mayavi/building_applications.html#integrating-in-a-qt-application. diff -Nru python-mne-0.18.1+dfsg/doc/install/contributing.rst python-mne-0.19.1+dfsg/doc/install/contributing.rst --- python-mne-0.18.1+dfsg/doc/install/contributing.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install/contributing.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,893 @@ +:orphan: + +.. _contributing: + +Contributing to MNE-Python +========================== + +.. contents:: Page contents + :local: + :depth: 2 + +.. highlight:: console + +.. NOTE: this first section (up until "overview of contribution process") is + basically a copy/paste of CONTRIBUTING.rst from the repository root, with + one sentence deleted to avoid self-referential linking. Changes made here + should be mirrored there, and vice-versa. + +MNE-Python is maintained by a community of scientists and research labs, and +accepts contributions in the form of bug reports, fixes, feature additions, and +documentation improvements (even just typo corrections). The best way to start +contributing is by `opening an issue`_ on our GitHub page to tell us about +errors you are encountering or to discuss your ideas for changes. For general +troubleshooting, you can also write to the `MNE mailing list`_ or chat with +developers on the `MNE gitter channel`_. + +Changes are typically made by `forking`_ the MNE-Python repository, making +changes to your fork (usually by `cloning`_ it to your personal computer, +making the changes, and then `pushing`_ the local changes up to your fork), and +finally creating a `pull request`_ to incorporate your changes back into the +shared "upstream" version of the codebase. + +Users and contributors to MNE-Python are expected to follow our `code of +conduct`_. + +.. collapse:: |rocket| Want an example to work through? + :class: success + + A great way to learn to contribute is to work through an actual example + We recommend that you take a look at the `GitHub issues marked "easy"`_, + pick one that looks interesting, and work through it while reading this + guide! + +.. _`opening an issue`: https://github.com/mne-tools/mne-python/issues/new/choose +.. _`MNE mailing list`: http://mail.nmr.mgh.harvard.edu/mailman/listinfo/mne_analysis +.. _`MNE gitter channel`: https://gitter.im/mne-tools/mne-python + +.. _`forking`: https://help.github.com/en/articles/fork-a-repo +.. _`cloning`: https://help.github.com/en/articles/cloning-a-repository +.. _`pushing`: https://help.github.com/en/articles/pushing-to-a-remote +.. _`pull request`: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork + +.. _`code of conduct`: https://github.com/mne-tools/mne-python/blob/master/CODE_OF_CONDUCT.md +.. _`GitHub issues marked "easy"`: + +Overview of contribution process +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In general you'll be working with three different copies of the MNE-Python +codebase: the official remote copy at https://github.com/mne-tools/mne-python +(usually called ``upstream``), your remote `fork`_ of the upstream repository +(similar URL, but with your username in place of ``mne-tools``, and usually +called ``origin``), and the local copy of the codebase on your computer. The +typical contribution process is to: + +1. synchronize your local copy with ``upstream`` + +2. make changes to your local copy + +3. `push`_ your changes to ``origin`` (your remote fork of the upstream) + +4. submit a `pull request`_ from your fork into ``upstream`` + +The sections :ref:`basic-git` and :ref:`github-workflow` (below) describe this +process in more detail. + + +Setting up your local environment for MNE-Python development +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configuring git +~~~~~~~~~~~~~~~ + +.. sidebar:: Git GUI alternative + + `GitHub desktop`_ is a GUI alternative to command line git that some users + appreciate; it is available for |windows| Windows and |apple| MacOS. + +To get set up for contributing, make sure you have git installed on your local +computer: + +- On Linux, the command ``sudo apt install git`` is usually sufficient; see the + `official Linux instructions`_ for more options. + +- On MacOS, download `the .dmg installer`_; Atlassian also provides `more + detailed instructions and alternatives`_ such as using MacPorts or Homebrew. + +- On Windows, we recommend `git Bash`_ rather than the `official Windows + version of git`_, because git Bash provides its own shell that includes many + Linux-equivalent command line programs that are useful for development. + Windows 10 also offers the `Windows subsystem for Linux`_ that offers similar + functionality to git Bash, but has not been widely tested by MNE-Python + developers yet. + + +Once git is installed, the only absolutely necessary configuration step is +identifying yourself and your contact info:: + + $ git config --global user.name "Your Name" + $ git config --global user.email you@yourdomain.example.com + +Make sure that the same email address is associated with your GitHub account +and with your local git configuration. It is possible to associate multiple +emails with a GitHub account, so if you initially set them up with different +emails, just add the local email to the GitHub account. + +Sooner or later, git is going to ask you what text editor you want it to use +when writing commit messages, so you might as well configure that now too:: + + $ git config --global core.editor emacs # or vim, or nano, or subl, or... + +There are many other ways to customize git's behavior; see `configuring git`_ +for more information. Once you have git installed and configured, and before +creating your local copy of the codebase, go to the `MNE-Python GitHub`_ page +and create a `fork`_ into your GitHub user account. + + +Setting up the development environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. sidebar:: Supported Python environments + + We strongly recommend the `Anaconda`_ or `Miniconda`_ environment managers + for Python. Other setups are possible but are not officially supported by + the MNE-Python development team; see discussion :ref:`here + `. These instructions use ``conda`` where possible; + experts may replace those lines with some combination of ``git`` and + ``pip``. + +These instructions will set up a Python environment that is separated from your +system-level Python and any other managed Python environments on your computer. +This lets you switch between different versions of Python (MNE-Python requires +version 3.5 or higher) and also switch between the stable and development +versions of MNE-Python (so you can, for example, use the same computer to +analyze your data with the stable release, and also work with the latest +development version to fix bugs or add new features). If you've already +followed the :ref:`installation instructions ` for the stable +version of MNE-Python, MNE-Python will be installed in the environment ``base`` +(unless you provided a custom environment name during installation). Before +continuing, you should create a new, separate environment for MNE-Python +development (here we'll call it ``mnedev``):: + + $ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml + $ conda env create --file environment.yml --name mnedev + $ conda activate mnedev + +Now you'll have *two* MNE-Python environments: ``base`` (or whatever you called +it) for the stable version and ``mnedev`` for the development version. Next +`clone`_ the MNE-Python repository from your remote fork, and also connect the +local copy to the ``upstream`` version of the codebase, so you can stay +up-to-date with changes from other contributors. First, edit these two +variables for your situation:: + + $ INSTALL_LOCATION="/opt" + $ GITHUB_USERNAME="new_mne_contributor" + +Then make a local clone of your remote fork (``origin``):: + + $ cd $INSTALL_LOCATION + $ git clone https://github.com/$GITHUB_USERNAME/mne-python.git + +.. sidebar:: Remote URLs in git + + Here we use ``git://`` instead of ``https://`` in the URL for the + ``upstream`` remote repository. ``git://`` URLs are read-only, so you can + *pull* changes from ``upstream`` into your local copy (to stay up-to-date + with changes from other contributors) but you cannot *push* changes from + your computer into the ``upstream`` remote. Instead, you must push your + changes to your own remote fork (``origin``) first, and then create a pull + request from your remote into the upstream remote. In :ref:`a later section + ` you'll see a third kind of remote URL for connecting to + GitHub using SSH. + +Finally, set up a link between your local clone and the official repository +(``upstream``):: + + $ cd mne-python + $ git remote add upstream git://github.com/mne-tools/mne-python.git + $ git fetch --all + +When you created the ``mnedev`` environment using the environment file, it +installed the *stable* version of MNE-Python, so next we'll remove that and +replace it with the *development* version (the clone we just created with git). +Make sure you're in the correct environment first (:samp:`conda activate +mnedev`), and then do:: + + $ cd $INSTALL_LOCATION/mne-python # make sure we're in the right folder + $ pip uninstall -y mne + $ pip install -e . + +The command ``pip install -e .`` installs a python module into the current +environment by creating a link to the source code directory (instead of +copying the code to pip's ``site_packages`` directory, which is what normally +happens). This means that any edits you make to the MNE-Python source code will +be reflected the next time you open a Python interpreter and ``import mne`` +(the ``-e`` flag of ``pip`` stands for an "editable" installation). + +Finally, we'll add a few dependencies that are not needed for running +MNE-Python, but are needed for locally running our test suite or building our +documentation:: + + $ pip install sphinx sphinx-gallery sphinx_bootstrap_theme sphinx_fontawesome memory_profiler + $ conda install sphinx-autobuild doc8 # linter packages for reStructuredText (optional) + + +.. _basic-git: + +Basic git commands +~~~~~~~~~~~~~~~~~~ + +Learning to work with git can take a long time, because it is a complex and +powerful tool for managing versions of files across multiple users, each of +whom have multiple copies of the codebase. We've already seen in the setup +commands above a few of the basic git commands useful to an MNE-Python +developer: + +- :samp:`git clone {}` (make a local copy of a repository) + +- :samp:`git remote add {} {}` (connect + a local copy to an additional remote) + +- ``git fetch --all`` (get the current state of connected remote repos) + +Other commands that you will undoubtedly need relate to `branches`_. Branches +represent multiple copies of the codebase *within a local clone or remote +repo*. Branches are typically used to experiment with new features while still +keeping a clean, working copy of the original codebase that you can switch back +to at any time. The default branch of any repo is always called ``master``, and +it is recommended that you reserve the ``master`` branch to be that clean copy +of the working ``upstream`` codebase. Therefore, if you want to add a new +feature, you should first synchronize your local ``master`` branch with the +``upstream`` repository, then create a new branch based off of ``master`` and +`check it out`_ so that any changes you make will exist on that new branch +(instead of on ``master``):: + + $ git checkout master # switch to local master branch + $ git fetch upstream # get the current state of the remote upstream repo + $ git merge upstream/master # synchronize local master branch with remote upstream master branch + $ git checkout -b new-feature-x # create local branch "new-feature-x" and check it out + +.. sidebar:: Alternative + + You can save some typing by using ``git pull upstream/master`` to replace + the ``fetch`` and ``merge`` lines above. + +Now that you're on a new branch, you can fix a bug or add a new feature, add a +test, update the documentation, etc. When you're done, it's time to organize +your changes into a series of `commits`_. Commits are like snapshots of the +repository — actually, more like a description of what has to change to get +from the most recent snapshot to the current snapshot. + +Git knows that people often work on multiple changes in multiple files all at +once, but that ultimately they should separate those changes into sets of +related changes that are grouped together based on common goals (so that it's +easier for their colleagues to understand and review the changes). For example, +you might want to group all the code changes together in one commit, put new +unit tests in another commit, and changes to the documentation in a third +commit. Git makes this easy(ish) with something called the `stage`_ (or +*staging area*). After you've made some changes to the codebase, you'll have +what git calls "unstaged changes", which will show up with the `status`_ +command:: + + $ git status # see what state the local copy of the codebase is in + +Those unstaged changes can be `added`_ to the stage one by one, by either +adding a whole file's worth of changes, or by adding only certain lines +interactively:: + + $ git add mne/some_file.py # add all the changes you made to this file + $ git add mne/some_new_file.py # add a completely new file in its entirety + $ # enter interactive staging mode, to add only portions of a file: + $ git add -p mne/viz/some_other_file.py + +Once you've collected all the related changes together on the stage, the ``git +status`` command will now refer to them as "changes staged for commit". You can +commit them to the current branch with the `commit`_ command. If you just type +``git commit`` by itself, git will open the text editor you configured it to +use so that you can write a *commit message* — a short description of the +changes you've grouped together in this commit. You can bypass the text editor +by passing a commit message on the command line with the ``-m`` flag. For +example, if your first commit adds a new feature, your commit message might be:: + + $ git commit -m 'ENH: adds feature X to the Epochs class' + +Once you've made the commit, the stage is now empty, and you can repeat the +cycle, adding the unit tests and documentation changes:: + + $ git add mne/tests/some_testing_file.py + $ git commit -m 'add test of new feature X of the Epochs class' + $ git add -p mne/some_file.py mne/viz/some_other_file.py + $ git commit -m 'DOC: update Epochs and BaseEpochs docstrings' + $ git add tutorials/new_tutorial_file.py + $ git commit -m 'DOC: adds new tutorial about feature X' + +When you're done, it's time to run the test suite to make sure your changes +haven't broken any existing functionality, and to make sure your new test +covers the lines of code you've added (see :ref:`run-tests` and +:ref:`build-docs`, below). Once everything looks good, it's time to push your +changes to your fork:: + + $ # push local changes to remote branch origin/new-feature-x + $ # (this will create the remote branch if it doesn't already exist) + $ git push origin new-feature-x + +Finally, go to the `MNE-Python GitHub`_ page, click on the pull requests tab, +click the "new pull request" button, and choose "compare across forks" to +select your new branch (``new-feature-x``) as the "head repository". See the +GitHub help page on `creating a PR from a fork`_ for more information about +opening pull requests. + +If any of the tests failed before you pushed your changes, try to fix them, +then add and commit the changes that fixed the tests, and push to your fork. If +you're stuck and can't figure out how to fix the tests, go ahead and push your +commits to your fork anyway and open a pull request (as described above), then +in the pull request you should describe how the tests are failing and ask for +advice about how to fix them. + +To learn more about git, check out the `GitHub help`_ website, the `GitHub +Learning Lab`_ tutorial series, and the `pro git book`_. + + +.. _github-ssh: + +Connecting to GitHub with SSH (optional) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One easy way to speed up development is to reduce the number of times you have +to type your password. SSH (secure shell) allows authentication with pre-shared +key pairs. The private half of your key pair is kept secret on your computer, +while the public half of your key pair is added to your GitHub account; when +you connect to GitHub from your computer, the local git client checks the +remote (public) key against your local (private) key, and grants access your +account only if the keys fit. GitHub has `several help pages`_ that guide you +through the process. + +Once you have set up GitHub to use SSH authentication, you should change the +addresses of your MNE-Python GitHub remotes, from ``https://`` addresses to +``git@`` addresses, so that git knows to connect via SSH instead of HTTPS. For +example:: + + $ git remote -v # show existing remote addresses + $ git remote set-url origin git@github.com:$GITHUB_USERNAME/mne-python.git + $ git remote set-url upstream git@github.com:mne-tools/mne-python.git + + +MNE-Python coding conventions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +General requirements +~~~~~~~~~~~~~~~~~~~~ + +All new functionality must have test coverage +--------------------------------------------- + +For example, a new :class:`mne.Evoked` method in :file:`mne/evoked.py` should +have a corresponding test in :file:`mne/tests/test_evoked.py`. + + +All new functionality must be documented +---------------------------------------- + +This includes thorough docstring descriptions for all public API changes, as +well as how-to examples or longer tutorials for major contributions. Docstrings +for private functions may be more sparse, but should not be omitted. + + +Avoid API changes when possible +------------------------------- + +Changes to the public API (e.g., class/function/method names and signatures) +should not be made lightly, as they can break existing user scripts. Changes to +the API require a deprecation cycle (with warnings) so that users have time to +adapt their code before API changes become default behavior. See :ref:`the +deprecation section ` and :class:`mne.utils.deprecated` for +instructions. Bug fixes (when something isn't doing what it says it will do) do +not require a deprecation cycle. + +Note that any new API elements should be added to the master reference; +classes, functions, methods, and attributes cannot be cross-referenced unless +they are included in the :doc:`python_reference` +(:file:`doc/python_reference.rst`). + + +.. _deprecating: + +Deprecate with a decorator or a warning +--------------------------------------- + +MNE-Python has a :func:`~mne.utils.deprecated` decorator for classes and +functions that will be removed in a future version: + +.. code-block:: python + + from mne.utils import deprecated + + @deprecated('my_function is deprecated and will be removed in 0.XX; please ' + 'use my_new_function instead.') + def my_function(): + return 'foo' + +If you need to deprecate a parameter, use :func:`mne.utils.warn`. For example, +to rename a parameter from ``old_param`` to ``new_param`` you can do something +like this: + +.. code-block:: python + + from mne.utils import warn + + def my_other_function(new_param=None, old_param=None): + if old_param is not None: + depr_message = ('old_param is deprecated and will be replaced by ' + 'new_param in 0.XX.') + if new_param is None: + new_param = old_param + warn(depr_message, DeprecationWarning) + else: + warn(depr_message + ' Since you passed values for both ' + 'old_param and new_param, old_param will be ignored.', + DeprecationWarning) + # Do whatever you have to do with new_param + return 'foo' + +When deprecating, you should also add corresponding test(s) to the relevant +test file(s), to make sure that the warning(s) are being issued in the +conditions you expect: + +.. code-block:: python + + # test deprecation warning for function + with pytest.warns(DeprecationWarning, match='my_function is deprecated'): + my_function() + + # test deprecation warning for parameter + with pytest.warns(DeprecationWarning, match='values for both old_param'): + my_other_function(new_param=1, old_param=2) + with pytest.warns(DeprecationWarning, match='old_param is deprecated and'): + my_other_function(old_param=2) + +You should also search the codebase for any cases where the deprecated function +or parameter are being used internally, and update them immediately (don't wait +to the *end* of the deprecation cycle to do this). Later, at the end of the +deprecation period when the stated release is being prepared: + +- delete the deprecated functions +- remove the deprecated parameters (along with the conditional branches of + ``my_other_function`` that handle the presence of ``old_param``) +- remove the deprecation tests +- double-check for any other tests that relied on the deprecated test or + parameter, and (if found) update them to use the new function / parameter. + + +Describe your changes in the changelog +-------------------------------------- + +Include in your changeset a brief description of the change in the +:doc:`changelog ` (:file:`doc/whats_new.rst`; this can be skipped +for very minor changes like correcting typos in the documentation). Note that +there are sections of the changelog for each release, and separate subsections +for bugfixes, new features, and changes to the public API. It is usually best +to wait to add a line to the changelog until your PR is finalized, to avoid +merge conflicts (since the changelog is updated with almost every PR). + + +Test locally before opening pull requests (PRs) +----------------------------------------------- + +MNE-Python uses `continuous integration`_ (CI) to ensure code quality and +test across multiple installation targets. However, the CIs are often slower +than testing locally, especially when other contributors also have open PRs +(which is basically always the case). Therefore, do not rely on the CIs to +catch bugs and style errors for you; :ref:`run the tests locally ` +instead before opening a new PR and before each time you push additional +changes to an already-open PR. + + +Make tests fast and thorough +---------------------------- + +Whenever possible, use the testing dataset rather than one of the sample +datasets when writing tests; it includes small versions of most MNE-Python +objects (e.g., :class:`~mne.io.Raw` objects with short durations and few +channels). You can also check which lines are missed by the tests, then modify +existing tests (or write new ones) to target the missed lines. Here's an +example that reports which lines within ``mne.viz`` are missed when running +``test_evoked.py`` and ``test_topo.py``:: + + $ pytest --cov=mne.viz --cov-report=term-missing mne/viz/tests/test_evoked.py mne/viz/tests/test_topo.py + +You can also use ``pytest --durations=5`` to ensure new or modified tests will +not slow down the test suite too much. + + +Code style +~~~~~~~~~~ + +Adhere to standard Python style guidelines +------------------------------------------ + +All contributions to MNE-Python are checked against style guidelines described +in `PEP 8`_. We also check for common coding errors (such as variables that are +defined but never used). We allow very few exceptions to these guidelines, and +use tools such as pep8_, pyflakes_, and flake8_ to check code style +automatically. From the :file:`mne-python` root directory, you can check for +style violations by running:: + + $ make flake + +in the shell. Several text editors or IDEs also have Python style checking, +which can highlight style errors while you code (and train you to make those +errors less frequently). This functionality is built-in to the Spyder_ IDE, but +most editors have plug-ins that provide similar functionality. Search for +:samp:`python linter ` to learn more. + + +Use consistent variable naming +------------------------------ + +Classes should be named using ``CamelCase``. Functions and instances/variables +should use ``snake_case`` (``n_samples`` rather than ``nsamples``). Avoid +single-character variable names, unless inside a :term:`comprehension ` or :ref:`generator `. + + +Follow NumPy style for docstrings +--------------------------------- + +In most cases imitating existing docstrings will be sufficient, but consult the +`Numpy docstring style guidelines`_ for more complicated formatting such as +embedding example code, citing references, or including rendered mathematics. +Private function/method docstrings may be brief for simple functions/methods, +but complete docstrings are appropriate when private functions/methods are +relatively complex. To run some basic tests on documentation, you can use:: + + $ pytest mne/tests/test_docstring_parameters.py + $ make docstyle + + +Cross-reference everywhere +-------------------------- + +Both the docstrings and dedicated documentation pages (tutorials, how-to +examples, discussions, and glossary) should include cross-references to any +mentioned module, class, function, method, attribute, or documentation page. +There are sphinx directives for all of these (``:mod:``, ``:class:``, +``:func:``, ``:meth:``, ``:attr:``, ``:doc:``) as well as a generic +cross-reference directive (``:ref:``) for linking to specific sections of a +documentation page. + +.. warning:: + + Some API elements have multiple exposure points (for example, + ``mne.set_config`` and ``mne.utils.set_config``). For cross-references to + work, they must match an entry in :file:`doc/python_reference.rst` (thus + ``:func:`mne.set_config``` will work but ``:func:`mne.utils.set_config``` + will not). + +MNE-Python also uses Intersphinx_, so you can (and should) +cross-reference to Python built-in classes and functions as well as API +elements in :mod:`NumPy `, :mod:`SciPy `, etc. See the Sphinx +configuration file (:file:`doc/conf.py`) for the list of Intersphinx projects +we link to. Their inventories can be examined using a tool like `sphobjinv`_ or +dumped to file with commands like:: + + $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv > python.txt + + +Other style guidance +-------------------- + +- Use single quotes whenever possible. + +- Prefer :ref:`generators ` or + :term:`comprehensions ` over :func:`filter`, :func:`map` + and other functional idioms. + +- Use explicit functional constructors for builtin containers to improve + readability (e.g., :ref:`list() `, :ref:`dict() `, + :ref:`set() `). + +- Avoid nested functions or class methods if possible — use private functions + instead. + +- Avoid ``*args`` and ``**kwargs`` in function/method signatures. + + +Code organization +~~~~~~~~~~~~~~~~~ + +Importing +--------- + +Import modules in this order: + +1. Python built-in (``os``, ``copy``, ``functools``, etc) +2. standard scientific (``numpy as np``, ``scipy.signal``, etc) +3. others +4. MNE-Python imports (e.g., ``from .pick import pick_types``) + +When importing from other parts of MNE-Python, use relative imports in the main +codebase and absolute imports in tests, tutorials, and how-to examples. Imports +for ``matplotlib`` and optional modules (``sklearn``, ``pandas``, etc.) should +be nested (i.e., within a function or method, not at the top of a file). + + +Return types +------------ + +Methods should modify inplace and return ``self``, functions should return +copies (where applicable). Docstrings should always give an informative name +for the return value, even if the function or method's return value is never +stored under that name in the code. + + +Vizualization +------------- + +Visualization capabilities should be made available in both function and method +forms. Add public visualization functions to the :mod:`mne.viz` submodule, and +call those functions from the corresponding object methods. For example, the +method :meth:`mne.Epochs.plot` internally calls the function +:func:`mne.viz.plot_epochs`. + +All visualization functions must accept a boolean ``show`` parameter and +typically return a :class:`matplotlib.figure.Figure` (or a list of +:class:`~matplotlib.figure.Figure` objects). 3D visualization functions return +a :class:`mayavi.core.api.Scene`, :class:`surfer.Brain`, or other return type +as appropriate. + +Visualization functions should default to the colormap ``RdBu_r`` for signed +data with a meaningful middle (zero-point) and ``Reds`` otherwise. This applies +to both visualization functions and tutorials/examples. + + +.. _run_tests: + +Running the test suite +~~~~~~~~~~~~~~~~~~~~~~ + +Running the full test suite is as simple as running :: + + $ make test + +.. sidebar:: pytest flags + + The ``-x`` flag exits the pytest run as soon as the first test fails; this + can save some time if you are running an entire file's or module's worth of + tests instead of selecting just a single test as shown here. + + The ``--pdb`` flag will automatically start the python debugger upon test + failure. + +from the ``mne-python`` root folder. Testing the entire module can be quite +slow, however, so to run individual tests while working on a new feature, you +can run, e.g.:: + + $ pytest mne/tests/test_evoked.py:test_io_evoked --verbose + +Or alternatively:: + + $ pytest mne/tests/test_evoked.py -k test_io_evoked --verbose + +Make sure you have the testing dataset, which you can get by running this in +a Python interpreter: + +.. code-block:: python + + >>> mne.datasets.testing.data_path(verbose=True) # doctest: +SKIP + + +.. _build-docs: + +Building the documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Our documentation (including docstrings in code files) is in +reStructuredText_ format and is built using Sphinx_ and `Sphinx-Gallery`_. +The easiest way to ensure that your contributions to the documentation are +properly formatted is to follow the style guidelines on this page, imitate +existing documentation examples, refer to the Sphinx and Sphinx-Gallery +reference materials when unsure how to format your contributions, and build the +docs locally to confirm that everything looks correct before submitting the +changes in a pull request. + +You can build the documentation locally using `GNU Make`_ with +:file:`doc/Makefile`. From within the :file:`doc` directory, you can test +formatting and linking by running:: + + $ make html_dev-noplot + +This will build the documentation *except* it will format (but not execute) the +tutorial and example files. If you have created or modified an example or +tutorial, you should instead run +:samp:`PATTERN={} make html_dev-pattern` to render +all the documentation and additionally execute just your example or tutorial +(so you can make sure it runs successfully and generates the output / figures +you expect). + +After either of these commands completes, ``make show`` will open the +locally-rendered documentation site in your browser. Additional ``make`` +recipes are available; run ``make help`` from the :file:`doc` directory or +consult the `Sphinx-Gallery`_ documentation for additional details. + + +Modifying command-line tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MNE-Python provides support for a limited set of :ref:`python_commands`. +These are typically used with a call like:: + + $ mne browse_raw ~/mne_data/MNE-sample-data/MEG/sample/sample_audvis_raw.fif + +These are generally available for convenience, and can be useful for quick +debugging (in this case, for :class:`mne.io.Raw.plot`). + +If a given command-line function fails, they can also be executed as part of +the ``mne`` module with ``python -m``. For example:: + + $ python -i -m mne browse_raw ... + +Because this was launched with ``python -i``, once the script completes +it will drop to a Python terminal. This is useful when there are errors, +because then you can drop into a :func:`post-mortem debugger `: + +.. code-block:: python + + >>> import pdb; pdb.pm() # doctest:+SKIP + + +.. _`github-workflow`: + +GitHub workflow +~~~~~~~~~~~~~~~ + +Nearly everyone in the community of MNE-Python contributors and maintainers is +a working scientist, engineer, or student who contributes to MNE-Python in +their spare time. For that reason, a set of best practices have been adopted to +streamline the collaboration and review process. Most of these practices are +common to many open-source software projects, so learning to follow them while +working on MNE-Python will bear fruit when you contribute to other projects +down the road. Here are the guidelines: + +- Search the `MNE-Python issues page`_ (both open and closed issues) in case + someone else has already started work on the same bugfix or feature. If you + don't find anything, `open a new issue`_ to discuss changes with maintainers + before starting work on your proposed changes. + +- Implement only one new feature or bugfix per pull request (PR). Occasionally + it may make sense to fix a few related bugs at once, but this makes PRs + harder to review and test, so check with MNE-Python maintainers first before + doing this. Avoid purely cosmetic changes to the code; they make PRs harder + to review. + +- It is usually better to make PRs *from* branches other than your master + branch, so that you can use your master branch to easily get back to a + working state of the code if needed (e.g., if you're working on multiple + changes at once, or need to pull in recent changes from someone else to get + your new feature to work properly). + +- In most cases you should make PRs *into* the upstream's master branch, unless + you are specifically asked by a maintainer to PR into another branch (e.g., + for backports or maintenance bugfixes to the current stable version). + +- Don't forget to include in your PR a brief description of the change in the + :doc:`changelog ` (:file:`doc/whats_new.rst`). + +- Our community uses the following commit tags and conventions: + + - Work-in-progress PRs should be created as `draft PRs`_ and the PR title + should begin with ``WIP``. + + - When you believe a PR is ready to be reviewed and merged, `convert it + from a draft PR to a normal PR`_, change its title to begin with ``MRG``, + and add a comment to the PR asking for reviews (changing the title does not + automatically notify maintainers). + + - PRs that only affect documentation should additionally be labelled + ``DOC``, bugfixes should be labelled ``FIX``, and new features should be + labelled ``ENH`` (for "enhancement"). ``STY`` is used for style changes + (i.e., improving docstring consistency or formatting without changing its + content). + + - the following commit tags are used to interact with our + `continuous integration`_ (CI) providers. Use them judiciously; *do not + skip tests simply because they are failing*: + + - ``[skip circle]`` Skip `circle`_, which tests successful building of our + documentation. + + - ``[skip travis]`` Skip `travis`_, which tests installation and execution + on Linux and macOS systems. + + - ``[skip azp]`` Skip `azure`_ which tests installation and execution on + Windows systems. + + - ``[ci skip]`` is an alias for ``[skip travis][skip azp][skip circle]``. + Notice that ``[skip ci]`` is not a valid tag. + + - ``[circle full]`` triggers a "full" documentation build, i.e., all code + in tutorials and how-to examples will be *executed* (instead of just + nicely formatted) and the resulting output and figures will be rendered + as part of the tutorial/example. + +`This sample pull request`_ exemplifies many of the conventions listed above: +it addresses only one problem; it started with an issue to discuss the problem +and some possible solutions; it is a PR from the user's non-master branch into +the upstream master branch; it separates different kinds of changes into +separate commits and uses labels like ``DOC``, ``FIX``, and ``STY`` to make it +easier for maintainers to review the changeset; etc. If you are new to GitHub +it can serve as a useful example of what to expect from the PR review process. + + +.. MNE + +.. _MNE-Python GitHub: https://github.com/mne-tools/mne-python +.. _MNE-Python issues page: https://github.com/mne-tools/mne-python/issues +.. _open a new issue: https://github.com/mne-tools/mne-python/issues/new/choose +.. _This sample pull request: https://github.com/mne-tools/mne-python/pull/6230 + +.. git installation + +.. _the .dmg installer: https://git-scm.com/download/mac +.. _official Windows version of git: https://git-scm.com/download/win +.. _official Linux instructions: https://git-scm.com/download/linux +.. _more detailed instructions and alternatives: https://www.atlassian.com/git/tutorials/install-git +.. _Windows subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/about +.. _git bash: https://gitforwindows.org/ +.. _GitHub desktop: https://desktop.github.com/ + +.. github help pages + +.. _GitHub Help: https://help.github.com +.. _GitHub learning lab: https://lab.github.com/ +.. _fork: https://help.github.com/en/articles/fork-a-repo +.. _clone: https://help.github.com/en/articles/cloning-a-repository +.. _push: https://help.github.com/en/articles/pushing-to-a-remote +.. _branches: https://help.github.com/en/articles/about-branches +.. _several help pages: https://help.github.com/en/articles/connecting-to-github-with-ssh +.. _draft PRs: https://help.github.com/en/articles/about-pull-requests#draft-pull-requests +.. _convert it from a draft PR to a normal PR: https://help.github.com/en/articles/changing-the-stage-of-a-pull-request +.. _pull request: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork +.. _creating a PR from a fork: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork + +.. git docs + +.. _check it out: https://git-scm.com/docs/git-checkout +.. _added: https://git-scm.com/docs/git-add +.. _commits: https://git-scm.com/docs/git-commit +.. _commit: https://git-scm.com/docs/git-commit +.. _status: https://git-scm.com/docs/git-status + +.. git book + +.. _pro git book: https://git-scm.com/book/ +.. _stage: https://git-scm.com/book/en/v2/Git-Tools-Interactive-Staging +.. _configuring git: https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration + +.. sphinx + +.. _sphinx: http://www.sphinx-doc.org +.. _sphinx-gallery: https://sphinx-gallery.github.io +.. _reStructuredText: http://sphinx-doc.org/rest.html +.. _intersphinx: http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html +.. _sphobjinv: https://sphobjinv.readthedocs.io/en/latest/ + +.. linting + +.. _NumPy docstring style guidelines: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt +.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ +.. _pep8: https://pypi.org/project/pep8 +.. _pyflakes: https://pypi.org/project/pyflakes +.. _Flake8: http://flake8.pycqa.org/ + +.. misc + +.. _anaconda: https://www.anaconda.com/distribution/ +.. _miniconda: https://conda.io/en/latest/miniconda.html +.. _Spyder: https://www.spyder-ide.org/ +.. _GNU Make: https://www.gnu.org/software/make/ +.. _continuous integration: https://en.wikipedia.org/wiki/Continuous_integration +.. _matplotlib: https://matplotlib.org/ +.. _travis: https://travis-ci.org/mne-tools/mne-python/branches +.. _azure: https://dev.azure.com/mne-tools/mne-python/_build/latest?definitionId=1&branchName=master +.. _circle: https://circleci.com/gh/mne-tools/mne-python diff -Nru python-mne-0.18.1+dfsg/doc/install/freesurfer.rst python-mne-0.19.1+dfsg/doc/install/freesurfer.rst --- python-mne-0.18.1+dfsg/doc/install/freesurfer.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install/freesurfer.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,27 @@ +Installing FreeSurfer +===================== + +`FreeSurfer `_ is software for analysis and visualization of MRI data. +In the MNE ecosystem, freesurfer is used to convert structural MRI scans into +models of the scalp, inner/outer skull, and cortical surfaces, which are used +to + +1. model how changes in the electrical and magnetic field caused by neural + activity propagate to the sensor locations (part of computing the "forward + solution"), and + +2. constrain the estimates of where brain activity may have occurred (in the + "inverse imaging" step of source localization). + +System requirements, setup instructions, and test scripts are provided on the +`FreeSurfer download page`_. Note that if you don't already have it, you will +need to install ``tcsh`` for FreeSurfer to work; ``tcsh`` is usually +pre-installed with macOS, and is available in the package repositories for +Linux-based systems (e.g., ``sudo apt install tcsh`` on Ubuntu-like systems). + +**Next:** :doc:`advanced` + +.. LINKS + +.. _fs-wiki: https://surfer.nmr.mgh.harvard.edu/fswiki/ +.. _`FreeSurfer download page`: https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall diff -Nru python-mne-0.18.1+dfsg/doc/install/index.rst python-mne-0.19.1+dfsg/doc/install/index.rst --- python-mne-0.18.1+dfsg/doc/install/index.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install/index.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,26 @@ +:orphan: + +Installation — contents +======================= + +MNE-Python is an open-source Python module for processing, analysis, and +visualization of functional neuroimaging data (EEG, MEG, sEEG, ECoG, and +fNIRS). Pages describing the installation procedure are listed below. The +:ref:`contributing guide ` has advanced installation instructions +for (future) contributors to MNE-Python. + +.. toctree:: + :maxdepth: 2 + + pre_install + mne_python + freesurfer + advanced + +Installation instructions are also provided for MNE-C (the Unix command-line +tools originally developed by Matti Hämäläinen). + +.. toctree:: + :maxdepth: 2 + + mne_c diff -Nru python-mne-0.18.1+dfsg/doc/install/mne_c.rst python-mne-0.19.1+dfsg/doc/install/mne_c.rst --- python-mne-0.18.1+dfsg/doc/install/mne_c.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install/mne_c.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,195 @@ +.. include:: ../links.inc + +.. _install_mne_c: + +Installing MNE-C +================ + +.. contents:: + :local: + :depth: 1 + +System requirements +^^^^^^^^^^^^^^^^^^^ + +MNE-C runs on macOS (version 10.5 "Leopard" or later) and Linux (kernel 2.6.9 +or later). Both 32- and 64-bit operating systems are supported; a PowerPC +version for macOS can be provided upon request. At least 2 GB of memory is +required, 4 GB or more is recommended. The software requires at least 80 MB of +disk space. MATLAB is an optional dependency; the free `MATLAB runtime`_ is +sufficient. If MATLAB is not present, the utilities ``mne_convert_mne_data``, +``mne_epochs2mat``, ``mne_raw2mat``, and ``mne_simu`` will not work. + +For boundary-element model (BEM) mesh generation, and for accessing the ``tkmedit`` +program from ``mne_analyze``, MNE-C needs access to a +working installation of :doc:`FreeSurfer `, including the +environment variables ``FREESURFER_HOME``, ``SUBJECTS_DIR``, and ``SUBJECT``. + +.. admonition:: |apple| macOS + :class: note + + For installation on macOS, you also need: + + - the `XCode developer tools`_. + - an X Window System such as XQuartz_. Version 2.7.9 of XQuartz should work + out of the box; the most current version (2.7.11, as of May 2019) may + require these additional steps to work: + + .. code-block:: console + + $ cd /opt/X11/lib + $ sudo cp libXt.6.dylib libXt.6.dylib.bak + $ cd flat_namespace/ + $ sudo cp libXt.6.dylib ../. + + - the netpbm_ library. The recommended way to get netpbm is to install + Homebrew_, and run ``brew install netpbm`` in the Terminal app. + Alternatively, if you prefer to use MacPorts_, you can run + ``sudo port install netpbm`` in the Terminal app. + + +Downloading and Installing MNE-C +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +MNE-C is distributed as either a compressed tar archive (.tar.gz) or a macOS +disk image (.dmg). The `MNE-C download page`_ requires registration with a +valid email address. The current stable version is 2.7.3; "nightly" builds of +the development version are also available on the download page. + +To install from the compressed tar archive, change directory to the desired +install location, and unpack the software using ``tar``: + +.. code-block:: console + + $ cd + $ tar zxvf + +To install from the macOS disk image, double-click the downloaded .dmg file. In +the window that opens, double-click the installer package file (.pkg) to launch +the installer, and follow its instructions. In newer versions of macOS, if you +see an error that the app is from an untrusted developer, you can override this +warning by opening it anyway from the Security & Privacy pane within the +computer's System Preferences. + +.. _user_environment: + +Configuring MNE-C +^^^^^^^^^^^^^^^^^ + +MNE-C requires two environment variables to be defined manually: + +- ``MNE_ROOT`` should give the path to the folder where MNE-C is installed +- ``MATLAB_ROOT`` should give the path to your MATLAB binary (e.g., + ``/opt/MATLAB/R2018b`` or similar). If you do not have MATLAB or the MATLAB + runtime, leave ``MATLAB_ROOT`` undefined. + +Other environment variables are defined by setup scripts provided with MNE-C. +You may either run the setup script each time you use MNE-C, or (recommended) +configure your shell to run it automatically each time you open a terminal. For +bash compatible shells, e.g., sh/bash/zsh, the script to source is +``$MNE_ROOT/bin/mne_setup_sh``. For C shells, e.g., csh/tcsh, the script to +source is ``$MNE_ROOT/bin/mne_setup``. If you don't know what shell you are +using, you can run the following command to find out: + +.. code-block:: console + + $ echo $SHELL + +To configure MNE-C automatically for ``bash`` or ``sh`` shells, add this to +your ``.bashrc``: + +.. code-block:: sh + + export MNE_ROOT= + export MATLAB_ROOT= + source $MNE_ROOT/bin/mne_setup_sh + +where ```` and ```` are replaced by the absolute +paths to MNE-C and MATLAB, respectively. If you don't have MATLAB, you should +still include the ``export MATLAB_ROOT=`` statement, but leave +```` blank. + +To configure MNE-C automatically for ``zsh``, use the built-in ``emulate`` +command in your ``.zshrc`` file: + +.. code-block:: sh + + export MNE_ROOT= + export MATLAB_ROOT= + emulate sh -c 'source $MNE_ROOT/bin/mne_setup_sh' + +To configure MNE-C automatically for ``csh`` or ``tcsh`` shells, the +corresponding commands in the ``.cshrc`` / ``.tcshrc`` file are: + +.. code-block:: tcsh + + setenv MNE_ROOT + setenv MATLAB_ROOT + source $MNE_ROOT/bin/mne_setup + +If you have done this correctly, the command ``ls $MNE_ROOT/bin/mne_setup_sh`` +should succeed when run in a new terminal. + +Testing MNE-C installation +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An easy way to verify whether your installation of MNE-C is working is to test +the OpenGL graphics performance: + +.. code-block:: console + + $ $MNE_ROOT/bin/mne_opengl_test + +This will render an inflated brain surface repeatedly, rotating it by 5 degrees +around the z-axis between redraws. The time spent for each full revolution is +printed to the terminal window where ``mne_opengl_test`` was invoked. Switch +focus to that terminal window and use the interrupt key (usually control-c) to +halt the test. + +The best graphics performance occurs when MNE-C renders to a local display on a +computer with hardware acceleration enabled. The ``mne_analyze`` GUI has a menu +item "On GLX..." in the Help menu; if the GLX dialog says "Direct rendering +context" then hardware acceleration is in use. If you are rendering to a local +display and see "Nondirect rendering context", it is recommended that you +enable hardware acceleration (consult a search engine or your local IT support +staff for assistance). If you are rendering to a remote display or using a VNC +connection, "Nondirect rendering context" is normal. + +On the fastest graphics cards, the time per revolution in the +``mne_opengl_test`` is well below 1 second. If your time per revolution is +longer than 10 seconds, either the graphics hardware acceleration is not in +effect or you need a faster graphics adapter. + +Troubleshooting MNE-C installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If MNE-C can't find ``libxp.so.6``, download libxp6 from ubuntu_ or debian_ and +install with ``dpkg`` or similar: + +.. code-block:: console + + $ sudo dpkg -i libxp6_1.0.2-1ubuntu1_amd64.deb + +If MNE-C can't find ``libgfortran.so.1``, you can probably safely link that +filename to the current version of libfortran that came with your system. On +a typical 64-bit Ubuntu-like system this would be accomplished by: + +.. code-block:: console + + $ cd /usr/lib/x86_64-linux-gnu + $ sudo ln -s libgfortran.so.1 $(find . -maxdepth 1 -type f -name libgfortran.so*) + +If you encounter other errors installing MNE-C, please send a message to the +`MNE mailing list`_. + +.. links + +.. _MNE-C download page: http://www.nmr.mgh.harvard.edu/martinos/userInfo/data/MNE_register/index.php +.. _MATLAB runtime: https://www.mathworks.com/products/compiler/matlab-runtime.html +.. _netpbm: http://netpbm.sourceforge.net/ +.. _MacPorts: https://www.macports.org/ +.. _Homebrew: https://brew.sh/ +.. _XCode developer tools: http://appstore.com/mac/apple/xcode +.. _xquartz: https://www.xquartz.org/ +.. _ubuntu: https://packages.ubuntu.com/search?keywords=libxp6 +.. _debian: https://packages.debian.org/search?keywords=libxp6 diff -Nru python-mne-0.18.1+dfsg/doc/install/mne_python.rst python-mne-0.19.1+dfsg/doc/install/mne_python.rst --- python-mne-0.18.1+dfsg/doc/install/mne_python.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install/mne_python.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,199 @@ +.. include:: ../links.inc + +.. _install_python_and_mne_python: + +Installing MNE-Python +===================== + +.. contents:: Page contents + :local: + :depth: 1 + +.. highlight:: console + +.. _install-python: + +Installing Python +^^^^^^^^^^^^^^^^^ + +MNE-Python runs within Python, and depends on several other Python packages. +MNE-Python 0.18 only supports Python version 3.5 or higher. We strongly +recommend the `Anaconda`_ distribution of Python, which comes with more than +250 scientific packages pre-bundled, and includes the ``conda`` command line +tool for installing new packages and managing different package sets +("environments") for different projects. + +To get started, follow the `installation instructions for Anaconda`_. +When you are done, if you type the following commands in a ``bash`` terminal, +you should see outputs similar to the following (assuming you installed +conda to ``/home/user/anaconda3``):: + + $ conda --version && python --version + conda 4.6.2 + Python 3.6.7 :: Anaconda, Inc. + $ which python + /home/user/anaconda3/bin/python + $ which pip + /home/user/anaconda3/bin/pip + +.. collapse:: |hand-stop-o| If you get an error or these look incorrect... + :class: danger + + **If you see something like**:: + + conda: command not found + + It means that your ``PATH`` variable (what the system uses to find + programs) is not set properly. In a correct installation, doing:: + + $ echo $PATH + ...:/home/user/anaconda3/bin:... + + Will show the Anaconda binary path (above) somewhere in the output + (probably at or near the beginning), but the ``command not found`` error + suggests that it is missing. + + On Linux or OSX, the installer should have put something + like the following in your ``~/.bashrc`` or ``~/.bash_profile`` + (or somewhere else if you are using a non-bash terminal): + + .. code-block:: bash + + . ~/anaconda3/etc/profile.d/conda.sh + + If this is missing, it is possible that you are not on the same shell that + was used during the installation. You can verify which shell you are on by + using the command:: + + $ echo $SHELL + + If you do not find this line in the configuration file for the shell you + are using (bash, tcsh, etc.), add the line to that shell's ``rc`` or + ``profile`` file to fix the problem. + + **If you see an error like**:: + + CommandNotFoundError: Your shell has not been properly configured to use 'conda activate'. + + It means that you have used an old method to set up Anaconda. This + means that you have something like:: + + PATH=~/anaconda3/bin:$PATH + + in your ``~/.bash_profile``. You should update this line to use + the modern way using ``anaconda3/etc/profile.d/conda.sh`` above. + + You can also consult the Anaconda documentation and search for + Anaconda install tips (`Stack Overflow`_ results are often helpful) + to fix these or other problems when ``conda`` does not work. + +.. _standard_instructions: + +Installing MNE-Python and its dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once you have Anaconda installed, the easiest way to install +MNE-Python with all dependencies is update your base Anaconda environment: + +.. _environment file: https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml + +.. collapse:: |linux| Linux + + Use the base `environment file`_, e.g.:: + + $ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml + $ conda env update --file environment.yml + +.. collapse:: |apple| macOS + + Use the base `environment file`_ and then update PyQt using :samp:`pip`, e.g.:: + + $ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml + $ conda env update --file environment.yml + $ pip install "PyQt5>=5.10" + +.. collapse:: |windows| Windows + + - Download the base `environment file`_ + - Open an Anaconda command prompt + - :samp:`cd` to the directory where you downloaded the file + - Run :samp:`conda env update --file environment.yml` + +.. raw:: html + +
+ +If you prefer an isolated Anaconda environment, instead of using\ +:samp:`conda env update` to modify your "base" environment, +you can create a new dedicated environment with +:samp:`conda env create --name mne --file environment.yml`. + +.. javascript below adapted from nilearn + +.. raw:: html + + + +Testing MNE-Python installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To make sure MNE-Python installed itself and its dependencies correctly, +type the following command in a terminal:: + + $ python -c 'import mne; mne.sys_info()' + +This should display some system information along with the versions of +MNE-Python and its dependencies. Typical output looks like this:: + + Platform: Linux-4.18.0-13-generic-x86_64-with-debian-buster-sid + Python: 3.6.8 |Anaconda, Inc.| (default, Dec 30 2018, 01:22:34) [GCC 7.3.0] + Executable: /home/travis/miniconda/bin/python + CPU: x86_64: 48 cores + Memory: 62.7 GB + + mne: 0.17.0 + numpy: 1.15.4 {blas=mkl_rt, lapack=mkl_rt} + scipy: 1.2.0 + matplotlib: 3.0.2 {backend=Qt5Agg} + + sklearn: 0.20.2 + numba: 0.45.0 + nibabel: 2.3.3 + cupy: Not found + pandas: 0.24.0 + dipy: 0.15.0 + mayavi: 4.7.1 {qt_api=pyqt5, PyQt5=5.10.1} + pyvista: 0.21.3 + vtk: 8.2.0 + +.. collapse:: |hand-stop-o| If you get an error... + :class: danger + + **If you see an error like**:: + + Traceback (most recent call last): + File "", line 1, in + ModuleNotFoundError: No module named 'mne' + + This suggests that your ``mne`` environment is not active. Try doing + ``conda activate mne`` and try again. If this works, you might want to + add ``conda activate mne`` to the end of your ``~/.bashrc`` or + ``~/.bash_profile`` files so that it gets executed automatically. + +If something else went wrong during installation and you can't figure it out, +check out the :doc:`advanced` page to see if your problem is discussed there. +If not, the `MNE mailing list`_ and `MNE gitter channel`_ are +good resources for troubleshooting installation problems. + +.. highlight:: python + +**Next:** :doc:`freesurfer` diff -Nru python-mne-0.18.1+dfsg/doc/install/pre_install.rst python-mne-0.19.1+dfsg/doc/install/pre_install.rst --- python-mne-0.18.1+dfsg/doc/install/pre_install.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install/pre_install.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,94 @@ +.. include:: ../links.inc + +Before you install +================== + +.. contents:: + :local: + :depth: 1 + +Overview of the MNE tools suite +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- MNE-C was the initial stage of this project, + providing a set of interrelated command-line and GUI programs focused on + computing cortically constrained Minimum Norm Estimates from MEG and EEG + data. These tools were written in C by Matti Hämäläinen, and are + documented `here `_. + +- :doc:`MNE-Python <../python_reference>` reimplements the functionality of + MNE-C, and extends considerably the analysis and visualization capabilities. + MNE-Python is collaboratively developed and has more than 150 contributors. + +- The :ref:`mne_matlab` provides a MATLAB interface to the .fif file + format and other MNE data structures, and provides example MATLAB + implementations of some of the core analysis functionality of MNE-C. It is + distributed alongside MNE-C, and can also be downloaded from the `MNE-MATLAB + git repository`_. + +- :doc:`MNE-CPP <../mne_cpp>` provides core MNE functionality implemented in + C++ and is primarily intended for embedded and real-time applications. + +There is also a growing ecosystem of other Python packages that work alongside +MNE-Python, including packages for: + +- a graphical user interface for MNE-Python (`MNELAB`_) +- easily importing MEG data from the Human Connectome Project for + use with MNE-Python (`MNE-HCP`_) +- managing MNE projects so that they comply with the `Brain + Imaging Data Structure`_ specification (`MNE-BIDS`_) +- automatic bad channel detection and interpolation (`autoreject`_) +- convolutional sparse dictionary learning and waveform shape estimation + (`alphaCSC`_) +- independent component analysis (ICA) with good performance on real data + (`PICARD`_) +- phase-amplitude coupling (`pactools`_) +- representational similarity analysis (`rsa`_) +- microstate analysis (`microstate`_) +- connectivity analysis using dynamic imaging of coherent sources (DICS) + (`conpy`_) +- general-purpose statistical analysis of M/EEG data (`eelbrain`_) +- post-hoc modification of linear models (`posthoc`_) + + +What should I install? +^^^^^^^^^^^^^^^^^^^^^^ + +If you intend only to perform ERP, ERF, or other sensor-level analyses, +:doc:`MNE-Python ` is all you need. If you prefer to work with +shell scripts and the Unix command line, or prefer MATLAB over Python, probably +all you need is :doc:`MNE-C ` — the MNE MATLAB toolbox is distributed +with it — although note that the C tools and the MATLAB toolbox are less +actively developed than the MNE-Python module, and hence are considerably less +feature-complete. + +If you want to transform sensor recordings into estimates of localized brain +activity, you will most likely also need :doc:`FreeSurfer ` to +convert structural MRI scans into models of the scalp, inner/outer skull, and +cortical surfaces (specifically, for command-line functions +:ref:`gen_mne_flash_bem`, :ref:`gen_mne_watershed_bem`, and +:ref:`gen_mne_make_scalp_surfaces`). + + +Getting help +^^^^^^^^^^^^ + +Help with installation is available through the `MNE mailing list`_ and +`MNE gitter channel`_. See the :ref:`help` page for more information. + + +**Next:** :doc:`mne_python` + + +.. LINKS: + +.. _MNELAB: https://github.com/cbrnr/mnelab +.. _autoreject: https://autoreject.github.io/ +.. _alphaCSC: https://alphacsc.github.io/ +.. _picard: https://pierreablin.github.io/picard/ +.. _pactools: https://pactools.github.io/ +.. _rsa: https://github.com/wmvanvliet/rsa +.. _microstate: https://github.com/wmvanvliet/mne_microstates +.. _conpy: https://aaltoimaginglanguage.github.io/conpy/ +.. _eelbrain: https://eelbrain.readthedocs.io/en/stable/index.html +.. _posthoc: https://users.aalto.fi/~vanvlm1/posthoc/python/ diff -Nru python-mne-0.18.1+dfsg/doc/install_freesurfer.rst python-mne-0.19.1+dfsg/doc/install_freesurfer.rst --- python-mne-0.18.1+dfsg/doc/install_freesurfer.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install_freesurfer.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,25 +0,0 @@ -.. include:: links.inc - -.. _install_freesurfer: - -Installing FreeSurfer -===================== - -`FreeSurfer`_ is software for analysis and visualization of MRI data. In the -MNE ecosystem, freesurfer is used to convert structural MRI scans into models -of the scalp, inner/outer skull, and cortical surfaces, which are used to - -1. model how changes in the electrical and magnetic field caused by neural - activity propagate to the sensor locations (part of computing the "forward - solution"), and - -2. constrain the estimates of where brain activity may have occurred (in the - "inverse imaging" step of source localization). - -System requirements, setup instructions, and test scripts are provided on the -`FreeSurfer download page`_. Note that if you don't already have it, you will -need to install ``tcsh`` for FreeSurfer to work; ``tcsh`` is usually -pre-installed with macOS, and is available in the package repositories for -Linux-based systems (e.g., ``sudo apt install tcsh`` on Ubuntu-like systems). - -**Next:** :doc:`install_mne_c` diff -Nru python-mne-0.18.1+dfsg/doc/install_mne_c.rst python-mne-0.19.1+dfsg/doc/install_mne_c.rst --- python-mne-0.18.1+dfsg/doc/install_mne_c.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install_mne_c.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,198 +0,0 @@ -.. include:: links.inc - -.. _install_mne_c: - -Installing MNE-C -================ - -.. contents:: - :local: - :depth: 1 - -System requirements -^^^^^^^^^^^^^^^^^^^ - -MNE-C runs on macOS (version 10.5 "Leopard" or later) and Linux (kernel 2.6.9 -or later). Both 32- and 64-bit operating systems are supported; a PowerPC -version for macOS can be provided upon request. At least 2 GB of memory is -required, 4 GB or more is recommended. The software requires at least 80 MB of -disk space. MATLAB is an optional dependency; the free `MATLAB runtime`_ is -sufficient. If MATLAB is not present, the utilities ``mne_convert_mne_data``, -``mne_epochs2mat``, ``mne_raw2mat``, and ``mne_simu`` will not work. - -For boundary-element model (BEM) mesh generation (see :doc:`Creating the BEM -meshes `), and for accessing the ``tkmedit`` program -from ``mne_analyze`` (see :ref:`CACCHCBF`), MNE-C needs access to a working -installation of :doc:`FreeSurfer `, including the -environment variables ``FREESURFER_HOME``, ``SUBJECTS_DIR``, and ``SUBJECT``. - -.. admonition:: |apple| macOS - :class: note - - For installation on macOS, you also need: - - - the `XCode developer tools`_. - - an X Window System such as XQuartz_. Version 2.7.9 of XQuartz should work - out of the box; the most current version (2.7.11, as of May 2019) may - require these additional steps to work: - - .. code-block:: console - - $ cd /opt/X11/lib - $ sudo cp libXt.6.dylib libXt.6.dylib.bak - $ cd flat_namespace/ - $ sudo cp libXt.6.dylib ../. - - - the netpbm_ library. The recommended way to get netpbm is to install - Homebrew_, and run ``brew install netpbm`` in the Terminal app. - Alternatively, if you prefer to use MacPorts_, you can run - ``sudo port install netpbm`` in the Terminal app. - - -Downloading and Installing MNE-C -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -MNE-C is distributed as either a compressed tar archive (.tar.gz) or a macOS -disk image (.dmg). The `MNE-C download page`_ requires registration with a -valid email address. The current stable version is 2.7.3; "nightly" builds of -the development version are also available on the download page. - -To install from the compressed tar archive, change directory to the desired -install location, and unpack the software using ``tar``: - -.. code-block:: console - - $ cd - $ tar zxvf - -To install from the macOS disk image, double-click the downloaded .dmg file. In -the window that opens, double-click the installer package file (.pkg) to launch -the installer, and follow its instructions. In newer versions of macOS, if you -see an error that the app is from an untrusted developer, you can override this -warning by opening it anyway from the Security & Privacy pane within the -computer's System Preferences. - -.. _user_environment: - -Configuring MNE-C -^^^^^^^^^^^^^^^^^ - -MNE-C requires two environment variables to be defined manually: - -- ``MNE_ROOT`` should give the path to the folder where MNE-C is installed -- ``MATLAB_ROOT`` should give the path to your MATLAB binary (e.g., - ``/opt/MATLAB/R2018b`` or similar). If you do not have MATLAB or the MATLAB - runtime, leave ``MATLAB_ROOT`` undefined. - -Other environment variables are defined by setup scripts provided with MNE-C. -You may either run the setup script each time you use MNE-C, or (recommended) -configure your shell to run it automatically each time you open a terminal. For -bash compatible shells, e.g., sh/bash/zsh, the script to source is -``$MNE_ROOT/bin/mne_setup_sh``. For C shells, e.g., csh/tcsh, the script to -source is ``$MNE_ROOT/bin/mne_setup``. If you don't know what shell you are -using, you can run the following command to find out: - -.. code-block:: console - - $ echo $SHELL - -To configure MNE-C automatically for ``bash`` or ``sh`` shells, add this to -your ``.bashrc``: - -.. code-block:: sh - - export MNE_ROOT= - export MATLAB_ROOT= - source $MNE_ROOT/bin/mne_setup_sh - -where ```` and ```` are replaced by the absolute -paths to MNE-C and MATLAB, respectively. If you don't have MATLAB, you should -still include the ``export MATLAB_ROOT=`` statement, but leave -```` blank. - -To configure MNE-C automatically for ``zsh``, use the built-in ``emulate`` -command in your ``.zshrc`` file: - -.. code-block:: sh - - export MNE_ROOT= - export MATLAB_ROOT= - emulate sh -c 'source $MNE_ROOT/bin/mne_setup_sh' - -To configure MNE-C automatically for ``csh`` or ``tcsh`` shells, the -corresponding commands in the ``.cshrc`` / ``.tcshrc`` file are: - -.. code-block:: tcsh - - setenv MNE_ROOT - setenv MATLAB_ROOT - source $MNE_ROOT/bin/mne_setup - -If you have done this correctly, the command ``ls $MNE_ROOT/bin/mne_setup_sh`` -should succeed when run in a new terminal. - -Testing MNE-C installation -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -An easy way to verify whether your installation of MNE-C is working is to test -the OpenGL graphics performance: - -.. code-block:: console - - $ $MNE_ROOT/bin/mne_opengl_test - -This will render an inflated brain surface repeatedly, rotating it by 5 degrees -around the z-axis between redraws. The time spent for each full revolution is -printed to the terminal window where ``mne_opengl_test`` was invoked. Switch -focus to that terminal window and use the interrupt key (usually control-c) to -halt the test. - -The best graphics performance occurs when MNE-C renders to a local display on a -computer with hardware acceleration enabled. The ``mne_analyze`` GUI has a menu -item "On GLX..." in the Help menu; if the GLX dialog says "Direct rendering -context" then hardware acceleration is in use. If you are rendering to a local -display and see "Nondirect rendering context", it is recommended that you -enable hardware acceleration (consult a search engine or your local IT support -staff for assistance). If you are rendering to a remote display or using a VNC -connection, "Nondirect rendering context" is normal. - -On the fastest graphics cards, the time per revolution in the -``mne_opengl_test`` is well below 1 second. If your time per revolution is -longer than 10 seconds, either the graphics hardware acceleration is not in -effect or you need a faster graphics adapter. - -Troubleshooting MNE-C installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If MNE-C can't find ``libxp.so.6``, download libxp6 from ubuntu_ or debian_ and -install with ``dpkg`` or similar: - -.. code-block:: console - - $ sudo dpkg -i libxp6_1.0.2-1ubuntu1_amd64.deb - -If MNE-C can't find ``libgfortran.so.1``, you can probably safely link that -filename to the current version of libfortran that came with your system. On -a typical 64-bit Ubuntu-like system this would be accomplished by: - -.. code-block:: console - - $ cd /usr/lib/x86_64-linux-gnu - $ sudo ln -s libgfortran.so.1 $(find . -maxdepth 1 -type f -name libgfortran.so*) - -If you encounter other errors installing MNE-C, please send a message to the -`MNE mailing list`_. - -**Next:** :doc:`advanced_setup` - -.. links - -.. _MNE-C download page: http://www.nmr.mgh.harvard.edu/martinos/userInfo/data/MNE_register/index.php -.. _MATLAB runtime: https://www.mathworks.com/products/compiler/matlab-runtime.html -.. _netpbm: http://netpbm.sourceforge.net/ -.. _MacPorts: https://www.macports.org/ -.. _Homebrew: https://brew.sh/ -.. _XCode developer tools: http://appstore.com/mac/apple/xcode -.. _xquartz: https://www.xquartz.org/ -.. _ubuntu: https://packages.ubuntu.com/search?keywords=libxp6 -.. _debian: https://packages.debian.org/search?keywords=libxp6 diff -Nru python-mne-0.18.1+dfsg/doc/install_mne_python.html python-mne-0.19.1+dfsg/doc/install_mne_python.html --- python-mne-0.18.1+dfsg/doc/install_mne_python.html 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install_mne_python.html 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,9 @@ + + + + + + +

Please follow this link.

+ + diff -Nru python-mne-0.18.1+dfsg/doc/install_mne_python.rst python-mne-0.19.1+dfsg/doc/install_mne_python.rst --- python-mne-0.18.1+dfsg/doc/install_mne_python.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/install_mne_python.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,107 +0,0 @@ -.. include:: links.inc - -.. _install_python_and_mne_python: - -Installing MNE-Python -===================== - -.. contents:: - :local: - :depth: 1 - -.. _install-python: - -Installing Python -^^^^^^^^^^^^^^^^^ - -MNE-Python runs within Python, and depends on several other Python packages. -MNE-Python 0.18 only supports Python version 3.5 or higher. We strongly -recommend the `Anaconda`_ distribution of Python, which comes with more than -250 scientific packages pre-bundled, and includes the ``conda`` command line -tool for installing new packages and managing different package sets -("environments") for different projects. Follow the `installation instructions -for Anaconda`_; when you are done, you should see a similar output if you type -the following command in a terminal: - -.. code-block:: console - - $ conda --version && python --version - conda 4.6.2 - Python 3.6.7 :: Anaconda, Inc. - -If you get an error message, consult the Anaconda documentation and search for -Anaconda install tips (`Stack Overflow`_ results are often helpful). - -Installing MNE-Python and its dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Once you have Anaconda installed, the easiest way to install -MNE-Python is to use the provided `environment file`_ to install MNE-Python -and its dependencies into a new conda environment: - -.. code-block:: console - - $ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml - $ conda env create -f environment.yml - $ conda activate mne - -(You can also use a web browser to download the required `environment file`_ if -you do not have ``curl``.) These commands will create a new environment called -``mne`` and then activate it. - -Make sure you activate the environment (``conda activate mne``) each time you -open a terminal, or put the activation command in your ``.bashrc`` or -``.profile`` so that it happens automatically. - -.. admonition:: |apple| macOS - :class: note - - If you are on macOS, you need to manually update PyQt5. This step is not - needed on Linux, and even breaks things on Windows. - - .. code-block:: console - - $ pip install --upgrade "pyqt5>=5.10" - -Testing MNE-Python installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To make sure MNE-Python installed correctly, type the following command in a -terminal: - -.. code-block:: console - - $ python -c 'import mne; mne.sys_info()' - -This should display some system information along with the versions of -MNE-Python and its dependencies. Typical output looks like this: - -.. code-block:: console - - Platform: Linux-4.18.0-13-generic-x86_64-with-debian-buster-sid - Python: 3.6.8 |Anaconda, Inc.| (default, Dec 30 2018, 01:22:34) [GCC 7.3.0] - Executable: /home/travis/miniconda/envs/test/bin/python - CPU: x86_64: 48 cores - Memory: 62.7 GB - - mne: 0.17.0 - numpy: 1.15.4 {blas=mkl_rt, lapack=mkl_rt} - scipy: 1.2.0 - matplotlib: 3.0.2 {backend=Qt5Agg} - - sklearn: 0.20.2 - nibabel: 2.3.3 - mayavi: 4.7.0.dev0 {qt_api=pyqt5, PyQt5=5.10.1} - cupy: Not found - pandas: 0.24.0 - dipy: 0.15.0 - -Troubleshooting MNE-Python installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If something went wrong during installation and you can't figure it out -yourself, check out the :doc:`advanced_setup` page to see if your problem is -discussed there. If not, the `MNE mailing list`_ and `MNE gitter channel`_ are -good resources for troubleshooting installation problems. - -**Next:** :doc:`install_freesurfer` diff -Nru python-mne-0.18.1+dfsg/doc/known_projects.inc python-mne-0.19.1+dfsg/doc/known_projects.inc --- python-mne-0.18.1+dfsg/doc/known_projects.inc 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/known_projects.inc 1970-01-01 00:00:00.000000000 +0000 @@ -1,63 +0,0 @@ -.. Known projects - -.. PROJECTNAME placeholders -.. _PROJECTNAME: http://neuroimaging.scipy.org -.. _`PROJECTNAME github`: http://github.com/nipy -.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel - -.. numpy -.. _numpy: http://www.numpy.org -.. _`numpy github`: http://github.com/numpy/numpy -.. _`numpy style`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt -.. _`numpy mailing list`: http://mail.scipy.org/mailman/listinfo/numpy-discussion - -.. scipy -.. _scipy: http://www.scipy.org -.. _`scipy github`: http://github.com/scipy/scipy -.. _`scipy mailing list`: http://mail.scipy.org/mailman/listinfo/scipy-dev - -.. nipy -.. _nipy: http://nipy.org/nipy -.. _`nipy github`: http://github.com/nipy/nipy -.. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel - -.. ipython -.. _ipython: https://ipython.org -.. _`ipython github`: https://github.com/ipython/ipython -.. _`ipython mailing list`: https://mail.python.org/mailman/listinfo/ipython-dev - -.. dipy -.. _dipy: http://nipy.org/dipy -.. _`dipy github`: http://github.com/Garyfallidis/dipy -.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel - -.. nibabel -.. _nibabel: http://nipy.org/nibabel -.. _`nibabel github`: http://github.com/nipy/nibabel -.. _`nibabel mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel - -.. h5py -.. _h5py: http://www.h5py.org -.. _`h5py github`: http://github.com/h5py/h5py -.. _`h5py mailing list`: https://groups.google.com/forum/#!forum/h5py - -.. marsbar -.. _marsbar: http://marsbar.sourceforge.net -.. _`marsbar github`: http://github.com/matthew-brett/marsbar -.. _`MarsBaR mailing list`: https://lists.sourceforge.net/lists/listinfo/marsbar-users - -.. Astropy -.. _Astropy: http://www.astropy.org -.. _`Astropy GitHub`: http://github.com/astropy/astropy - -.. Pytest -.. _pytest: https://docs.pytest.org/ - -.. Flake8 -.. _Flake8: http://flake8.pycqa.org/ - -.. pymatreader -.. _pymatreader: https://gitlab.com/obob/pymatreader - -.. CuPy -.. _CuPy: https://cupy.chainer.org/ \ No newline at end of file diff -Nru python-mne-0.18.1+dfsg/doc/links.inc python-mne-0.19.1+dfsg/doc/links.inc --- python-mne-0.18.1+dfsg/doc/links.inc 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/links.inc 2019-10-25 14:42:45.000000000 +0000 @@ -1,4 +1,218 @@ -.. compiling links file -.. include:: known_projects.inc -.. include:: this_project.inc -.. include:: git_links.inc +.. This (-*- rst -*-) format file contains commonly used link targets + and name substitutions. It may be included in many files, + therefore it should only contain link targets and name + substitutions. Try grepping for "^\.\. _" to find plausible + candidates for this list. + +.. NOTE: reST targets are + __not_case_sensitive__, so only one target definition is needed for + nipy, NIPY, Nipy, etc... + + +.. mne + +.. _`mne-python`: http://mne-tools.github.io/mne-python-intro +.. _`mne-python GitHub`: https://github.com/mne-tools/mne-python +.. _`mne-python sample dataset`: https://s3.amazonaws.com/mne-python/datasets/MNE-sample-data-processed.tar.gz +.. _`mne command line utilities`: http://www.nmr.mgh.harvard.edu/martinos/userInfo/data/MNE_register/ +.. _`mne-scripts`: https://github.com/mne-tools/mne-scripts/ +.. _`MNE-C manual`: https://mne.tools/mne-c-manual/MNE-manual-2.7.3.pdf +.. _`MNE mailing list`: http://mail.nmr.mgh.harvard.edu/mailman/listinfo/mne_analysis +.. _`GitHub issues page`: https://github.com/mne-tools/mne-python/issues/ +.. _`MNE gitter channel`: https://gitter.im/mne-tools/mne-python +.. _`MNE-BIDS`: https://mne-tools.github.io/mne-bids/ +.. _`MNE-HCP`: http://mne-tools.github.io/mne-hcp/ +.. _`MNE-Realtime`: https://github.com/mne-tools/mne-realtime +.. _`MNE-MATLAB git repository`: https://github.com/mne-tools/mne-matlab + +.. TUTORIAL LINKS + +.. _errors: https://en.wikipedia.org/w/index.php?title=Type_I_and_type_II_errors#Table_of_error_types +.. _fwer: https://en.wikipedia.org/wiki/Family-wise_error_rate +.. _fdr: https://en.wikipedia.org/wiki/False_discovery_rate +.. _ft_cluster: http://www.fieldtriptoolbox.org/faq/how_not_to_interpret_results_from_a_cluster-based_permutation_test +.. _ft_cluster_effect_size: https://mailman.science.ru.nl/pipermail/fieldtrip/2017-September/024644.html +.. _ft_exch: https://mailman.science.ru.nl/pipermail/fieldtrip/2008-October/001794.html + + + +.. TEMPLATE FOR LINKS TO OTHER PROJECTS +.. _PROJECTNAME: http://neuroimaging.scipy.org +.. _`PROJECTNAME github`: http://github.com/nipy +.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel + +.. numpy + +.. _numpy: http://www.numpy.org +.. _`numpy github`: http://github.com/numpy/numpy +.. _`numpy style`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt +.. _`numpy mailing list`: http://mail.scipy.org/mailman/listinfo/numpy-discussion + + +.. scipy + +.. _scipy: http://www.scipy.org +.. _`scipy github`: http://github.com/scipy/scipy +.. _`scipy mailing list`: http://mail.scipy.org/mailman/listinfo/scipy-dev + + +.. nipy + +.. _nipy: http://nipy.org/nipy +.. _`nipy github`: http://github.com/nipy/nipy +.. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel + + +.. ipython + +.. _ipython: https://ipython.org +.. _`ipython github`: https://github.com/ipython/ipython +.. _`ipython mailing list`: https://mail.python.org/mailman/listinfo/ipython-dev + + +.. dipy + +.. _dipy: http://nipy.org/dipy +.. _`dipy github`: http://github.com/Garyfallidis/dipy +.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel + + +.. nibabel + +.. _nibabel: http://nipy.org/nibabel +.. _`nibabel github`: http://github.com/nipy/nibabel +.. _`nibabel mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel + + +.. h5py + +.. _h5py: http://www.h5py.org +.. _`h5py github`: http://github.com/h5py/h5py +.. _`h5py mailing list`: https://groups.google.com/forum/#!forum/h5py + + +.. marsbar + +.. _marsbar: http://marsbar.sourceforge.net +.. _`marsbar github`: http://github.com/matthew-brett/marsbar +.. _`MarsBaR mailing list`: https://lists.sourceforge.net/lists/listinfo/marsbar-users + + +.. Astropy + +.. _Astropy: http://www.astropy.org +.. _`Astropy GitHub`: http://github.com/astropy/astropy + + +.. Pytest + +.. _pytest: https://docs.pytest.org/ + + +.. Flake8 + +.. _Flake8: http://flake8.pycqa.org/ + + +.. pymatreader + +.. _pymatreader: https://gitlab.com/obob/pymatreader + + +.. CuPy + +.. _CuPy: https://cupy.chainer.org/ + + +.. git stuff + +.. _git: https://git-scm.com/ +.. _github: https://github.com +.. _GitHub Help: https://help.github.com +.. _msysgit: http://code.google.com/p/msysgit/downloads/list +.. _git-osx-installer: http://code.google.com/p/git-osx-installer/downloads/list +.. _subversion: http://subversion.tigris.org/ +.. _git cheat sheet: http://github.com/guides/git-cheat-sheet +.. _pro git book: http://progit.org/ +.. _git svn crash course: http://git-scm.com/course/svn.html +.. _learn.github: http://learn.github.com/ +.. _network graph visualizer: https://github.com/blog/39-say-hello-to-the-network-graph-visualizer +.. _git user manual: https://schacon.github.io/git/user-manual.html +.. _git tutorial: https://schacon.github.io/git/gittutorial.html +.. _git community book: http://book.git-scm.com/ +.. _git ready: http://www.gitready.com/ +.. _git casts: http://www.gitcasts.com/ +.. _git magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html +.. _git concepts: http://www.eecs.harvard.edu/~cduan/technical/git/ +.. _git clone: http://schacon.github.com/git/git-clone.html +.. _git checkout: https://schacon.github.io/git/git-checkout.html +.. _git commit: https://schacon.github.io/git/git-commit.html +.. _git push: https://schacon.github.io/git/git-push.html +.. _git pull: https://schacon.github.io/git/git-pull.html +.. _git add: https://schacon.github.io/git/git-add.html +.. _git status: https://schacon.github.io/git/git-status.html +.. _git diff: https://schacon.github.io/git/git-diff.html +.. _git log: https://schacon.github.io/git/git-log.html +.. _git branch: https://schacon.github.io/git/git-branch.html +.. _git remote: https://schacon.github.io/git/git-remote.html +.. _git rebase: https://schacon.github.io/git/git-rebase.html +.. _git config: https://schacon.github.io/git/git-config.html +.. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html +.. _tangled working copy problem: http://tomayko.com/writings/the-thing-about-git +.. _git management: http://kerneltrap.org/Linux/Git_Management +.. _linux git workflow: http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html +.. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html +.. _git foundation: http://matthew-brett.github.io/pydagogue/foundation.html +.. _deleting master on github: http://matthew-brett.github.io/pydagogue/gh_delete_master.html +.. _rebase without tears: http://matthew-brett.github.io/pydagogue/rebase_without_tears.html +.. _resolving a merge: https://schacon.github.io/git/user-manual.html#resolving-a-merge +.. _ipython git workflow: https://web.archive.org/web/*/http://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html +.. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html +.. _Fernando's git page: http://www.fperez.org/py4science/git.html + +.. other stuff + +.. _python: http://www.python.org +.. _travis: https://travis-ci.org/ +.. _linterflake8: https://atom.io/packages/linter-flake8 +.. _Brain Imaging Data Structure: https://bids.neuroimaging.io/ + +.. python packages + +.. _pep8: https://pypi.org/project/pep8/ +.. _pyflakes: https://pypi.org/project/pyflakes +.. _coverage: https://pypi.python.org/pypi/coverage +.. _mayavi: https//docs.enthought.com/mayavi/mayavi/ +.. _nitime: http://nipy.org/nitime/ +.. _joblib: https://pypi.python.org/pypi/joblib +.. _scikit-learn: https://scikit-learn.org/stable/ +.. _pysurfer: https://pysurfer.github.io/ +.. _pyDICOM: https://pypi.python.org/pypi/pydicom/ +.. _matplotlib: https://matplotlib.org/ +.. _sphinx: http://sphinx-doc.org/ +.. _pandas: http://pandas.pydata.org/ +.. _PIL: https://pypi.python.org/pypi/PIL + +.. python editors + +.. _atom: https://atom.io/ +.. _Spyder: https://www.spyder-ide.org/ +.. _anaconda: https://www.anaconda.com/distribution/ +.. _miniconda: https://conda.io/en/latest/miniconda.html +.. _installation instructions for Anaconda: http://docs.continuum.io/anaconda/install +.. _installation instructions for Miniconda: https://conda.io/projects/conda/en/latest/user-guide/install/index.html +.. _EPD: https://www.enthought.com/products/epd/ +.. _sublime text: http://www.sublimetext.com/ + +.. installation links + +.. _requirements file: https://raw.githubusercontent.com/mne-tools/mne-python/master/requirements.txt +.. _NVIDIA CUDA GPU processing: https://developer.nvidia.com/cuda-zone +.. _NVIDIA proprietary drivers: https://www.geforce.com/drivers + +.. _Sphinx documentation: http://sphinx-doc.org/rest.html +.. _sphinx gallery documentation: https://sphinx-gallery.github.io +.. _NumPy docstring standard: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt +.. _Stack Overflow: https://stackoverflow.com/ + +.. vim: ft=rst diff -Nru python-mne-0.18.1+dfsg/doc/manual/appendix/bem_model.rst python-mne-0.19.1+dfsg/doc/manual/appendix/bem_model.rst --- python-mne-0.18.1+dfsg/doc/manual/appendix/bem_model.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/appendix/bem_model.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,358 +0,0 @@ - -.. _create_bem_model: - -======================= -Creating the BEM meshes -======================= - -.. contents:: Contents - :local: - :depth: 2 - - -.. _BABBDHAG: - -Using the watershed algorithm -############################# - -The watershed algorithm [Segonne *et al.*, -2004] is part of the FreeSurfer software. -The name of the program is mri_watershed . -Its use in the MNE environment is facilitated by the script `mne_watershed_bem`. - -After mne_watershed_bem has -completed, the following files appear in the subject's ``bem/watershed`` directory: - -** <*subject*> _brain_surface** - - Contains the brain surface triangulation. - -** <*subject*> _inner_skull_surface** - - Contains the inner skull triangulation. - -** <*subject*> _outer_skull_surface** - - Contains the outer skull triangulation. - -** <*subject*> _outer_skin_surface** - - Contains the scalp triangulation. - -All of these surfaces are in the FreeSurfer format. In addition, -there will be a directory called ``bem/watershed/ws`` which -contains the brain MRI volume. Furthermore, mne_watershed_bem script -converts the scalp surface to fif format and saves the result to ``bem/`` <*subject*> ``-head.fif`` . The mne_analyze tool -described :ref:`c_legacy_ch_interactive_analysis` looks for this file the visualizations -involving the scalp surface. - -.. _BABFCDJH: - -Using FLASH images -################## - -This method depends on the availablily of MRI data acquired -with a multi-echo FLASH sequence at two flip angles (5 and 30 degrees). -These data can be acquired separately from the MPRAGE data employed -in FreeSurfer cortical reconstructions but it is strongly recommended -that they are collected at the same time with the MPRAGEs or at -least with the same scanner. For easy co-registration, the images -should have FOV, matrix, slice thickness, gap, and slice orientation -as the MPRAGE data. For information on suitable pulse sequences, -see reference [B. Fischl *et al.* and J. Jovicich *et -al.*, 2006] in :ref:`CEGEGDEI`. At the Martinos -Center, use of the 1.5-T Avanto scanner (Bay 2) is recommended for -best results. - -Creation of the BEM meshes using this method involves the -following steps: - -- Organizing the MRI data. This is facilitated - by the script mne_organize_dicom , - see :ref:`BABEBJHI`. - -- Creating a synthetic 5-degree flip angle FLASH volume, register - it with the MPRAGE data, and run the segmentation and meshing program. - This step is accomplished by running the script mne_flash_bem , see :ref:`BABGICFE`. - -- Inspecting the meshes with tkmedit, see :ref:`BABHJBED`. - -.. note:: Different methods can be employed for the creation of the - individual surfaces. For example, it may turn out that the - watershed algorithm produces are better quality skin surface than - the segmentation approach based on the FLASH images. If this is - the case, ``outer_skin.surf`` can set to point to the corresponding - watershed output file while the other surfaces can be picked from - the FLASH segmentation data. - -.. note:: The :ref:`mne_convert_surface` C utility can be used to convert - text format triangulation files into the FreeSurfer surface format. - -.. note:: The following sections assume that you have run the appropriate - setup scripts to make both MNE and FreeSurfer software available. - -.. _BABEBJHI: - -Organizing MRI data into directories -==================================== - -Since all images comprising the multi-echo FLASH data are -contained in a single series, it is necessary to organize the images -according to the echoes before proceeding to the BEM surface reconstruction. -This is accomplished by the mne_organize_dicom script, -which creates a directory tree with symbolic links to the original -DICOM image files. To run mne_organize_dicom , -proceed as follows: - -- Copy all of your images or create symbolic - links to them in a single directory. The images must be in DICOM - format. We will refer to this directory as <*source*> . - -- Create another directory to hold the output of mne_organize_dicom . We - will refer to this directory as <*dest*> . - -- Change the working directory to <*dest*> . - -- Say ``mne_organize_dicom`` <*source*> . - Depending on the total number of images in <*source*> this - script may take quite a while to run. Progress is indicated by - listing the number of images processed at 50-image intervals. - -As a result, <*dest*> will -contain several directories named <*three-digit number*> _ <*protocol_name*> corresponding -to the different series of images acquired. Spaces and parenthesis -in protocol names will be replaced by underscores. Under each of -these directories there are one or more directories named <*three-digit*> number -corresponding to one or more subsets of images in this series (protocol). -The only subset division scheme implemented in mne_organize_dicom is -that according to different echoes, typically found in multi-echo -FLASH data. These second level directories will contain symbolic -links pointing to the original image data. - -.. note:: mne_organize_dicom was developed specifically for Siemens DICOM data. Its correct behavior with DICOM files originating from other MRI scanners has not been verified at this time. - -.. note:: Since mne_organize_dicom processes all images, not only the FLASH data, it may be a useful preprocessing step before FreeSurfer reconstruction process as well. - -.. _BABGICFE: - -Creating the surface tessellations -================================== - -The BEM surface segmentation and tessellation is automated -with the script :ref:`mne_flash_bem`. -It assumes that a FreeSurfer reconstruction for this subject is -already in place. - -Before running mne_flash_bem do the following: - -- Run mne_organize_dicom as - described above. - -- Change to the <*dest*> directory - where mne_organize_dicom created the - image directory structure. - -- Create symbolic links from the directories containing the - 5-degree and 30-degree flip angle FLASH series to ``flash05`` and ``flash30`` , respectively: - - - ``ln -s`` <*FLASH 5 series dir*> ``flash05`` - - - ``ln -s`` <*FLASH 30 series dir*> ``flash30`` - -- Some partition formats (e.g. FAT32) do not support symbolic links. In this case, copy the file to the appropriate series: - - - ``cp`` <*FLASH 5 series dir*> ``flash05`` - - - ``cp`` <*FLASH 30 series dir*> ``flash30`` - -- Set the ``SUBJECTS_DIR`` and ``SUBJECT`` environment - variables - -.. note:: If mne_flash_bem is run with the ``--noflash30`` option, the flash30 directory is not needed, *i.e.*, only the 5-degree flip angle flash data are employed. - -It may take a while for mne_flash_bem to -complete. It uses the FreeSurfer directory structure under ``$SUBJECTS_DIR/$SUBJECT`` . -The script encapsulates the following processing steps: - -- It creates an mgz file corresponding - to each of the eight echoes in each of the FLASH directories in ``mri/flash`` . - The files will be called ``mef`` <*flip-angle*> _ <*echo-number*> ``.mgz`` . - -- If the ``--unwarp`` option is specified, run grad_unwarp and produce - files ``mef`` <*flip-angle*> _ <*echo-number*> ``u.mgz`` . - These files will be then used in the following steps. - -- It creates parameter maps in ``mri/flash/parameter_maps`` using mri_ms_fitparms . - -- It creates a synthetic 5-degree flip angle volume in ``mri/flash/parameter_maps/flash5.mgz`` using mri_synthesize . - -- Using fsl_rigid_register , - it creates a registered 5-degree flip angle volume ``mri/flash/parameter_maps/flash5_reg.mgz`` by - registering ``mri/flash/parameter_maps/flash5.mgz`` to - the *T1* volume under ``mri`` . - -- Using mri_convert , it converts - the flash5_reg volume to COR - format under ``mri/flash5`` . If necessary, the T1 and brain volumes - are also converted into the COR format. - -- It runs mri_make_bem_surfaces to - create the BEM surface tessellations. - -- It creates the directory ``bem/flash`` , moves the - tri-format tringulations there and creates the corresponding FreeSurfer - surface files in the same directory. - -- The COR format volumes created by mne_flash_bem are - removed. - -If the ``--noflash30`` option is specified to mne_flash_bem , -steps 3 and 4 in the above are replaced by averaging over the different -echo times in 5-degree flip angle data. - -.. _BABHJBED: - -Inspecting the meshes -===================== - -It is advisable to check the validity of the BEM meshes before -using them. This can be done with help of tkmedit, see :ref:`CIHDBFEG`. - -Using seglab -############ - -The brain segmentation provided by FreeSurfer in the directory ``mri/brain`` can -be employed to create the inner skull surface triangulation with -help of seglab, the Neuromag MRI segmentation tool. The description -below assumes that the user is familiar with the seglab tool. If -necessary, consult the seglab manual, Neuromag P/N NM20420A-A. - -The data set mri/brain typically -contains tissues within or outside the skull, in particular around -the eyes. These must be removed manually before the inner skull -triangulation is created.The editing and triangulation can be accomplished -as outlined below - -**1. Set up the MRIs for Neuromag software access** - - Run the mne_setup_mri too as described in :ref:`BABCCEHF`. - As a result, the directories mri/T1-neuromag and mri/brain-neuromag - are set up. - -**2. Load the MRI data** - - Open the file mri/brain-neuromag/sets/COR.fif and adjust the scaling - of the data. - -**3. Preparatory steps** - - Set the minimum data value to 1 using the min3D operator. - Make a backup of the data with the backup3D operator. - -**4. Manual editing** - - The maskDraw3D operation is recommended - for manual editing. To use it, first employ the grow3D operator - with threshold interval 2...255 and the seed point inside - the brain. Then do the editing in the slicer window as described - in Section 5.4.2 of the seglab manual. Note that it is enough to - remove the connectivity to the extracerebral tissues rather than - erasing them completely. - -**5. Grow again and mask** - - Once manual editing is complete, employ the grow3D operator again - and do mask3D with the backup - data to see whether the result is satisfactory. If not, undo mask3D and - continue manual editing. Otherwise, undo mask3D and - proceed to the next step. - -**6. Dilation** - - It is advisable to make the inner skull surface slightly bigger - than the brain envelope obtained in the previous step. Therefore, - apply the dilate3D operation - once or twice. Use the values 1 for nbours and 26 for nhood in the - first dilation and 1 and 18 in the second one, respectively. - -**7. Triangulation** - - Triangulate the resulting object with the triangulate3D operator. Use - a sidelength of 5 to 6 mm. Check that the triangulation looks reasonable - in the 3D viewing window. - -**8. Save the triangulation** - - Save the triangulated surface as a mesh into bem/inner_skull.tri. Select - unit of measure as millimeters and employ the MRI coordinate system. - -Using BrainSuite -################ - -The BrainSuite software -running under the Windows operating system can also be used for -BEM mesh generation. This software, written by David W. Shattuck, -is distributed as a collaborative project between the Laboratory -of Neuro Imaging at the University of California Los Angeles (Director: -Dr. Arthur W. Toga) and the Biomedical Imaging Research Group at -the University of Southern California (Director: Dr. Richard M. Leahy). -For further information, see https://neuroimage.usc.edu/neuro/BrainSuite. - -The conversion of BrainSuite tessellation -files to MNE software compatible formats is accomplished with the mne_convert_surface utility, -covered in :ref:`mne_convert_surface`. - -The workflow needed to employ the BrainSuite tessellations -is: - -**Step 1** - - Using the mri_convert utility - available in FreeSurfer , convert - an MRI volume to the img (Analyze) format. This volume should be the - T1.mgz volume or a volume registered with T1.mgz in FreeSurfer :``mri_convert`` <*volume*> ``.mgz`` <*volume*> ``.img`` - -**Step 2** - - Transfer <*volume*> ``.mgz`` to - a location accessible to BrainSuite , running - on Windows. - -**Step 3** - - Using <*volume*> ``.img`` as - input, create the tessellations of scalp, outer skull, and inner - skull surfaces in BrainSuite . - -**Step 4** - - Transfer the dfs files containing the tessellations in the bem directory - of your subject's FreeSurfer reconstruction. - -**Step 5** - - Go to the bem directory where you placed the two dfs files. Using mne_convert_surface , - convert them to the FreeSurfer surface - format, *e,g.*: - ``mne_convert_surface `` ``--dfs inner_skull.dfs `` ``--mghmri ../mri/T1.mgz `` ``--surf inner_skull_dfs.surf`` - -**Step 6** - - Using tkmedit, check that the surfaces are correct, *e.g.*: - ``tkmedit -f ../mri/T1.mgz `` ``-surface inner_skull_dfs.surf`` - -**Step7** - - Using the mne_reduce_surface function - in Matlab, reduce the number of triangles on the surfaces to 10000 - - 20000. Call the output files ``outer_skin.surf`` , ``outer_skull.surf`` , - and ``inner_skull.surf`` . - -**Step 8** - - Proceed to mne_setup_forward_model . - Use the ``--surf`` and ``--noswap`` options. - -.. note:: If left and right are flipped in BrainSuite, use the ``--flip`` option in mne_convert_surface to set the coordinate transformation correctly. - -.. note:: The BrainSuite scalp surface can be also used for visualization in mne_analyze , see :ref:`CHDCGHIF`. diff -Nru python-mne-0.18.1+dfsg/doc/manual/appendix/c_EULA.rst python-mne-0.19.1+dfsg/doc/manual/appendix/c_EULA.rst --- python-mne-0.18.1+dfsg/doc/manual/appendix/c_EULA.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/appendix/c_EULA.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,140 +0,0 @@ - - -.. _licence: - -================= -Licence agreement -================= - -.. contents:: Contents - :local: - :depth: 2 - - -This appendix includes the terms of the MNE software End-User -License Agreement (EULA). - -License agreement -################# - -THE GENERAL HOSPITAL CORPORATION - -ACADEMIC RESEARCH USE - -SOFTWARE LICENSE AGREEMENT FOR BINARY CODE - -By downloading and/or using the MNE software which is the -subject of this Agreement (the "Software"), you -hereby accept and agree to all of the terms and conditions of this -Agreement. As used in this Agreement, "you" means -the individual who clicks the "I accept" button -required as a condition of downloading the Software and the not-for-profit -or governmental institution or entity which employs or is otherwise -affiliated with such individual at the time of such download (the "Institution"). - -- *License Grant.* Subject - to all of the terms and conditions of this Agreement, [The General - Hospital Corporation, d/b/a Massachusetts General Hospital] [The - Brigham and Women's Hospital, Inc.] ("Licensor") hereby - grants you a non-exclusive, non-transferable, non-sublicensable license - under Licensor's rights in the Software to copy and use the binary - code of the Software solely for research and educational purposes - under your direction at the Institution ("Research and - Educational Purposes," which term shall include company - sponsored research conducted by you in accordance with Institution's - policies). - -- *No Transfer.* You may not sell, license, - distribute, rent, lease, offer on an ASP or service bureau basis, - grant a security interest in or otherwise transfer the Software - to any third party or use the Software for any commercial purpose. - -- *Installation and Maintenance.* You are - solely responsible for installing and maintaining the Software and - for testing the Software for proper operation. Licensor shall have - no obligation to provide any support, maintenance, corrections, - debugging, improvements, modifications, upgrades or updates of the - Software or notice of any of the forgoing, or otherwise assist Licensee - in installing, configuring, integrating, understanding or using - the Software. - -- *Attributions and Acknowledgments.* You - must preserve and maintain all applicable attributions, copyright - notices and licenses included in or applicable to the Software. - You agree to provide acknowledgement of Licensor and its designated - professional staff who participated in the creation of the Software - in publications or presentations in accordance with standard academic - practice, provided that you may not otherwise use Licensor's name, - logos or trademarks or the name of any individual associated with - Licensor, or of any funding agency, in any advertising, promotional - or sales material or publicity or in any document employed to obtain - funds or financing, or to endorse or promote any research results - or products related to or arising from the Software, without the - prior written consent of a person authorized to make such consent. - -- *Third Party Software.* This Agreement - does not grant any rights with respect to any third party software, - except those rights that Licensor has been authorized by a third - party to grant to you, and accordingly you are solely responsible - for obtaining any permissions from third parties which are necessary - to use and copy the Software. - -- *Compliance with Law.* You must comply - with all applicable governmental laws, regulations and orders, including - without limitation those relating to export and import control, - in exercising your rights under this Agreement. - -- *Termination.* You may terminate this - Agreement at any time by destroying all copies of the Software. - Licensor may terminate this Agreement at any time by providing - notice to you of such termination. Any use or copying of the Software - by you which is inconsistent with the terms and conditions of this - Agreement shall automatically render this Agreement null and void - and terminate the license granted hereunder. Upon any termination - of this Agreement you must stop using the Software and return or - destroy all copies of the Software, including any portion thereof. - -- *DISCLAIMERS.* YOU ACKNOWLEDGE THAT THE - SOFTWARE HAS BEEN DESIGNED FOR RESEARCH PURPOSES ONLY AND HAS NOT - BEEN REVIEWED OR APPROVED BY THE FOOD AND DRUG ADMINISTRATION OR - BY ANY OTHER AGENCY, AND YOU FURTHER ACKNOWLEDGE THAT CLINICAL APPLICATIONS - ARE NEITHER RECOMMENDED NOR ADVISED. The Software is provided "AS - IS", is experimental, may contain errors and is subject to further - development and revision. Licensor does not guarantee the accuracy - of the Software, or of any results or data. LICENSOR SPECIFICALLY - DISCLAIMS ALL EXPRESS AND IMPLIED WARRANTIES OF ANY KIND INCLUDING, - BUT NOT LIMITED TO, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A - PARTICULAR PURPOSE AND NON-INFRINGEMENT - -- *LIMITATION OF LIABILITY*. IN NO EVENT - SHALL LICENSOR OR ANY OF ITS TRUSTEES, DIRECTORS, OFFICERS, MEDICAL OR - PROFESSIONAL STAFF, EMPLOYEES, STUDENTS OR AGENTS ("LICENSOR'S - PERSONNEL") BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, - SPECIAL, INCIDENTAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES HOWEVER CAUSED - AND ON ANY THEORY OF LIABILITY ARISING IN ANY WAY RELATED TO THE - SOFTWARE, EVEN IF LICENSOR OR ANY OF LICENSOR'S PERSONNEL HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. EXCEPT TO THE EXTENT - PROHIBITED BY LAW OR REGULATION, YOU ASSUME ALL RISK AND LIABILITY - FOR YOUR USE AND COPYING OF THE SOFTWARE, AND AGREE TO INDEMNIFY AND - HOLD HARMLESS LICENSOR AND EACH OF LICENSOR'S PERSONNEL FROM AND - AGAINST ANY AND ALL CLAIMS, SUITS, ACTIONS, DEMANDS AND JUDGMENTS ARISING - THEREFROM - -- *U.S. Government Rights.* For Software - supported by federal funding, the license granted under this Agreement - is subject to the rights, conditions and limitations imposed by - U.S. law including without limitation 35 U.S.C. § 202 et - seq. and regulations pertaining thereto. - -- *General.* This Agreement constitutes - the entire understanding between you and Licensor with respect to - the subject matter hereof, and supercedes any prior or contemporaneous - oral or written agreements with respect thereto. :ref:`c_reference`, - :ref:`ch_browse`, :ref:`c_legacy_ch_forward`, :ref:`c_legacy_ch_mne`, - :ref:`c_legacy_ch_morph`, and :ref:`c_legacy_misc` - shall survive any termination of this Agreement. This - Agreement may be modified or amended only in a writing signed by - duly authorized representatives of both Parties hereto. The invalidity - or unenforceability of any provision of this Agreement shall not - affect any other provision hereof. This Agreement and the license - granted hereunder may not be assigned diff -Nru python-mne-0.18.1+dfsg/doc/manual/appendix/c_misc.rst python-mne-0.19.1+dfsg/doc/manual/appendix/c_misc.rst --- python-mne-0.18.1+dfsg/doc/manual/appendix/c_misc.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/appendix/c_misc.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,101 +0,0 @@ -.. _c_legacy_misc: - -Miscellaneous C functionality -============================= - -.. _BABCCEHF: - -Setting up anatomical MR images for MRIlab ------------------------------------------- - -If you have the Neuromag software installed, the Neuromag -MRI viewer, MRIlab, can be used to access the MRI slice data created -by FreeSurfer . In addition, the -Neuromag MRI directories can be used for storing the MEG/MRI coordinate -transformations created with mne_analyze , -see :ref:`CACEHGCD`. During the computation of the forward -solution, mne_do_forwand_solution searches -for the MEG/MRI coordinate in the Neuromag MRI directories, see :ref:`BABCHEJD`. The fif files created by mne_setup_mri can -be loaded into Matlab with the fiff_read_mri function, -see :ref:`ch_matlab`. - -These functions require running the script mne_setup_mri which -requires that the subject is set with the ``--subject`` option -or by the SUBJECT environment variable. The script processes one -or more MRI data sets from ``$SUBJECTS_DIR/$SUBJECT/mri`` , -by default they are T1 and brain. This default can be changed by -specifying the sets by one or more ``--mri`` options. - -The script creates the directories ``mri/`` <*name*> ``-neuromag/slices`` and ``mri/`` <*name*> ``-neuromag/sets`` . -If the input data set is in COR format, mne_setup_mri makes -symbolic links from the COR files in the directory ``mri/`` <*name*> into ``mri/`` <*name*> ``-neuromag/slices`` , -and creates a corresponding fif file COR.fif in ``mri/`` <*name*> ``-neuromag/sets`` .. -This "description file" contains references to -the actual MRI slices. - -If the input MRI data are stored in the newer mgz format, -the file created in the ``mri/`` <*name*> ``-neuromag/sets`` directory -will include the MRI pixel data as well. If available, the coordinate -transformations to allow conversion between the MRI (surface RAS) -coordinates and MNI and FreeSurfer Talairach coordinates are copied -to the MRI description file. mne_setup_mri invokes mne_make_cor_set , -described in :ref:`mne_make_cor_set` to convert the data. - -For example: - -``mne_setup_mri --subject duck_donald --mri T1`` - -This command processes the MRI data set T1 for subject duck_donald. - -.. note:: If the SUBJECT environment variable is set it is usually sufficient to run mne_setup_mri without any options. - -.. note:: If the name specified with the ``--mri`` option contains a slash, the MRI data are accessed from the directory specified and the ``SUBJECT`` and ``SUBJECTS_DIR`` environment variables as well as the ``--subject`` option are ignored. - -MRIlab can also be used for coordinate frame alignment. -Section 3.3.1 of the MRIlab User's Guide, -Neuromag P/N NM20419A-A contains a detailed description of -this task. Employ the images in the set ``mri/T1-neuromag/sets/COR.fif`` for -the alignment. Check the alignment carefully using the digitization -data included in the measurement file as described in Section 5.3.1 -of the above manual. Save the aligned description file in the same -directory as the original description file without the alignment -information but under a different name. - - -.. _BABCDBDI: - -Cleaning the digital trigger channel ------------------------------------- - -The calibration factor of the digital trigger channel used -to be set to a value much smaller than one by the Neuromag data -acquisition software. Especially to facilitate viewing of raw data -in graph it is advisable to change the calibration factor to one. -Furthermore, the eighth bit of the trigger word is coded incorrectly -in the original raw files. Both problems can be corrected by saying: - -``mne_fix_stim14`` <*raw file*> - -More information about mne_fix_stim14 is -available in :ref:`mne_fix_stim14`. It is recommended that this -fix is included as the first raw data processing step. Note, however, -the mne_browse_raw and mne_process_raw always sets -the calibration factor to one internally. - -.. note:: If your data file was acquired on or after November 10, 2005 on the Martinos center Vectorview system, it is not necessary to use mne_fix_stim14 . - -.. _BABCDFJH: - -Fixing channel information --------------------------- - -There are two potential discrepancies in the channel information -which need to be fixed before proceeding: - -- EEG electrode locations may be incorrect - if more than 60 EEG channels are acquired. - -- The magnetometer coil identifiers are not always correct. - -These potential problems can be fixed with the utilities mne_check_eeg_locations and mne_fix_mag_coil_types, -see :ref:`mne_check_eeg_locations` and :ref:`mne_fix_mag_coil_types`. diff -Nru python-mne-0.18.1+dfsg/doc/manual/appendix/c_release_notes.rst python-mne-0.19.1+dfsg/doc/manual/appendix/c_release_notes.rst --- python-mne-0.18.1+dfsg/doc/manual/appendix/c_release_notes.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/appendix/c_release_notes.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,854 +0,0 @@ - - -.. _c_legacy_release_notes: - -============= -Release notes -============= - -.. contents:: Contents - :local: - :depth: 2 - - -This appendix contains a brief description of the changes -in MNE software in each major release. - -Release notes for MNE software 2.4 -################################## - -Manual -====== - -The manual has been significantly expanded and reorganized. -:ref:`c_legacy_ch_interactive_analysis` describing mne_analyze has -been added. :ref:`ch_sample_data` contains instructions for analyzing -the sample data set provided with the software. Useful background -material is listed in :ref:`ch_reading`. Almost all utility programs -are now covered in the manual. - -General software changes -======================== - -The following overall changes have been made: - -- A forward solution library independent - of Neuromag software was written. - -- The MEG sensor information is now imported from the coil definition file - instead of being hardcoded in the software. - -- CTF and 4D Neuroimaging sensors are now supported. - -- The number of Neuromag-based utilities was minimized. - -- The LINUX port of Neuromag software modules was completely - separated from the MNE software and now resides under a separate - directory tree. - -- Support for topologically connected source spaces was added. - -- A lot of bugs were fixed. - -File conversion utilities -========================= - -The following import utilities were added: - -- mne_ctf2fiff to convert CTF data to the fif format. - -- mne_tufts2fiff to convert - EEG data from Tufts university to fif format. - -The output of the Matlab conversion utilities was changed -to use structures. - -Matlab tools to import and export w and stc files were added. - -mne_browse_raw -============== - -Output of decimated and filtered data is now available. mne_analyze now fully -supports 32-bit integer data found in CTF and new Neuromag raw data -files. - -mne_analyze -=========== - -The following changes have been made in mne_analyze : - -- Curved and flat surface patches are - now supported. - -- An iterative coordinate alignment procedure was added, see - :ref:`CACEHGCD`. - -- Utility to view continuous HPI information was added. - -- Several small changes and bug fixes were done. - -mne_make_movie -============== - -The only major change in mne_make_movie is -the addition of support for curved and surface patches. - -Averaging -========= - -The highly inefficient program mne_grand_average has -been removed from the distribution and replaced with the combined -use of mne_make_movie and a new -averaging program mne_average_estimates. - -Release notes for MNE software 2.5 -################################## - -Manual -====== - -The MNE Matlab toolbox is now covered in a separate chapter. -Change bars are employed to indicate changes in the chapters that -existed in the previous version of the manual. Note that :ref:`ch_matlab` describing -the Matlab toolbox is totally new and change bars have not been -used there. Furthermore, :ref:`setup_martinos` now contains all the -information specific to the Martinos Center. - -mne_browse_raw -============== - -There are several improvements in the raw data processor mne_browse_raw/mne_process_raw : - -- Possibility to delete and add channel - selections interactively has been added. A nonstandard channel selection - file can be now specified on the command line. - -- Handling of CTF software gradient compensation has been added. - -- The vertical scale of the digital trigger channel is now automatically - set to accommodate the largest trigger value. - -- It is now possible to load evoked-response data sets from - files. Time scales of the evoked-response data and data averaged - in mne_browse_raw can be now - set from the scales dialog. :ref:`CHDHBGGH` has - been updated to employ mne_browse_raw in - viewing the averages computed from the sample raw data set. - -- It is now possible to create new SSP operators in mne_browse_raw. - -- Listing of amplitude values have been added to both the strip-chart - and topographical displays. - -- Text format event files can now be loaded for easy inspection - of rejected epochs, for example. - -- Handling of derived channels has been added. - -- SSS information is now transferred to the covariance matrix - output files. - -- Neuromag processing history is included with the output files. - -mne_epochs2mat -============== - -This new utility extracts epochs from a raw data file, applies -a bandpass filter to them and outputs them in a format convenient -for processing in Matlab. - -mne_analyze -=========== - -The following new features have been added: - -- Processing of raw data segment and easy - switching between multiple evoked data sets (not in the manual yet). - -- Sketchy surface display mode for source spaces with selection - triangulation information created with the ``--ico`` option - to mne_setup_source_space. - -- Rotation of the coordinate frame in the coordinate system - alignment dialog. - -- Several new graphics output file formats as well as automatic - and snapshot output modes. - -- It is now possible to inquire timecourses from stc overlays. - Both labels and surface picking are supported. - -- Added an option to include surface vertex numbers to the timecourse output. - -- Overlays matching the scalp surface can now be loaded. - -- The dipole display dialog has now control over the dipole - display properties. Multiple dipoles can be now displayed. - -- Time stepping with cursor keys has been added. - -- Dynamic cursors have been added to the full view display. - -- The viewer display now automatically rotates to facilitate - fiducial picking from the head surface. - -mne_ctf2fiff -============ - -Correct errors in compensation channel information and compensation data -output. The transformation between the CTF and Neuromag coordinate -frames is now included in the output file. - -mne_make_movie -============== - -Added the ``--labelverts`` option. - -mne_surf2bem -============ - -Added the ``--shift`` option to move surface vertices -outwards. Fixed some loopholes in topology checks. Also added the ``--innershift`` option -to mne_setup_forward_model. - -mne_forward_solution -==================== - -Added code to compute forward solutions for CTF data with -software gradient compensation on. - -mne_inverse_operator -==================== - -The following changes have been made in mne_inverse_operator : - -- Added options to regularize the noise-covariance - matrix. - -- Added correct handling of the rank-deficient covariance matrix - resulting from the use of SSS. - -- Additional projections cannot be specified if the noise covariance matrix - was computed with projections on. - -- Bad channels can be added only in special circumstances if - the noise covariance matrix was computed with projections on. - -mne_compute_raw_inverse -======================= - -This utility is now documented in :ref:`c_legacy_computing_inverse`. The -utility mne_make_raw_inverse_operator has been removed from the software. - -Time range settings -=================== - -The tools mne_compute_raw_inverse , mne_convert_mne_data , -and mne_compute_mne no longer have command-line options to restrict -the time range of evoked data input. - -mne_change_baselines -==================== - -It is now possible to process all data sets in a file at -once. All processed data are stored in a single output file. - -New utilities -============= - -mne_show_fiff -------------- - -Replacement for the Neuromag utility show_fiff . -This utility conforms to the standard command-line option conventions -in MNE software. - -mne_make_cor_set ----------------- - -Replaces the functionality of the Neuromag utility create_mri_set_simple to -create a fif format description file for the FreeSurfer MRI data. -This utility is called by the mne_setup_mri script. - -mne_compensate_data -------------------- - -This utility applies or removes CTF software gradient compensation -from evoked-response data. - -mne_insert_4D_comp ------------------- - -This utility merges 4D Magnes compensation data from a text -file and the main helmet sensor data from a fif file and creates -a new fif file :ref:`mne_insert_4D_comp`. - -mne_ctf_dig2fiff ----------------- - -This utility reads a text format Polhemus data file, transforms -the data into the Neuromag head coordinate system, and outputs the -data in fif or hpts format. - -mne_kit2fiff ------------- - -The purpose of this new utility is to import data from the -KIT MEG system. - -mne_make_derivations --------------------- - -This new utility will take derivation data from a text file -and convert it to fif format for use with mne_browse_raw. - -BEM mesh generation -=================== - -All information concerning BEM mesh generation has been moved -to :ref:`create_bem_model`. Utilities for BEM mesh generation using -FLASH images have been added. - -Matlab toolbox -============== - -The MNE Matlab toolbox has been significantly enhanced. New -features include: - -- Basic routines for reading and writing - fif files. - -- High-level functions to read and write evoked-response fif - data. - -- High-level functions to read raw data. - -- High-level routines to read source space information, covariance - matrices, forward solutions, and inverse operator decompositions - directly from fif files. - -The Matlab toolbox is documented in :ref:`ch_matlab`. - -The mne_div_w utility -has been removed because it is now easy to perform its function -and much more using the Matlab Toolbox. - -Release notes for MNE software 2.6 -################################## - -Manual -====== - -The changes described below briefly are documented in the -relevant sections of the manual. Change bars are employed to indicate -changes with respect to manual version 2.5. :ref:`c_legacy_ch_forward` now -contains a comprehensive discussion of the various coordinate systems -used in MEG/EEG data. - -Command-line options -==================== - -All compiled C programs now check that the command line does -not contain any unknown options. Consequently, scripts that have -inadvertently specified some options which are invalid will now -fail. - -Changes to existing software -============================ - -mne_add_patch_info ------------------- - -- Changed option ``--in`` to ``--src`` and ``--out`` to ``--srcp`` . - -- Added ``--labeldir`` option. - -mne_analyze ------------ - -New features include: - -- The name of the digital trigger channel - can be specified with the MNE_TRIGGER_CH_NAME environment variable. - -- Using information from the fif data files, the wall clock - time corresponding to the current file position is shown on the - status line - -- mne_analyze can now be - controlled by mne_browse_raw to - facilitate interactive analysis of clinical data. - -- Added compatibility with Elekta-Neuromag Report Composer (cliplab and - improved the quality of hardcopies. - -- Both in mne_browse_raw and - in mne_analyze , a non-standard - default layout can be set on a user-by-user basis. - -- Added the ``--digtrigmask`` option. - -- Added new image rotation functionality using the mouse wheel - or trackball. - -- Added remote control of the FreeSurfer MRI - viewer (tkmedit ). - -- Added fitting of single equivalent current dipoles and channel - selections. - -- Added loading of FreeSurfer cortical - parcellation data as labels. - -- Added support for using the FreeSurfer average - brain (fsaverage) as a surrogate. - -- The surface selection dialog was redesigned for faster access - to the files and to remove problems with a large number of subjects. - -- A shortcut button to direct a file selector to the appropriate - default directory was added to several file loading dialogs. - -- The vertex coordinates can now be displayed. - -mne_average_forward_solutions ------------------------------ - -EEG forward solutions are now averaged as well. - -mne_browse_raw and mne_process_raw ----------------------------------- - -Improvements in the raw data processor mne_browse_raw /mne_process_raw include: - -- The name of the digital trigger channel - can be specified with the MNE_TRIGGER_CH_NAME environment variable. - -- The format of the text event files was slightly changed. The - sample numbers are now "absolute" sample numbers - taking into account the initial skip in the event files. The new - format is indicated by an additional "pseudoevent" in - the beginning of the file. mne_browse_raw and mne_process_raw are - still compatible with the old event file format. - -- Using information from the fif data files, the wall clock - time corresponding to the current file position is shown on the - status line - -- mne_browse_raw can now - control mne_analyze to facilitate - interactive analysis of clinical data. - -- If the length of an output raw data file exceeds the 2-Gbyte - fif file size limit, the output is split into multiple files. - -- ``-split`` and ``--events`` options was - added to mne_process_raw . - -- The ``--allowmaxshield`` option was added to mne_browse_raw to allow - loading of unprocessed data with MaxShield in the Elekta-Neuromag - systems. These kind of data should never be used as an input for source - localization. - -- The ``--savehere`` option was added. - -- The stderr parameter was - added to the averaging definition files. - -- Added compatibility with Elekta-Neuromag Report Composer (cliplab and - improved the quality of hardcopies. - -- Both in mne_browse_raw and - in mne_analyze , a non-standard - default layout can be set on a user-by-user basis. - -- mne_browse_raw now includes - an interactive editor to create derived channels. - -- The menus in mne_browse_raw were - reorganized and an time point specification text field was added - -- Possibility to keep the old projection items added to the - new projection definition dialog. - -- Added ``--cd`` option. - -- Added filter buttons for raw files and Maxfilter (TM) output - to the open dialog. - -- Added possibility to create a graph-compatible projection - to the Save projection dialog - -- Added possibility to compute a projection operator from epochs - specified by events. - -- Added the ``--keepsamplemean`` option - to the covariance matrix computation files. - -- Added the ``--digtrigmask`` option. - -- Added Load channel selections... item - to the File menu. - -- Added new browsing functionality using the mouse wheel or - trackball. - -- Added optional items to the topographical data displays. - -- Added an event list window. - -- Added an annotator window. - -- Keep events sorted by time. - -- User-defined events are automatically kept in a fif-format - annotation file. - -- Added the delay parameter - to the averaging and covariance matrix estimation description files. - -Detailed information on these changes can be found in :ref:`ch_browse`. - -mne_compute_raw_inverse ------------------------ - -The ``--digtrig`` , ``--extra`` , ``--noextra`` , ``--split`` , ``--labeldir`` , and ``--out`` options -were added. - -mne_convert_surface -------------------- - -The functionality of mne_convert_dfs was -integrated into mne_convert_surface . -Text output as a triangle file and and file file containing the -list of vertex points was added. The Matlab output option was removed. -Consequently, mne_convert_dfs , mne_surface2mat , -and mne_list_surface_nodes were -deleted from the distribution. - -mne_dump_triggers ------------------ - -This obsolete utility was deleted from the distribution. - -mne_epochs2mat --------------- - -The name of the digital trigger channel can be specified -with the MNE_TRIGGER_CH_NAME environment variable. Added -the ``--digtrigmask`` option. - -mne_forward_solution --------------------- - -Added code to compute the derivatives of with respect to -the dipole position coordinates. - -mne_list_bem ------------- - -The ``--surfno`` option is replaced with the ``--id`` option. - -mne_make_cor_set ----------------- - -Include data from mgh/mgz files to the output automatically. -Include the Talairach transformations from the FreeSurfer data to -the output file if possible. - -mne_make_movie --------------- - -Added the ``--noscalebar``, ``--nocomments``, ``--morphgrade``, ``--rate``, -and ``--pickrange`` options. - -mne_make_source_space ---------------------- - -The ``--spacing`` option is now implemented in this -program, which means mne_mris_trix is -now obsolete. The mne_setup_source_space script -was modified accordingly. Support for tri, dec, and dip files was dropped. - -mne_mdip2stc ------------- - -This utility is obsolete and was removed from the distribution. - -mne_project_raw ---------------- - -This is utility is obsolete and was removed from the distribution. -The functionality is included in mne_process_raw . - -mne_rename_channels -------------------- - -Added the ``--revert`` option. - -mne_setup_forward_model ------------------------ - -Added the ``--outershift`` and ``--scalpshift`` options. - -mne_simu --------- - -Added source waveform expressions and the ``--raw`` option. - -mne_transform_points --------------------- - -Removed the ``--tomrivol`` option. - -Matlab toolbox --------------- - -Several new functions were added, see :ref:`ch_matlab`. - -.. note:: The matlab function fiff_setup_read_raw has a significant change. The sample numbers now take into account possible initial skip in the file, *i.e.*, the time between the start of the data acquisition and the start of saving the data to disk. The first_samp member of the returned structure indicates the initial skip in samples. If you want your own routines, which assume that initial skip has been removed, perform identically with the previous version, subtract first_samp from the sample numbers you specify to fiff_read_raw_segment . Furthermore, fiff_setup_read_raw has an optional argument to allow reading of unprocessed MaxShield data acquired with the Elekta MEG systems. - -New utilities -============= - -mne_collect_transforms ----------------------- - -This utility collects coordinate transformation information -from several sources into a single file. - -mne_convert_dig_data --------------------- - -This new utility convertes digitization (Polhemus) data between -different file formats. - -mne_edf2fiff ------------- - -This is a new utility to convert EEG data from EDF, EDF+, -and BDF formats to the fif format. - -mne_brain_vision2fiff ---------------------- - -This is a new utility to convert BrainVision EEG data to -the fif format. This utility is also -used by the mne_eximia_2fiff script -to convert EEG data from the Nexstim eXimia EEG system to the fif -format. - -mne_anonymize -------------- - -New utility to remove subject identifying information from -measurement files. - -mne_opengl_test ---------------- - -New utility for testing the OpenGL graphics performance. - -mne_volume_data2mri -------------------- - -Convert data defined in a volume created with mne_volume_source_space to -an MRI overlay. - -mne_volume_source_space ------------------------ - -Create a a grid of source points within a volume. mne_volume_source_space also -optionally creates a trilinear interpolator matrix to facilitate -converting values a distribution in the volume grid into an MRI -overlay using mne_volume_data2mri. - -mne_copy_processing_history ---------------------------- - -This new utility copies the processing history block from -one data file to another. - -Release notes for MNE software 2.7 -################################## - -Software engineering -==================== - -There have been two significant changes in the software engineering -since MNE Version 2.6: - -- CMake is now used in building the software - package and - -- Subversion (SVN) is now used for revision control instead - of Concurrent Versions System (CVS). - -These changes have the effects on the distribution of the -MNE software and setup for individual users: - -- There is now a separate software package - for each of the platforms supported. - -- The software is now organized completely under standard directories (bin, - lib, and share). In particular, the directory setup/mne has been moved - to share/mne and the directories app-defaults and doc are now under - share. All files under share are platform independent. - -- The use of shared libraries has been minimized. This alleviates - compatibility problems across operating system versions. - -- The setup scripts have changed. - -The installation and user-level effects of the new software -organization are discussed in :ref:`install_mne_c`. - -In addition, several minor bugs have been fixed in the source -code. Most relevant changes visible to the user are listed below. - -Matlab tools -============ - -- The performance of the fiff I/O routines - has been significantly improved thanks to the contributions of François - Tadel at USC. - -- Label file I/O routines mne_read_label_file and mne_write_label_file as - well as a routine to extract time courses corresponding to a label from - an stc file (mne_label_time_courses) have been added. - -- The patch information is now read from the source space file - and included in the source space data structure. - -mne_browse_raw -============== - -- Rejection criteria to detect flat channels - have been added. - -- Possibility to detect temporal skew between trigger input - lines has been added. - -- ``--allowmaxshield`` option now works in the batch mode as well. - -- Added the ``--projevent`` option to batch mode. - -- It is now possible to compute an SSP operator for EEG. - -mne_analyze -=========== - -- Both hemispheres can now be displayed - simultaneously. - -- If the source space was created with mne_make_source_space version 2.3 - or later, the subject's surface data are automatically - loaded after loading the data and the inverse operator. - -Miscellaneous -============= - -- mne_smooth_w was - renamed to mne_smooth and can - now handle both w and stc files. Say ``mne_smooth --help`` to - find the options. - -- All binaries now reside in $MNE_ROOT/bin. There are no separate bin/mne - and bin/admin directories. - -- mne_anonymize now has the - ``--his`` option to remove the HIS ID of the subject. - -- mne_check_surface now has - the ``--bem`` and ``--id`` options to check surfaces from a BEM fif file. - -- mne_compute_raw_inverse now has the ``--orignames`` option. - -- Added ``--headcoord`` option to mne_convert_dig_data. - -- Added ``--talairach`` option to mne_make_cor_set. - -- Added the ``--morph`` option to mne_setup_source_space and mne_make_source_space. - -- Added the ``--prefix`` option to mne_morph_labels. - -- Added the ``--blocks`` and ``--indent`` options to mne_show_fiff. - -- Added the ``--proj`` option as well as map types 5 and 6 to mne_sensitivity_map. - -- Fixed a bug in mne_inverse_operator which - caused erroneous calculation of EEG-only source estimates if the - data were processed with Maxfilter software and sometimes caused - similar behavior on MEG/EEG source estimates. - -Release notes for MNE software 2.7.1 -#################################### - -mne_analyze -=========== - -- Added a new restricted mode for visualizing - head position within the helmet. - -- Added information about mne_make_scalp_surfaces to :ref:`CHDCGHIF`. - -mne_browse_raw -============== - -- Added possibility for multiple event - parameters and the mask parameter in averaging and noise covariance - calculation. - -- Added simple conditional averaging. - -Release notes for MNE software 2.7.2 -#################################### - -mne_add_patch_info -================== - -Added the capability to compute distances between source -space vertices. - -Matlab toolbox -============== - -- Added new functions to for stc and w - file I/O to employ 1-based vertex numbering inside Matlab, see Table 10.11. - -- mne_read_source_spaces.m now reads the inter-vertex distance - information now optionally produced by mne_add_patch_info. - -Miscellaneous -============= - -- Added ``--shift`` option to mne_convert_surface. - -- Added ``--alpha`` option to mne_make_movie. - -- Added ``--noiserank`` option to mne_inverse_operator and mne_do_inverse_operator. - -- The fif output from mne_convert_dig_data now - includes the transformation between the digitizer and MNE head coordinate - systems if such a transformation has been requested. - This also affects the output from mne_eximia2fiff. - -- Added ``--noflash30``, ``--noconvert``, and ``--unwarp`` options to mne_flash_bem. - -Release notes for MNE software 2.7.3 -#################################### - -Miscellaneous -============= - -- Added preservation of the volume geometry - information in the FreeSurfer surface files. - -- The ``--mghmri`` option in combination with ``--surfout`` inserts - the volume geometry information to the output of mne_convert_surface. - -- Added ``--replacegeom`` option to mne_convert_surface. - -- Modified mne_watershed_bem and mne_flash_bem to - include the volume geometry information to the output. This allows - viewing of the output surfaces in the FreeSurfer freeview utility. diff -Nru python-mne-0.18.1+dfsg/doc/manual/appendix/martinos.rst python-mne-0.19.1+dfsg/doc/manual/appendix/martinos.rst --- python-mne-0.18.1+dfsg/doc/manual/appendix/martinos.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/appendix/martinos.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,117 +0,0 @@ - - -.. _setup_martinos: - -============================ -Setup at the Martinos Center -============================ - -.. contents:: Contents - :local: - :depth: 2 - - -This Appendix contains information specific to the Martinos -Center setup. - -.. _user_environment_martinos: - -User environment -################ - -In the Martinos Center computer network, the 2.7 version -of MNE is located at /usr/pubsw/packages/mne/stable. To use this -version, follow :ref:`user_environment` substituting /usr/pubsw/packages/mne/stable -for <*MNE*> and /usr/pubsw/packages/matlab/current -for <*Matlab*> . For most users, -the default shell is tcsh. - -.. note:: A new version of MNE is build every night from the latest sources. This version is located at /usr/pubsw/packages/mne/nightly. - -.. _BABGFDJG: - -Using Neuromag software -####################### - -Software overview -================= - -The complete set of Neuromag software is available on the -LINUX workstations. The programs can be accessed from the command -line, see :ref:`BABFIEHC`. The corresponding manuals, located -at ``$NEUROMAG_ROOT/manuals`` are listed in :ref:`BABCJJGF`. - -.. _BABFIEHC: - -.. table:: Principal Neuromag software modules. - - =========== ================================= - Module Description - =========== ================================= - xfit Source modelling - xplotter Data plotting - graph General purpose data processor - mrilab MEG-MRI integration - seglab MRI segmentation - cliplab Graphics clipboard - =========== ================================= - -.. _BABCJJGF: - -.. table:: List of Neuromag software manuals. - - =========== ========================================= - Module pdf - =========== ========================================= - xfit XFit.pdf - xplotter Xplotter.pdf - graph GraphUsersGuide.pdf GraphReference.pdf - mrilab Mrilab.pdf - seglab Seglab.pdf - cliplab Cliplab.pdf - =========== ========================================= - -To access the Neuromag software on the LINUX workstations -in the Martinos Center, say (in tcsh or csh) - -``source /space/orsay/8/megdev/Neuromag-LINUX/neuromag_setup_csh`` - -or in POSIX shell - -``. /space/orsay/8/megdev/Neuromag-LINUX/neuromag_setup_sh`` - -Using MRIlab for coordinate system alignment -============================================ - -The MEG-MRI coordinate system alignment can be also accomplished with -the Neuromag tool MRIlab, part of the standard software on Neuromag -MEG systems. - -In MRIlab, the following steps are necessary for the coordinate -system alignment: - -- Load the MRI description file ``COR.fif`` from ``subjects/sample/mri/T1-neuromag/sets`` through File/Open . - -- Open the landmark setting dialog from Windows/Landmarks . - -- Click on one of the coordinate setting fields on the Nasion line. - Click Goto . Select the crosshair - tool and move the crosshair to the nasion. Click Get . - -- Proceed similarly for the left and right auricular points. - Your instructor will help you with the selection of the correct - points. - -- Click OK to set the alignment - -- Load the digitization data from the file ``sample_audvis_raw.fif`` or ``sample_audvis-ave.fif`` (the - on-line evoked-response average file) in ``MEG/sample`` through File/Import/Isotrak data . Click Make points to - show all the digitization data on the MRI slices. - -- Check that the alignment is correct by looking at the locations - of the digitized points are reasonable. Adjust the landmark locations - using the Landmarks dialog, if - necessary. - -- Save the aligned file to the file suggested in the dialog - coming up from File/Save . diff -Nru python-mne-0.18.1+dfsg/doc/manual/channel_interpolation.rst python-mne-0.19.1+dfsg/doc/manual/channel_interpolation.rst --- python-mne-0.18.1+dfsg/doc/manual/channel_interpolation.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/channel_interpolation.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,71 +0,0 @@ - -.. contents:: Contents - :local: - :depth: 2 - -.. _channel_interpolation: - -Bad channel repair via interpolation -#################################### - -Spherical spline interpolation (EEG) -==================================== - -In short, data repair using spherical spline interpolation [1]_ consists of the following steps: - -* Project the good and bad electrodes onto a unit sphere -* Compute a mapping matrix that maps :math:`N` good channels to :math:`M` bad channels -* Use this mapping matrix to compute interpolated data in the bad channels - -Spherical splines assume that the potential :math:`V(\boldsymbol{r_i})` at any point :math:`\boldsymbol{r_i}` on the surface of the sphere can be represented by: - -.. math:: V(\boldsymbol{r_i}) = c_0 + \sum_{j=1}^{N}c_{i}g_{m}(cos(\boldsymbol{r_i}, \boldsymbol{r_{j}})) - :label: model - -where the :math:`C = (c_{1}, ..., c_{N})^{T}` are constants which must be estimated. The function :math:`g_{m}(\cdot)` of order :math:`m` is given by: - -.. math:: g_{m}(x) = \frac{1}{4 \pi}\sum_{n=1}^{\infty} \frac{2n + 1}{(n(n + 1))^m}P_{n}(x) - :label: legendre - -where :math:`P_{n}(x)` are `Legendre polynomials`_ of order `n`. - -.. _Legendre polynomials: https://en.wikipedia.org/wiki/Legendre_polynomials - -To estimate the constants :math:`C`, we must solve the following two equations simultaneously: - -.. math:: G_{ss}C + T_{s}c_0 = X - :label: matrix_form - -.. math:: {T_s}^{T}C = 0 - :label: constraint - -where :math:`G_{ss} \in R^{N \times N}` is a matrix whose entries are :math:`G_{ss}[i, j] = g_{m}(cos(\boldsymbol{r_i}, \boldsymbol{r_j}))` and :math:`X \in R^{N \times 1}` are the potentials :math:`V(\boldsymbol{r_i})` measured at the good channels. :math:`T_{s} = (1, 1, ..., 1)^T` is a column vector of dimension :math:`N`. Equation :eq:`matrix_form` is the matrix formulation of Equation :eq:`model` and equation :eq:`constraint` is like applying an average reference to the data. From equation :eq:`matrix_form` and :eq:`constraint`, we get: - -.. math:: \begin{bmatrix} c_0 \\ C \end{bmatrix} = {\begin{bmatrix} {T_s}^{T} && 0 \\ T_s && G_{ss} \end{bmatrix}}^{-1} \begin{bmatrix} 0 \\ X \end{bmatrix} = C_{i}X - :label: estimate_constant - -:math:`C_{i}` is the same as matrix :math:`{\begin{bmatrix} {T_s}^{T} && 0 \\ T_s && G_{ss} \end{bmatrix}}^{-1}` but with its first column deleted, therefore giving a matrix of dimension :math:`(N + 1) \times N`. - -Now, to estimate the potentials :math:`\hat{X} \in R^{M \times 1}` at the bad channels, we have to do: - -.. math:: \hat{X} = G_{ds}C + T_{d}c_0 - :label: estimate_data - -where :math:`G_{ds} \in R^{M \times N}` computes :math:`g_{m}(\boldsymbol{r_i}, \boldsymbol{r_j})` between the bad and good channels. :math:`T_{d} = (1, 1, ..., 1)^T` is a column vector of dimension :math:`M`. Plugging in equation :eq:`estimate_constant` in :eq:`estimate_data`, we get - -.. math:: \hat{X} = \begin{bmatrix} T_d && G_{ds} \end{bmatrix} \begin{bmatrix} c_0 \\ C \end{bmatrix} = \underbrace{\begin{bmatrix} T_d && G_{ds} \end{bmatrix} C_{i}}_\text{mapping matrix}X - - -To interpolate bad channels, one can simply do: - - >>> evoked.interpolate_bads(reset_bads=False) # doctest: +SKIP - -and the bad channel will be fixed. - -.. topic:: Examples: - - * :ref:`sphx_glr_auto_examples_preprocessing_plot_interpolate_bad_channels.py` - -References -========== -.. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989). Spherical splines for scalp potential and current density mapping. Electroencephalography Clinical Neurophysiology, Feb; 72(2):184-7. diff -Nru python-mne-0.18.1+dfsg/doc/manual/cookbook.rst python-mne-0.19.1+dfsg/doc/manual/cookbook.rst --- python-mne-0.18.1+dfsg/doc/manual/cookbook.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/cookbook.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,440 +0,0 @@ -.. _cookbook: - -========================== -The typical M/EEG workflow -========================== - -.. contents:: Contents - :local: - :depth: 2 - -Overview -======== - -This section describes a typical MEG/EEG workflow, eventually up to source -reconstruction. The workflow is summarized in :ref:`flow_diagram`. -References below refer to Python functions and objects. - -.. _flow_diagram: - -.. figure:: ../_static/flow_diagram.svg - :alt: MNE Workflow Flowchart - :align: center - - **Workflow of the MNE software** - - -Preprocessing -============= -The following MEG and EEG data preprocessing steps are recommended: - -- Bad channels in the MEG and EEG data must be identified, see :ref:`BABBHCFG`. - -- The data has to be filtered to the desired passband. - -- Artifacts should be suppressed (e.g., using ICA or SSP). - -.. note:: For older systems, coding problems on the trigger channel - STI 014 and EEG/MEG information may need to be fixed, see - :ref:`BABCDBDI` and :ref:`BABCDFJH`. - - -.. _BABBHCFG: - -Marking bad channels --------------------- - -Sometimes some MEG or EEG channels are not functioning properly -for various reasons. These channels should be excluded from -analysis by marking them bad as:: - - >>> raw.info['bads'] = ['MEG2443'] # doctest: +SKIP - -Especially if a channel does not show -a signal at all (flat) it is important to exclude it from the -analysis, since its noise estimate will be unrealistically low and -thus the current estimate calculations will give a strong weight -to the zero signal on the flat channels and will essentially vanish. -It is also important to exclude noisy channels because they can -possibly affect others when signal-space projections or EEG average electrode -reference is employed. Noisy bad channels can also adversely affect -averaging and noise-covariance matrix estimation by causing -unnecessary rejections of epochs. - -Recommended ways to identify bad channels are: - -- Observe the quality of data during data - acquisition and make notes of observed malfunctioning channels to - your measurement protocol sheet. - -- View the on-line averages and check the condition of the channels. - -- Compute preliminary off-line averages with artifact rejection, - SSP/ICA, and EEG average electrode reference computation - off and check the condition of the channels. - -- View raw data with :func:`mne.io.Raw.plot` without SSP/ICA - enabled and identify bad channels. - -.. note:: It is strongly recommended that bad channels are identified and - marked in the original raw data files. If present in the raw data - files, the bad channel selections will be automatically transferred - to averaged files, noise-covariance matrices, forward solution - files, and inverse operator decompositions. - -Artifact suppression --------------------- - -SSP -### - -The Signal-Space Projection (SSP) is one approach to rejection -of external disturbances in software. Unlike many other -noise-cancellation approaches, SSP does -not require additional reference sensors to record the disturbance -fields. Instead, SSP relies on the fact that the magnetic field -distributions generated by the sources in the brain have spatial -distributions sufficiently different from those generated by external -noise sources. Furthermore, it is implicitly assumed that the linear -space spanned by the significant external noise patters has a low -dimension. - -SSP-based rejection is often done using the -:func:`mne.preprocessing.compute_proj_ecg` and -:func:`mne.preprocessing.compute_proj_eog` methods, see :ref:`ssp` -section for more information. - -ICA -### - -Many M/EEG signals including biological artifacts reflect non-Gaussian -processes. Therefore PCA-based artifact rejection will likely perform worse at -separating the signal from noise sources. - -ICA-based artifact rejection is done using the :class:`mne.preprocessing.ICA` -class, see the :ref:`ica` section for more information. - - -Epoching and evoked data -======================== - -Epoching of raw data is done using events, which define a ``t=0`` for your -data chunks. Event times stamped to the acquisition software can be extracted -using :func:`mne.find_events`:: - - >>> events = mne.find_events(raw) # doctest: +SKIP - -The ``events`` array can then be modified, extended, or changed if necessary. -If the original trigger codes and trigger times are correct for the analysis -of interest, :class:`mne.Epochs` for the first event type (``1``) can be -constructed using:: - - >>> reject = dict(grad=4000e-13, mag=4e-12, eog=150e-6) # doctest: +SKIP - >>> epochs = mne.Epochs(raw, events, event_id=1, tmin=-0.2, tmax=0.5, # doctest: +SKIP - >>> proj=True, picks=picks, baseline=(None, 0), # doctest: +SKIP - >>> preload=True, reject=reject) # doctest: +SKIP - -.. note:: The rejection thresholds (set with argument ``reject``) are defined - in T / m for gradiometers, T for magnetometers and V for EEG and EOG - channels. - - -Rejection using annotations ---------------------------- - -The reject keyword of :class:`mne.Epochs` is used for rejecting bad epochs -based on peak-to-peak thresholds. Bad segments of data can also be rejected -by marking segments of raw data with annotations. See -:ref:`tut-artifact-rejection` and :class:`mne.Annotations` for more . - -Once the :class:`mne.Epochs` are constructed, they can be averaged to obtain -:class:`mne.Evoked` data as:: - - >>> evoked = epochs.average() # doctest: +SKIP - - -Source localization -=================== - -MNE makes extensive use of the FreeSurfer file structure for analysis. -Before starting data analysis, we recommend setting up the environment -variable ``SUBJECTS_DIR`` (or set it permanently using :func:`mne.set_config`) -to select the directory under which the anatomical MRI data are stored. -This makes it so that the ``subjects_dir`` argument does not need to -be passed to many functions. - -Anatomical information ----------------------- - -.. _CHDBBCEJ: - -Cortical surface reconstruction with FreeSurfer -############################################### - -The first processing stage is the creation of various surface -reconstructions with FreeSurfer. The recommended FreeSurfer workflow -is summarized on the `FreeSurfer wiki pages `_. See -also this information :ref:`tut-freesurfer`. - -.. _setting_up_source_space: - -Setting up the source space -########################### - -This stage consists of the following: - -- Creating a suitable decimated dipole grid on the white matter surface. - -- Creating the source space file in fif format. - -This is accomplished with using :func:`mne.setup_source_space` and -:func:`mne.write_source_spaces`. These assume that the anatomical MRI processing -has been completed as described in :ref:`CHDBBCEJ`. - -.. _BABGCDHA: - -.. table:: Recommended subdivisions of an icosahedron and an octahedron for - the creation of source spaces. The approximate source spacing and - corresponding surface area have been calculated assuming a - 1000-cm2 surface area per hemisphere. - - =========== ====================== =================== ============================= - ``spacing`` Sources per hemisphere Source spacing / mm Surface area per source / mm2 - =========== ====================== =================== ============================= - ``'oct5'`` 1026 9.9 97 - ``'ico4'`` 2562 6.2 39 - ``'oct6'`` 4098 4.9 24 - ``'ico5'`` 10242 3.1 9.8 - =========== ====================== =================== ============================= - -For example, to create the reconstruction geometry for ``subject='sample'`` -with a ~5-mm spacing between the grid points, say:: - - >>> src = setup_source_space('sample', spacing='oct6') # doctest: +SKIP - >>> write_source_spaces('sample-oct6-src.fif', src) # doctest: +SKIP - -This creates the source spaces and writes them to disk. - -:ref:`plot_forward_source_space` illustrates how the source space is used to -compute the forward model. - -.. _CHDBJCIA: - -Creating the BEM model meshes -############################# - -Calculation of the forward solution using the boundary-element -model (BEM) requires that the surfaces separating regions of different -electrical conductivities are tessellated with suitable surface -elements. Our BEM software employs triangular tessellations. Therefore, -prerequisites for BEM calculations are the segmentation of the MRI -data and the triangulation of the relevant surfaces. - -For MEG computations, a reasonably accurate solution can -be obtained by using a single-compartment BEM assuming the shape -of the intracranial volume. For EEG, the standard model contains -the intracranial space, the skull, and the scalp. - -At present, no bulletproof method exists for creating the -triangulations. Feasible approaches are described in :ref:`create_bem_model`. - -.. _BABDBBFC: - -Setting up the head surface triangulation files -############################################### - -The segmentation algorithms described in :ref:`create_bem_model` produce -either FreeSurfer surfaces or triangulation -data in text. Before proceeding to the creation of the boundary -element model, standard files for FreeSurfer surfaces must be present: - -1. **inner_skull.surf** contains the inner skull triangulation. - -2. **outer_skull.surf** contains the outer skull triangulation. - -3. **outer_skin.surf** contains the head surface triangulation. - -.. _CIHDBFEG: - -Setting up the boundary-element model -##################################### - -This stage sets up the subject-dependent data for computing -the forward solutions:" - - >>> model = make_bem_model('sample') # doctest: +SKIP - >>> write_bem_surfaces('sample-5120-5120-5120-bem.fif', model) # doctest: +SKIP - -Where ``surfaces`` is a list of BEM surfaces that have each been read using -:func:`mne.read_surface`. This step also checks that the input surfaces -are complete and that they are topologically correct, *i.e.*, -that the surfaces do not intersect and that the surfaces are correctly -ordered (outer skull surface inside the scalp and inner skull surface -inside the outer skull). - -This step assigns the conductivity values to the BEM compartments. -For the scalp and the brain compartments, the default is 0.3 S/m. -The default skull conductivity is 50 times smaller, *i.e.*, -0.006 S/m. Recent publications, see :ref:`CEGEGDEI`, report -a range of skull conductivity ratios ranging from 1:15 (Oostendorp *et -al.*, 2000) to 1:25 - 1:50 (Slew *et al.*, -2009, Conçalves *et al.*, 2003). The -MNE default ratio 1:50 is based on the typical values reported in -(Conçalves *et al.*, 2003), since their -approach is based comparison of SEF/SEP measurements in a BEM model. -The variability across publications may depend on individual variations -but, more importantly, on the precision of the skull compartment -segmentation. - -.. note:: To produce single layer BEM models (--homog flag in the C command - line tools) pass a list with one single conductivity value, - e.g. ``conductivities=[0.3]``. - -Using this model, the BEM solution can be computed using -:func:`mne.make_bem_solution` as:: - - >>> bem_sol = make_bem_solution(model) # doctest: +SKIP - >>> write_bem_solution('sample-5120-5120-5120-bem-sol.fif', bem_sol) # doctest: +SKIP - -After the BEM is set up it is advisable to check that the -BEM model meshes are correctly positioned using *e.g.* -:func:`mne.viz.plot_alignment` or :class:`mne.Report`. - -.. note:: Up to this point all processing stages depend on the - anatomical (geometrical) information only and thus remain - identical across different MEG studies. - -.. note:: If you use custom head models you might need to set the ``ico=None`` - parameter to ``None`` and skip subsampling of the surface. - - -.. _CHDBEHDC: - -Aligning coordinate frames --------------------------- - -The calculation of the forward solution requires knowledge -of the relative location and orientation of the MEG/EEG and MRI -coordinate systems (see :ref:`BJEBIBAI`). The head coordinate -frame is defined by identifying the fiducial landmark locations, -making the origin and orientation of the head coordinate system -slightly user dependent. As a result, it is safest to reestablish -the definition of the coordinate transformation computation -for each experimental session, *i.e.*, each time when new head -digitization data are employed. - -The corregistration is stored in ``-trans.fif`` file. If is present, -you can follow :ref:`plot_source_alignment` to validate its correctness. -If the ``-trans.fif`` is not present or the alignment is not correct -you need to use :func:`mne.gui.coregistration` (or its convenient command line -equivalent :ref:`gen_mne_coreg`) to generate it. - -.. XXX: It would be good to link to the ``-trans.fif`` file description - -.. warning:: This step is important. If the alignment of the - coordinate frames is inaccurate all subsequent processing - steps suffer from the error. Therefore, this step should be - performed by the person in charge of the study or by a trained - technician. Written or photographic documentation of the alignment - points employed during the MEG/EEG acquisition can also be - helpful. - -.. _BABCHEJD: - -Computing the forward solution ------------------------------- - -After the MRI-MEG/EEG alignment has been set, the forward -solution, *i.e.*, the magnetic fields and electric -potentials at the measurement sensors and electrodes due to dipole -sources located on the cortex, can be calculated with help of -:func:`mne.make_forward_solution` as:: - - >>> fwd = make_forward_solution(raw.info, fname_trans, src, bem_sol) # doctest: +SKIP - -.. _BABDEEEB: - -Computing the noise-covariance matrix -------------------------------------- - -The MNE software employs an estimate of the noise-covariance -matrix to weight the channels correctly in the calculations. The -noise-covariance matrix provides information about field and potential -patterns representing uninteresting noise sources of either human -or environmental origin. - -The noise covariance matrix can be calculated in several -ways: - -- Employ the individual epochs during - off-line averaging to calculate the full noise covariance matrix. - This is the recommended approach for evoked responses, *e.g.* using - :func:`mne.compute_covariance`:: - - >>> cov = mne.compute_covariance(epochs, method='auto') # doctest: +SKIP - -- Employ empty room data (collected without the subject) to - calculate the full noise covariance matrix. This is recommended - for analyzing ongoing spontaneous activity. This can be done using - :func:`mne.compute_raw_covariance` as:: - - >>> cov = mne.compute_raw_covariance(raw_erm) # doctest: +SKIP - -- Employ a section of continuous raw data collected in the presence - of the subject to calculate the full noise covariance matrix. This - is the recommended approach for analyzing epileptic activity. The - data used for this purpose should be free of technical artifacts - and epileptic activity of interest. The length of the data segment - employed should be at least 20 seconds. One can also use a long - (``*> 200 s``) segment of data with epileptic spikes present provided - that the spikes occur infrequently and that the segment is apparently - stationary with respect to background brain activity. This can also - use :func:`mne.compute_raw_covariance`. - -.. _CIHCFJEI: - -Calculating the inverse operator --------------------------------- - -The MNE software doesn't calculate the inverse operator -explicitly but rather computes an SVD of a matrix composed of the -noise-covariance matrix, the result of the forward calculation, -and the source covariance matrix. This approach has the benefit -that the regularization parameter ('SNR') can -be adjusted easily when the final source estimates or dSPMs are -computed. For mathematical details of this approach, -please consult :ref:`CBBDJFBJ`. - -This computation stage can be done by using -:func:`mne.minimum_norm.make_inverse_operator` as:: - - >>> inv = mne.minimum_norm.make_inverse_operator(raw.info, fwd, cov, loose=0.2) # doctest: +SKIP - -Creating source estimates -------------------------- - -Once all the preprocessing steps described above have been -completed, the inverse operator computed can be applied to the MEG -and EEG data as:: - - >>> stc = mne.minimum_norm.apply_inverse(evoked, inv, lambda2=1. / 9.) # doctest: +SKIP - -And the results can be viewed as:: - - >>> stc.plot() # doctest: +SKIP - -The interactive analysis tool :ref:`mne_analyze` can also -be used to explore the data and to produce quantitative analysis -results, screen snapshots, and QuickTime (TM) movie files, -see :ref:`c_legacy_ch_interactive_analysis`. - -Group analyses --------------- - -Group analysis is facilitated by morphing source estimates, which can be -done *e.g.*, to ``subject='fsaverage'`` as:: - - >>> morph = mne.compute_source_morph(stc, subject_from='sample', subject_to='fsaverage') # doctest: +SKIP - >>> stc_fsaverage = morph.apply(stc) # doctest: +SKIP - -See :ref:`ch_morph` for more information. diff -Nru python-mne-0.18.1+dfsg/doc/manual/c_reference.rst python-mne-0.19.1+dfsg/doc/manual/c_reference.rst --- python-mne-0.18.1+dfsg/doc/manual/c_reference.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/c_reference.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,6448 +0,0 @@ - - -.. _c_reference: - -=============== -C API Reference -=============== - -Note that most programs have the options ``--version`` and ``--help`` which -give the version information and usage information, respectively. - -.. contents:: Contents - :local: - :depth: 2 - - -List of components -################## - -Software components -=================== - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.65\linewidth}| -.. table:: - - - +----------------------------+--------------------------------------------+ - | Name | Purpose | - +============================+============================================+ - | `mne_analyze`_ | An interactive analysis tool for computing | - | | source estimates, see | - | | :ref:`c_legacy_ch_interactive_analysis`. | - +----------------------------+--------------------------------------------+ - | `mne_average_estimates`_ | Average data across subjects. | - +----------------------------+--------------------------------------------+ - | `mne_browse_raw`_ | Interactive raw data browser. Includes | - | | filtering, offline averaging, and | - | | computation of covariance matrices, | - | | see :ref:`ch_browse`. | - +----------------------------+--------------------------------------------+ - | `mne_compute_mne`_ | Computes the minimum-norm estimates, | - | | Most functionality is included in | - | | :ref:`mne_make_movie`. | - +----------------------------+--------------------------------------------+ - | `mne_compute_raw_inverse`_ | Compute the inverse solution from raw data | - | | see :ref:`c_legacy_computing_inverse`. | - +----------------------------+--------------------------------------------+ - | `mne_convert_mne_data`_ | Convert MNE data files to other file | - | | formats. | - +----------------------------+--------------------------------------------+ - | `mne_do_forward_solution`_ | Convenience script to calculate the forward| - | | solution matrix, see :ref:`BABCHEJD`. | - +----------------------------+--------------------------------------------+ - | `mne_do_inverse_operator`_ | Convenience script for inverse operator | - | | decomposition, see :ref:`CIHCFJEI`. | - +----------------------------+--------------------------------------------+ - | `mne_forward_solution`_ | Calculate the forward solution matrix, see | - | | :ref:`c_legacy_CHDDIBAH`. | - +----------------------------+--------------------------------------------+ - | `mne_inverse_operator`_ | Compute the inverse operator decomposition | - | | see :ref:`c_legacy_inverse_operator`. | - +----------------------------+--------------------------------------------+ - | `mne_make_movie`_ | Make movies in batch mode, see | - | | :ref:`c_legacy_movies_and_snapshots`. | - +----------------------------+--------------------------------------------+ - | `mne_make_source_space`_ | Create a *fif* source space description | - | | file, see :ref:`c_legacy_BEHCGJDD`. | - +----------------------------+--------------------------------------------+ - | `mne_process_raw`_ | A batch-mode version of mne_browse_raw, | - | | see :ref:`ch_browse`. | - +----------------------------+--------------------------------------------+ - | `mne_redo_file`_ | Many intermediate result files contain a | - | | description of their | - | | 'production environment'. Such files can | - | | be recreated easily with this utility. | - | | This is convenient if, for example, | - | | the selection of bad channels is changed | - | | and the inverse operator decomposition has | - | | to be recalculated. | - +----------------------------+--------------------------------------------+ - | `mne_redo_file_nocwd`_ | Works like mne_redo_file but does not try | - | | to change in to the working directory | - | | specified in the 'production environment'. | - +----------------------------+--------------------------------------------+ - | `mne_setup_forward_model`_ | Set up the BEM-related fif files, | - | | see :ref:`CIHDBFEG`. | - +----------------------------+--------------------------------------------+ - | `mne_setup_mri`_ | A convenience script to create the fif | - | | files describing the anatomical MRI data, | - | | see :ref:`BABCCEHF` | - +----------------------------+--------------------------------------------+ - | `mne_setup_source_space`_ | A convenience script to create source space| - | | description file, see | - | | :ref:`setting_up_source_space`. | - +----------------------------+--------------------------------------------+ - | `mne_show_environment`_ | Show information about the production | - | | environment of a file. | - +----------------------------+--------------------------------------------+ - - -.. _c_legacy_utilities: - -Utilities -========= - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.65\linewidth}| -.. _BABDJHGH: -.. table:: - - +----------------------------------+--------------------------------------------+ - | Name | Purpose | - +==================================+============================================+ - | `mne_add_patch_info`_ | Add neighborhood information to a source | - | | space file. | - +----------------------------------+--------------------------------------------+ - | `mne_add_to_meas_info`_ | Utility to add new information to the | - | | measurement info block of a fif file. The | - | | source of information is another fif file. | - +----------------------------------+--------------------------------------------+ - | `mne_add_triggers`_ | Modify the trigger channel STI 014 in a raw| - | | data file. The same effect can be reached | - | | by using an event file for averaging in | - | | :ref:`mne_process_raw` and | - | | :ref:`mne_browse_raw`. | - +----------------------------------+--------------------------------------------+ - | `mne_annot2labels`_ | Convert parcellation data into label files.| - +----------------------------------+--------------------------------------------+ - | `mne_anonymize`_ | Remove subject-specific information from a | - | | fif data file. | - +----------------------------------+--------------------------------------------+ - | `mne_average_forward_solutions`_ | Calculate an average of forward solutions, | - | | see :ref:`c_legacy_CHDBBFCA`. | - +----------------------------------+--------------------------------------------+ - | `mne_brain_vision2fiff`_ | Convert EEG data from BrainVision format | - | | to fif format. | - +----------------------------------+--------------------------------------------+ - | `mne_change_baselines`_ | Change the dc offsets according to | - | | specifications given in a text file. | - +----------------------------------+--------------------------------------------+ - | `mne_change_nave`_ | Change the number of averages in an | - | | evoked-response data file. This is often | - | | necessary if the file was derived from | - | | several files. | - +----------------------------------+--------------------------------------------+ - | `mne_check_eeg_locations`_ | Checks that the EEG electrode locations | - | | have been correctly transferred from the | - | | Polhemus data block to the channel | - | | information tags | - +----------------------------------+--------------------------------------------+ - | `mne_check_surface`_ | Check the validity of a FreeSurfer surface | - | | file or one of the surfaces within a BEM | - | | file. This program simply checks for | - | | topological errors in surface files. | - +----------------------------------+--------------------------------------------+ - | `mne_collect_transforms`_ | Collect coordinate transformations from | - | | several sources into a single fif file. | - +----------------------------------+--------------------------------------------+ - | `mne_compensate_data`_ | Change the applied software gradient | - | | compensation in an evoked-response data | - | | file, see :ref:`BEHDDFBI`. | - +----------------------------------+--------------------------------------------+ - | `mne_copy_processing_history`_ | Copy the processing history between files. | - +----------------------------------+--------------------------------------------+ - | `mne_convert_dig_data`_ | Convert digitization data between | - | | different formats. | - +----------------------------------+--------------------------------------------+ - | `mne_convert_lspcov`_ | Convert the LISP format noise covariance | - | | matrix output by graph into fif. | - +----------------------------------+--------------------------------------------+ - | `mne_convert_ncov`_ | Convert the ncov format noise covariance | - | | file to fif. | - +----------------------------------+--------------------------------------------+ - | `mne_convert_surface`_ | Convert FreeSurfer and text format surface | - | | files into Matlab mat files. | - +----------------------------------+--------------------------------------------+ - | `mne_cov2proj`_ | Pick eigenvectors from a covariance matrix | - | | and create a signal-space projection (SSP) | - | | file out of them. | - +----------------------------------+--------------------------------------------+ - | `mne_create_comp_data`_ | Create a fif file containing software | - | | gradient compensation information from a | - | | text file. | - +----------------------------------+--------------------------------------------+ - | `mne_ctf2fiff`_ | Convert a CTF ds folder into a fif file. | - +----------------------------------+--------------------------------------------+ - | `mne_ctf_dig2fiff`_ | Convert text format digitization data to | - | | fif format. | - +----------------------------------+--------------------------------------------+ - | `mne_dicom_essentials`_ | List essential information from a | - | | DICOM file. | - | | This utility is used by the script | - | | mne_organize_dicom, see :ref:`BABEBJHI`. | - +----------------------------------+--------------------------------------------+ - | `mne_edf2fiff`_ | Convert EEG data from the EDF/EDF+/BDF | - | | formats to the fif format. | - +----------------------------------+--------------------------------------------+ - | `mne_epochs2mat`_ | Apply bandpass filter to raw data and | - | | extract epochs for subsequent processing | - | | in Matlab. | - +----------------------------------+--------------------------------------------+ - | `mne_evoked_data_summary`_ | List summary of averaged data from a fif | - | | file to the standard output. | - +----------------------------------+--------------------------------------------+ - | `mne_eximia2fiff`_ | Convert EEG data from the Nexstim eXimia | - | | system to fif format. | - +----------------------------------+--------------------------------------------+ - | `mne_fit_sphere_to_surf`_ | Fit a sphere to a surface given in fif | - | | or FreeSurfer format. | - +----------------------------------+--------------------------------------------+ - | `mne_fix_mag_coil_types`_ | Update the coil types for magnetometers | - | | in a fif file. | - +----------------------------------+--------------------------------------------+ - | `mne_fix_stim14`_ | Fix coding errors of trigger channel | - | | STI 014, see :ref:`BABCDBDI`. | - +----------------------------------+--------------------------------------------+ - | `mne_flash_bem`_ | Create BEM tessellation using multi-echo | - | | FLASH MRI data, see :ref:`BABFCDJH`. | - +----------------------------------+--------------------------------------------+ - | `mne_insert_4D_comp`_ | Read Magnes compensation channel data from | - | | a text file and merge it with raw data | - | | from other channels in a fif file. | - +----------------------------------+--------------------------------------------+ - | `mne_kit2fiff`_ | Convert KIT data to FIF. | - +----------------------------------+--------------------------------------------+ - | `mne_list_bem`_ | List BEM information in text format. | - +----------------------------------+--------------------------------------------+ - | `mne_list_coil_def`_ | Create the coil description file. This | - | | is run automatically at when the software | - | | is set up, see :ref:`c_legacy_BJEHHJIJ`. | - +----------------------------------+--------------------------------------------+ - | `mne_list_proj`_ | List signal-space projection data from a | - | | fif file. | - +----------------------------------+--------------------------------------------+ - | `mne_list_source_space`_ | List source space information in text | - | | format suitable for importing into | - | | Neuromag MRIlab. | - +----------------------------------+--------------------------------------------+ - | `mne_list_versions`_ | List versions and compilation dates of MNE | - | | software modules. | - +----------------------------------+--------------------------------------------+ - | `mne_make_cor_set`_ | Used by mne_setup_mri to create fif format | - | | MRI description files from COR or mgh/mgz | - | | format MRI data, see :ref:`BABCCEHF`. | - +----------------------------------+--------------------------------------------+ - | `mne_make_derivations`_ | Create a channel derivation data file. | - +----------------------------------+--------------------------------------------+ - | `mne_make_eeg_layout`_ | Make a topographical trace layout file | - | | using the EEG electrode locations from | - | | an actual measurement. | - +----------------------------------+--------------------------------------------+ - | `mne_make_morph_maps`_ | Precompute the mapping data needed for | - | | morphing between subjects, see | - | | :ref:`CHDBBHDH`. | - +----------------------------------+--------------------------------------------+ - | `mne_make_uniform_stc`_ | Create a spatially uniform stc file for | - | | testing purposes. | - +----------------------------------+--------------------------------------------+ - | `mne_mark_bad_channels`_ | Update the list of unusable channels in | - | | a data file | - +----------------------------------+--------------------------------------------+ - | `mne_morph_labels`_ | Morph label file definitions between | - | | subjects. | - +----------------------------------+--------------------------------------------+ - | `mne_organize_dicom`_ | Organized DICOM MRI image files into | - | | directories, see :ref:`BABEBJHI`. | - +----------------------------------+--------------------------------------------+ - | `mne_prepare_bem_model`_ | Perform the geometry calculations for | - | | BEM forward solutions, see | - | | :ref:`c_legacy_CHDJFHEB`. | - +----------------------------------+--------------------------------------------+ - | `mne_process_stc`_ | Manipulate stc files. | - +----------------------------------+--------------------------------------------+ - | `mne_raw2mat`_ | Convert raw data into a Matlab file. | - +----------------------------------+--------------------------------------------+ - | `mne_rename_channels`_ | Change the names and types of channels | - | | in a fif file. | - +----------------------------------+--------------------------------------------+ - | `mne_sensitivity_map`_ | Compute a sensitivity map and output | - | | the result in a w-file. | - +----------------------------------+--------------------------------------------+ - | `mne_sensor_locations`_ | Create a file containing the sensor | - | | locations in text format. | - +----------------------------------+--------------------------------------------+ - | `mne_show_fiff`_ | List contents of a fif file. | - +----------------------------------+--------------------------------------------+ - | `mne_simu`_ | Simulate MEG and EEG data. | - +----------------------------------+--------------------------------------------+ - | `mne_smooth`_ | Smooth a w or stc file. | - +----------------------------------+--------------------------------------------+ - | `mne_surf2bem`_ | Create a *fif* file describing the | - | | triangulated compartment boundaries for | - | | the boundary-element model (BEM), | - | | see :ref:`c_legacy_BEHCACCJ`. | - +----------------------------------+--------------------------------------------+ - | `mne_toggle_skips`_ | Change data skip tags in a raw file into | - | | ignored skips or vice versa. | - +----------------------------------+--------------------------------------------+ - | `mne_transform_points`_ | Transform between MRI and MEG head | - | | coordinate frames. | - +----------------------------------+--------------------------------------------+ - | `mne_tufts2fiff`_ | Convert EEG data from the Tufts | - | | University format to fif format. | - +----------------------------------+--------------------------------------------+ - | `mne_view_manual`_ | Starts a PDF reader to show this manual | - | | from its standard location. | - +----------------------------------+--------------------------------------------+ - | `mne_volume_data2mri`_ | Convert volumetric data defined in a | - | | source space created with | - | | mne_volume_source_space into an MRI | - | | overlay. | - +----------------------------------+--------------------------------------------+ - | `mne_volume_source_space`_ | Make a volumetric source space, | - | | see :ref:`c_legacy_BJEFEHJI`. | - +----------------------------------+--------------------------------------------+ - | `mne_watershed_bem`_ | Do the segmentation for BEM using the | - | | watershed algorithm, see :ref:`BABBDHAG`. | - +----------------------------------+--------------------------------------------+ - - -Software component command-line arguments -######################################### - -.. _mne_analyze: - -mne_analyze -=========== - -Since mne_analyze is primarily an interactive analysis tool, there are only a -few command-line options: - -``\---cd <*dir*>`` - - Change to this directory before starting. - -``\---subject <*name*>`` - - Specify the default subject name for surface loading. - -``\---digtrig <*name*>`` - - Name of the digital trigger channel. The default value is 'STI - 014'. Underscores in the channel name will be replaced - by spaces. - -``\---digtrigmask <*number*>`` - - Mask to be applied to the raw data trigger channel values before considering - them. This option is useful if one wants to set some bits in a don't - care state. For example, some finger response pads keep the trigger - lines high if not in use, *i.e.*, a finger is - not in place. Yet, it is convenient to keep these devices permanently - connected to the acquisition system. The number can be given in - decimal or hexadecimal format (beginning with 0x or 0X). For example, - the value 255 (0xFF) means that only the lowest order byte (usually - trigger lines 1 - 8 or bits 0 - 7) will be considered. - -``\---visualizehpi`` - - Start mne_analyze in the restricted *head - position visualization* mode. For details, see :ref:`CHDEDFAE`. - -``\---dig <*filename*>`` - - Specify a file containing the head shape digitization data. This option - is only usable if the *head position visualization* position - visualization mode has been first invoked with the --visualizehpi - option. - -``\---hpi <*filename*>`` - - Specify a file containing the transformation between the MEG device - and head coordinate frames. This option is only usable if the *head - position visualization* position visualization mode has - been first invoked with the ``--visualizehpi`` option. - -``\---scalehead`` - - In *head position visualization* mode, scale - the average scalp surface according to the head surface digitization - data before aligning them to the scalp surface. This option is - recommended. - -``\---rthelmet`` - - Use the room-temperature helmet surface instead of the MEG sensor - surface when showing the relative position of the MEG sensors and - the head in the *head position visualization* mode. - -.. note:: Before starting mne_analyze the ``SUBJECTS_DIR`` environment variable has to be set. - -.. note:: Strictly speaking, trigger mask value zero would mean that all trigger inputs are ignored. However, for convenience, setting the mask to zero or not setting it at all has the same effect as 0xFFFFFFFF, *i.e.*, all bits set. - -.. note:: The digital trigger channel can also be set with the MNE_TRIGGER_CH_NAME environment variable. Underscores in the variable value will *not* be replaced with spaces by mne_analyze . Using the ``--digtrig`` option supersedes the MNE_TRIGGER_CH_NAME environment variable. - -.. note:: The digital trigger channel mask can also be set with the MNE_TRIGGER_CH_MASK environment variable. Using the ``--digtrigmask`` option supersedes the MNE_TRIGGER_CH_MASK environment variable. - - -.. _mne_average_estimates: - -mne_average_estimates -===================== -This is a utility for averaging data in stc files. It requires that -all stc files represent data on one individual's cortical -surface and contain identical sets of vertices. mne_average_estimates uses -linear interpolation to resample data in time as necessary. The -command line arguments are: - -``---desc `` - - Specifies the description file for averaging. The format of this - file is described below. - -The description file --------------------- - -The description file for mne_average_estimates consists -of a sequence of tokens, separated by whitespace (space, tab, or -newline). If a token consists of several words it has to be enclosed -in quotes. One or more tokens constitute an phrase, which has a -meaning for the averaging definition. Any line starting with the -pound sign (#) is a considered to be a comment line. There are two -kinds of phrases in the description file: global and contextual. -The global phrases have the same meaning independent on their location -in the file while the contextual phrases have different effects depending -on their location in the file. - -There are three types of contexts in the description file: -the global context, an input context, -and the output context. In the -beginning of the file the context is global for -defining global parameters. The input context -defines one of the input files (subjects) while the output context -specifies the destination for the average. - -The global phrases are: - -``tmin <*value/ms*>`` - - The minimum time to be considered. The output stc file starts at - this time point if the time ranges of the stc files include this - time. Otherwise the output starts from the next later available - time point. - -``tstep <*step/ms*>`` - - Time step between consecutive movie frames, specified in milliseconds. - -``tmax <*value/ms*>`` - - The maximum time point to be considered. A multiple of tstep will be - added to the first time point selected until this value or the last time - point in one of the input stc files is reached. - -``integ <:math:`\Delta t` /*ms*>`` - - Integration time for each frame. Defaults to zero. The integration will - be performed on sensor data. If the time specified for a frame is :math:`t_0`, - the integration range will be :math:`t_0 - ^{\Delta t}/_2 \leq t \leq t_0 + ^{\Delta t}/_2`. - -``stc <*filename*>`` - - Specifies an input stc file. The filename can be specified with - one of the ``-lh.stc`` and ``-rh.stc`` endings - or without them. This phrase ends the present context and starts - an input context. - -``deststc <*filename*>`` - - Specifies the output stc file. The filename can be specified with - one of the ``-lh.stc`` and ``-rh.stc`` endings - or without them. This phrase ends the present context and starts - the output context. - -``lh`` - - Process the left hemisphere. By default, both hemispheres are processed. - -``rh`` - - Process the left hemisphere. By default, both hemispheres are processed. - -The contextual phrases are: - -``weight <*value*>`` - - Specifies the weight of the current data set. This phrase is valid - in the input and output contexts. - -``abs`` - - Specifies that the absolute value of the data should be taken. Valid - in all contexts. If specified in the global context, applies to - all subsequent input and output contexts. If specified in the input - or output contexts, applies only to the data associated with that - context. - -``pow <*value*>`` - - Specifies that the data should raised to the specified power. For - negative values, the absolute value of the data will be taken and - the negative sign will be transferred to the result, unless abs is - specified. Valid in all contexts. Rules of application are identical - to abs . - -``sqrt`` - - Means pow 0.5 - -The effects of the options can be summarized as follows. -Suppose that the description file includes :math:`P` contexts -and the temporally resampled data are organized in matrices :math:`S^{(p)}`, -where :math:`p = 1 \dotso P` is the subject index, and -the rows are the signals at different vertices of the cortical surface. -The average computed by mne_average_estimates is -then: - -.. math:: A_{jk} = |w[\newcommand\sgn{\mathop{\mathrm{sgn}}\nolimits}\sgn(B_{jk})]^{\alpha}|B_{jk}|^{\beta} - -with - -.. math:: B_{jk} = \sum_{p = 1}^p {\bar{w_p}[\newcommand\sgn{\mathop{\mathrm{sgn}}\nolimits}\sgn(S_{jk}^{(p)})^{\alpha_p}|S_{jk}^{(p)}|^{\beta_p}} - -and - -.. math:: \bar{w_p} = w_p / \sum_{p = 1}^p {|w_p|}\ . - -In the above, :math:`\beta_p` and :math:`w_p` are -the powers and weights assigned to each of the subjects whereas :math:`\beta` and :math:`w` are -the output weight and power value, respectively. The sign is either -included (:math:`\alpha_p = 1`, :math:`\alpha = 1`) -or omitted (:math:`\alpha_p = 2`, :math:`\alpha = 2`) -depending on the presence of abs phrases in the description file. - -.. note:: mne_average_estimates requires that the number of vertices in the stc files are the same and that the vertex numbers are identical. This will be the case if the files have been produced in mne_make_movie using the ``--morph`` option. - -.. note:: It is straightforward to read and write stc files using the MNE Matlab toolbox described in :ref:`ch_matlab` and thus write custom Matlab functions to realize more complicated custom group analysis tools. - - -.. _mne_browse_raw: - -mne_browse_raw -============== - -``--cd <*dir*>`` - - Change to this directory before starting. - -``--raw <*name*>`` - - Specifies the raw data file to be opened. If a raw data file is not - specified, an empty interactive browser will open. - -``--grad <*number*>`` - - Apply software gradient compensation of the given order to the data loaded - with the ``--raw`` option. This option is effective only - for data acquired with the CTF and 4D Magnes MEG systems. If orders - different from zero are requested for Neuromag data, an error message appears - and data are not loaded. Any compensation already existing in the - file can be undone or changed to another order by using an appropriate ``--grad`` options. - Possible orders are 0 (No compensation), 1 - 3 (CTF data), and 101 - (Magnes data). This applies only to the data file loaded by specifying the ``--raw`` option. - For interactive data loading, the software gradient compensation - is specified in the corresponding file selection dialog, see :ref:`CACDCHAJ`. - -``--filtersize <*size*>`` - - Adjust the length of the FFT to be applied in filtering. The number will - be rounded up to the next power of two. If the size is :math:`N`, - the corresponding length of time is :math:`N/f_s`, - where :math:`f_s` is the sampling frequency - of your data. The filtering procedure includes overlapping tapers - of length :math:`N/2` so that the total FFT - length will actually be :math:`2N`. This - value cannot be changed after the program has been started. - -``--highpass <*value/Hz*>`` - - Highpass filter frequency limit. If this is too low with respect - to the selected FFT length and, the data will not be highpass filtered. It - is best to experiment with the interactive version to find the lowest applicable - filter for your data. This value can be adjusted in the interactive - version of the program. The default is 0, *i.e.*, - no highpass filter apart from that used during the acquisition will - be in effect. - -``--highpassw <*value/Hz*>`` - - The width of the transition band of the highpass filter. The default - is 6 frequency bins, where one bin is :math:`f_s / (2N)`. This - value cannot be adjusted in the interactive version of the program. - -``--lowpass <*value/Hz*>`` - - Lowpass filter frequency limit. This value can be adjusted in the interactive - version of the program. The default is 40 Hz. - -``--lowpassw <*value/Hz*>`` - - The width of the transition band of the lowpass filter. This value - can be adjusted in the interactive version of the program. The default - is 5 Hz. - -``--eoghighpass <*value/Hz*>`` - - Highpass filter frequency limit for EOG. If this is too low with respect - to the selected FFT length and, the data will not be highpass filtered. - It is best to experiment with the interactive version to find the - lowest applicable filter for your data. This value can be adjusted in - the interactive version of the program. The default is 0, *i.e.*, - no highpass filter apart from that used during the acquisition will - be in effect. - -``--eoghighpassw <*value/Hz*>`` - - The width of the transition band of the EOG highpass filter. The default - is 6 frequency bins, where one bin is :math:`f_s / (2N)`. - This value cannot be adjusted in the interactive version of the - program. - -``--eoglowpass <*value/Hz*>`` - - Lowpass filter frequency limit for EOG. This value can be adjusted in - the interactive version of the program. The default is 40 Hz. - -``--eoglowpassw <*value/Hz*>`` - - The width of the transition band of the EOG lowpass filter. This value - can be adjusted in the interactive version of the program. The default - is 5 Hz. - -``--filteroff`` - - Do not filter the data. This initial value can be changed in the - interactive version of the program. - -``--digtrig <*name*>`` - - Name of the composite digital trigger channel. The default value - is 'STI 014'. Underscores in the channel name - will be replaced by spaces. - -``--digtrigmask <*number*>`` - - Mask to be applied to the trigger channel values before considering them. - This option is useful if one wants to set some bits in a don't care - state. For example, some finger response pads keep the trigger lines - high if not in use, *i.e.*, a finger is not in - place. Yet, it is convenient to keep these devices permanently connected - to the acquisition system. The number can be given in decimal or - hexadecimal format (beginning with 0x or 0X). For example, the value - 255 (0xFF) means that only the lowest order byte (usually trigger - lines 1 - 8 or bits 0 - 7) will be considered. - -``--allowmaxshield`` - - Allow loading of unprocessed Elekta-Neuromag data with MaxShield - on. These kind of data should never be used for source localization - without further processing with Elekta-Neuromag software. - -``--deriv <*name*>`` - - Specifies the name of a derivation file. This overrides the use - of a standard derivation file, see :ref:`CACFHAFH`. - -``--sel <*name*>`` - - Specifies the channel selection file to be used. This overrides - the use of the standard channel selection files, see :ref:`CACCJEJD`. - -.. note:: Strictly speaking, trigger mask value zero would mean that all trigger inputs are ignored. However, for convenience, setting the mask to zero or not setting it at all has the same effect as 0xFFFFFFFF, *i.e.*, all bits set. - -.. note:: The digital trigger channel can also be set with the MNE_TRIGGER_CH_NAME environment variable. Underscores in the variable value will *not* be replaced with spaces. Using the ``--digtrig`` option supersedes the MNE_TRIGGER_CH_NAME environment variable. - -.. note:: The digital trigger channel mask can also be set with the MNE_TRIGGER_CH_MASK environment variable. Using the ``--digtrigmask`` option supersedes the MNE_TRIGGER_CH_MASK environment variable. - - - -.. _mne_compute_mne: - -mne_compute_mne -=============== - -This program is gradually becoming obsolete. All of its functions will -be eventually included to :ref:`mne_make_movie`, -see :ref:`c_legacy_movies_and_snapshots`. At this time, :ref:`mne_compute_mne` is -still needed to produce time-collapsed w files unless you are willing -to write a Matlab script of your own for this purpose. - - -``--inv <*name*>`` - - Load the inverse operator decomposition from here. - -``--meas <*name*>`` - - Load the MEG or EEG data from this file. - -``--set <*number*>`` - - The data set (condition) number to load. The list of data sets can - be seen, *e.g.*, in mne_analyze , mne_browse_raw , - and xplotter . - -``--bmin <*time/ms*>`` - - Specifies the starting time of the baseline. In order to activate - baseline correction, both ``--bmin`` and ``--bmax`` options - must be present. - -``--bmax <*time/ms*>`` - - Specifies the finishing time of the baseline. - -``--nave <*value*>`` - - Specifies the number of averaged epochs in the input data. If the input - data file is one produced by mne_process_raw or mne_browse_raw , - the number of averages is correct in the file. However, if subtractions - or some more complicated combinations of simple averages are produced, *e.g.*, - by using the xplotter software, the - number of averages should be manually adjusted. This is accomplished - either by employing this flag or by adjusting the number of averages - in the data file with help of mne_change_nave . - -``--snr <*value*>`` - - An estimate for the amplitude SNR. The regularization parameter will - be set as :math:`\lambda = ^1/_{\text{SNR}}`. If the SNR option is - absent, the regularization parameter will be estimated from the - data. The regularization parameter will be then time dependent. - -``--snronly`` - - Only estimate SNR and output the result into a file called SNR. Each - line of the file contains three values: the time point in ms, the estimated - SNR + 1, and the regularization parameter estimated from the data - at this time point. - -``--abs`` - - Calculate the absolute value of the current and the dSPM for fixed-orientation - data. - -``--spm`` - - Calculate the dSPM instead of the expected current value. - -``--chi2`` - - Calculate an approximate :math:`\chi_2^3` statistic - instead of the *F* statistic. This is simply - accomplished by multiplying the *F* statistic - by three. - -``--sqrtF`` - - Take the square root of the :math:`\chi_2^3` or *F* statistic - before outputting the stc file. - -``--collapse`` - - Make all frames in the stc file (or the wfile) identical. The value - at each source location is the maximum value of the output quantity - at this location over the analysis period. This option is convenient - for determining the correct thresholds for the rendering of the - final brain-activity movies. - -``--collapse1`` - - Make all frames in the stc file (or the wfile) identical. The value - at each source location is the :math:`L_1` norm - of the output quantity at this location over the analysis period. - -``--collapse2`` - - Make all frames in the stc file (or the wfile) identical. The value - at each source location is the :math:`L_2` norm - of the output quantity at this location over the analysis period. - -``--SIcurrents`` - - Output true current values in SI units (Am). By default, the currents are - scaled so that the maximum current value is set to 50 (Am). - -``--out <*name*>`` - - Specifies the output file name. This is the 'stem' of - the output file name. The actual name is derived by removing anything up - to and including the last period from the end of <*name*> . - According to the hemisphere, ``-lh`` or ``-rh`` is - then appended. Finally, ``.stc`` or ``.w`` is added, - depending on the output file type. - -``--wfiles`` - - Use binary w-files in the output whenever possible. The noise-normalization - factors can be always output in this format. The current estimates - and dSPMs can be output as wfiles if one of the collapse options - is selected. - -``--pred <*name*>`` - - Save the predicted data into this file. This is a fif file containing - the predicted data waveforms, see :ref:`c_legacy_CHDCACDC`. - -``--outputnorm <*name*>`` - - Output noise-normalization factors to this file. - -``--invnorm`` - - Output inverse noise-normalization factors to the file defined by - the ``--outputnorm`` option. - -``--dip <*name*>`` - - Specifies a dipole distribution snapshot file. This is a file containing the - current distribution at a time specified with the ``--diptime`` option. - The file format is the ASCII dip file format produced by the Neuromag - source modelling software (xfit). Therefore, the file can be loaded - to the Neuromag MRIlab MRI viewer to display the actual current - distribution. This option is only effective if the ``--spm`` option - is absent. - -``--diptime <*time/ms*>`` - - Time for the dipole snapshot, see ``--dip`` option above. - -``--label <*name*>`` - - Label to process. The label files are produced by tksurfer and specify - regions of interests (ROIs). A label file name should end with ``-lh.label`` for - left-hemisphere ROIs and with ``-rh.label`` for right-hemisphere - ones. The corresponding output files are tagged with ``-lh-`` <*data type* ``.amp`` and ``-rh-`` <*data type* ``.amp`` , respectively. <*data type*> equals ``MNE`` for expected current - data and ``spm`` for dSPM data. Each line of the output - file contains the waveform of the output quantity at one of the - source locations falling inside the ROI. - -.. note:: The ``--tmin`` and ``--tmax`` options which existed in previous versions of mne_compute_mne have been removed. mne_compute_mne can now process only the entire averaged epoch. - - -.. _mne_compute_raw_inverse: - -mne_compute_raw_inverse -======================= - -``--in <*filename*>`` - - Specifies the input data file. This can be either an evoked data - file or a raw data file. - -``--bmin <*time/ms*>`` - - Specifies the starting time of the baseline. In order to activate - baseline correction, both ``--bmin`` and ``--bmax`` options - must be present. This option applies to evoked data only. - -``--bmax <*time/ms*>`` - - Specifies the finishing time of the baseline. This option applies - to evoked data only. - -``--set <*number*>`` - - The data set (condition) number to load. This is the sequential - number of the condition. You can easily see the association by looking - at the condition list in mne_analyze when - you load the file. - -``--inv <*name*>`` - - Load the inverse operator decomposition from here. - -``--nave <*value*>`` - - Specifies the effective number of averaged epochs in the input data, :math:`L_{eff}`, - as discussed in :ref:`c_legacy_CBBDGIAE`. If the input data file is - one produced by mne_browse_raw or mne_process_raw , - the number of averages is correct in the file. However, if subtractions - or some more complicated combinations of simple averages are produced, - e.g., by using the xplotter software, - the number of averages should be manually adjusted along the guidelines - given in :ref:`c_legacy_CBBDGIAE`. This is accomplished either by - employing this flag or by adjusting the number of averages in the - data file with help of the utility mne_change_nave . - -``--snr <*value*>`` - - An estimate for the amplitude SNR. The regularization parameter will - be set as :math:`\lambda^2 = 1/SNR^2`. The default value is - SNR = 1. Automatic selection of the regularization parameter is - currently not supported. - -``--spm`` - - Calculate the dSPM instead of the expected current value. - -``--picknormalcomp`` - - The components of the estimates corresponding to directions tangential - with the cortical mantle are zeroed out. - -``--mricoord`` - - Provide source locations and orientations in the MRI coordinate frame - instead of the default head coordinate frame. - -``--label <*name*>`` - - Specifies a label file to process. For each label file, the values - of the computed estimates stored in a fif file. For more details, - see :ref:`c_legacy_implementation_details`. The label files are produced by tksurfer - or mne_analyze and specify regions - of interests (ROIs). A label file name should end with ``-lh.label`` for - left-hemisphere ROIs and with ``-rh.label`` for right-hemisphere - ones. The corresponding output files are tagged with ``-lh-`` <*data type*> ``.fif`` and ``-rh-`` <*data type*> ``.fif`` , respectively. <*data type*> equals ``'mne`` ' for expected - current data and ``'spm`` ' for dSPM data. - For raw data, ``_raw.fif`` is employed instead of ``.fif`` . - The output files are stored in the same directory as the label files. - -``--labelselout`` - - Produces additional label files for each label processed, containing only - those vertices within the input label which correspond to available - source space vertices in the inverse operator. These files have the - same name as the original label except that ``-lh`` and ``-rh`` are replaced - by ``-sel-lh`` and ``-sel-rh`` , respectively. - -``--align_z`` - - Instructs the program to try to align the waveform signs within - the label. For more information, see :ref:`c_legacy_implementation_details`. This - flag will not have any effect if the inverse operator has been computed - with the strict orientation constraint active. - -``--labeldir <*directory*>`` - - All previous ``--label`` options will be ignored when this - option is encountered. For each label in the directory, the output - file defined with the ``--out`` option will contain a summarizing - waveform which is the average of the waveforms in the vertices of - the label. The ``--labeldir`` option implies ``--align_z`` and ``--picknormalcomp`` options. - -``--orignames`` - - This option is used with the ``--labeldir`` option, above. - With this option, the output file channel names will be the names - of the label files, truncated to 15 characters, instead of names - containing the vertex numbers. - -``--out <*name*>`` - - Required with ``--labeldir`` . This is the output file for - the data. - -``--extra <*name*>`` - - By default, the output includes the current estimate signals and - the digital trigger channel, see ``--digtrig`` option, - below. With the ``--extra`` option, a custom set of additional - channels can be included. The extra channel text file should contain - the names of these channels, one channel name on each line. With - this option present, the digital trigger channel is not included - unless specified in the extra channel file. - -``--noextra`` - - No additional channels will be included with this option present. - -``--digtrig <*name*>`` - - Name of the composite digital trigger channel. The default value - is 'STI 014'. Underscores in the channel name - will be replaced by spaces. - -``--split <*size/MB*>`` - - Specifies the maximum size of the raw data files saved. By default, the - output is split into files which are just below 2 GB so that the - fif file maximum size is not exceed. - -.. note:: The digital trigger channel can also be set with the MNE_TRIGGER_CH_NAME environment variable. Underscores in the variable value will *not* be replaced with spaces by mne_compute_raw_inverse . Using the ``--digtrig`` option supersedes the MNE_TRIGGER_CH_NAME environment variable. - - -.. _mne_convert_mne_data: - -mne_convert_mne_data -==================== - -This utility allows the conversion of various fif files related to the MNE -computations to other formats. The two principal purposes of this utility are -to facilitate development of new analysis approaches with Matlab -and conversion of the forward model and noise covariance matrix -data into evoked-response type fif files, which can be accessed -and displayed with the Neuromag source modelling software. - -.. note:: Most of the functions of mne_convert_mne_data are now covered by the MNE Matlab toolbox covered in :ref:`ch_matlab`. This toolbox is recommended to avoid creating additional files occupying disk space. - -The command-line options recognized by mne_convert_mne_data are: - -``--fwd <*name*>`` - - Specity the name of the forward solution file to be converted. Channels - specified with the ``--bad`` option will be excluded from - the file. - -``--fixed`` - - Convert the forward solution to the fixed-orientation mode before outputting - the converted file. With this option only the field patterns corresponding - to a dipole aligned with the estimated cortex surface normal are - output. - -``--surfsrc`` - - When outputting a free-orientation forward model (three orthogonal dipole - components present) rotate the dipole coordinate system at each - source node so that the two tangential dipole components are output - first, followed by the field corresponding to the dipole aligned - with the estimated cortex surface normal. The orientation of the - first two dipole components in the tangential plane is arbitrarily selected - to create an orthogonal coordinate system. - -``--noiseonly`` - - When creating a 'measurement' fif file, do not - output a forward model file, just the noise-covariance matrix. - -``--senscov <*name*>`` - - Specifies the fif file containing a sensor covariance matrix to - be included with the output. If no other input files are specified - only the covariance matrix is output - -``--srccov <*name*>`` - - Specifies the fif file containing the source covariance matrix to - be included with the output. Only diagonal source covariance files - can be handled at the moment. - -``--bad <*name*>`` - - Specifies the name of the file containing the names of the channels to - be omitted, one channel name per line. This does not affect the output - of the inverse operator since the channels have been already selected - when the file was created. - -``--fif`` - - Output the forward model and the noise-covariance matrix into 'measurement' fif - files. The forward model files are tagged with <*modalities*> ``-meas-fwd.fif`` and - the noise-covariance matrix files with <*modalities*> ``-meas-cov.fif`` . - Here, modalities is ``-meg`` if MEG is included, ``-eeg`` if - EEG is included, and ``-meg-eeg`` if both types of signals - are present. The inclusion of modalities is controlled by the ``--meg`` and ``--eeg`` options. - -``--mat`` - - Output the data into MATLAB mat files. This is the default. The - forward model files are tagged with <*modalities*> ``-fwd.mat`` forward model - and noise-covariance matrix output, with ``-inv.mat`` for inverse - operator output, and with ``-inv-meas.mat`` for combined inverse - operator and measurement data output, respectively. The meaning - of <*modalities*> is the same - as in the fif output, described above. - -``--tag <*name*>`` - - By default, all variables in the matlab output files start with - ``mne\_``. This option allows to change this prefix to <*name*> _. - -``--meg`` - - Include MEG channels from the forward solution and noise-covariance - matrix. - -``--eeg`` - - Include EEG channels from the forward solution and noise-covariance - matrix. - -``--inv <*name*>`` - - Output the inverse operator data from the specified file into a - mat file. The source and noise covariance matrices as well as active channels - have been previously selected when the inverse operator was created - with mne_inverse_operator . Thus - the options ``--meg`` , ``--eeg`` , ``--senscov`` , ``--srccov`` , ``--noiseonly`` , - and ``--bad`` do not affect the output of the inverse operator. - -``--meas <*name*>`` - - Specifies the file containing measurement data to be output together with - the inverse operator. The channels corresponding to the inverse operator - are automatically selected from the file if ``--inv`` . - option is present. Otherwise, the channel selection given with ``--sel`` option will - be taken into account. - -``--set <*number*>`` - - Select the data set to be output from the measurement file. - -``--bmin <*value/ms*>`` - - Specifies the baseline minimum value setting for the measurement signal - output. - -``--bmax <*value/ms*>`` - - Specifies the baseline maximum value setting for the measurement signal - output. - -.. note:: The ``--tmin`` and ``--tmax`` options which existed in previous versions of mne_converted_mne_data have been removed. If output of measurement data is requested, the entire averaged epoch is now included. - -Guide to combining options --------------------------- - -The combination of options is quite complicated. The :ref:`BEHDCIII` should be -helpful to determine the combination of options appropriate for your needs. - - -.. tabularcolumns:: |p{0.38\linewidth}|p{0.1\linewidth}|p{0.2\linewidth}|p{0.3\linewidth}| -.. _BEHDCIII: -.. table:: Guide to combining mne_convert_mne_data options. - - +-------------------------------------+---------+--------------------------+-----------------------+ - | Desired output | Format | Required options | Optional options | - +-------------------------------------+---------+--------------------------+-----------------------+ - | forward model | fif | \---fwd <*name*> | \---bad <*name*> | - | | | \---out <*name*> | \---surfsrc | - | | | \---meg and/or \---eeg | | - | | | \---fif | | - +-------------------------------------+---------+--------------------------+-----------------------+ - | forward model | mat | \---fwd <*name*> | \---bad <*name*> | - | | | \---out <*name*> | \---surfsrc | - | | | \---meg and/or --eeg | | - +-------------------------------------+---------+--------------------------+-----------------------+ - | forward model and sensor covariance | mat | \---fwd <*name*> | \---bad <*name*> | - | | | \---out <*name*> | \---surfsrc | - | | | \---senscov <*name*> | | - | | | \---meg and/or --eeg | | - +-------------------------------------+---------+--------------------------+-----------------------+ - | sensor covariance | fif | \---fwd <*name*> | \---bad <*name*> | - | | | \---out <*name*> | | - | | | \---senscov <*name*> | | - | | | \---noiseonly | | - | | | \---fif | | - | | | \---meg and/or --eeg | | - +-------------------------------------+---------+--------------------------+-----------------------+ - | sensor covariance | mat | \---senscov <*name*> | \---bad <*name*> | - | | | \---out <*name*> | | - +-------------------------------------+---------+--------------------------+-----------------------+ - | sensor covariance eigenvalues | text | \---senscov <*name*> | \---bad <*name*> | - | | | \---out <*name*> | | - | | | \---eig | | - +-------------------------------------+---------+--------------------------+-----------------------+ - | evoked MEG/EEG data | mat | \---meas <*name*> | \---sel <*name*> | - | | | \---out <*name*> | \---set <*number*> | - +-------------------------------------+---------+--------------------------+-----------------------+ - | evoked MEG/EEG data forward model | mat | \---meas <*name*> | \---bad <*name*> | - | | | \---fwd <*name*> | \---set <*number*> | - | | | \---out <*name*> | | - +-------------------------------------+---------+--------------------------+-----------------------+ - | inverse operator data | mat | \---inv <*name*> | | - | | | \---out <*name*> | | - +-------------------------------------+---------+--------------------------+-----------------------+ - | inverse operator data evoked | mat | \–--inv <*name*> | | - | MEG/EEG data | | \–--meas <*name*> | | - | | | \–--out <*name*> | | - +-------------------------------------+---------+--------------------------+-----------------------+ - -Matlab data structures ----------------------- - -The Matlab output provided by mne_convert_mne_data is -organized in structures, listed in :ref:`BEHCICCA`. The fields -occurring in these structures are listed in :ref:`BABCBIGF`. - - -The symbols employed in variable size descriptions are: - -``nloc`` - - Number - of source locations - -``nsource`` - - Number - of sources. For fixed orientation sources nsource = nloc whereas nsource = 3*nloc for - free orientation sources - -``nchan`` - - Number - of measurement channels. - -``ntime`` - - Number - of time points in the measurement data. - -.. _BEHCICCA: -.. table:: Matlab structures produced by mne_convert_mne_data. - - =============== ======================================= - Structure Contents - =============== ======================================= - <*tag*> _meas Measured data - <*tag*> _inv The inverse operator decomposition - <*tag*> _fwd The forward solution - <*tag*> _noise A standalone noise-covariance matrix - =============== ======================================= - -The prefix given with the ``--tag`` option is indicated <*tag*> , see :ref:`mne_convert_mne_data`. Its default value is MNE. - - -.. tabularcolumns:: |p{0.14\linewidth}|p{0.13\linewidth}|p{0.73\linewidth}| -.. _BABCBIGF: -.. table:: The fields of Matlab structures. - - - +-----------------------+-----------------+------------------------------------------------------------+ - | Variable | Size | Description | - +-----------------------+-----------------+------------------------------------------------------------+ - | fwd | nsource x nchan | The forward solution, one source on each row. For free | - | | | orientation sources, the fields of the three orthogonal | - | | | dipoles for each location are listed consecutively. | - +-----------------------+-----------------+------------------------------------------------------------+ - | names ch_names | nchan (string) | String array containing the names of the channels included | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_types | nchan x 2 | The column lists the types of the channels (1 = MEG, | - | | | 2 = EEG). The second column lists the coil types, see | - | | | :ref:`c_legacy_BGBBHGEC` and :ref:`c_legacy_CHDBDFJE`. | - | | | For EEG electrodes, this value equals one. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_pos | nchan x 3 | The location information for each channel. The first three | - | | | values specify the origin of the sensor coordinate system | - | | | or the location of the electrode. For MEG channels, the | - | | | following nine number specify the *x*, *y*, and | - | | | *z*-direction unit vectors of the sensor coordinate system.| - | | | For EEG electrodes the first unit vector specifies the | - | | | location of the reference electrode. If the reference is | - | | | not specified this value is all zeroes. The remaining unit | - | | | vectors are irrelevant for EEG electrodes. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_lognos | nchan x 1 | Logical channel numbers as listed in the fiff file | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_units | nchan x 2 | Units and unit multipliers as listed in the fif file. The | - | | | unit of the data is listed in the first column (T = 112, | - | | | T/m = 201, V = 107). At present, the second column will be | - | | | always zero, *i.e.*, no unit multiplier. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_cals | nchan x 2 | Even if the data comes from the conversion already | - | | | calibrated, the original calibration factors are included. | - | | | The first column is the range member of the fif data | - | | | structures and while the second is the cal member. To get | - | | | calibrated values in the units given in ch_units from the | - | | | raw data, the data must be multiplied with the product of | - | | | range and cal. | - +-----------------------+-----------------+------------------------------------------------------------+ - | sfreq | 1 | The sampling frequency in Hz. | - +-----------------------+-----------------+------------------------------------------------------------+ - | lowpass | 1 | Lowpass filter frequency (Hz) | - +-----------------------+-----------------+------------------------------------------------------------+ - | highpass | 1 | Highpass filter frequency (Hz) | - +-----------------------+-----------------+------------------------------------------------------------+ - | source_loc | nloc x 3 | The source locations given in the coordinate frame | - | | | indicated by the coord_frame member. | - +-----------------------+-----------------+------------------------------------------------------------+ - | source_ori | nsource x 3 | The source orientations | - +-----------------------+-----------------+------------------------------------------------------------+ - | source_selection | nsource x 2 | Indication of the sources selected from the complete source| - | | | spaces. Each row contains the number of the source in the | - | | | complete source space (starting with 0) and the source | - | | | space number (1 or 2). These numbers refer to the order the| - | | | two hemispheres where listed when mne_make_source_space was| - | | | invoked. mne_setup_source_space lists the left hemisphere | - | | | first. | - +-----------------------+-----------------+------------------------------------------------------------+ - | coord_frame | string | Name of the coordinate frame employed in the forward | - | | | calculations. Possible values are 'head' and 'mri'. | - +-----------------------+-----------------+------------------------------------------------------------+ - | mri_head_trans | 4 x 4 | The coordinate frame transformation from mri the MEG 'head'| - | | | coordinates. | - +-----------------------+-----------------+------------------------------------------------------------+ - | meg_head_trans | 4 x 4 | The coordinate frame transformation from the MEG device | - | | | coordinates to the MEG head coordinates | - +-----------------------+-----------------+------------------------------------------------------------+ - | noise_cov | nchan x nchan | The noise covariance matrix | - +-----------------------+-----------------+------------------------------------------------------------+ - | source_cov | nsource | The elements of the diagonal source covariance matrix. | - +-----------------------+-----------------+------------------------------------------------------------+ - | sing | nchan | The singular values of | - | | | :math:`A = C_0^{-^1/_2} G R^C = U \Lambda V^T` | - | | | with :math:`R` selected so that | - | | | :math:`\text{trace}(AA^T) / \text{trace}(I) = 1` | - | | | as discussed in :ref:`c_legacy_CHDDHAGE` | - +-----------------------+-----------------+------------------------------------------------------------+ - | eigen_fields | nchan x nchan | The rows of this matrix are the left singular vectors of | - | | | :math:`A`, i.e., the columns of :math:`U`, see above. | - +-----------------------+-----------------+------------------------------------------------------------+ - | eigen_leads | nchan x nsource | The rows of this matrix are the right singular vectors of | - | | | :math:`A`, i.e., the columns of :math:`V`, see above. | - +-----------------------+-----------------+------------------------------------------------------------+ - | noise_eigenval | nchan | In terms of :ref:`c_legacy_CHDDHAGE`, eigenvalues of | - | | | :math:`C_0`, i.e., not scaled with number of averages. | - +-----------------------+-----------------+------------------------------------------------------------+ - | noise_eigenvec | nchan | Eigenvectors of the noise covariance matrix. In terms of | - | | | :ref:`c_legacy_CHDDHAGE`, :math:`U_C^T`. | - +-----------------------+-----------------+------------------------------------------------------------+ - | data | nchan x ntime | The measured data. One row contains the data at one time | - | | | point. | - +-----------------------+-----------------+------------------------------------------------------------+ - | times | ntime | The time points in the above matrix in seconds | - +-----------------------+-----------------+------------------------------------------------------------+ - | nave | 1 | Number of averages as listed in the data file. | - +-----------------------+-----------------+------------------------------------------------------------+ - | meas_times | ntime | The time points in seconds. | - +-----------------------+-----------------+------------------------------------------------------------+ - -.. note:: The Matlab files can also be read in Python using :py:func:`scipy.io.loadmat` - - -.. _mne_do_forward_solution: - -mne_do_forward_solution -======================= - -This utility accepts the following options: - -``--subject <*subject*>`` - - Defines the name of the subject. This can be also accomplished - by setting the SUBJECT environment variable. - -``--src <*name*>`` - - Source space name to use. This option overrides the ``--spacing`` option. The - source space is searched first from the current working directory - and then from ``$SUBJECTS_DIR/`` <*subject*> /bem. - The source space file must be specified exactly, including the ``fif`` extension. - -``--spacing <*spacing/mm*> or ``ico-`` <*number or ``oct-`` <*number*>`` - - This is an alternate way to specify the name of the source space - file. For example, if ``--spacing 6`` is given on the command - line, the source space files searched for are./<*subject*> -6-src.fif - and ``$SUBJECTS_DIR/$SUBJECT/`` bem/<*subject*> -6-src.fif. - The first file found is used. Spacing defaults to 7 mm. - -``--bem <*name*>`` - - Specifies the BEM to be used. The name of the file can be any of <*name*> , <*name*> -bem.fif, <*name*> -bem-sol.fif. - The file is searched for from the current working directory and - from ``bem`` . If this option is omitted, the most recent - BEM file in the ``bem`` directory is used. - -``--mri <*name*>`` - - The name of the MRI description file containing the MEG/MRI coordinate - transformation. This file was saved as part of the alignment procedure - outlined in :ref:`CHDBEHDC`. The file is searched for from - the current working directory and from ``mri/T1-neuromag/sets`` . - The search order for MEG/MRI coordinate transformations is discussed - below. - -``--trans <*name*>`` - - The name of a text file containing the 4 x 4 matrix for the coordinate transformation - from head to mri coordinates, see below. If the option ``--trans`` is - present, the ``--mri`` option is not required. The search - order for MEG/MRI coordinate transformations is discussed below. - -``--meas <*name*>`` - - This file is the measurement fif file or an off-line average file - produced thereof. It is recommended that the average file is employed for - evoked-response data and the original raw data file otherwise. This - file provides the MEG sensor locations and orientations as well as - EEG electrode locations as well as the coordinate transformation between - the MEG device coordinates and MEG head-based coordinates. - -``--fwd <*name*>`` - - This file will contain the forward solution as well as the coordinate transformations, - sensor and electrode location information, and the source space - data. A name of the form <*name*> ``-fwd.fif`` is - recommended. If this option is omitted the forward solution file - name is automatically created from the measurement file name and - the source space name. - -``--destdir <*directory*>`` - - Optionally specifies a directory where the forward solution will - be stored. - -``--mindist <*dist/mm*>`` - - Omit source space points closer than this value to the inner skull surface. - Any source space points outside the inner skull surface are automatically - omitted. The use of this option ensures that numerical inaccuracies - for very superficial sources do not cause unexpected effects in - the final current estimates. Suitable value for this parameter is - of the order of the size of the triangles on the inner skull surface. - If you employ the seglab software - to create the triangulations, this value should be about equal to - the wish for the side length of the triangles. - -``--megonly`` - - Omit EEG forward calculations. - -``--eegonly`` - - Omit MEG forward calculations. - -``--all`` - - Compute the forward solution for all vertices on the source space. - -``--overwrite`` - - Overwrite the possibly existing forward model file. - -``--help`` - - Show usage information for the script. - -The MEG/MRI transformation is determined by the following -search sequence: - -- If the ``--mri`` option was - present, the file is looked for literally as specified, in the directory - of the measurement file specified with the ``--meas`` option, - and in the directory $SUBJECTS_DIR/$SUBJECT/mri/T1-neuromag/sets. - If the file is not found, the script exits with an error message. - -- If the ``--trans`` option was present, the file is - looked up literally as specified. If the file is not found, the - script exists with an error message. - -- If neither ``--mri`` nor ``--trans`` option - was not present, the following default search sequence is engaged: - - - The ``.fif`` ending in the - measurement file name is replaced by ``-trans.fif`` . If - this file is present, it will be used. - - - The newest file whose name ends with ``-trans.fif`` in - the directory of the measurement file is looked up. If such a file - is present, it will be used. - - - The newest file whose name starts with ``COR-`` in - directory $SUBJECTS_DIR/$SUBJECT/mri/T1-neuromag/sets is looked - up. If such a file is present, it will be used. - - - If all the above searches fail, the script exits with an error - message. - -This search sequence is designed to work well with the MEG/MRI -transformation files output by mne_analyze , -see :ref:`CACEHGCD`. It is recommended that -trans.fif file -saved with the Save default and Save... options in -the mne_analyze alignment dialog -are used because then the $SUBJECTS_DIR/$SUBJECT directory will -be composed of files which are dependent on the subjects's -anatomy only, not on the MEG/EEG data to be analyzed. - -.. note:: If the standard MRI description file and BEM file selections are appropriate and the 7-mm source space grid spacing is appropriate, only the ``--meas`` option is necessary. If EEG data is not used ``--megonly`` option should be included. - -.. note:: If it is conceivable that the current-density transformation will be incorporated into the inverse operator, specify a source space with patch information for the forward computation. This is not mandatory but saves a lot of time when the inverse operator is created, since the patch information does not need to be created at that stage. - -.. note:: The MEG head to MRI transformation matrix specified with the ``--trans`` option should be a text file containing a 4-by-4 matrix: - -.. math:: T = \begin{bmatrix} - R_{11} & R_{12} & R_{13} & x_0 \\ - R_{13} & R_{13} & R_{13} & y_0 \\ - R_{13} & R_{13} & R_{13} & z_0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} - -defined so that if the augmented location vectors in MRI -head and MRI coordinate systems are denoted by :math:`r_{head}[x_{head}\ y_{head}\ z_{head}\ 1]` and :math:`r_{MRI}[x_{MRI}\ y_{MRI}\ z_{MRI}\ 1]`, -respectively, - -.. math:: r_{MRI} = T r_{head} - -.. note:: It is not possible to calculate an EEG forward solution with a single-layer BEM. - - -.. _mne_do_inverse_operator: - -mne_do_inverse_operator -======================= - -``--fwd <*name of the forward solution file*>`` - - This is the forward solution file produced in the computations step described - in :ref:`BABCHEJD`. - -``--meg`` - - Employ MEG data in the inverse calculation. If neither ``--meg`` nor ``--eeg`` is - set only MEG channels are included. - -``--eeg`` - - Employ EEG data in the inverse calculation. If neither ``--meg`` nor ``--eeg`` is - set only MEG channels are included. - -``--fixed`` - - Use fixed source orientations normal to the cortical mantle. By default, - the source orientations are not constrained. If ``--fixed`` is specified, - the ``--loose`` flag is ignored. - -``--loose <*amount*>`` - - Use a 'loose' orientation constraint. This means - that the source covariance matrix entries corresponding to the current - component normal to the cortex are set equal to one and the transverse - components are set to <*amount*> . - Recommended value of amount is 0.1...0.6. - -``--depth`` - - Employ depth weighting with the standard settings. For details, - see :ref:`c_legacy_depth_weighting` and :ref:`c_legacy_inverse_operator`. - -``--bad <*name*>`` - - Specifies a text file to designate bad channels, listed one channel name - (like MEG 1933) on each line of the file. Be sure to include both - noisy and flat (non-functioning) channels in the list. If bad channels - were designated using mne_mark_bad_channels in - the measurement file which was specified with the ``--meas`` option when - the forward solution was computed, the bad channel information will - be automatically included. Also, any bad channel information in - the noise-covariance matrix file will be included. - -``--noisecov <*name*>`` - - Name of the noise-covariance matrix file computed with one of the methods - described in :ref:`BABDEEEB`. By default, the script looks - for a file whose name is derived from the forward solution file - by replacing its ending ``-`` <*anything*> ``-fwd.fif`` by ``-cov.fif`` . - If this file contains a projection operator, which will automatically - attached to the noise-covariance matrix by mne_browse_raw and mne_process_raw , - no ``--proj`` option is necessary because mne_inverse_operator will - automatically include the projectors from the noise-covariance matrix - file. For backward compatibility, --senscov can be used as a synonym - for --noisecov. - -``--noiserank <*value*>`` - - Specifies the rank of the noise covariance matrix explicitly rather than - trying to reduce it automatically. This option is sheldom needed, - -``--megreg <*value*>`` - - Regularize the MEG part of the noise-covariance matrix by this amount. - Suitable values are in the range 0.05...0.2. For details, see :ref:`c_legacy_cov_regularization`. - -``--eegreg <*value*>`` - - Like ``--megreg`` but applies to the EEG channels. - -``--diagnoise`` - - Omit the off-diagonal terms of the noise covariance matrix. This option - is irrelevant to most users. - -``--fmri <*name*>`` - - With help of this w file, an *a priori* weighting - can be applied to the source covariance matrix. The source of the weighting - is usually fMRI but may be also some other data, provided that the weighting can - be expressed as a scalar value on the cortical surface, stored in - a w file. It is recommended that this w file is appropriately smoothed (see :ref:`CHDEBAHH`) - in mne_analyze , tksurfer or - with mne_smooth_w to contain - nonzero values at all vertices of the triangular tessellation of - the cortical surface. The name of the file given is used as a stem of - the w files. The actual files should be called <*name*> ``-lh.pri`` and <*name*> ``-rh.pri`` for - the left and right hemisphere weight files, respectively. The application - of the weighting is discussed in :ref:`c_legacy_mne_fmri_estimates`. - -``--fmrithresh <*value*>`` - - This option is mandatory and has an effect only if a weighting function - has been specified with the ``--fmri`` option. If the value - is in the *a priori* files falls below this value - at a particular source space point, the source covariance matrix - values are multiplied by the value specified with the ``--fmrioff`` option - (default 0.1). Otherwise it is left unchanged. - -``--fmrioff <*value*>`` - - The value by which the source covariance elements are multiplied - if the *a priori* weight falls below the threshold - set with ``--fmrithresh`` , see above. - -``--srccov <*name*>`` - - Use this diagonal source covariance matrix. By default the source covariance - matrix is a multiple of the identity matrix. This option is irrelevant - to most users. - -``--proj <*name*>`` - - Include signal-space projection information from this file. - -``--inv <*name*>`` - - Save the inverse operator decomposition here. By default, the script looks - for a file whose name is derived from the forward solution file by - replacing its ending ``-fwd.fif`` by <*options*> ``-inv.fif`` , where - <*options*> includes options ``--meg``, ``--eeg``, and ``--fixed`` with the double - dashes replaced by single ones. - -``--destdir <*directory*>`` - - Optionally specifies a directory where the inverse operator will - be stored. - -.. note:: If bad channels are included in the calculation, strange results may ensue. Therefore, it is recommended that the data to be analyzed is carefully inspected with to assign the bad channels correctly. - -.. note:: For convenience, the MNE software includes bad-channel designation files which can be used to ignore all magnetometer or all gradiometer channels in Vectorview measurements. These files are called ``vv_grad_only.bad`` and ``vv_mag_only.bad`` , respectively. Both files are located in ``$MNE_ROOT/share/mne/templates`` . - - -.. _mne_forward_solution: - -mne_forward_solution -==================== - -``--src <*name*>`` - - Source space name to use. The name of the file must be specified exactly, - including the directory. Typically, the source space files reside - in $SUBJECTS_DIR/$SUBJECT/bem. - -``--bem <*name*>`` - - Specifies the BEM to be used. These files end with bem.fif or bem-sol.fif and - reside in $SUBJECTS_DIR/$SUBJECT/bem. The former file contains only - the BEM surface information while the latter files contain the geometry - information precomputed with :ref:`mne_prepare_bem_model`, - see :ref:`c_legacy_CHDJFHEB`. If precomputed geometry is not available, - the linear collocation solution will be computed by mne_forward_solution . - -``--origin <*x/mm*> : <*x/mm*> : <*z/mm*>`` - - Indicates that the sphere model should be used in the forward calculations. - The origin is specified in MEG head coordinates unless the ``--mricoord`` option - is present. The MEG sphere model solution computed using the analytical - Sarvas formula. For EEG, an approximative solution described in - -``--eegmodels <*name*>`` - - This option is significant only if the sphere model is used and - EEG channels are present. The specified file contains specifications - of the EEG sphere model layer structures as detailed in :ref:`c_legacy_CHDIAFIG`. If this option is absent the file ``$HOME/.mne/EEG_models`` will - be consulted if it exists. - -``--eegmodel <*model name*>`` - - Specifies the name of the sphere model to be used for EEG. If this option - is missing, the model Default will - be employed, see :ref:`c_legacy_CHDIAFIG`. - -``--eegrad <*radius/mm*>`` - - Specifies the radius of the outermost surface (scalp) of the EEG sphere - model, see :ref:`c_legacy_CHDIAFIG`. The default value is 90 mm. - -``--eegscalp`` - - Scale the EEG electrode locations to the surface of the outermost sphere - when using the sphere model. - -``--accurate`` - - Use accurate MEG sensor coil descriptions. This is the recommended - choice. More information - -``--fixed`` - - Compute the solution for sources normal to the cortical mantle only. This - option should be used only for surface-based and discrete source - spaces. - -``--all`` - - Compute the forward solution for all vertices on the source space. - -``--label <*name*>`` - - Compute the solution only for points within the specified label. Multiple - labels can be present. The label files should end with ``-lh.label`` or ``-rh.label`` for - left and right hemisphere label files, respectively. If ``--all`` flag - is present, all surface points falling within the labels are included. - Otherwise, only decimated points with in the label are selected. - -``--mindist <*dist/mm*>`` - - Omit source space points closer than this value to the inner skull surface. - Any source space points outside the inner skull surface are automatically - omitted. The use of this option ensures that numerical inaccuracies - for very superficial sources do not cause unexpected effects in - the final current estimates. Suitable value for this parameter is - of the order of the size of the triangles on the inner skull surface. - If you employ the seglab software to create the triangulations, this - value should be about equal to the wish for the side length of the - triangles. - -``--mindistout <*name*>`` - - Specifies a file name to contain the coordinates of source space points - omitted due to the ``--mindist`` option. - -``--mri <*name*>`` - - The name of the MRI description file containing the MEG/MRI coordinate - transformation. This file was saved as part of the alignment procedure - outlined in :ref:`CHDBEHDC`. These files typically reside in ``$SUBJECTS_DIR/$SUBJECT/mri/T1-neuromag/sets`` . - -``--trans <*name*>`` - - The name of a text file containing the 4 x 4 matrix for the coordinate transformation - from head to mri coordinates. With ``--trans``, ``--mri`` option is not - required. - -``--notrans`` - - The MEG/MRI coordinate transformation is taken as the identity transformation, *i.e.*, - the two coordinate systems are the same. This option is useful only - in special circumstances. If more than one of the ``--mri`` , ``--trans`` , - and ``--notrans`` options are specified, the last one remains - in effect. - -``--mricoord`` - - Do all computations in the MRI coordinate system. The forward solution - matrix is not affected by this option if the source orientations - are fixed to be normal to the cortical mantle. If all three source components - are included, the forward three source orientations parallel to - the coordinate axes is computed. If ``--mricoord`` is present, these - axes correspond to MRI coordinate system rather than the default - MEG head coordinate system. This option is useful only in special - circumstances. - -``--meas <*name*>`` - - This file is the measurement fif file or an off-line average file - produced thereof. It is recommended that the average file is employed for - evoked-response data and the original raw data file otherwise. This - file provides the MEG sensor locations and orientations as well as - EEG electrode locations as well as the coordinate transformation between - the MEG device coordinates and MEG head-based coordinates. - -``--fwd <*name*>`` - - This file will contain the forward solution as well as the coordinate transformations, - sensor and electrode location information, and the source space - data. A name of the form <*name*>-fwd.fif is - recommended. - -``--meg`` - - Compute the MEG forward solution. - -``--eeg`` - - Compute the EEG forward solution. - -``--grad`` - - Include the derivatives of the fields with respect to the dipole - position coordinates to the output, see :ref:`c_legacy_BJEFEJJG`. - - -.. _mne_inverse_operator: - -mne_inverse_operator -==================== - -``--meg`` - - Employ MEG data in the calculation of the estimates. - -``--eeg`` - - Employ EEG data in the calculation of the estimates. Note: The EEG - computations have not been thoroughly tested at this time. - -``--fixed`` - - Use fixed source orientations normal to the cortical mantle. By default, - the source orientations are not constrained. - -``--loose `` - - Employ a loose orientation constraint (LOC). This means that the source - covariance matrix entries corresponding to the current component - normal to the cortex are set equal to one and the transverse components - are set to <*amount*> . Recommended - value of amount is 0.2...0.6. - -``--loosevar `` - - Use an adaptive loose orientation constraint. This option can be - only employed if the source spaces included in the forward solution - have the patch information computed, see :ref:`setting_up_source_space`. - -``--fwd `` - - Specifies the name of the forward solution to use. - -``--noisecov `` - - Specifies the name of the noise-covariance matrix to use. If this - file contains a projection operator, attached by :ref:`mne_browse_raw` and :ref:`mne_process_raw`, - no additional projection vectors can be added with the ``--proj`` option. For - backward compatibility, ``--senscov`` can be used as a synonym for ``--noisecov``. - -``--noiserank `` - - Specifies the rank of the noise covariance matrix explicitly rather than - trying to reduce it automatically. This option is seldom needed, - -``--gradreg `` - - Regularize the planar gradiometer section (channels for which the unit - of measurement is T/m) of the noise-covariance matrix by the given - amount. The value is restricted to the range 0...1. For details, see :ref:`c_legacy_cov_regularization`. - -``--magreg `` - - Regularize the magnetometer and axial gradiometer section (channels - for which the unit of measurement is T) of the noise-covariance matrix - by the given amount. The value is restricted to the range 0...1. - For details, see :ref:`c_legacy_cov_regularization`. - -``--eegreg `` - - Regularize the EEG section of the noise-covariance matrix by the given - amount. The value is restricted to the range 0...1. For details, see :ref:`c_legacy_cov_regularization`. - -``--diagnoise`` - - Omit the off-diagonal terms from the noise-covariance matrix in - the computations. This may be useful if the amount of signal-free - data has been insufficient to calculate a reliable estimate of the - full noise-covariance matrix. - -``--srccov `` - - Specifies the name of the diagonal source-covariance matrix to use. - By default the source covariance matrix is a multiple of the identity matrix. - This option can be employed to incorporate the fMRI constraint. - The software to create a source-covariance matrix file from fMRI - data will be provided in a future release of this software package. - -``--depth`` - - Employ depth weighting. For details, see :ref:`c_legacy_depth_weighting`. - -``--weightexp `` - - This parameter determines the steepness of the depth weighting function - (default = 0.8). For details, see :ref:`c_legacy_depth_weighting`. - -``--weightlimit `` - - Maximum relative strength of the depth weighting (default = 10). For - details, see :ref:`c_legacy_depth_weighting`. - -``--fmri `` - - With help of this w file, an *a priori* weighting - can be applied to the source covariance matrix. The source of the - weighting is usually fMRI but may be also some other data, provided - that the weighting can be expressed as a scalar value on the cortical - surface, stored in a w file. It is recommended that this w file - is appropriately smoothed (see :ref:`CHDEBAHH`) in mne_analyze , tksurfer or - with mne_smooth_w to contain - nonzero values at all vertices of the triangular tessellation of - the cortical surface. The name of the file given is used as a stem of - the w files. The actual files should be called <*name*> ``-lh.pri`` and <*name*> ``-rh.pri`` for - the left and right hemsphere weight files, respectively. The application - of the weighting is discussed in :ref:`c_legacy_mne_fmri_estimates`. - -``--fmrithresh `` - - This option is mandatory and has an effect only if a weighting function - has been specified with the ``--fmri`` option. If the value - is in the *a priori* files falls below this value - at a particular source space point, the source covariance matrix - values are multiplied by the value specified with the ``--fmrioff`` option - (default 0.1). Otherwise it is left unchanged. - -``--fmrioff `` - - The value by which the source covariance elements are multiplied - if the *a priori* weight falls below the threshold - set with ``--fmrithresh`` , see above. - -``--bad `` - - A text file to designate bad channels, listed one channel name on each - line of the file. If the noise-covariance matrix specified with the ``--noisecov`` option - contains projections, bad channel lists can be included only if - they specify all channels containing non-zero entries in a projection - vector. For example, bad channels can usually specify all magnetometers - or all gradiometers since the projection vectors for these channel - types are completely separate. Similarly, it is possible to include - MEG data only or EEG data only by using only one of ``--meg`` or ``--eeg`` options - since the projection vectors for MEG and EEG are always separate. - -``--surfsrc`` - - Use a source coordinate system based on the local surface orientation - at the source location. By default, the three dipole components are - pointing to the directions of the x, y, and z axis of the coordinate system - employed in the forward calculation (usually the MEG head coordinate - frame). This option changes the orientation so that the first two - source components lie in the plane normal to the surface normal - at the source location and the third component is aligned with it. - If patch information is available in the source space, the normal - is the average patch normal, otherwise the vertex normal at the source - location is used. If the ``--loose`` or ``--loosevar`` option - is employed, ``--surfsrc`` is implied. - -``--exclude `` - - Exclude the source space points defined by the given FreeSurfer 'label' file - from the source reconstruction. This is accomplished by setting - the corresponding entries in the source-covariance matrix equal - to zero. The name of the file should end with ``-lh.label`` - if it refers to the left hemisphere and with ``-rh.label`` if - it lists points in the right hemisphere, respectively. - -``--proj `` - - Include signal-space projection (SSP) information from this file. For information - on SSP, see :ref:`CACCHABI`. If the projections are present in - the noise-covariance matrix, the ``--proj`` option is - not allowed. - -``--csd`` - - Compute the inverse operator for surface current densities instead - of the dipole source amplitudes. This requires the computation of patch - statistics for the source space. Since this computation is time consuming, - it is recommended that the patch statistics are precomputed and - the source space file containing the patch information is employed - already when the forward solution is computed, see :ref:`setting_up_source_space` and :ref:`BABCHEJD`. - For technical details of the patch information, please consult :ref:`c_legacy_patch_stats`. This option is considered experimental at - the moment. - -``--inv `` - - Save the inverse operator decomposition here. - - -.. _mne_make_movie: - -mne_make_movie -============== - -Input files ------------ - -``--inv <*name*>`` - - Load the inverse operator decomposition from here. - -``--meas <*name*>`` - - Load the MEG or EEG data from this file. - -``--set <*number*>`` - - The data set (condition) number to load. This is the sequential - number of the condition. You can easily see the association by looking - at the condition list in mne_analyze when - you load the file. - -``--stcin <*name*>`` - - Specifies an stc file to read as input. - -Times and baseline ------------------- - -``--tmin <*time/ms*>`` - - Specifies the starting time employed in the analysis. If ``--tmin`` option - is missing the analysis starts from the beginning of the epoch. - -``--tmax <*time/ms*>`` - - Specifies the finishing time employed in the analysis. If ``--tmax`` option - is missing the analysis extends to the end of the epoch. - -``--tstep <*step/ms*>`` - - Time step between consecutive movie frames, specified in milliseconds. - -``--integ <*:math:`\Delta`t/ms*>`` - - Integration time for each frame. Defaults to zero. The integration will - be performed on sensor data. If the time specified for a frame is :math:`t_0`, - the integration range will be :math:`t_0 - \Delta t/2 \leq t \leq t_0 + \Delta t/2`. - -``--pick <*time/ms*>`` - - Pick a time for the production of rgb, tif, jpg, png, or w files. - Several pick options may be present. The time must be with in the - analysis interval, indicated by the ``--tmin`` and ``--tmax`` options. - The ``--rgb`` , ``--tif`` , ``--jpg`` , ``--png`` , and ``--w`` options - control which file types are actually produced. When a ``--pick`` option - is encountered, the effect of any preceding ``--pickrange`` option - is ignored. - -``--pickrange`` - - All previous ``-pick`` options will be ignored. Instead, - snapshots are produced as indicated by the ``--tmin`` , ``--tmax`` , - and ``--tstep`` options. This is useful, *e.g.*, - for producing input for scripts merging the individual graphics - snapshots into a composite "filmstrip" representation. - However, such scripts are not yet part of the MNE software. - -``--bmin <*time/ms*>`` - - Specifies the starting time of the baseline. In order to activate - baseline correction, both ``--bmin`` and ``--bmax`` options - must be present. - -``--bmax <*time/ms*>`` - - Specifies the finishing time of the baseline. - -``--baselines <*file_name*>`` - - Specifies a file which contains the baseline settings. Each line - of the file should contain a name of a channel, followed by the - baseline value, separated from the channel name by a colon. The - baseline values must be specified in basic units, i.e., Teslas/meter - for gradiometers, Teslas for magnetometers, and Volts for EEG channels. - If some channels are missing from the baseline file, warning messages are - issued: for these channels, the ``--bmin`` and ``--bmax`` settings will - be used. - -Options controlling the estimates ---------------------------------- - -``--nave <*value*>`` - - Specifies the effective number of averaged epochs in the input data, :math:`L_{eff}`, - as discussed in :ref:`c_legacy_CBBDGIAE`. If the input data file is - one produced by :ref:`mne_browse_raw` or :ref:`mne_process_raw`, the - number of averages is correct in the file. However, if subtractions - or some more complicated combinations of simple averages are produced, - e.g., by using the xplotter software, - the number of averages should be manually adjusted along the guidelines - given in :ref:`c_legacy_CBBDGIAE`. This is accomplished either by - employing this flag or by adjusting the number of averages in the - data file with help of the utility mne_change_nave . - -``--snr <*value*>`` - - An estimate for the amplitude SNR. The regularization parameter will - be set as :math:`\lambda^2 = 1/SNR^2`. The default value is - SNR = 3. Automatic selection of the regularization parameter is - currently not supported. - -``--spm`` - - Calculate the dSPM instead of the expected current value. - -``--sLORETA`` - - Calculate the noise-normalized estimate using the sLORETA approach. - sLORETA solutions have in general a smaller location bias than either - the expected current (MNE) or the dSPM. - -``--signed`` - - Indicate the current direction with respect to the cortex outer - normal by sign. Currents flowing out of the cortex are thus considered - positive (warm colors) and currents flowing into the cortex negative (cold - colors). - -``--picknormalcomp`` - - The components of the estimates corresponding to directions tangential - with the cortical mantle are zeroed out. - -.. _CBBBBHIF: - -Visualization options ---------------------- - -``--subject <*subject*>`` - - Specifies the subject whose MRI data is employed in the visualization. - This must be the same subject that was used for computing the current - estimates. The environment variable SUBJECTS_DIR must be set to - point to a locations where the subjects are to be found. - -``--morph <*subject*>`` - - Morph the data to to the cortical surface of another subject. The Quicktime - movie, stc-file, graphics snapshot, and w-file outputs are affected - by this option, *i.e.*, they will take the morphing - into account and will represent the data on the cortical surface - of the subject defined with this option. The stc files morphed to - a single subject's cortical surface are used by mne_average_estimates to - combine data from different subjects. - If morphing is selected appropriate smoothing must be specified - with the ``--smooth`` option. The morphing process can - be made faster by precomputing the necessary morphing maps with mne_make_morph_maps , - see :ref:`CHDBBHDH`. More information about morphing and averaging - can be found in :ref:`c_legacy_ch_morph`. - -``--morphgrade <*number*>`` - - Adjusts the number of vertices in the stc files produced when morphing - is in effect. By default the number of vertices is 10242 corresponding - to --morphgrade value 5. Allowed values are 3, 4, 5, and 6 corresponding - to 642, 2562, 10242, and 40962 vertices, respectively. - -``--surface <*surface name*>`` - - Name of the surface employed in the visualization. The default is inflated . - -``--curv <*name*>`` - - Specify a nonstandard curvature file name. The default curvature files - are ``lh.curv`` and ``rh.curv`` . With this option, - the names become ``lh.`` <*name*> and ``rh.`` <*name*> . - -``--patch <*name*> [: <*angle/deg*> ]`` - - Specify the name of a surface patch to be used for visualization instead - of the complete cortical surface. A complete name of a patch file - in the FreeSurface surf directory must be given. The name should - begin with lh or rh to allow association of the patch with a hemisphere. - Maximum of two ``--patch`` options can be in effect, one patch for each - hemisphere. If the name refers to a flat patch, the name can be - optionally followed by a colon and a rotation angle in degrees. - The flat patch will be then rotated counterclockwise by this amount - before display. You can check a suitable value for the rotation - angle by loading the patch interactively in mne_analyze . - -``--width <*value*>`` - - Width of the graphics output frames in pixels. The default width - is 600 pixels. - -``--height <*value*>`` - - Height of the graphics output frames in pixels. The default height - is 400 pixels. - -``--mag <*factor*>`` - - Magnify the the visualized scene by this factor. - -``--lh`` - - Select the left hemisphere for graphics output. By default, both hemisphere - are processed. - -``--rh`` - - Select the right hemisphere for graphics output. By default, both hemisphere - are processed. - -``--view <*name*>`` - - Select the name of the view for mov, rgb, and tif graphics output files. - The default viewnames, defined in ``$MNE_ROOT/share/mne/mne_analyze/eyes`` , - are *lat* (lateral), *med* (medial), *ven* (ventral), - and *occ* (occipital). You can override these - defaults by creating the directory .mne under your home directory - and copying the eyes file there. Each line of the eyes file contains - the name of the view, the viewpoint for the left hemisphere, the - viewpoint for the right hemisphere, left hemisphere up vector, and - right hemisphere up vector. The entities are separated by semicolons. - Lines beginning with the pound sign (#) are considered to be comments. - -``--smooth <*nstep*>`` - - Number of smoothsteps to take when producing the output frames. Depending - on the source space decimation, an appropriate number is 4 - 7. - Smoothing does not have any effect for the original brain if stc - files are produced. However, if morphing is selected smoothing is - mandatory even with stc output. For details of the smoothing procedure, - see :ref:`CHDEBAHH`. - -``--nocomments`` - - Do not include the comments in the image output files or movies. - -``--noscalebar`` - - Do not include the scalebar in the image output files or movies. - -``--alpha <*value*>`` - - Adjust the opacity of maps shown on the cortical surface (0 = transparent, - 1 = totally opaque). The default value is 1. - -Thresholding ------------- - -``--fthresh <*value*>`` - - Specifies the threshold for the displayed colormaps. At the threshold, - the overlaid color will be equal to the background surface color. - For currents, the value will be multiplied by :math:`1^{-10}`. - The default value is 8. - -``--fmid <*value*>`` - - Specifies the midpoint for the displayed colormaps. At this value, the - overlaid color will be read (positive values) or blue (negative values). - For currents, the value will be multiplied by :math:`1^{-10}`. - The default value is 15. - -``--fmax <*value*>`` - - Specifies the maximum point for the displayed colormaps. At this value, - the overlaid color will bright yellow (positive values) or light - blue (negative values). For currents, the value will be multiplied - by :math:`1^{-10}`. The default value is 20. - -``--fslope <*value*>`` - - Included for backwards compatibility. If this option is specified - and ``--fmax`` option is *not* specified, :math:`F_{max} = F_{mid} + 1/F_{slope}`. - -Output files ------------- - -``--mov <*name*>`` - - Produce QuickTime movie files. This is the 'stem' of - the output file name. The actual name is derived by stripping anything - up to and including the last period from the end of <*name*> . - According to the hemisphere, ``-lh`` or ``-rh`` is - then appended. The name of the view is indicated with ``-`` <*viename*> . - Finally, ``.mov`` is added to indicate a QuickTime output - file. The movie is produced for all times as dictated by the ``--tmin`` , ``--tmax`` , ``--tstep`` , - and ``--integ`` options. - -``--qual <*value*>`` - - Quality of the QuickTime movie output. The default quality is 80 and - allowed range is 25 - 100. The size of the movie files is a monotonously - increasing function of the movie quality. - -``--rate <*rate*>`` - - Specifies the frame rate of the QuickTime movies. The default value is :math:`1/(10t_{step})`, - where :math:`t_{step}` is the time between subsequent - movie frames produced in seconds. - -``--rgb <*name*>`` - - Produce rgb snapshots. This is the 'stem' of the - output file name. The actual name is derived by stripping anything - up to and including the last period from the end of <*name*> . - According to the hemisphere, ``-lh`` or ``-rh`` is - then appended. The name of the view is indicated with ``-`` <*viename*> . - Finally, ``.rgb`` is added to indicate an rgb output file. - Files are produced for all picked times as dictated by the ``--pick`` and ``--integ`` options. - -``--tif <*name*>`` - - Produce tif snapshots. This is the 'stem' of the - output file name. The actual name is derived by stripping anything - up to and including the last period from the end of <*name*> . - According to the hemisphere, ``-lh`` or ``-rh`` is - then appended. The name of the view is indicated with ``-`` <*viename*> . - Finally, ``.tif`` is added to indicate an rgb output file. - Files are produced for all picked times as dictated by the ``--pick`` and ``--integ`` options. - The tif output files are *not* compressed. Pass - the files through an image processing program to compress them. - -``--jpg <*name*>`` - - Produce jpg snapshots. This is the 'stem' of the - output file name. The actual name is derived by stripping anything - up to and including the last period from the end of <*name*> . - According to the hemisphere, ``-lh`` or ``-rh`` is - then appended. The name of the view is indicated with ``-`` <*viename*> . - Finally, ``.jpg`` is added to indicate an rgb output file. - Files are produced for all picked times as dictated by the ``--pick`` and ``--integ`` options. - -``--png <*name*>`` - - Produce png snapshots. This is the 'stem' of the - output file name. The actual name is derived by stripping anything - up to and including the last period from the end of <*name*> . - According to the hemisphere, ``-lh`` or ``-rh`` is - then appended. The name of the view is indicated with ``-`` <*viename*> . - Finally, ``.png`` is added to indicate an rgb output file. - Files are produced for all picked times as dictated by the ``--pick`` and ``--integ`` options. - -``--w <*name*>`` - - Produce w file snapshots. This is the 'stem' of - the output file name. The actual name is derived by stripping anything - up to and including the last period from the end of <*name*> . - According to the hemisphere, ``-lh`` .w or ``-rh`` .w - is then appended. Files are produced for all picked times as dictated - by the ``--pick`` and ``--integ`` options. - -``--stc <*name*>`` - - Produce stc files for either the original subject or the one selected with - the ``--morph`` option. These files will contain data only - for the decimated locations. If morphing is selected, appropriate - smoothing is mandatory. The morphed maps will be decimated with - help of a subdivided icosahedron so that the morphed stc files will - always contain 10242 vertices. These morphed stc files can be easily - averaged together, e.g., in Matlab since they always contain an - identical set of vertices. - -``--norm <*name*>`` - - Indicates that a separate w file - containing the noise-normalization values will be produced. The - option ``--spm`` must also be present. Nevertheless, the - movies and stc files output will - contain MNE values. The noise normalization data files will be called <*name*>- <*SNR*> ``-lh.w`` and <*name*>- <*SNR*> ``-rh.w`` . - -.. _CBBHHCEF: - -Label processing ----------------- - -``--label <*name*>`` - - Specifies a label file to process. For each label file, the values - of the computed estimates are listed in text files. The label files - are produced by tksurfer or mne_analyze and - specify regions of interests (ROIs). A label file name should end - with ``-lh.label`` for left-hemisphere ROIs and with ``-rh.label`` for - right-hemisphere ones. The corresponding output files are tagged - with ``-lh-`` <*data type*> ``.amp`` and ``-rh-`` <*data type*> ``.amp``, respectively. <*data type*> equals ``'mne`` ' for - expected current data and ``'spm`` ' for - dSPM data. Each line of the output file contains the waveform of - the output quantity at one of the source locations falling inside - the ROI. For more information about the label output formats, see :ref:`CACJJGFA`. - -``--labelcoords`` - - Include coordinates of the vertices in the output. The coordinates will - be listed in millimeters in the coordinate system which was specified - for the forward model computations. This option cannot be used with - stc input files (``--stcin`` ) because the stc files do - not contain the coordinates of the vertices. - -``--labelverts`` - - Include vertex numbers in the output. The numbers refer to the complete - triangulation of the corresponding surface and are zero based. The - vertex numbers are by default on the first row or first column of the - output file depending on whether or not the ``--labeltimebytime`` option - is present. - -``--labeltimebytime`` - - Output the label data time by time instead of the default vertex-by-vertex - output. - -``--labeltag <*tag*>`` - - End the output files with the specified tag. By default, the output files - will end with ``-mne.amp`` or ``-spm.amp`` depending - on whether MNE or one of the noise-normalized estimates (dSPM or sLORETA) - was selected. - -``--labeloutdir <*directory*>`` - - Specifies the directory where the output files will be located. - By default, they will be in the current working directory. - -``--labelcomments`` - - Include comments in the output files. The comment lines begin with the - percent sign to make the files compatible with Matlab. - -``--scaleby <*factor*>`` - - By default, the current values output to the files will be in the - actual physical units (Am). This option allows scaling of the current - values to other units. mne_analyze typically - uses 1e10 to bring the numbers to a human-friendly scale. - -Using stc file input --------------------- - -The ``--stcin`` option allows input of stc files. -This feature has several uses: - -- QuickTime movies can be produced from - existing stc files without having to resort to EasyMeg. - -- Graphics snapshot can be produced from existing stc files. - -- Existing stc files can be temporally resampled with help of - the ``--tmin`` , ``--tmax`` , ``--tstep`` , - and ``--integ`` options. - -- Existing stc files can be morphed to another cortical surface - by specifying the ``--morph`` option. - -- Timecourses can be inquired and stored into text files with - help of the ``--label`` options, see above. - - -.. _mne_make_source_space: - -mne_make_source_space -===================== - -``--subject `` - - Name of the subject. - -``--morph `` - - Name of the subject to morph the source space to. - -``--spacing `` - - Approximate source space spacing in mm. - -``--ico `` - - Use the subdivided icosahedron or octahedron in downsampling instead of the --spacing option. - -``--oct `` - - Same as --ico -grade. - -``--surf `` - - Surface file names (separated by colons) - -``--src `` - - Name of the output file. - - -.. _mne_process_raw: - -mne_process_raw -=============== - -``--cd <*dir*>`` - - Change to this directory before starting. - -``--raw <*name*>`` - - Specifies the raw data file to be opened. This option is required. - -``--grad <*number*>`` - - Apply software gradient compensation of the given order to the data loaded - with the ``--raw`` option. This option is effective only - for data acquired with the CTF and 4D Magnes MEG systems. If orders - different from zero are requested for Neuromag data, an error message appears - and data are not loaded. Any compensation already existing in the - file can be undone or changed to another order by using an appropriate ``--grad`` options. - Possible orders are 0 (No compensation), 1 - 3 (CTF data), and 101 - (Magnes data). The same compensation will be applied to all loaded data - files. - -``--filtersize <*size*>`` - - Adjust the length of the FFT to be applied in filtering. The number will - be rounded up to the next power of two. If the size is :math:`N`, - the corresponding length of time is :math:`N/f_s`, - where :math:`f_s` is the sampling frequency - of your data. The filtering procedure includes overlapping tapers - of length :math:`N/2` so that the total FFT - length will actually be :math:`2N`. This - value cannot be changed after the program has been started. - -``--highpass <*value/Hz*>`` - - Highpass filter frequency limit. If this is too low with respect - to the selected FFT length and, the data will not be highpass filtered. It - is best to experiment with the interactive version to find the lowest applicable - filter for your data. This value can be adjusted in the interactive - version of the program. The default is 0, *i.e.*, - no highpass filter apart from that used during the acquisition will - be in effect. - -``--highpassw <*value/Hz*>`` - - The width of the transition band of the highpass filter. The default - is 6 frequency bins, where one bin is :math:`f_s / (2N)`. This - value cannot be adjusted in the interactive version of the program. - -``--lowpass <*value/Hz*>`` - - Lowpass filter frequency limit. This value can be adjusted in the interactive - version of the program. The default is 40 Hz. - -``--lowpassw <*value/Hz*>`` - - The width of the transition band of the lowpass filter. This value - can be adjusted in the interactive version of the program. The default - is 5 Hz. - -``--eoghighpass <*value/Hz*>`` - - Highpass filter frequency limit for EOG. If this is too low with respect - to the selected FFT length and, the data will not be highpass filtered. - It is best to experiment with the interactive version to find the - lowest applicable filter for your data. This value can be adjusted in - the interactive version of the program. The default is 0, *i.e.*, - no highpass filter apart from that used during the acquisition will - be in effect. - -``--eoghighpassw <*value/Hz*>`` - - The width of the transition band of the EOG highpass filter. The default - is 6 frequency bins, where one bin is :math:`f_s / (2N)`. - This value cannot be adjusted in the interactive version of the - program. - -``--eoglowpass <*value/Hz*>`` - - Lowpass filter frequency limit for EOG. This value can be adjusted in - the interactive version of the program. The default is 40 Hz. - -``--eoglowpassw <*value/Hz*>`` - - The width of the transition band of the EOG lowpass filter. This value - can be adjusted in the interactive version of the program. The default - is 5 Hz. - -``--filteroff`` - - Do not filter the data. This initial value can be changed in the - interactive version of the program. - -``--digtrig <*name*>`` - - Name of the composite digital trigger channel. The default value - is 'STI 014'. Underscores in the channel name - will be replaced by spaces. May also be specified by an environment - variable ``MNE_TRIGGER_CH_NAME``. - -``--digtrigmask <*number*>`` - - Mask to be applied to the trigger channel values before considering them. - This option is useful if one wants to set some bits in a don't care - state. For example, some finger response pads keep the trigger lines - high if not in use, *i.e.*, a finger is not in - place. Yet, it is convenient to keep these devices permanently connected - to the acquisition system. The number can be given in decimal or - hexadecimal format (beginning with 0x or 0X). For example, the value - 255 (0xFF) means that only the lowest order byte (usually trigger - lines 1 - 8 or bits 0 - 7) will be considered. May also be specified by an - environment variable ``MNE_TRIGGER_CH_MASK``. - -``--proj <*name*>`` - - Specify the name of the file of the file containing a signal-space - projection (SSP) operator. If ``--proj`` options are present - the data file is not consulted for an SSP operator. The operator - corresponding to average EEG reference is always added if EEG data - are present. - -``--projon`` - - Activate the projections loaded. One of the options ``--projon`` or ``--projoff`` must - be present on the mne_processs_raw command line. - -``--projoff`` - - Deactivate the projections loaded. One of the options ``--projon`` or ``--projoff`` must - be present on the mne_processs_raw command line. - -``--makeproj`` - - Estimate the noise subspace from the data and create a new signal-space - projection operator instead of using one attached to the data file - or those specified with the ``--proj`` option. The following - eight options define the parameters of the noise subspace estimation. More - information on the signal-space projection can be found in :ref:`CACCHABI`. - -``--projevent <*no*>`` - - Specifies the events which identify the time points of interest - for projector calculation. When this option is present, ``--projtmin`` and ``--projtmax`` are - relative to the time point of the event rather than the whole raw - data file. - -``--projtmin <*time/s*>`` - - Specify the beginning time for the calculation of the covariance matrix - which serves as the basis for the new SSP operator. This option - is required with ``--projevent`` and defaults to the beginning - of the raw data file otherwise. This option is effective only if ``--makeproj`` or ``--saveprojtag`` options - are present. - -``--projtmax <*time/s*>`` - - Specify the ending time for the calculation of the covariance matrix which - serves as the basis for the new SSP operator. This option is required - with ``--projevent`` and defaults to the end of the raw data - file otherwise. This option is effective only if ``--makeproj`` or ``--saveprojtag`` options - are present. - -``--projngrad <*number*>`` - - Number of SSP components to include for planar gradiometers (default - = 5). This value is system dependent. For example, in a well-shielded - quiet environment, no planar gradiometer projections are usually - needed. - -``--projnmag <*number*>`` - - Number of SSP components to include for magnetometers / axial gradiometers - (default = 8). This value is system dependent. For example, in a - well-shielded quiet environment, 3 - 4 components are need - while in a noisy environment with light shielding even more than - 8 components may be necessary. - -``--projgradrej <*value/ fT/cm*>`` - - Rejection limit for planar gradiometers in the estimation of the covariance - matrix frfixom which the new SSP operator is derived. The default - value is 2000 fT/cm. Again, this value is system dependent. - -``--projmagrej <*value/ fT*>`` - - Rejection limit for planar gradiometers in the estimation of the covariance - matrix from which the new SSP operator is derived. The default value - is 3000 fT. Again, this value is system dependent. - -``--saveprojtag <*tag*>`` - - This option defines the names of files to hold the SSP operator. - If this option is present the ``--makeproj`` option is - implied. The SSP operator file name is formed by removing the trailing ``.fif`` or ``_raw.fif`` from - the raw data file name by appending <*tag*> .fif - to this stem. Recommended value for <*tag*> is ``-proj`` . - -``--saveprojaug`` - - Specify this option if you want to use the projection operator file output - in the Elekta-Neuromag Signal processor (graph) software. - -``--eventsout <*name*>`` - - List the digital trigger channel events to the specified file. By default, - only transitions from zero to a non-zero value are listed. If multiple - raw data files are specified, an equal number of ``--eventsout`` options - should be present. If the file name ends with .fif, the output will - be in fif format, otherwise a text event file will be output. - -``--allevents`` - - List all transitions to file specified with the ``--eventsout`` option. - -``--events <*name*>`` - - Specifies the name of a fif or text format event file (see :ref:`CACBCEGC`) to be associated with a raw data file to be - processed. If multiple raw data files are specified, the number - of ``--events`` options can be smaller or equal to the - number of raw data files. If it is equal, the event filenames will - be associated with the raw data files in the order given. If it - is smaller, the remaining raw data files for which an event file - is not specified will *not* have an event file associated - with them. The event file format is recognized from the file name: - if it ends with ``.fif`` , the file is assumed to be in - fif format, otherwise a text file is expected. - -``--ave <*name*>`` - - Specifies the name of an off-line averaging description file. For details - of the format of this file, please consult :ref:`CACBBDGC`. - If multiple raw data files are specified, the number of ``--ave`` options - can be smaller or equal to the number of raw data files. If it is - equal, the averaging description file names will be associated with - the raw data files in the order given. If it is smaller, the last - description file will be used for the remaining raw data files. - -``--saveavetag <*tag*>`` - - If this option is present and averaging is evoked with the ``--ave`` option, - the outfile and logfile options in the averaging description file - are ignored. Instead, trailing ``.fif`` or ``_raw.fif`` is - removed from the raw data file name and <*tag*> ``.fif`` or <*tag*> ``.log`` is appended - to create the output and log file names, respectively. - -``--gave <*name*>`` - - If multiple raw data files are specified as input and averaging - is requested, the grand average over all data files will be saved - to <*name*> . - -``--cov <*name*>`` - - Specify the name of a description file for covariance matrix estimation. For - details of the format of this file, please see :ref:`CACEBACG`. - If multiple raw data files are specified, the number of ``--cov`` options can - be smaller or equal to the number of raw data files. If it is equal, the - averaging description file names will be associated with the raw data - files in the order given. If it is smaller, the last description - file will be used for the remaining raw data files. - -``--savecovtag <*tag*>`` - - If this option is present and covariance matrix estimation is evoked with - the ``--cov`` option, the outfile and logfile options in - the covariance estimation description file are ignored. Instead, - trailing ``.fif`` or ``_raw.fif`` is removed from - the raw data file name and <*tag*> .fif or <*tag*> .log - is appended to create the output and log file names, respectively. - For compatibility with other MNE software scripts, ``--savecovtag -cov`` is recommended. - -``--savehere`` - - If the ``--saveavetag`` and ``--savecovtag`` options - are used to generate the file output file names, the resulting files - will go to the same directory as raw data by default. With this - option the output files will be generated in the current working - directory instead. - -``--gcov <*name*>`` - - If multiple raw data files are specified as input and covariance matrix estimation - is requested, the grand average over all data files will be saved - to <*name*> . The details of - the covariance matrix estimation are given in :ref:`CACHAAEG`. - -``--save <*name*>`` - - Save a filtered and optionally down-sampled version of the data - file to <*name*> . If multiple - raw data files are specified, an equal number of ``--save`` options - should be present. If <*filename*> ends - with ``.fif`` or ``_raw.fif`` , these endings are - deleted. After these modifications, ``_raw.fif`` is inserted - after the remaining part of the file name. If the file is split - into multiple parts (see ``--split`` option below), the - additional parts will be called <*name*> ``-`` <*number*> ``_raw.fif`` - -``--split <*size/MB*>`` - - Specifies the maximum size of the raw data files saved with the ``--save`` option. - By default, the output is split into files which are just below - 2 GB so that the fif file maximum size is not exceed. - -``--anon`` - - Do not include any subject information in the output files created with - the ``--save`` option. - -``--decim <*number*>`` - - The data are decimated by this factor before saving to the file - specified with the ``--save`` option. For decimation to - succeed, the data must be lowpass filtered to less than third of - the sampling frequency effective after decimation. - - -.. _mne_redo_file: - -mne_redo_file -============= - -Usage: ``mne_redo_file file-to-redo`` - - -.. _mne_redo_file_nocwd: - -mne_redo_file_nocwd -=================== - -Usage: ``mne_redo_file_nocwd file-to-redo`` - - -.. _mne_setup_forward_model: - -mne_setup_forward_model -======================= - -``--subject <*subject*>`` - - Defines the name of the subject. This can be also accomplished - by setting the SUBJECT environment variable. - -``--surf`` - - Use the FreeSurfer surface files instead of the default ASCII triangulation - files. Please consult :ref:`BABDBBFC` for the standard file - naming scheme. - -``--noswap`` - - Traditionally, the vertices of the triangles in 'tri' files - have been ordered so that, seen from the outside of the triangulation, - the vertices are ordered in clockwise fashion. The fif files, however, - employ the more standard convention with the vertices ordered counterclockwise. - Therefore, mne_setup_forward_model by - default reverses the vertex ordering before writing the fif file. - If, for some reason, you have counterclockwise-ordered tri files - available this behavior can be turned off by defining ``--noswap`` . - When the fif file is created, the vertex ordering is checked and - the process is aborted if it is incorrect after taking into account - the state of the swapping. Should this happen, try to run mne_setup_forward_model again including - the ``--noswap`` flag. In particular, if you employ the seglab software - to create the triangulations (see :ref:`create_bem_model`), the ``--noswap`` flag - is required. This option is ignored if ``--surf`` is specified - -``--ico <*number*>`` - - This option is relevant (and required) only with the ``--surf`` option and - if the surface files have been produced by the watershed algorithm. - The watershed triangulations are isomorphic with an icosahedron, - which has been recursively subdivided six times to yield 20480 triangles. - However, this number of triangles results in a long computation - time even in a workstation with generous amounts of memory. Therefore, - the triangulations have to be decimated. Specifying ``--ico 4`` yields 5120 triangles per surface while ``--ico 3`` results - in 1280 triangles. The recommended choice is ``--ico 4`` . - -``--homog`` - - Use a single compartment model (brain only) instead a three layer one - (scalp, skull, and brain). Only the ``inner_skull.tri`` triangulation - is required. This model is usually sufficient for MEG but invalid - for EEG. If you are employing MEG data only, this option is recommended - because of faster computation times. If this flag is specified, - the options ``--brainc`` , ``--skullc`` , and ``--scalpc`` are irrelevant. - -``--brainc <*conductivity/ S/m*>`` - - Defines the brain compartment conductivity. The default value is 0.3 S/m. - -``--skullc <*conductivity/ S/m*>`` - - Defines the skull compartment conductivity. The default value is 0.006 S/m - corresponding to a conductivity ratio 1/50 between the brain and - skull compartments. - -``--scalpc <*conductivity/ S/m*>`` - - Defines the brain compartment conductivity. The default value is 0.3 S/m. - -``--innershift <*value/mm*>`` - - Shift the inner skull surface outwards along the vertex normal directions - by this amount. - -``--outershift <*value/mm*>`` - - Shift the outer skull surface outwards along the vertex normal directions - by this amount. - -``--scalpshift <*value/mm*>`` - - Shift the scalp surface outwards along the vertex normal directions by - this amount. - -``--nosol`` - - Omit the BEM model geometry dependent data preparation step. This - can be done later by running mne_setup_forward_model without the ``--nosol`` option. - -``--model <*name*>`` - - Name for the BEM model geometry file. The model will be created into - the directory bem as <*name*>- ``bem.fif`` . If - this option is missing, standard model names will be used (see below). - - -.. _mne_setup_mri: - -mne_setup_mri -============= - -This command sets up the directories ``subjects/$SUBJECT/mri/T1-neuromag`` and -``subjects/$SUBJECT/mri/brain-neuromag`` . - - -.. _mne_setup_source_space: - -mne_setup_source_space -====================== - -``--subject <*name*>`` - - Name of the subject in SUBJECTS_DIR. In the absence of this option, - the SUBJECT environment variable will be consulted. If it is not - defined, mne_setup_source_space exits - with an error. - -``--morph <*name*>`` - - Name of a subject in SUBJECTS_DIR. If this option is present, the source - space will be first constructed for the subject defined by the --subject - option or the SUBJECT environment variable and then morphed to this - subject. This option is useful if you want to create a source spaces - for several subjects and want to directly compare the data across - subjects at the source space vertices without any morphing procedure - afterwards. The drawback of this approach is that the spacing between - source locations in the "morph" subject is not going - to be as uniform as it would be without morphing. - -``--surf <*name1*>: <*name2*>:...`` - - FreeSurfer surface file names specifying the source surfaces, separated - by colons. - -``--spacing <*spacing/mm*>`` - - Specifies the approximate grid spacing of the source space in mm. - -``--ico <*number*>`` - - Instead of using the traditional method for cortical surface decimation - it is possible to create the source space using the topology of - a recursively subdivided icosahedron ( <*number*> > 0) - or an octahedron ( <*number*> < 0). - This method uses the cortical surface inflated to a sphere as a - tool to find the appropriate vertices for the source space. The - benefit of the ``--ico`` option is that the source space will have triangulation - information between the decimated vertices included, which some - future versions of MNE software may be able to utilize. The number - of triangles increases by a factor of four in each subdivision, - starting from 20 triangles in an icosahedron and 8 triangles in - an octahedron. Since the number of vertices on a closed surface - is :math:`n_{vert} = (n_{tri} + 4) / 2`, the number of vertices in - the *k* th subdivision of an icosahedron and an - octahedron are :math:`10 \cdot 4^k +2` and :math:`4_{k + 1} + 2`, - respectively. The recommended values for <*number*> and - the corresponding number of source space locations are listed in Table 3.1. - -``--all`` - - Include all nodes to the output. The active dipole nodes are identified - in the fif file by a separate tag. If tri files were used as input - the output file will also contain information about the surface - triangulation. This option is always recommended to include complete - information. - -``--src <*name*>`` - - Output file name. Use a name <*dir*>/<*name*>-src.fif - -.. note:: If both ``--ico`` and ``--spacing`` options are present the later one on the command line takes precedence. - -.. note:: Due to the differences between the FreeSurfer and MNE libraries, the number of source space points generated with the ``--spacing`` option may be different between the current version of MNE and versions 2.5 or earlier (using ``--spacing`` option to mne_setup_source_space ) if the FreeSurfer surfaces employ the (old) quadrangle format or if there are topological defects on the surfaces. All new FreeSurfer surfaces are specified as triangular tessellations and are e of defects. - - -.. _mne_show_environment: - -mne_show_environment -==================== - -Usage: ``mne_show_environment files`` - - -Utility command-line arguments -############################## - -.. _mne_add_patch_info: - -mne_add_patch_info -================== - -Purpose -------- - -The utility mne_add_patch_info uses -the detailed cortical surface geometry information to add data about -cortical patches corresponding to each source space point. A new -copy of the source space(s) included in the input file is created -with the patch information included. In addition to the patch information, mne_add_patch_info can -optionally calculate distances, along the cortical surface, between -the vertices selected to the source space. - -.. note:: Depending on the speed of your computer and the options selected, mne_add_patch_info takes 5 - 30 minutes to run. - -.. _CJAGCDCC: - -Command line options --------------------- - -mne_add_patch_info accepts -the following command-line options: - -``--verbose`` - - Provide verbose output during the calculations. - -``--dist <*dist/mm*>`` - - Invokes the calculation of distances between vertices included in - the source space along the cortical surface. Only pairs whose distance in - the three-dimensional volume is less than the specified distance are - considered. For details, see :ref:`CJAIFJDD`, below. - -``--src <*name*>`` - - The input source space file. The source space files usually end - with ``-src.fif`` . - -``--srcp <*name*>`` - - The output source space file which will contain the patch information. - If the file exists it will overwritten without asking for permission. - A recommended naming convention is to add the letter ``p`` after the - source spacing included in the file name. For example, if the input - file is ``mh-7-src.fif`` , a recommended output file name - is ``mh-7p-src.fif`` . - -``--w <*name*>`` - - Name of a w file, which will contain the patch area information. Two - files will be created: <*name*> ``-lh.w`` and <*name*> ``-rh.w`` . - The numbers in the files are patch areas in :math:`\text{mm}^2`. - The source space vertices are marked with value 150. - -``--labeldir <*directory*>`` - - Create a label file corresponding to each of the patches in the - given directory. The directory must be created before running mne_add_patch_info . - -.. _CJAIFJDD: - -Computational details ---------------------- - -By default, mne_add_patch_info creates -a copy of the source space(s) with the following additional information -for each vertex in the original dense triangulation of the cortex: - -- The number of the closest active source - space vertex and - -- The distance to this vertex. - -This information can be used to determine, *e.g.*, -the sizes of the patches, their average normals, and the standard -deviation of the normal directions. This information is also returned -by the mne_read_source_space Matlab function as described in Table 10.28. - -The ``--dist`` option to mne_add_patch_info invokes -the calculation of inter-vertex distances. These distances are computed -along the the cortical surface (usually the white matter) on which -the source space vertices are located. - -Since the calculation of all possible distances would take -a very long time, the distance given with the ``--dist`` option allows -restriction to the neighborhood of each source space vertex. This -neighborhood is defined as the sphere around each source space vertex, -with radius given by the ``--dist`` option. Because the distance calculation -is done along the folded cortical surface whose details are given -by the dense triangulation of the cortical surface produced by FreeSurfer, -some of the distances computed will be larger than the value give -with --dist. - - -.. _mne_add_to_meas_info: - -mne_add_to_meas_info -==================== - -Add new data to meas info. - -``--add `` - - The file to add. - -``--dest `` - - the destination file. - - -.. _mne_add_triggers: - -mne_add_triggers -================ - -Purpose -------- - -The utility mne_add_triggers modifies -the digital trigger channel (STI 014) in raw data files -to include additional transitions. Since the raw data file is modified, -it is possible to make irreversible changes. Use this utility with -caution. It is recommended that you never run mne_add_triggers on -an original raw data file. - -Command line options --------------------- - -mne_add_triggers accepts -the following command-line options: - -``--raw <*name*>`` - - Specifies the raw data file to be modified. - -``--trg <*name*>`` - - Specifies the trigger line modification list. This text file should - contain two entries per line: the sample number and the trigger - number to be added into the file. The number of the first sample - in the file is zero. It is recommended that trigger numbers whose - binary equivalent has lower eight bits equal to zero are used to - avoid conflicts with the ordinary triggers occurring in the file. - -``--delete`` - - Delete the triggers defined by the trigger file instead of adding - them. This enables changing the file to its original state, provided - that the trigger file is preserved. - -.. note:: Since :ref:`mne_browse_raw` and :ref:`mne_process_raw` can employ an event file which effectively adds new trigger instants, mne_add_triggers is for the most part obsolete but it has been retained in the MNE software suite for backward compatibility. - - - -.. _mne_annot2labels: - -mne_annot2labels -================ - -The utility mne_annot2labels converts -cortical parcellation data into a set of labels. The parcellation -data are read from the directory ``$SUBJECTS_DIR/$SUBJECT/label`` and -the resulting labels are written to the current directory. mne_annot2labels requires -that the environment variable ``$SUBJECTS_DIR`` is set. -The command line options for mne_annot2labels are: - -``--subject <*name*>`` - - Specifies the name of the subject. If this option is not present - the ``$SUBJECT`` environment variable is consulted. If - the subject name cannot be determined, the program quits. - -``--parc <*name*>`` - - Specifies the parcellation name to convert. The corresponding parcellation - file names will be ``$SUBJECTS_DIR/$SUBJECT/label/`` <*hemi*> ``h.`` <*name*> ``.annot`` where <*hemi*> is ``l`` or ``r`` for the - left and right hemisphere, respectively. - - -.. _mne_anonymize: - -mne_anonymize -============= - -Depending no the settings during acquisition in the Elekta-Neuromag EEG/MEG -systems the data files may contain subject identifying information -in unencrypted form. The utility mne_anonymize was -written to clear tags containing such information from a fif file. -Specifically, this utility removes the following tags from the fif -file: - -.. _CHDEHBCG: - -.. table:: Tags cleared by mne_anonymize . - - ======================== =========================================================================== - Tag Description - ======================== =========================================================================== - FIFF_SUBJ_FIRST_NAME First name of the subject - FIFF_SUBJ_MIDDLE_NAME Middle name of the subject - FIFF_SUBJ_LAST_NAME Last name of the subject - FIFF_SUBJ_BIRTH_DAY Birthday of the subject (Julian day number) - FIFF_SUBJ_SEX The sex of the subject - FIFF_SUBJ_HAND Handedness of the subject - FIFF_SUBJ_WEIGHT Weight of the subject in kg - FIFF_SUBJ_HEIGHT Height of the subject in m - FIFF_SUBJ_COMMENT Comment about the subject - FIFF_MEAS_DATE The date of the recordings - FIFF_SUBJ_HIS_ID The ID used in the Hospital Information System (only with ``--his`` option) - ======================== =========================================================================== - -.. note:: mne_anonymize normally keeps the FIFF_SUBJ_HIS_ID tag which can be used to identify the subjects uniquely after the information listed in :ref:`CHDEHBCG` have been removed. If the ``--his`` option is specified on the command line, the FIFF_SUBJ_HIS_ID tag will be removed as well. The data of the tags listed in :ref:`CHDEHBCG` and the optional FIFF_SUBJ_HIS_ID tag are overwritten with zeros and the space claimed by omitting these tags is added to the free space list of the file. Therefore, after mne_anonymize has processed a data file there is no way to recover the removed information. Use this utility with caution. - -mne_anonymize recognizes the following command-line options: - -``--his`` - - Remove the FIFF_SUBJ_HIS_ID tag as well, see above. - -``--file <*name*>`` - - Specifies the name of the file to be modified. - -.. note:: You need write permission to the file to be processed. - - -.. _mne_average_forward_solutions: - -mne_average_forward_solutions -============================= - -``--fwd <*name*> :[ <*weight*> ]`` - - Specifies a forward solution to include. If no weight is specified, - 1.0 is assumed. In the averaging process the weights are divided - by their sum. For example, if two forward solutions are averaged - and their specified weights are 2 and 3, the average is formed with - a weight of 2/5 for the first solution and 3/5 for the second one. - -``--out <*name*>`` - - Specifies the output file which will contain the averaged forward solution. - - -.. _mne_brain_vision2fiff: - -mne_brain_vision2fiff -===================== - -The utility mne_brain_vision2fiff was -created to import BrainVision EEG data. This utility also helps -to import the eXimia (Nexstim) TMS-compatible EEG system data to -the MNE software. The utility uses an optional fif file containing -the head digitization data to allow source modeling. The MNE Matlab -toolbox contains the function fiff_write_dig_file to -write a digitization file based on digitization data available in -another format, see :ref:`ch_matlab`. - -.. note:: - - mne_brain_vision2fiff reads events from the ``vmrk`` file referenced in the - ``vhdr`` file, but it only includes events whose "Type" is ``Stimulus`` and - whose "description" is given by ``S``. All other events are ignored. - - -The command-line options of mne_brain_vision2fiff are: - -``--header <*name*>`` - - The name of the BrainVision header file. The extension of this file - is ``vhdr`` . The header file typically refers to a marker - file (``vmrk`` ) which is automatically processed and a - digital trigger channel (STI 014) is formed from the marker information. - The ``vmrk`` file is ignored if the ``--eximia`` option - is present. - -``--dig <*name*>`` - - The name of the fif file containing the digitization data. - -``--orignames`` - - Use the original EEG channel labels. If this option is absent the EEG - channels will be automatically renamed to EEG 001, EEG 002, *etc.* - -``--eximia`` - - Interpret this as an eXimia data file. The first three channels - will be thresholded and interpreted as trigger channels. The composite - digital trigger channel will be composed in the same way as in the - :ref:`mne_kit2fiff` utility. In addition, the fourth channel - will be assigned as an EOG channel. This option is normally used - by the :ref:`mne_eximia2fiff` script. - -``--split <*size/MB*>`` - - Split the output data into several files which are no more than <*size*> MB. - By default, the output is split into files which are just below - 2 GB so that the fif file maximum size is not exceeded. - -``--out <*filename*>`` - - Specifies the name of the output fif format data file. If <*filename*> ends - with ``.fif`` or ``_raw.fif`` , these endings are - deleted. After these modifications, ``_raw.fif`` is inserted - after the remaining part of the file name. If the file is split - into multiple parts, the additional parts will be called - <*name*> ``-`` <*number*> ``_raw.fif`` . - - -.. _mne_change_baselines: - -mne_change_baselines -==================== - -The utility mne_change_baselines computes -baseline values and applies them to an evoked-response data file. -The command-line options are: - -``--in <*name*>`` - - Specifies the input data file. - -``--set <*number*>`` - - The data set number to compute baselines from or to apply baselines - to. If this option is omitted, all average data sets in the input file - are processed. - -``--out <*name*>`` - - The output file. - -``--baselines <*name*>`` - - Specifies a text file which contains the baseline values to be applied. Each - line should contain a channel name, colon, and the baseline value - given in 'native' units (T/m, T, or V). If this - option is encountered, the limits specified by previous ``--bmin`` and ``--bmax`` options will not - have an effect. - -``--list <*name*>`` - - Specifies a text file to contain the baseline values. Listing is - provided only if a specific data set is selected with the ``--set`` option. - -``--bmin <*value/ms*>`` - - Lower limit of the baseline. Effective only if ``--baselines`` option is - not present. Both ``--bmin`` and ``--bmax`` must - be present to compute the baseline values. If either ``--bmin`` or ``--bmax`` is - encountered, previous ``--baselines`` option will be ignored. - -``--bmax <*value/ms*>`` - - Upper limit of the baseline. - - -.. _mne_change_nave: - -mne_change_nave -=============== - -Usage: ``mne_change_nave --nave ...`` - - -.. _mne_check_eeg_locations: - -mne_check_eeg_locations -======================= - -Some versions of the Neuromag acquisition software did not -copy the EEG channel location information properly from the Polhemus -digitizer information data block to the EEG channel information -records if the number of EEG channels exceeds 60. The purpose of mne_check_eeg_locations is -to detect this problem and fix it, if requested. The command-line -options are: - -``--file <*name*>`` - - Specify the measurement data file to be checked or modified. - -``--dig <*name*>`` - - Name of the file containing the Polhemus digitizer information. Default - is the data file name. - -``--fix`` - - By default mne_check_eeg_locations only - checks for missing EEG locations (locations close to the origin). - With --fix mne_check_eeg_locations reads - the Polhemus data from the specified file and copies the EEG electrode - location information to the channel information records in the measurement - file. There is no harm running mne_check_eeg_locations on - a data file even if the EEG channel locations were correct in the - first place. - - -.. _mne_check_surface: - -mne_check_surface -================= -This program just reads a surface file to check whether it is valid. - -``--surf `` - - The input file (FreeSurfer surface format). - -``--bem `` - - The input file (a BEM fif file) - -``--id `` - - Surface id to list (default : 4) - - * 4 for outer skin (scalp) surface - * 3 for outer skull surface - * 1 for inner skull surface - - -``--checkmore`` - - Do more thorough testing - - -.. _mne_collect_transforms: - -mne_collect_transforms -====================== - -The utility mne_collect_transforms collects -coordinate transform information from various sources and saves -them into a single fif file. The coordinate transformations used -by MNE software are summarized in Figure 5.1. The output -of mne_collect_transforms may -include all transforms referred to therein except for the sensor -coordinate system transformations :math:`T_{s_1} \dotso T_{s_n}`. -The command-line options are: - -``--meas <*name*>`` - - Specifies a measurement data file which provides :math:`T_1`. - A forward solution or an inverse operator file can also be specified - as implied by Table 5.1. - -``--mri <*name*>`` - - Specifies an MRI description or a standalone coordinate transformation - file produced by mne_analyze which - provides :math:`T_2`. If the ``--mgh`` option - is not present mne_collect_transforms also - tries to find :math:`T_3`, :math:`T_4`, :math:`T_-`, - and :math:`T_+` from this file. - -``--mgh <*name*>`` - - An MRI volume volume file in mgh or mgz format. - This file provides :math:`T_3`. The transformation :math:`T_4` will - be read from the talairach.xfm file referred to in the MRI volume. - The fixed transforms :math:`T_-` and :math:`T_+` will - also be created. - -``--out <*name*>`` - - Specifies the output file. If this option is not present, the collected transformations - will be output on screen but not saved. - - -.. _mne_compensate_data: - -mne_compensate_data -=================== - -``--in <*name*>`` - - Specifies the input data file. - -``--out <*name*>`` - - Specifies the output data file. - -``--grad <*number*>`` - - Specifies the desired compensation grade in the output file. The value - can be 1, 2, 3, or 101. The values starting from 101 will be used - for 4D Magnes compensation matrices. - -.. note:: Only average data is included in the output. Evoked-response data files produced with mne_browse_raw or mne_process_raw may include standard errors of mean, which can not be re-compensated using the above method and are thus omitted. - -.. note:: Raw data cannot be compensated using mne_compensate_data . For this purpose, load the data to mne_browse_raw or mne_process_raw , specify the desired compensation grade, and save a new raw data file. - - -.. _mne_copy_processing_history: - -mne_copy_processing_history -=========================== - -In order for the inverse operator calculation to work correctly -with data processed with the Elekta-Neuromag Maxfilter (TM) software, -the so-called *processing history* block must -be included in data files. Previous versions of the MNE Matlab functions -did not copy processing history to files saved. As of March 30, -2009, the Matlab toolbox routines fiff_start_writing_raw and fiff_write_evoked have -been enhanced to include these data to the output file as appropriate. -If you have older raw data files created in Matlab from input which -has been processed Maxfilter, it is necessary to copy the *processing -history* block from the original to modified raw data -file using the mne_copy_processing_history utility described -below. The raw data processing programs mne_browse_raw and mne_process_raw have -handled copying of the processing history since revision 2.5 of -the MNE software. - -mne_copy_processing_history is -simple to use: - -``mne_copy_processing_history --from`` <*from*> ``--to`` <*to*> , - -where <*from*> is an -original raw data file containing the processing history and <*to*> is -a file output with older MNE Matlab routines. Be careful: this operation -cannot be undone. If the <*from*> file -does not have the processing history block or the <*to*> file -already has it, the destination file remains unchanged. - - -.. _mne_convert_dig_data: - -mne_convert_dig_data -==================== - -Converts Polhemus digitization data between different file formats. -The input formats are: - -``fif`` - - The - standard format used in MNE. The digitization data are typically - present in the measurement files. - -``hpts`` - - A text format which is a translation - of the fif format data, see :ref:`CJADJEBH` below. - -``elp`` - - A text format produced by the *Source - Signal Imaging, Inc.* software. For description of this "probe" format, - see http://www.sourcesignal.com/formats_probe.html. - -The data can be output in fif and hpts formats. -Only the last command-line option specifying an input file will -be honored. Zero or more output file options can be present on the -command line. - -.. note:: The elp and hpts input files may contain textual EEG electrode labels. They will not be copied to the fif format output. - -The command-line options of mne_convert_dig_data are: - -``--fif <*name*>`` - - Specifies the name of an input fif file. - -``--hpts <*name*>`` - - Specifies the name of an input hpts file. - -``--elp <*name*>`` - - Specifies the name of an input elp file. - -``--fifout <*name*>`` - - Specifies the name of an output fif file. - -``--hptsout <*name*>`` - - Specifies the name of an output hpts file. - -``--headcoord`` - - The fif and hpts input - files are assumed to contain data in the MNE head coordinate system, - see :ref:`c_legacy_BJEBIBAI`. With this option present, the data are - transformed to the MNE head coordinate system with help of the fiducial - locations in the data. Use this option if this is not the case or - if you are unsure about the definition of the coordinate system - of the fif and hpts input - data. This option is implied with elp input - files. If this option is present, the fif format output file will contain - the transformation between the original digitizer data coordinates - the MNE head coordinate system. - -.. _CJADJEBH: - -The hpts format ---------------- - -The hpts format digitzer -data file may contain comment lines starting with the pound sign -(#) and data lines of the form: - - <*category*> <*identifier*> <*x/mm*> <*y/mm*> <*z/mm*> - -where - -`` <*category*>`` - - defines the type of points. Allowed categories are: hpi , cardinal (fiducial ),eeg , - and extra corresponding to head-position - indicator coil locations, cardinal landmarks, EEG electrode locations, - and additional head surface points, respectively. Note that tkmedit does not - recognize the fiducial as an - alias for cardinal . - -`` <*identifier*>`` - - identifies the point. The identifiers are usually sequential numbers. For - cardinal landmarks, 1 = left auricular point, 2 = nasion, and 3 - = right auricular point. For EEG electrodes, identifier = 0 signifies - the reference electrode. Some programs (not tkmedit ) - accept electrode labels as identifiers in the eeg category. - -`` <*x/mm*> , <*y/mm*> , <*z/mm*>`` - - Location of the point, usually in the MEG head coordinate system, see :ref:`c_legacy_BJEBIBAI`. - Some programs have options to accept coordinates in meters instead - of millimeters. With ``--meters`` option, mne_transform_points lists - the coordinates in meters. - - -.. _mne_convert_lspcov: - -mne_convert_lspcov -================== - -The utility mne_convert_lspcov converts a LISP-format noise-covariance file, -produced by the Neuromag signal processor, graph into fif format. - -The command-line options are: - -``--lspcov <*name*>`` - - The LISP noise-covariance matrix file to be converted. - -``--meas <*name*>`` - - A fif format measurement file used to assign channel names to the noise-covariance - matrix elements. This file should have precisely the same channel - order within MEG and EEG as the LISP-format covariance matrix file. - -``--out <*name*>`` - - The name of a fif format output file. The file name should end with - -cov.fif.text format output file. No information about the channel names - is included. The covariance matrix file is listed row by row. This - file can be loaded to MATLAB, for example - -``--outasc <*name*>`` - - The name of a text format output file. No information about the channel - names is included. The covariance matrix file is listed row by row. - This file can be loaded to MATLAB, for example - - -.. _mne_convert_ncov: - -mne_convert_ncov -================ - -The ncov file format was used to store the noise-covariance -matrix file. The MNE software requires that the covariance matrix -files are in fif format. The utility mne_convert_ncov converts -ncov files to fif format. - -The command-line options are: - -``--ncov <*name*>`` - - The ncov file to be converted. - -``--meas <*name*>`` - - A fif format measurement file used to assign channel names to the noise-covariance - matrix elements. This file should have precisely the same channel - order within MEG and EEG as the ncov file. Typically, both the ncov - file and the measurement file are created by the now mature off-line - averager, meg_average. - - -.. _mne_convert_surface: - -mne_convert_surface -=================== - -The utility mne_convert_surface converts -surface data files between different formats. - -.. note:: The MNE Matlab toolbox functions enable reading of FreeSurfer surface files directly. Therefore, the ``--mat`` option has been removed. The dfs file format conversion functionality has been moved here from mne_convert_dfs . Consequently, mne_convert_dfs has been removed from MNE software. - -.. _BABEABAA: - -command-line options --------------------- - -mne_convert_surface accepts -the following command-line options: - -``--fif <*name*>`` - - Specifies a fif format input file. The first surface (source space) - from this file will be read. - -``--tri <*name*>`` - - Specifies a text format input file. The format of this file is described in :ref:`c_legacy_BEHDEFCD`. - -``--meters`` - - The unit of measure for the vertex locations in a text input files - is meters instead of the default millimeters. This option does not - have any effect on the interpretation of the FreeSurfer surface - files specified with the ``--surf`` option. - -``--swap`` - - Swap the ordering or the triangle vertices. The standard convention in - the MNE software is to have the vertices in text format files ordered - so that the vector cross product of the vectors from vertex 1 to - 2 and 1 to 3 gives the direction of the outward surface normal. This - is also called the counterclockwise ordering. If your text input file - does not comply with this right-hand rule, use the ``--swap`` option. - This option does not have any effect on the interpretation of the FreeSurfer surface - files specified with the ``--surf`` option. - -``--surf <*name*>`` - - Specifies a FreeSurfer format - input file. - -``--dfs <*name*>`` - - Specifies the name of a dfs file to be converted. The surfaces produced - by BrainSuite are in the dfs format. - -``--mghmri <*name*>`` - - Specifies a mgh/mgz format MRI data file which will be used to define - the coordinate transformation to be applied to the data read from - a dfs file to bring it to the FreeSurfer MRI - coordinates, *i.e.*, the coordinate system of - the MRI stack in the file. In addition, this option can be used - to insert "volume geometry" information to the FreeSurfer - surface file output (``--surfout`` option). If the input file already - contains the volume geometry information, --replacegeom is needed - to override the input volume geometry and to proceed to writing - the data. - -``--replacegeom`` - - Replaces existing volume geometry information. Used in conjunction - with the ``--mghmri`` option described above. - -``--fifmri <*name*>`` - - Specifies a fif format MRI destription file which will be used to define - the coordinate transformation to be applied to the data read from - a dfs file to bring it to the same coordinate system as the MRI stack - in the file. - -``--trans <*name*>`` - - Specifies the name of a text file which contains the coordinate - transformation to be applied to the data read from the dfs file - to bring it to the MRI coordinates, see below. This option is rarely - needed. - -``--flip`` - - By default, the dfs surface nodes are assumed to be in a right-anterior-superior - (RAS) coordinate system with its origin at the left-posterior-inferior - (LPI) corner of the MRI stack. Sometimes the dfs file has left and - right flipped. This option reverses this flip, *i.e.*, - assumes the surface coordinate system is left-anterior-superior - (LAS) with its origin in the right-posterior-inferior (RPI) corner - of the MRI stack. - -``--shift <*value/mm*>`` - - Shift the surface vertices to the direction of the surface normals - by this amount before saving the surface. - -``--surfout <*name*>`` - - Specifies a FreeSurfer format output file. - -``--fifout <*name*>`` - - Specifies a fif format output file. - -``--triout <*name*>`` - - Specifies an ASCII output file that will contain the surface data - in the triangle file format described in :ref:`c_legacy_BEHDEFCD`. - -``--pntout <*name*>`` - - Specifies a ASCII output file which will contain the vertex numbers only. - -``--metersout`` - - With this option the ASCII output will list the vertex coordinates - in meters instead of millimeters. - -``--swapout`` - - Defines the vertex ordering of ASCII triangle files to be output. - For details, see ``--swap`` option, above. - -``--smfout <*name*>`` - - Specifies a smf (Simple Model Format) output file. For details of this - format, see http://people.sc.fsu.edu/~jburkardt/data/smf/smf.txt. - -.. note:: Multiple output options can be specified to produce outputs in several different formats with a single invocation of mne_convert_surface . - -The coordinate transformation file specified with the ``--trans`` should contain -a 4 x 4 coordinate transformation matrix: - -.. math:: T = \begin{bmatrix} - R_{11} & R_{12} & R_{13} & x_0 \\ - R_{13} & R_{13} & R_{13} & y_0 \\ - R_{13} & R_{13} & R_{13} & z_0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} - -defined so that if the augmented location vectors in the -dfs file and MRI coordinate systems are denoted by :math:`r_{dfs} = [x_{dfs} y_{dfs} z_{dfs} 1]^T` and :math:`r_{MRI} = [x_{MRI} y_{MRI} z_{MRI} 1]^T`, -respectively, - -.. math:: r_{MRI} = Tr_{dfs} - - -.. _mne_cov2proj: - -mne_cov2proj -============ - -Purpose -------- - -The utility mne_cov2proj picks -eigenvectors from a covariance matrix and outputs them as a signal-space -projection (SSP) file. - -Command line options --------------------- - -mne_cov2proj accepts the -following command-line options: - -``--cov <*name*>`` - - The covariance matrix file to be used a source. The covariance matrix - files usually end with ``-cov.fif`` . - -``--proj <*name*>`` - - The output file to contain the projection. It is recommended that - the file name ends with ``-proj.fif`` . - -``--bad <*name*>`` - - Specify channels not to be included when an eigenvalue decomposition - of the covariance matrix is computed. - -``--include <*val1*> [: <*val2*> ]`` - - Select an eigenvector or a range of eigenvectors to include. It - is recommended that magnetometers, gradiometers, and EEG data are handled - separately with help of the ``--bad`` , ``--meg`` , ``--megmag`` , ``--meggrad`` , - and ``--eeg`` options. - -``--meg`` - - After loading the covariance matrix, modify it so that only elements corresponding - to MEG channels are included. - -``--eeg`` - - After loading the covariance matrix, modify it so that only elements corresponding - to EEG channels are included. - -``--megmag`` - - After loading the covariance matrix, modify it so that only elements corresponding - to MEG magnetometer channels are included. - -``--meggrad`` - - After loading the covariance matrix, modify it so that only elements corresponding - to MEG planar gradiometer channels are included. - -.. note:: The ``--megmag`` and ``--meggrad`` employ the Vectorview channel numbering scheme to recognize MEG magnetometers (channel names ending with '1') and planar gradiometers (other channels). Therefore, these options are only meaningful in conjunction with data acquired with a Neuromag Vectorview system. - - -.. _mne_create_comp_data: - -mne_create_comp_data -==================== - -``--in <*name*>`` - - Specifies the input text file containing the compensation data. - -``--kind <*value*>`` - - The compensation type to be stored in the output file with the data. This - value defaults to 101 for the Magnes compensation and does not need - to be changed. - -``--out <*name*>`` - - Specifies the output fif file containing the compensation channel weight - matrix :math:`C_{(k)}`, see :ref:`BEHDDFBI`. - -The format of the text-format compensation data file is: - - <*number of MEG helmet channels*> <*number of compensation channels included*> - <*cname_1*> <*cname_2*> ... - <*name_1*> <*weights*> - <*name_2*> <*weights*> ... - -In the above <*name_k*> denote -names of MEG helmet channels and <*cname_k*> -those of the compensation channels, respectively. If the channel -names contain spaces, they must be surrounded by quotes, for example, ``"MEG 0111"`` . - - - -.. _mne_ctf2fiff: - -mne_ctf2fiff -============ - -``--verbose`` - - Produce a verbose listing of the conversion process to stdout. - -``--ds <*directory*>`` - - Read the data from this directory - -``--omit <*filename*>`` - - Read the names of channels to be omitted from this text file. Enter one - channel name per line. The names should match exactly with those - listed in the CTF data structures. By default, all channels are included. - -``--fif <*filename*>`` - - The name of the output file. If the length of the raw data exceeds - the 2-GByte fif file limit, several output files will be produced. - These additional 'extension' files will be tagged - with ``_001.fif`` , ``_002.fif`` , etc. - -``--evoked`` - - Produce and evoked-response fif file instead of a raw data file. - Each trial in the CTF data file is included as a separate category - (condition). The maximum number of samples in each trial is limited - to 25000. - -``--infoonly`` - - Write only the measurement info to the output file, do not include data. - -During conversion, the following files are consulted from -the ds directory: - -`` <*name*> .res4`` - - This file contains most of the header information pertaining the acquisition. - -`` <*name*> .hc`` - - This file contains the HPI coil locations in sensor and head coordinates. - -`` <*name*> .meg4`` - - This file contains the actual MEG data. If the data are split across several - files due to the 2-GByte file size restriction, the 'extension' files - are called <*name*> ``.`` <*number*> ``_meg4`` . - -`` <*name*> .eeg`` - - This is an optional input file containing the EEG electrode locations. More - details are given below. - -If the <*name*> ``.eeg`` file, -produced from the Polhemus data file with CTF software, is present, -it is assumed to contain lines with the format: - - <*number*> <*name*> <*x/cm*> <*y/cm*> <*z/cm*> - -The field <*number*> is -a sequential number to be assigned to the converted data point in -the fif file. <*name*> is either -a name of an EEG channel, one of ``left`` , ``right`` , -or ``nasion`` to indicate a fiducial landmark, or any word -which is not a name of any channel in the data. If <*name*> is -a name of an EEG channel available in the data, the location is -included in the Polhemus data as an EEG electrode locations and -inserted as the location of the EEG electrode. If the name is one -of the fiducial landmark names, the point is included in the Polhemus -data as a fiducial landmark. Otherwise, the point is included as -an additional head surface points. - -The standard ``eeg`` file produced by CTF software -does not contain the fiducial locations. If desired, they can be -manually copied from the ``pos`` file which was the source -of the ``eeg`` file. - -.. note:: In newer CTF data the EEG position information maybe present in the ``res4`` file. If the ``eeg`` file is present, the positions given there take precedence over the information in the ``res4`` file. - -.. note:: mne_ctf2fiff converts both epoch mode and continuous raw data file into raw data fif files. It is not advisable to use epoch mode files with time gaps between the epochs because the data will be discontinuous in the resulting fif file with jumps at the junctions between epochs. These discontinuities produce artifacts if the raw data is filtered in mne_browse_raw , mne_process_raw , or graph . - -.. note:: The conversion process includes a transformation from the CTF head coordinate system convention to that used in the Neuromag systems. - - -.. _mne_ctf_dig2fiff: - -mne_ctf_dig2fiff -================ - -The input data to mne_ctf_dig2fiff is -a text file, which contains the coordinates of the digitization -points in centimeters. The first line should contain a single number -which is the number of points listed in the file. Each of the following -lines contains a sequential number of the point, followed by the -three coordinates. mne_ctf_dig2fiff ignores -any text following the :math:`z` coordinate -on each line. If the ``--numfids`` option is specified, -the first three points indicate the three fiducial locations (1 -= nasion, 2 = left auricular point, 3 = right auricular point). -Otherwise, the input file must end with three lines beginning with ``left`` , ``right`` , -or ``nasion`` to indicate the locations of the fiducial -landmarks, respectively. - -.. note:: The sequential numbers should be unique within a file. I particular, the numbers 1, 2, and 3 must not be appear more than once if the ``--numfids`` options is used. - -The command-line options for mne_ctf_dig2fiff are: - -``--dig <*name*>`` - - Specifies the input data file in CTF output format. - -``--numfids`` - - Fiducial locations are numbered instead of labeled, see above. - -``--hpts <*name*>`` - - Specifies the output hpts file. The format of this text file is - described in :ref:`CJADJEBH`. - -``--fif <*name*>`` - - Specifies the output fif file. - - -.. _mne_dicom_essentials: - -mne_dicom_essentials -==================== - -Print essential information about a dicom file. - -``--in `` - - The input file. - - -.. _mne_edf2fiff: - -mne_edf2fiff -============ - -The mne_edf2fiff allows -conversion of EEG data from EDF, EDF+, and BDF formats to the fif -format. Documentation for these three input formats can be found -at: - -``EDF:`` - - http://www.edfplus.info/specs/edf.html - -``EDF+:`` - - http://www.edfplus.info/specs/edfplus.html - -``BDF:`` - - http://www.biosemi.com/faq/file_format.htm - -EDF (European Data Format) and EDF+ are 16-bit formats while -BDF is a 24-bit variant of this format used by the EEG systems manufactured -by a company called BioSemi. - -None of these formats support electrode location information -and head shape digitization information. Therefore, this information -has to be provided separately. Presently hpts and elp file formats -are supported to include digitization data. For information on these -formats, see :ref:`CJADJEBH` and http://www.sourcesignal.com/formats_probe.html. -Note that it is mandatory to have the three fiducial locations (nasion -and the two auricular points) included in the digitization data. -Using the locations of the fiducial points the digitization data -are converted to the MEG head coordinate system employed in the -MNE software, see :ref:`c_legacy_BJEBIBAI`. In the comparison of the -channel names only the initial segment up to the first '-' (dash) -in the EDF/EDF+/BDF channel name is significant. - -The EDF+ files may contain an annotation channel which can -be used to store trigger information. The Time-stamped Annotation -Lists (TALs) on the annotation data can be converted to a trigger -channel (STI 014) using an annotation map file which associates -an annotation label with a number on the trigger channel. The TALs -can be listed with the ``--listtal`` option, -see below. - -.. warning:: The data samples in a BDF file are represented in a 3-byte (24-bit) format. Since 3-byte raw data buffers are not presently supported in the fif format these data will be changed to 4-byte integers in the conversion. Since the maximum size of a fif file is 2 GBytes, the maximum size of a BDF file to be converted is approximately 1.5 GBytes - -.. warning:: The EDF/EDF+/BDF formats support channel dependent sampling rates. This feature is not supported by mne_edf2fiff . However, the annotation channel in the EDF+ format can have a different sampling rate. The annotation channel data is not included in the fif files output. - -Using mne_edf2fiff ------------------- - -The command-line options of mne_edf2fiff are: - -``--edf <*filename*>`` - - Specifies the name of the raw data file to process. - -``--tal <*filename*>`` - - List the time-stamped annotation list (TAL) data from an EDF+ file here. - This output is useful to assist in creating the annotation map file, - see the ``--annotmap`` option, below. - This output file is an event file compatible with mne_browse_raw and mne_process_raw , - see :ref:`ch_browse`. In addition, in the mapping between TAL - labels and trigger numbers provided by the ``--annotmap`` option is - employed to assign trigger numbers in the event file produced. In - the absence of the ``--annotmap`` option default trigger number 1024 - is used. - -``--annotmap <*filename*>`` - - Specify a file which maps the labels of the TALs to numbers on a trigger - channel (STI 014) which will be added to the output file if this - option is present. This annotation map file - may contain comment lines starting with the '%' or '#' characters. - The data lines contain a label-number pair, separated by a colon. - For example, a line 'Trigger-1:9' means that each - annotation labeled with the text 'Trigger-1' will - be translated to the number 9 on the trigger channel. - -``--elp <*filename*>`` - - Specifies the name of the an electrode location file. This file - is in the "probe" file format used by the *Source - Signal Imaging, Inc.* software. For description of the - format, see http://www.sourcesignal.com/formats_probe.html. Note - that some other software packages may produce electrode-position - files with the elp ending not - conforming to the above specification. As discussed above, the fiducial - marker locations, optional in the "probe" file - format specification are mandatory for mne_edf2fiff . - When this option is encountered on the command line any previously - specified hpts file will be ignored. - -``--hpts <*filename*>`` - - Specifies the name of an electrode position file in the hpts format discussed - in :ref:`CJADJEBH`. The mandatory entries are the fiducial marker - locations and the EEG electrode locations. It is recommended that - electrode (channel) names instead of numbers are used to label the - EEG electrode locations. When this option is encountered on the - command line any previously specified elp file - will be ignored. - -``--meters`` - - Assumes that the digitization data in an hpts file - is given in meters instead of millimeters. - -``--fif <*filename*>`` - - Specifies the name of the fif file to be output. - -Post-conversion tasks ---------------------- - -This section outlines additional steps to be taken to use -the EDF/EDF+/BDF file is converted to the fif format in MNE: - -- Some of the channels may not have a - digitized electrode location associated with them. If these channels - are used for EOG or EMG measurements, their channel types should - be changed to the correct ones using the :ref:`mne_rename_channels` utility, - EEG channels which do not have a location - associated with them should be assigned to be MISC channels. - -- After the channel types are correctly defined, a topographical - layout file can be created for mne_browse_raw and mne_analyze using - the :ref:`mne_make_eeg_layout` utility. - -- The trigger channel name in BDF files is "Status". - This must be specified with the ``--digtrig`` option or with help of - the MNE_TRIGGER_CH_NAME environment variable when :ref:`mne_browse_raw` or - :ref:`mne_process_raw` is invoked. - -- Only the two least significant bytes on the "Status" channel - of BDF files are significant as trigger information the ``--digtrigmask`` - 0xff option MNE_TRIGGER_CH_MASK environment variable should be used - to specify this to :ref:`mne_browse_raw` and :ref:`mne_process_raw`, - - -.. _mne_epochs2mat: - -mne_epochs2mat -============== - -The utility mne_epochs2mat converts -epoch data including all or selected channels from a raw data file -to a simple binary file with an associated description file in Matlab -mat file format. With help of the description file, a matlab program -can easily read the epoch data from the simple binary file. Signal -space projection and bandpass filtering can be optionally applied -to the raw data prior to saving the epochs. - -.. note:: The MNE Matlab toolbox described in :ref:`ch_matlab` provides direct access to raw fif files without conversion with mne_epochs2mat first. Therefore, it is recommended that you use the Matlab toolbox rather than mne_epochs2mat which creates large files occupying disk space unnecessarily. An exception to this is the case where you apply a filter to the data and save the band-pass filtered epochs. - -Command-line options --------------------- - -mne_epochs2mat accepts -the following command-line options are: - -``--raw <*name*>`` - - Specifies the name of the raw data fif file to use as input. - -``--mat <*name*>`` - - Specifies the name of the destination file. Anything following the last - period in the file name will be removed before composing the output - file name. The binary epoch file will be called <*trimmed name*> ``.epochs`` and - the corresponding Matlab description file will be <*trimmed name*> ``_desc.mat`` . - -``--tag <*tag*>`` - - By default, all Matlab variables included in the description file - start with ``mne\_``. This option changes the prefix to <*tag*> _. - -``--events <*name*>`` - - The file containing the event definitions. This can be a text or - fif format file produced by :ref:`mne_process_raw` or - :ref:`mne_browse_raw`. With help of this file it is possible - to select virtually any data segment from the raw data file. If - this option is missing, the digital trigger channel in the raw data - file or a fif format event file produced automatically by mne_process_raw or mne_browse_raw is - consulted for event information. - -``--event <*name*>`` - - Event number identifying the epochs of interest. - -``--tmin <*time/ms*>`` - - The starting point of the epoch with respect to the event of interest. - -``--tmax <*time/ms*>`` - - The endpoint of the epoch with respect to the event of interest. - -``--sel <*name*>`` - - Specifies a text file which contains the names of the channels to include - in the output file, one channel name per line. If the ``--inv`` option - is specified, ``--sel`` is ignored. If neither ``--inv`` nor ``--sel`` is - present, all MEG and EEG channels are included. The digital trigger - channel can be included with the ``--includetrig`` option, described - below. - -``--inv <*name*>`` - - Specifies an inverse operator, which will be employed in two ways. First, - the channels included to output will be those included in the inverse - operator. Second, any signal-space projection operator present in - the inverse operator file will be applied to the data. This option - cancels the effect of ``--sel`` and ``--proj`` options. - -``--digtrig <*name*>`` - - Name of the composite digital trigger channel. The default value - is 'STI 014'. Underscores in the channel name - will be replaced by spaces. - -``--digtrigmask <*number*>`` - - Mask to be applied to the trigger channel values before considering them. - This option is useful if one wants to set some bits in a don't care - state. For example, some finger response pads keep the trigger lines - high if not in use, *i.e.*, a finger is not in - place. Yet, it is convenient to keep these devices permanently connected - to the acquisition system. The number can be given in decimal or - hexadecimal format (beginning with 0x or 0X). For example, the value - 255 (0xFF) means that only the lowest order byte (usually trigger - lines 1 - 8 or bits 0 - 7) will be considered. - -``--includetrig`` - - Add the digital trigger channel to the list of channels to output. - This option should not be used if the trigger channel is already - included in the selection specified with the ``--sel`` option. - -``--filtersize <*size*>`` - - Adjust the length of the FFT to be applied in filtering. The number will - be rounded up to the next power of two. If the size is :math:`N`, - the corresponding length of time is :math:`^N/_{f_s}`, - where :math:`f_s` is the sampling frequency - of your data. The filtering procedure includes overlapping tapers - of length :math:`^N/_2` so that the total FFT - length will actually be :math:`2N`. The default - value is 4096. - -``--highpass <*value/Hz*>`` - - Highpass filter frequency limit. If this is too low with respect - to the selected FFT length and data file sampling frequency, the - data will not be highpass filtered. You can experiment with the - interactive version to find the lowest applicable filter for your - data. This value can be adjusted in the interactive version of the - program. The default is 0, i.e., no highpass filter in effect. - -``--highpassw <*value/Hz*>`` - - The width of the transition band of the highpass filter. The default - is 6 frequency bins, where one bin is :math:`^{f_s}/_{(2N)}`. - -``--lowpass <*value/Hz*>`` - - Lowpass filter frequency limit. This value can be adjusted in the interactive - version of the program. The default is 40 Hz. - -``--lowpassw <*value/Hz*>`` - - The width of the transition band of the lowpass filter. This value - can be adjusted in the interactive version of the program. The default - is 5 Hz. - -``--filteroff`` - - Do not filter the data. - -``--proj <*name*>`` - - Include signal-space projection (SSP) information from this file. - If the ``--inv`` option is present, ``--proj`` has - no effect. - -.. note:: Baseline has not been subtracted from the epochs. This has to be done in subsequent processing with Matlab if so desired. - -.. note:: Strictly speaking, trigger mask value zero would mean that all trigger inputs are ignored. However, for convenience, setting the mask to zero or not setting it at all has the same effect as 0xFFFFFFFF, *i.e.*, all bits set. - -.. note:: The digital trigger channel can also be set with the MNE_TRIGGER_CH_NAME environment variable. Underscores in the variable value will *not* be replaced with spaces by mne_browse_raw or mne_process_raw . Using the ``--digtrig`` option supersedes the MNE_TRIGGER_CH_NAME environment variable. - -.. note:: The digital trigger channel mask can also be set with the MNE_TRIGGER_CH_MASK environment variable. Using the ``--digtrigmask`` option supersedes the MNE_TRIGGER_CH_MASK environment variable. - -The binary epoch data file --------------------------- - -mne_epochs2mat saves the -epoch data extracted from the raw data file is a simple binary file. -The data are stored as big-endian single-precision floating point -numbers. Assuming that each of the total of :math:`p` epochs -contains :math:`n` channels and :math:`m` time -points, the data :math:`s_{jkl}` are ordered -as - -.. math:: s_{111} \dotso s_{1n1} s_{211} \dotso s_{mn1} \dotso s_{mnp}\ , - -where the first index stands for the time point, the second -for the channel, and the third for the epoch number, respectively. -The data are not calibrated, i.e., the calibration factors present -in the Matlab description file have to be applied to get to physical -units as described below. - -.. note:: The maximum size of an epoch data file is 2 Gbytes, *i.e.*, 0.5 Gsamples. - -Matlab data structures ----------------------- - -The Matlab description files output by mne_epochs2mat contain -a data structure <*tag*>_epoch_info . -The fields of the this structure are listed in :ref:`BEHFDCIH`. -Further explanation of the epochs member -is provided in :ref:`BEHHAGHE`. - - -.. tabularcolumns:: |p{0.15\linewidth}|p{0.15\linewidth}|p{0.6\linewidth}| -.. _BEHIFJIJ: -.. table:: The fields of the raw data info structure. - - +-----------------------+-----------------+------------------------------------------------------------+ - | Variable | Size | Description | - +-----------------------+-----------------+------------------------------------------------------------+ - | orig_file | string | The name of the original fif file specified with the | - | | | ``--raw`` option. | - +-----------------------+-----------------+------------------------------------------------------------+ - | epoch_file | string | The name of the epoch data file produced by mne_epocs2mat. | - +-----------------------+-----------------+------------------------------------------------------------+ - | nchan | 1 | Number of channels. | - +-----------------------+-----------------+------------------------------------------------------------+ - | nepoch | 1 | Total number of epochs. | - +-----------------------+-----------------+------------------------------------------------------------+ - | epochs | nepoch x 5 | Description of the content of the epoch data file, | - | | | see :ref:`BEHHAGHE`. | - +-----------------------+-----------------+------------------------------------------------------------+ - | sfreq | 1 | The sampling frequency in Hz. | - +-----------------------+-----------------+------------------------------------------------------------+ - | lowpass | 1 | Lowpass filter frequency (Hz) | - +-----------------------+-----------------+------------------------------------------------------------+ - | highpass | 1 | Highpass filter frequency (Hz) | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_names | nchan (string) | String array containing the names of the channels included | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_types | nchan x 2 | The column lists the types of the channels (1 = MEG, 2 = | - | | | EEG). The second column lists the coil types, see | - | | | :ref:`c_legacy_BGBBHGEC` and :ref:`c_legacy_CHDBDFJE`. | - | | | For EEG electrodes, this value equals one. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_lognos | nchan x 1 | Logical channel numbers as listed in the fiff file | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_units | nchan x 2 | Units and unit multipliers as listed in the fif file. | - | | | The unit of the data is listed in the first column | - | | | (T = 112, T/m = 201, V = 107). At present, the second | - | | | column will be always zero, *i.e.*, no unit multiplier. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_pos | nchan x 12 | The location information for each channel. The first three | - | | | values specify the origin of the sensor coordinate system | - | | | or the location of the electrode. For MEG channels, the | - | | | following nine number specify the *x*, *y*, and | - | | | *z*-direction unit vectors of the sensor coordinate | - | | | system. For EEG electrodes the first vector after the | - | | | electrode location specifies the location of the reference | - | | | electrode. If the reference is not specified this value is | - | | | all zeroes. The remaining unit vectors are irrelevant for | - | | | EEG electrodes. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_cals | nchan x 2 | The raw data output by mne_raw2mat are not calibrated. | - | | | The first column is the range member of the fiff data | - | | | structures and while the second is the cal member. To | - | | | get calibrated data values in the units given in | - | | | ch_units from the raw data, the data must be multiplied | - | | | with the product of range and cal . | - +-----------------------+-----------------+------------------------------------------------------------+ - | meg_head_trans | 4 x 4 | The coordinate frame transformation from the MEG device | - | | | coordinates to the MEG head coordinates. | - +-----------------------+-----------------+------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.6\linewidth}| -.. _BEHHAGHE: -.. table:: The epochs member of the raw data info structure. - - +---------------+------------------------------------------------------------------+ - | Column | Contents | - +---------------+------------------------------------------------------------------+ - | 1 | The raw data type (2 or 16 = 2-byte signed integer, 3 = 4-byte | - | | signed integer, 4 = single-precision float). The epoch data are | - | | written using the big-endian byte order. The data are stored | - | | sample by sample. | - +---------------+------------------------------------------------------------------+ - | 2 | Byte location of this epoch in the binary epoch file. | - +---------------+------------------------------------------------------------------+ - | 3 | First sample of this epoch in the original raw data file. | - +---------------+------------------------------------------------------------------+ - | 4 | First sample of the epoch with respect to the event. | - +---------------+------------------------------------------------------------------+ - | 5 | Number of samples in the epoch. | - +---------------+------------------------------------------------------------------+ - -.. note:: For source modelling purposes, it is recommended that the MNE Matlab toolbox, see :ref:`ch_matlab` is employed to read the measurement info instead of using the channel information in the raw data info structure described in :ref:`BEHIFJIJ`. - - -.. _mne_evoked_data_summary: - -mne_evoked_data_summary -======================= - -Print a summary of evoked-response data sets in a file (averages only). - -``--in `` - - The input file. - - -.. _mne_eximia2fiff: - -mne_eximia2fiff -=============== - -Usage: - -``mne_eximia2fiff`` [``--dig`` dfile ] [``--orignames`` ] file1 file2 ... - -where file1 file2 ... -are eXimia ``nxe`` files and the ``--orignames`` option -is passed on to :ref:`mne_brain_vision2fiff`. -If you want to convert all data files in a directory, say - -``mne_eximia2fiff *.nxe`` - -The optional file specified with the ``--dig`` option is assumed -to contain digitizer data from the recording in the Nexstim format. -The resulting fif data file will contain these data converted to -the fif format as well as the coordinate transformation between -the eXimia digitizer and MNE head coordinate systems. - -.. note:: This script converts raw data files only. - - -.. _mne_fit_sphere_to_surf: - -mne_fit_sphere_to_surf -====================== - -Purpose -------- - -The utility mne_fit_sphere_to_surf finds -the sphere which best fits a given surface. - -Command line options --------------------- - -mne_fit_sphere_to_surf accepts -the following command-line options: - -``--bem <*name*>`` - - A BEM file to use. The names of these files usually end with ``bem.fif`` or ``bem-sol.fif`` . - -``--surf <*name*>`` - - A FreeSurfer surface file to read. This is an alternative to using - a surface from the BEM file. - -``--scalp`` - - Use the scalp surface instead of the inner skull surface in sphere - fitting. If the surface is specified with the ``--surf`` option, - this one is irrelevant. - -``--mritrans <*name*>`` - - A file containing a transformation matrix between the MEG head coordinates - and MRI coordinates. With this option, the sphere origin will be - output in MEG head coordinates. Otherwise the output will be in MRI - coordinates. - - -.. _mne_fix_mag_coil_types: - -mne_fix_mag_coil_types -====================== - -The purpose of mne_fix_mag_coil_types is -to change coil type 3022 to 3024 in the MEG channel definition records -in the data files specified on the command line. - -As shown in Tables 5.2 and 5.3, the Neuromag Vectorview systems -can contain magnetometers with two different coil sizes (coil types -3022 and 3023 vs. 3024). The systems incorporating coils of type -3024 were introduced last. At some sites the data files have still -defined the magnetometers to be of type 3022 to ensure compatibility -with older versions of Neuromag software. In the MNE software as -well as in the present version of Neuromag software coil type 3024 -is fully supported. Therefore, it is now safe to upgrade the data -files to use the true coil type. - -If the ``--magnes`` option is specified, the 4D -Magnes magnetometer coil type (4001) is changed to 4D Magnes gradiometer -coil type (4002). Use this option always and *only -if* your Magnes data comes from a system with axial gradiometers -instead of magnetometers. The fif converter included with the Magnes -system does not assign the gradiometer coil type correctly. - -.. note:: The effect of the difference between the coil sizes of magnetometer types 3022 and 3024 on the current estimates computed by the MNE software is very small. Therefore the use of mne_fix_mag_coil_types is not mandatory. - - -.. _mne_fix_stim14: - -mne_fix_stim14 -============== - -Some earlier versions of the Neuromag acquisition software -had a problem with the encoding of the eighth bit on the digital -stimulus channel STI 014. This problem has been now fixed. Old data -files can be fixed with mne_fix_stim14 , -which takes raw data file names as arguments. mne_fix_stim14 also -changes the calibration of STI 014 to unity. If the encoding of -STI 014 is already correct, running mne_fix_stim14 will -not have any effect on the raw data. - -In newer Neuromag Vectorview systems with 16-bit digital -inputs the upper two bytes of the samples may be incorrectly set -when stimulus input 16 is used and the data are acquired in the -32-bit mode. This problem can be fixed by running mne_fix_stim14 on -a raw data file with the ``--32`` option: - -``mne_fix_stim14 --32`` <*raw data file*> - -In this case, the correction will be applied to the stimulus -channels 'STI101' and 'STI201'. - - -.. _mne_flash_bem: - -mne_flash_bem -============= - -``--help`` - - Prints the usage information. - -``--usage`` - - Prints the usage information. - -``--noconvert`` - - Skip conversion of the original MRI data. The original data are - not needed and the preparatory steps 1.-3. listed below - are thus not needed. - -``--noflash30`` - - The 30-degree flip angle data are not used. - -``--unwarp <*type*>`` - - Run grad_unwarp with ``--unwarp`` <*type*> option on each of the converted - data sets. - - -.. _mne_insert_4D_comp: - -mne_insert_4D_comp -================== - -Import Magnes WH3600 reference channel data from a text file. - -``--in `` - - The name of the fif file containing the helmet data. - -``--ref `` - - The name of the text file containing the reference channel data. - -``--out `` - - The output fif file. - - -.. _mne_kit2fiff: - -mne_kit2fiff -============ - -The utility mne_kit2fiff was -created in collaboration with Alec Maranz and Asaf Bachrach to import -their MEG data acquired with the 160-channel KIT MEG system to MNE -software. - -To import the data, the following input files are mandatory: - -- The Polhemus data file (elp file) - containing the locations of the fiducials and the head-position - indicator (HPI) coils. These data are usually given in the CTF/4D - head coordinate system. However, mne_kit2fiff does - not rely on this assumption. This file can be exported directly from - the KIT system. - -- A file containing the locations of the HPI coils in the MEG - device coordinate system. These data are used together with the elp file - to establish the coordinate transformation between the head and - device coordinate systems. This file can be produced easily by manually - editing one of the files exported by the KIT system. - -- A sensor data file (sns file) - containing the locations and orientations of the sensors. This file - can be exported directly from the KIT system. - -.. note:: The output fif file will use the Neuromag head coordinate system convention, see :ref:`c_legacy_BJEBIBAI`. A coordinate transformation between the CTF/4D head coordinates and the Neuromag head coordinates is included. This transformation can be read with MNE Matlab Toolbox routines, see :ref:`ch_matlab`. - -The following input files are optional: - -- A head shape data file (hsp file) - containing locations of additional points from the head surface. - These points must be given in the same coordinate system as that - used for the elp file and the - fiducial locations must be within 1 mm from those in the elp file. - -- A raw data file containing the raw data values, sample by - sample, as text. If this file is not specified, the output fif file - will only contain the measurement info block. - -By default mne_kit2fiff includes -the first 157 channels, assumed to be the MEG channels, in the output -file. The compensation channel data are not converted by default -but can be added, together with other channels, with the ``--type`` . -The channels from 160 onwards are designated as miscellaneous input -channels (MISC 001, MISC 002, etc.). The channel names and types -of these channels can be afterwards changed with the :ref:`mne_rename_channels` -utility. In addition, it is possible to synthesize -the digital trigger channel (STI 014) from available analog -trigger channel data, see the ``--stim`` option, below. -The synthesized trigger channel data value at sample :math:`k` will -be: - -.. math:: s(k) = \sum_{p = 1}^n {t_p(k) 2^{p - 1}}\ , - -where :math:`t_p(k)` are the thresholded -from the input channel data d_p(k): - -.. math:: t_p(k) = \Bigg\{ \begin{array}{l} - 0 \text{ if } d_p(k) \leq t\\ - 1 \text{ if } d_p(k) > t - \end{array}\ . - -The threshold value :math:`t` can -be adjusted with the ``--stimthresh`` option, see below. - -mne_kit2fiff accepts the following command-line options: - -``--elp <*filename*>`` - - The name of the file containing the locations of the fiducials and - the HPI coils. This option is mandatory. - -``--hsp <*filename*>`` - - The name of the file containing the locations of the fiducials and additional - points on the head surface. This file is optional. - -``--sns <*filename*>`` - - The name of file containing the sensor locations and orientations. This - option is mandatory. - -``--hpi <*filename*>`` - - The name of a text file containing the locations of the HPI coils - in the MEG device coordinate frame, given in millimeters. The order of - the coils in this file does not have to be the same as that in the elp file. - This option is mandatory. - -``--raw <*filename*>`` - - Specifies the name of the raw data file. If this file is not specified, the - output fif file will only contain the measurement info block. - -``--sfreq <*value/Hz*>`` - - The sampling frequency of the data. If this option is not specified, the - sampling frequency defaults to 1000 Hz. - -``--lowpass <*value/Hz*>`` - - The lowpass filter corner frequency used in the data acquisition. - If not specified, this value defaults to 200 Hz. - -``--highpass <*value/Hz*>`` - - The highpass filter corner frequency used in the data acquisition. - If not specified, this value defaults to 0 Hz (DC recording). - -``--out <*filename*>`` - - Specifies the name of the output fif format data file. If this file - is not specified, no output is produced but the elp , hpi , - and hsp files are processed normally. - -``--stim <*chs*>`` - - Specifies a colon-separated list of numbers of channels to be used - to synthesize a digital trigger channel. These numbers refer to - the scanning order channels as listed in the sns file, - starting from one. The digital trigger channel will be the last - channel in the file. If this option is absent, the output file will - not contain a trigger channel. - -``--stimthresh <*value*>`` - - The threshold value used when synthesizing the digital trigger channel, - see above. Defaults to 1.0. - -``--add <*chs*>`` - - Specifies a colon-separated list of numbers of channels to include between - the 157 default MEG channels and the digital trigger channel. These - numbers refer to the scanning order channels as listed in the sns file, - starting from one. - -.. note:: The mne_kit2fiff utility has not been extensively tested yet. - - -.. _mne_list_bem: - -mne_list_bem -============ - -The utility mne_list_bem outputs -the BEM meshes in text format. The default output data contains -the *x*, *y*, and *z* coordinates -of the vertices, listed in millimeters, one vertex per line. - -The command-line options are: - -``--bem <*name*>`` - - The BEM file to be listed. The file name normally ends with -bem.fif or -bem-sol.fif . - -``--out <*name*>`` - - The output file name. - -``--id <*number*>`` - - Identify the surface to be listed. The surfaces are numbered starting with - the innermost surface. Thus, for a three-layer model the surface numbers - are: 4 = scalp, 3 = outer skull, 1 = inner skull - Default value is 4. - -``--gdipoli`` - - List the surfaces in the format required by Thom Oostendorp's - gdipoli program. This is also the default input format for mne_surf2bem . - -``--meters`` - - List the surface coordinates in meters instead of millimeters. - -``--surf`` - - Write the output in the binary FreeSurfer format. - -``--xfit`` - - Write a file compatible with xfit. This is the same effect as using - the options ``--gdipoli`` and ``--meters`` together. - - -.. _mne_list_coil_def: - -mne_list_coil_def -================= - -List available coil definitions. - -``--in `` - - Validate a coil definition file. - -``--out `` - - List the coil definitions to this file (default: stdout). - -``--type `` - - Coil type to list. - - -.. _mne_list_proj: - -mne_list_proj -============= - -``--in `` - - Input file. - -``--ascin `` - - Input file. - -``--exclude `` - - Exclude these channels from the projection (set entries to zero). - -``--chs `` - - Specify a file which contains a channel selection for the output (useful for graph) - -``--asc `` - - Text output. - -``--fif `` - - Fif output. - -``--lisp `` - - Lisp output. - - -.. _mne_list_source_space: - -mne_list_source_space -===================== - -The utility mne_list_source_space outputs -the source space information into text files suitable for loading -into the Neuromag MRIlab software. - -``--src <*name*>`` - - The source space to be listed. This can be either the output from mne_make_source_space - (`*src.fif`), output from the forward calculation (`*fwd.fif`), or - the output from the inverse operator decomposition (`*inv.fif`). - -``--mri <*name*>`` - - A file containing the transformation between the head and MRI coordinates - is specified with this option. This file can be either a Neuromag - MRI description file, the output from the forward calculation (`*fwd.fif`), - or the output from the inverse operator decomposition (`*inv.fif`). - If this file is included, the output will be in head coordinates. - Otherwise the source space will be listed in MRI coordinates. - -``--dip <*name*>`` - - Specifies the 'stem' for the Neuromag text format - dipole files to be output. Two files will be produced: <*stem*> -lh.dip - and <*stem*> -rh.dip. These correspond - to the left and right hemisphere part of the source space, respectively. - This source space data can be imported to MRIlab through the File/Import/Dipoles menu - item. - -``--pnt <*name*>`` - - Specifies the 'stem' for Neuromag text format - point files to be output. Two files will be produced: <*stem*> -lh.pnt - and <*stem*> -rh.pnt. These correspond - to the left and right hemisphere part of the source space, respectively. - This source space data can be imported to MRIlab through the File/Import/Strings menu - item. - -``--exclude <*name*>`` - - Exclude the source space points defined by the given FreeSurfer 'label' file - from the output. The name of the file should end with ``-lh.label`` - if it refers to the left hemisphere and with ``-rh.label`` if - it lists points in the right hemisphere, respectively. - -``--include <*name*>`` - - Include only the source space points defined by the given FreeSurfer 'label' file - to the output. The file naming convention is the same as described - above under the ``--exclude`` option. Are 'include' labels are - processed before the 'exclude' labels. - -``--all`` - - Include all nodes in the output files instead of only those active - in the source space. Note that the output files will be huge if - this option is active. - - -.. _mne_list_versions: - -mne_list_versions -================= - -The utility mne_list_versions lists -version numbers and compilation dates of all software modules that -provide this information. This administration utility is located -in ``$MNE_ROOT/bin/admin`` , The output from mne_list_versions or -output of individual modules with ``--version`` option -is useful when bugs are reported to the developers of MNE software. - - -.. _mne_make_cor_set: - -mne_make_cor_set -================ - -The utility mne_make_cor_set creates -a fif format MRI description -file optionally including the MRI data using FreeSurfer MRI volume -data as input. The command-line options are: - -``--dir <*directory*>`` - - Specifies a directory containing the MRI volume in COR format. Any - previous ``--mgh`` options are cancelled when this option - is encountered. - -``--withdata`` - - Include the pixel data to the output file. This option is implied - with the ``--mgh`` option. - -``--mgh <*name*>`` - - An MRI volume volume file in mgh or mgz format. - The ``--withdata`` option is implied with this type of - input. Furthermore, the :math:`T_3` transformation, - the Talairach transformation :math:`T_4` from - the talairach.xfm file referred to in the MRI volume, and the the - fixed transforms :math:`T_-` and :math:`T_+` will - added to the output file. For definition of the coordinate transformations, - see :ref:`c_legacy_CHDEDFIB`. - -``--talairach <*name*>`` - - Take the Talairach transform from this file instead of the one specified - in mgh/mgz files. - -``--out <*name*>`` - - Specifies the output file, which is a fif-format MRI description - file. - - -.. _mne_make_derivations: - -mne_make_derivations -==================== - -Purpose -------- - -In mne_browse_raw , channel -derivations are defined as linear combinations of real channels -existing in the data files. The utility mne_make_derivations reads -derivation data from a suitably formatted text file and produces -a fif file containing the weights of derived channels as a sparse -matrix. Two input file formats are accepted: - -- A file containing arithmetic expressions - defining the derivations and - -- A file containing a matrix which specifies the weights of - the channels in each derivation. - -Both of these formats are described in - -Command-line options --------------------- - -mne_make_derivations recognizes -the following command-line options: - -``--in <*name*>`` - - Specifies a measurement file which contains the EEG electrode locations. - This file is not modified. - -``--inmat <*name*>`` - - Specifies the output file where the layout is stored. Suffix ``.lout`` is recommended - for layout files. mne_analyze and mne_browse_raw look - for the custom layout files from the directory ``$HOME/.mne/lout`` . - -``--trans`` - - Indicates that the file specified with the ``--inmat`` option - contains a transpose of the derivation matrix. - -``--thresh <*value*>`` - - Specifies the threshold between values to be considered zero and non-zero - in the input file specified with the ``--inmat`` option. - The default threshold is :math:`10^{-6}`. - -``--out <*name*>`` - - Specifies output fif file to contain the derivation data. The recommended - name of the derivation file has the format <:math:`name`> ``-deriv.fif`` . - -``--list <*name*>`` - - List the contents of a derivation file to standard output. If this - option is missing and ``--out`` is specified, the content - of the output file will be listed once it is complete. If neither ``--list`` nor ``--out`` is present, - and ``--in`` or ``--inmat`` is specified, the - interpreted contents of the input file is listed. - -Derivation file formats ------------------------ - -All lines in the input files starting with the pound sign -(#) are considered to be comments. The format of a derivation in -a arithmetic input file is: - -.. math:: \langle name \rangle = [\langle w_1 \rangle *] \langle name_1 \rangle + [\langle w_2 \rangle *] \langle name_2 \rangle \dotso - -where <:math:`name`> is the -name of the derived channel, :math:`name_k` are -the names of the channels comprising the derivation, and :math:`w_k` are -their weights. Note that spaces are necessary between the items. -Channel names containing spaces must be put in quotes. For example, - -``EEG-diff = "EEG 003" - "EEG 002"`` - -defines a channel ``EEG-diff`` which is a difference -between ``EEG 003`` and ``EEG 002`` . Similarly, - -``EEG-der = 3 * "EEG 010" - 2 * "EEG 002"`` - -defines a channel which is three times ``EEG 010`` minus -two times ``EEG 002`` . - -The format of a matrix derivation file is: - -.. math:: \langle nrow \rangle \langle ncol \rangle \langle names\ of\ the\ input\ channels \rangle \langle name_1 \rangle \langle weights \rangle \dotso - -The combination of the two arithmetic examples, above can -be thus represented as: - -``2 3 "EEG 002" "EEG 003" "EEG 010" EEG-diff -1 1 0 EEG-der -2 0 3`` - -Before a derivation is accepted to use by mne_browse_raw , -the following criteria have to be met: - -- All channels to be combined into a single - derivation must have identical units of measure. - -- All channels in a single derivation have to be of the same - kind, *e.g.*, MEG channels or EEG channels. - -- All channels specified in a derivation have to be present - in the currently loaded data set. - -The validity check is done when a derivation file is loaded -into mne_browse_raw , see :ref:`CACFHAFH`. - -.. note:: You might consider renaming the EEG channels with descriptive labels related to the standard 10-20 system using the :ref:`mne_rename_channels` utility. This allows you to use standard EEG channel names in the derivations you define as well as in the channel selection files used in mne_browse_raw , see :ref:`CACCJEJD`. - - -.. _mne_make_eeg_layout: - -mne_make_eeg_layout -=================== - -Purpose -------- - -Both MNE software (mne_analyze and mne_browse_raw) -and Neuromag software (xplotter and xfit) -employ text layout files to create topographical displays of MEG -and EEG data. While the MEG channel layout is fixed, the EEG layout -varies from experiment to experiment, depending on the number of -electrodes used and the electrode cap configuration. The utility mne_make_eeg_layout was -created to produce custom EEG layout files based on the EEG electrode -location information included in the channel description records. - -mne_make_eeg_layout uses -azimuthal equidistant projection to map the EEG channel locations -onto a plane. The mapping consists of the following steps: - -- A sphere is fitted to the electrode - locations and the locations are translated by the location of the - origin of the best-fitting sphere. - -- The spherical coordinates (:math:`r_k`, :math:`\theta_k`, and :math:`\phi_k`) - corresponding to each translated electrode location are computed. - -- The projected locations :math:`u_k = R \theta_k \cos{\phi_k}` and :math:`v_k = R \theta_k \sin{\phi_k}` are - computed. By default, :math:`R = 20/{^{\pi}/_2}`, *i.e.* at - the equator (:math:`\theta = ^{\pi}/_2`) the multiplier is - 20. This projection radius can be adjusted with the ``--prad`` option. - Increasing or decreasing :math:`R` makes - the spacing between the channel viewports larger or smaller, respectively. - -- A viewport with width 5 and height 4 is placed centered at - the projected location. The width and height of the viewport can - be adjusted with the ``--width`` and ``--height`` options - -The command-line options are: - -``--lout <*name*>`` - - Specifies the name of the layout file to be output. - -``--nofit`` - - Do not fit a sphere to the electrode locations but use a standard sphere - center (:math:`x = y = 0`, and :math:`z = 40` mm) instead. - -``--prad <*value*>`` - - Specifies a non-standard projection radius :math:`R`, - see above. - -``--width <*value*>`` - - Specifies the width of the viewports. Default value = 5. - -``--height <*value*>`` - - Specifies the height of the viewports. Default value = 4. - - -.. _mne_make_morph_maps: - -mne_make_morph_maps -=================== -Prepare the mapping data for subject-to-subject morphing. - -``--redo`` - - Recompute the morphing maps even if they already exist. - -``--from `` - - Compute morphing maps from this subject. - -``--to `` - - Compute morphing maps to this subject. - -``--all`` - - Do all combinations. If this is used without either ``--from`` or ``--to`` options, - morphing maps for all possible combinations are computed. If ``--from`` or ``--to`` is - present, only maps between the specified subject and all others - are computed. - -.. note:: Because all morphing map files contain maps in both directions, the choice of ``--from`` and ``--to`` options only affect the naming of the morphing map files to be produced. mne_make_morph_maps creates directory ``$SUBJECTS_DIR/morph-maps`` if necessary. - - -.. _mne_make_uniform_stc: - -mne_make_uniform_stc -==================== - -The output will have a time range from -100 to 300 ms. -There will be one cycle of 5-Hz sine wave, with the peaks at 50 and 150 ms - -``--src `` - - Source space to use. - -``--stc `` - - Stc file to produce. - -``--maxval `` - - Maximum value (at 50 ms, default 10). - -``--all`` - - Include all points to the output files. - - -.. _mne_mark_bad_channels: - -mne_mark_bad_channels -===================== - -This utility adds or replaces information about unusable -(bad) channels. The command line options are: - -``--bad <*filename*>`` - - Specify a text file containing the names of the bad channels, one channel - name per line. The names of the channels in this file must match - those in the data file exactly. If this option is missing, the bad channel - information is cleared. - -``<*data file name*>`` - - The remaining arguments are taken as data file names to be modified. - - -.. _mne_morph_labels: - -mne_morph_labels -================ -Morph label files from one brain to another. - -``--from <*subject*>`` - - Name of the subject for which the labels were originally defined. - -``--to <*subject*>`` - - Name of the subject for which the morphed labels should be created. - -``--labeldir <*directory*>`` - - A directory containing the labels to morph. - -``--prefix `` - - Adds <*prefix*> in the beginning - of the output label names. A dash will be inserted between <*prefix*> and - the rest of the name. - -``--smooth `` - - Apply smoothing with the indicated number of iteration steps (see :ref:`CHDEBAHH`) to the labels before morphing them. This is - advisable because otherwise the resulting labels may have little - holes in them since the morphing map is not a bijection. By default, - two smoothsteps are taken. - -As the labels are morphed, a directory with the name of the -subject specified with the ``--to`` option is created under -the directory specified with ``--labeldir`` to hold the -morphed labels. - - -.. _mne_organize_dicom: - -mne_organize_dicom -================== - - -.. _mne_prepare_bem_model: - -mne_prepare_bem_model -===================== - -``--bem <*name*>`` - - Specify the name of the file containing the triangulations of the BEM - surfaces and the conductivities of the compartments. The standard - ending for this file is ``-bem.fif`` and it is produced - either with the utility :ref:`mne_surf2bem` (:ref:`c_legacy_BEHCACCJ`) or the - convenience script :ref:`mne_setup_forward_model`, - see :ref:`CIHDBFEG`. - -``--sol <*name*>`` - - Specify the name of the file containing the triangulation and conductivity - information together with the BEM geometry matrix computed by mne_prepare_bem_model . - The standard ending for this file is ``-bem-sol.fif`` . - -``--method <*approximation method*>`` - - Select the BEM approach. If <*approximation method*> is ``constant`` , - the BEM basis functions are constant functions on each triangle - and the collocation points are the midpoints of the triangles. With ``linear`` , - the BEM basis functions are linear functions on each triangle and - the collocation points are the vertices of the triangulation. This - is the preferred method to use. The accuracy will be the same or - better than in the constant collocation approach with about half - the number of unknowns in the BEM equations. - - -.. _mne_process_stc: - -mne_process_stc -=============== - -``--stc `` - - Specify the stc file to process. - -``--out `` - - Specify a stc output file name. - -``--outasc `` - - Specify a text output file name. - -``--scaleto `` - - Scale the data so that the maximum is this value. - -``--scaleby `` - - Multiply the values by this. - - -.. _mne_raw2mat: - -mne_raw2mat -=========== - -The utility mne_raw2mat converts -all or selected channels from a raw data file to a Matlab mat file. -In addition, this utility can provide information about the raw -data file so that the raw data can be read directly from the original -fif file using Matlab file I/O routines. - -.. note:: The MNE Matlab toolbox described in :ref:`ch_matlab` provides direct access to raw fif files without a need for conversion to mat file format first. Therefore, it is recommended that you use the Matlab toolbox rather than mne_raw2mat which creates large files occupying disk space unnecessarily. - -Command-line options --------------------- - -mne_raw2mat accepts the -following command-line options: - -``--raw <*name*>`` - - Specifies the name of the raw data fif file to convert. - -``--mat <*name*>`` - - Specifies the name of the destination Matlab file. - -``--info`` - - With this option present, only information about the raw data file - is included. The raw data itself is omitted. - -``--sel <*name*>`` - - Specifies a text file which contains the names of the channels to include - in the output file, one channel name per line. If the ``--info`` option - is specified, ``--sel`` does not have any effect. - -``--tag <*tag*>`` - - By default, all Matlab variables included in the output file start - with ``mne\_``. This option changes the prefix to <*tag*> _. - -Matlab data structures ----------------------- - -The Matlab files output by mne_raw2mat can -contain two data structures, <*tag*>_raw and <*tag*>_raw_info . -If ``--info`` option is specified, the file contains the -latter structure only. - -The <*tag*>_raw structure -contains only one field, data which -is a matrix containing the raw data. Each row of this matrix constitutes -the data from one channel in the original file. The data type of -this matrix is the same of the original data (2-byte signed integer, -4-byte signed integer, or single-precision float). - -The fields of the <*tag*>_raw_info structure -are listed in :ref:`BEHFDCIH`. Further explanation of the bufs field -is provided in :ref:`BEHJEIHJ`. - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.15\linewidth}|p{0.6\linewidth}| -.. _BEHFDCIH: -.. table:: The fields of the raw data info structure. - - +-----------------------+-----------------+------------------------------------------------------------+ - | Variable | Size | Description | - +-----------------------+-----------------+------------------------------------------------------------+ - | orig_file | string | The name of the original fif file specified with the | - | | | ``--raw`` option. | - +-----------------------+-----------------+------------------------------------------------------------+ - | nchan | 1 | Number of channels. | - +-----------------------+-----------------+------------------------------------------------------------+ - | nsamp | 1 | Total number of samples | - +-----------------------+-----------------+------------------------------------------------------------+ - | bufs | nbuf x 4 | This field is present if ``--info`` option was specified on| - | | | the command line. For details, see :ref:`BEHJEIHJ`. | - +-----------------------+-----------------+------------------------------------------------------------+ - | sfreq | 1 | The sampling frequency in Hz. | - +-----------------------+-----------------+------------------------------------------------------------+ - | lowpass | 1 | Lowpass filter frequency (Hz) | - +-----------------------+-----------------+------------------------------------------------------------+ - | highpass | 1 | Highpass filter frequency (Hz) | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_names | nchan (string) | String array containing the names of the channels included | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_types | nchan x 2 | The column lists the types of the channesl (1 = MEG, 2 = | - | | | EEG). The second column lists the coil types, see | - | | | :ref:`c_legacy_BGBBHGEC` and :ref:`c_legacy_CHDBDFJE`. | - | | | For EEG electrodes, this value equals one. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_lognos | nchan x 1 | Logical channel numbers as listed in the fiff file | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_units | nchan x 2 | Units and unit multipliers as listed in the fif file. | - | | | The unit of the data is listed in the first column | - | | | (T = 112, T/m = 201, V = 107). At present, the second | - | | | column will be always zero, *i.e.*, no unit multiplier. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_pos | nchan x 12 | The location information for each channel. The first three | - | | | values specify the origin of the sensor coordinate system | - | | | or the location of the electrode. For MEG channels, the | - | | | following nine number specify the *x*, *y*, and | - | | | *z*-direction unit vectors of the sensor coordinate system.| - | | | For EEG electrodes the first vector after the electrode | - | | | location specifies the location of the reference electrode.| - | | | If the reference is not specified this value is all zeroes.| - | | | The remaining unit vectors are irrelevant for EEG | - | | | electrodes. | - +-----------------------+-----------------+------------------------------------------------------------+ - | ch_cals | nchan x 2 | The raw data output by mne_raw2mat is uncalibrated. | - | | | The first column is the range member of the fiff data | - | | | structures and while the second is the cal member. To get | - | | | calibrared data values in the units given in ch_units from | - | | | the raw data, the data must be multiplied with the product | - | | | of range and cal . | - +-----------------------+-----------------+------------------------------------------------------------+ - | meg_head_trans | 4 x 4 | The coordinate frame transformation from the MEG device | - | | | coordinates to the MEG head coordinates. | - +-----------------------+-----------------+------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.6\linewidth}| -.. _BEHJEIHJ: -.. table:: The bufs member of the raw data info structure. - - +-----------------------+-------------------------------------------------------------------------+ - | Column | Contents | - +-----------------------+-------------------------------------------------------------------------+ - | 1 | The raw data type (2 or 16 = 2-byte signed integer, 3 = 4-byte signed | - | | integer, 4 = single-precision float). All data in the fif file are | - | | written in the big-endian byte order. The raw data are stored sample by | - | | sample. | - +-----------------------+-------------------------------------------------------------------------+ - | 2 | Byte location of this buffer in the original fif file. | - +-----------------------+-------------------------------------------------------------------------+ - | 3 | First sample of this buffer. Since raw data storing can be switched on | - | | and off during the acquisition, there might be gaps between the end of | - | | one buffer and the beginning of the next. | - +-----------------------+-------------------------------------------------------------------------+ - | 4 | Number of samples in the buffer. | - +-----------------------+-------------------------------------------------------------------------+ - - -.. _mne_rename_channels: - -mne_rename_channels -=================== - -Sometimes it is necessary to change the names types of channels -in MEG/EEG data files. Such situations include: - -- Designating an EEG as an EOG channel. - For example, the EOG channels are not recognized as such in the - fif files converted from CTF data files. - -- Changing the name of the digital trigger channel of interest - to STI 014 so that mne_browse_raw and mne_process_raw will - recognize the correct channel without the need to specify the ``--digtrig`` - option or the MNE_TRIGGER_CH_NAME environment variable every time a - data file is loaded. - -The utility mne_rename_channels was -designed to meet the above needs. It recognizes the following command-line -options: - -``--fif <*name*>`` - - Specifies the name of the data file to modify. - -``--alias <*name*>`` - - Specifies the text file which contains the modifications to be applied, - see below. - -``--revert`` - - Reverse the roles of old and new channel names in the alias file. - -Each line in the alias file contains the old name and new -name for a channel, separated by a colon. The old name is a name -of one of the channels presently in the file and the new name is -the name to be assigned to it. The old name must match an existing -channel name in the file exactly. The new name may be followed by -another colon and a number which is the channel type to be assigned -to this channel. The channel type options are listed below. - -.. table:: Channel types. - - ============== ====================== - Channel type Corresponding number - ============== ====================== - MEG 1 - MCG 201 - EEG 2 - EOG 202 - EMG 302 - ECG 402 - MISC 502 - STIM 3 - ============== ====================== - -.. warning:: Do not attempt to designate MEG channels to EEG channels or vice versa. This may result in strange errors during source estimation. - -.. note:: You might consider renaming the EEG channels with descriptive labels related to the standard 10-20 system. This allows you to use standard EEG channel names when defining derivations, see :ref:`mne_make_derivations` and :ref:`CACFHAFH`, as well as in the channel selection files used in mne_browse_raw , see :ref:`CACCJEJD`. - - -.. _mne_sensitivity_map: - -mne_sensitivity_map -=================== - -Purpose -------- - -mne_sensitivity_map computes -the size of the columns of the forward operator and outputs the -result in w files. - -Command line options --------------------- - -mne_sensitivity_map accepts -the following command-line options: - -``--fwd <*name*>`` - - Specifies a forward solution file to analyze. By default the MEG - forward solution is considered. - -``--proj <*name*>`` - - Specifies a file containing an SSP operator to be applied. If necessary, - multiple ``--proj`` options can be specified. For map types 1 - 4 (see - below), SSP is applied to the forward model data. For map types - 5 and 6, the effects of SSP are evaluated against the unmodified - forward model. - -``--eeg`` - - Use the EEG forward solution instead of the MEG one. It does not make - sense to consider a combination because of the different units of - measure. For the same reason, gradiometers and magnetometers have - to be handled separately, see ``--mag`` option below. By - default MEG gradiometers are included. - -``--mag`` - - Include MEG magnetometers instead of gradiometers - -``--w <*name*>`` - - Specifies the stem of the output w files. To obtain the final output file - names, ``-lh.w`` and ``-rh.w`` is appended for - the left and right hemisphere, respectively. - -``--smooth <*number*>`` - - Specifies the number of smooth steps to apply to the resulting w files. - Default: no smoothing. - -``--map <*number*>`` - - Select the type of a sensitivity map to compute. At present, valid numbers - are 1 - 6. For details, see :ref:`CHDCDJIJ`, below. - -.. _CHDCDJIJ: - -Available sensitivity maps --------------------------- - -In the following, let - -.. math:: G_k = [g_{xk} g_{yk} g_{zk}] - -denote the three consecutive columns of the gain matrix :math:`G` corresponding to -the fields of three orthogonal dipoles at source space location :math:`k`. -Further, lets assume that the source coordinate system has been -selected so that the :math:`z` -axis points -to the cortical normal direction and the :math:`xy` plane -is thus the tangent plane of the cortex at the source space location :math:`k` -Next, compute the SVD - -.. math:: G_k = U_k \Lambda_k V_k - -and let :math:`g_{1k} = u_{1k} \lambda_{1k}`, where :math:`\lambda_{1k}` and :math:`u_{1k}` are -the largest singular value and the corresponding left singular vector -of :math:`G_k`, respectively. It is easy to see -that :math:`g_{1k}` is has the largest power -among the signal distributions produced by unit dipoles at source -space location :math:`k`. - -Furthermore, assume that the columns orthogonal matrix :math:`U_P` (:math:`U_P^T U_P = I`) contain -the orthogonal basis of the noise subspace corresponding to the signal -space projection (SSP) operator :math:`P` specified -with one or more ``--proj`` options so that :math:`P = I - U_P U_P^T`. -For more information on SSP, see :ref:`CACCHABI`. - -With these definitions the map selections defined with the ``--map`` option correspond -to the following - -``--map 1`` - - Compute :math:`\sqrt{g_{1k}^T g_{1k}} = \lambda_{1k}` at each source space point. - Normalize the result so that the maximum values equals one. - -``--map 2`` - - Compute :math:`\sqrt{g_z^T g_z}` at each source space point. - Normalize the result so that the maximum values equals one. This - is the amplitude of the signals produced by unit dipoles normal - to the cortical surface. - -``--map 3`` - - Compute :math:`\sqrt{g_z^T g_z / g_{1k}^T g_{1k}}` at each source space point. - -``--map 4`` - - Compute :math:`1 - \sqrt{g_z^T g_z / g_{1k}^T g_{1k}}` at each source space point. - This could be called the *radiality index*. - -``--map 5`` - - Compute the subspace correlation between :math:`g_z` and :math:`U_P`: :math:`\text{subcorr}^2(g_z , U_P) = (g_z^T U_P U_P^T g_z)/(g_z^T g_z)`. - This index equals zero, if :math:`g_z` is - orthogonal to :math:`U_P` and one if :math:`g_z` lies - in the subspace defined by :math:`U_P`. This - map shows how close the field pattern of a dipole oriented perpendicular - to the cortex at each cortical location is to the subspace removed - by the SSP. - -``--map 6`` - - Compute :math:`\sqrt{g_z^T P g_z / g_z^T g_z}`, which is the fraction - of the field pattern of a dipole oriented perpendicular to the cortex - at each cortical location remaining after applying the SSP a dipole - remaining - - -.. _mne_sensor_locations: - -mne_sensor_locations -==================== - -``--meas `` - - Measurement file. - -``--magonly`` - - Magnetometers only. - -``--ell`` - - Output sensor ellipsoids for MRIlab. - -``--dir`` - - Output direction info as well. - -``--dev`` - - Output in MEG device coordinates. - -``--out `` - - Name output file - - -.. _mne_show_fiff: - -mne_show_fiff -============= - -Using the utility mne_show_fiff it -is possible to display information about the contents of a fif file -to the standard output. The command line options for mne_show_fiff are: - -``--in <*name*>`` - - Specifies the fif file whose contents will be listed. - -``--verbose`` - - Produce a verbose output. The data of most tags is included in the output. - This excludes matrices and vectors. Only the first 80 characters - of strings are listed unless the ``--long`` option is present. - -``--blocks`` - - Only list the blocks (the tree structure) of the file. The tags - within each block are not listed. - -``--indent <*number*>`` - - Number of spaces for indentation for each deeper level in the tree structure - of the fif files. The default indentation is 3 spaces in terse and - no spaces in verbose listing mode. - -``--long`` - - List all data from string tags instead of the first 80 characters. - This options has no effect unless the ``--verbose`` option - is also present. - -``--tag <*number*>`` - - List only tags of this kind. Multiple ``--tag`` options - can be specified to list several different kinds of data. - -mne_show_fiff reads the -explanations of tag kinds, block kinds, and units from ``$MNE_ROOT/share/mne/fiff_explanations.txt`` . - - -.. _mne_simu: - -mne_simu -======== - -Purpose -------- - -The utility mne_simu creates -simulated evoked response data for investigation of the properties -of the inverse solutions. It computes MEG signals generated by dipoles -normal to the cortical mantle at one or several ROIs defined with -label files. Colored noise can be added to the signals. - -Command-line options --------------------- - -mne_simu has the following -command-line options: - -``--fwd <*name*>`` - - Specify a forward solution file to employ in the simulation. - -``--label <*name*>`` - - Specify a label - -``--meg`` - - Provide MEG data in the output file. - -``--eeg`` - - Provide EEG data in the output file. - -``--out <*name*>`` - - Specify the output file. By default, this will be an evoked data - file in the fif format. - -``--raw`` - - Output the data as a raw data fif file instead of an evoked one. - -``--mat`` - - Produce Matlab output of the simulated fields instead of the fif evoked - file. - -``--label <*name*>`` - - Define an ROI. Several label files can be present. By default, the sources - in the labels will have :math:`\cos^2` -shaped non-overlapping - timecourses, see below. - -``--timecourse <*name*>`` - - Specifies a text file which contains an expression for a source - time course, see :ref:`CHDCFIBH`. If no --timecourse options - are present, the standard source time courses described in :ref:`CHDFIIII` are used. Otherwise, the time course expressions - are read from the files specified. The time course expressions are - associated with the labels in the order they are specified. If the - number of expressions is smaller than the number of labels, the - last expression specified will reused for the remaining labels. - -``--sfreq <*freq/Hz*>`` - - Specifies the sampling frequency of the output data (default = 1000 Hz). This - option is used only with the time course files. - -``--tmin <*time/ms*>`` - - Specifies the starting time of the data, used only with time course files - (default -200 ms). - -``--tmax <*time/ms*>`` - - Specifies the ending time of the data, used only with time course files - (default 500 ms). - -``--seed <*number*>`` - - Specifies the seed for random numbers. This seed is used both for adding - noise, see :ref:`CHDFBJIJ` and for random numbers in source waveform - expressions, see :ref:`CHDCFIBH`. If no seed is specified, the - current time in seconds since Epoch (January 1, 1970) is used. - -``--all`` - - Activate all sources on the cortical surface uniformly. This overrides the ``--label`` options. - -.. _CHDFBJIJ: - -Noise simulation ----------------- - -Noise is added to the signals if the ``--senscov`` and ``--nave`` options -are present. If ``--nave`` is omitted the number of averages -is set to :math:`L = 100`. The noise is computed -by first generating vectors of Gaussian random numbers :math:`n(t)` with :math:`n_j(t) \sim N(0,1)`. -Thereafter, the noise-covariance matrix :math:`C` is -used to color the noise: - -.. math:: n_c(t) = \frac{1}{\sqrt{L}} \Lambda U^T n(t)\ , - -where we have used the eigenvalue decomposition positive-definite -covariance matrix: - -.. math:: C = U \Lambda^2 U^T\ . - -Note that it is assumed that the noise-covariance matrix -is given for raw data, *i.e.*, for :math:`L = 1`. - -.. _CHDFIIII: - -Simulated data --------------- - -The default source waveform :math:`q_k` for -the :math:`k^{th}` label is nonzero at times :math:`t_{kp} = (100(k - 1) + p)/f_s`, :math:`p = 0 \dotso 100` with: - -.. math:: q_k(t_{kp}) = Q_k \cos^2{(\frac{\pi p}{100} - \frac{\pi}{2})}\ , - -i.e., the source waveforms are non-overlapping 100-samples -wide :math:`\cos^2` pulses. The sampling frequency :math:`f_s = 600` Hz. -The source amplitude :math:`Q_k` is determined -so that the strength of each of the dipoles in a label will be :math:`50 \text{nAm}/N_k`. - -Let us denote the sums of the magnetic fields and electric -potentials produced by the dipoles normal to the cortical mantle -at label :math:`k` by :math:`x_k`. The simulated -signals are then: - -.. math:: x(t_j) = \sum_{k = 1}^{N_s} {q_k(t_j) x_k + n_c(t_j)}\ , - -where :math:`N_s` is the number of -sources. - -.. _CHDCFIBH: - -Source waveform expressions ---------------------------- - -The ``--timecourse`` option provides flexible possibilities -to define the source waveforms in a functional form. The source -waveform expression files consist of lines of the form: - - <*variable*> ``=`` <*arithmetic expression*> - -Each file may contain multiple lines. At the end of the evaluation, -only the values in the variable ``y`` (``q`` ) -are significant, see :ref:`CHDJBIEE`. They assume the role -of :math:`q_k(t_j)` to compute the simulated signals -as described in :ref:`CHDFIIII`, above. - -All expressions are case insensitive. The variables are vectors -with the length equal to the number of samples in the responses, -determined by the ``--tmin`` , ``--tmax`` , and ``--sfreq`` options. -The available variables are listed in :ref:`CHDJBIEE`. - -.. _CHDJBIEE: - -.. table:: Available variable names in source waveform expressions. - - ================ ======================================= - Variable Meaning - ================ ======================================= - x time [s] - t current value of x in [ms] - y the source amplitude [Am] - q synonym for y - a , b , c , d help variables, initialized to zeros - ================ ======================================= - -The arithmetic expressions can use usual arithmetic operations -as well as mathematical functions listed in :ref:`CHDJIBHA`. -The arguments can be vectors or scalar numbers. In addition, standard -relational operators ( <, >, ==, <=, >=) and their textual -equivalents (lt, gt, eq, le, ge) are available. Table :ref:`CHDDJEHH` gives some -useful examples of source waveform expressions. - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.6\linewidth}| -.. _CHDJIBHA: -.. table:: Mathematical functions available for source waveform expressions - - +-----------------------+---------------------------------------------------------------+ - | Function | Description | - +-----------------------+---------------------------------------------------------------+ - | abs(x) | absolute value | - +-----------------------+---------------------------------------------------------------+ - | acos(x) | :math:`\cos^{-1}x` | - +-----------------------+---------------------------------------------------------------+ - | asin(x) | :math:`\sin^{-1}x` | - +-----------------------+---------------------------------------------------------------+ - | atan(x) | :math:`\tan^{-1}x` | - +-----------------------+---------------------------------------------------------------+ - | atan2(x,y) | :math:`\tan^{-1}(^y/_x)` | - +-----------------------+---------------------------------------------------------------+ - | ceil(x) | nearest integer larger than :math:`x` | - +-----------------------+---------------------------------------------------------------+ - | cos(x) | :math:`\cos x` | - +-----------------------+---------------------------------------------------------------+ - | cosw(x,a,b,c) | :math:`\cos^2` -shaped window centered at :math:`b` with a | - | | rising slope of length :math:`a` and a trailing slope of | - | | length :math:`b`. | - +-----------------------+---------------------------------------------------------------+ - | deg(x) | The value of :math:`x` converted to from radians to degrees | - +-----------------------+---------------------------------------------------------------+ - | erf(x) | :math:`\frac{1}{2\pi} \int_0^x{\text{exp}(-t^2)dt}` | - +-----------------------+---------------------------------------------------------------+ - | erfc(x) | :math:`1 - \text{erf}(x)` | - +-----------------------+---------------------------------------------------------------+ - | exp(x) | :math:`e^x` | - +-----------------------+---------------------------------------------------------------+ - | floor(x) | Largest integer value not larger than :math:`x` | - +-----------------------+---------------------------------------------------------------+ - | hypot(x,y) | :math:`\sqrt{x^2 + y^2}` | - +-----------------------+---------------------------------------------------------------+ - | ln(x) | :math:`\ln x` | - +-----------------------+---------------------------------------------------------------+ - | log(x) | :math:`\log_{10} x` | - +-----------------------+---------------------------------------------------------------+ - | maxp(x,y) | Takes the maximum between :math:`x` and :math:`y` | - +-----------------------+---------------------------------------------------------------+ - | minp(x,y) | Takes the minimum between :math:`x` and :math:`y` | - +-----------------------+---------------------------------------------------------------+ - | mod(x,y) | Gives the remainder of :math:`x` divided by :math:`y` | - +-----------------------+---------------------------------------------------------------+ - | pi | Ratio of the circumference of a circle and its diameter. | - +-----------------------+---------------------------------------------------------------+ - | rand | Gives a vector of uniformly distributed random numbers | - | | from 0 to 1. | - +-----------------------+---------------------------------------------------------------+ - | rnorm(x,y) | Gives a vector of Gaussian random numbers distributed as | - | | :math:`N(x,y)`. Note that if :math:`x` and :math:`y` are | - | | vectors, each number generated will a different mean and | - | | variance according to the arguments. | - +-----------------------+---------------------------------------------------------------+ - | shift(x,s) | Shifts the values in the input vector :math:`x` by the number | - | | of positions given by :math:`s`. Note that :math:`s` must be | - | | a scalar. | - +-----------------------+---------------------------------------------------------------+ - | sin(x) | :math:`\sin x` | - +-----------------------+---------------------------------------------------------------+ - | sqr(x) | :math:`x^2` | - +-----------------------+---------------------------------------------------------------+ - | sqrt(x) | :math:`\sqrt{x}` | - +-----------------------+---------------------------------------------------------------+ - | tan(x) | :math:`\tan x` | - +-----------------------+---------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.4\linewidth}|p{0.4\linewidth}| -.. _CHDDJEHH: -.. table:: Examples of source waveform expressions. - - +---------------------------------------------+-------------------------------------------------------------+ - | Expression | Meaning | - +---------------------------------------------+-------------------------------------------------------------+ - | q = 20e-9*sin(2*pi*10*x) | A 10-Hz sine wave with 20 nAm amplitude | - +---------------------------------------------+-------------------------------------------------------------+ - | q = 20e-9*sin(2*pi*2*x)*sin(2*pi*10*x) | A 10-Hz 20-nAm sine wave, amplitude modulated | - | | sinusoidally at 2 Hz. | - +---------------------------------------------+-------------------------------------------------------------+ - | q = 20e-9*cosw(t,100,100,100) | :math:`\cos^2`-shaped pulse, centered at :math:`t` = 100 ms | - | | with 100 ms leading and trailing slopes, 20 nAm amplitude | - +---------------------------------------------+-------------------------------------------------------------+ - | q = 30e-9*(t > 0)*(t <* 300)*sin(2*pi*20*x)| 20-Hz sine wave, 30 nAm amplitude, cropped in time to | - | | 0...300 ms. | - +---------------------------------------------+-------------------------------------------------------------+ - - -.. _mne_smooth: - -mne_smooth -========== - -Produce a smoothed version of a w or an stc file - -``--src `` - - The source space file. - -``--in `` - - The w or stc file to smooth. - -``--smooth `` - - Number of smoothsteps - - -.. _mne_surf2bem: - -mne_surf2bem -============ - -``--surf <*name*>`` - - Specifies a FreeSurfer binary format surface file. Before specifying the - next surface (``--surf`` or ``--tri`` options) - details of the surface specification can be given with the options - listed in :ref:`BEHCDICC`. - -``--tri <*name*>`` - - Specifies a text format surface file. Before specifying the next - surface (``--surf`` or ``--tri`` options) details - of the surface specification can be given with the options listed - in :ref:`BEHCDICC`. The format of these files is described - in :ref:`c_legacy_BEHDEFCD`. - -``--check`` - - Check that the surfaces are complete and that they do not intersect. This - is a recommended option. For more information, see :ref:`c_legacy_BEHCBDDE`. - -``--checkmore`` - - In addition to the checks implied by the ``--check`` option, - check skull and skull thicknesses. For more information, see - :ref:`c_legacy_BEHCBDDE`. - -``--fif <*name*>`` - - The output fif file containing the BEM. These files normally reside in - the bem subdirectory under the subject's mri data. A name - ending with ``-bem.fif`` is recommended. - -.. _BEHCDICC: - -Surface options ---------------- - -These options can be specified after each ``--surf`` or ``--tri`` option -to define details for the corresponding surface. - -``--swap`` - - Swap the ordering or the triangle vertices. The standard convention in - the MNE software is to have the vertices ordered so that the vector - cross product of the vectors from vertex 1 to 2 and 1 to 3 gives the - direction of the outward surface normal. Text format triangle files - produced by the some software packages have an opposite order. For - these files, the ``--swap`` . option is required. This option does - not have any effect on the interpretation of the FreeSurfer surface - files specified with the ``--surf`` option. - -``--sigma <*value*>`` - - The conductivity of the compartment inside this surface in S/m. - -``--shift <*value/mm*>`` - - Shift the vertices of this surface by this amount, given in mm, - in the outward direction, *i.e.*, in the positive - vertex normal direction. - -``--meters`` - - The vertex coordinates of this surface are given in meters instead - of millimeters. This option applies to text format files only. This - definition does not affect the units of the shift option. - -``--id <*number*>`` - - Identification number to assign to this surface. (1 = inner skull, 3 - = outer skull, 4 = scalp). - -``--ico <*number*>`` - - Downsample the surface to the designated subdivision of an icosahedron. - This option is relevant (and required) only if the triangulation - is isomorphic with a recursively subdivided icosahedron. For example, - the surfaces produced by with mri_watershed are - isomorphic with the 5th subdivision of a an icosahedron thus containing 20480 - triangles. However, this number of triangles is too large for present - computers. Therefore, the triangulations have to be decimated. Specifying ``--ico 4`` yields 5120 triangles per surface while ``--ico 3`` results - in 1280 triangles. The recommended choice is ``--ico 4`` . - - -.. _mne_toggle_skips: - -mne_toggle_skips -================ - -Toggle skip tags on and off. - -``--raw `` - - The raw data file to process. - - -.. _mne_transform_points: - -mne_transform_points -==================== - -Purpose -------- - -mne_transform_points applies -the coordinate transformation relating the MEG head coordinates -and the MRI coordinates to a set of locations listed in a text file. - -Command line options --------------------- - -mne_transform_points accepts -the following command-line options: - -``--in <*name*>`` - - Specifies the input file. The file must contain three numbers on - each line which are the *x*, *y*, - and *z* coordinates of point in space. By default, - the input is in millimeters. - -``--iso <*name*>`` - - Specifies a name of a fif file containing Isotrak data. If this - option is present file will be used as the input instead of the - text file specified with the ``--in`` option. - -``--trans <*name*>`` - - Specifies the name of a fif file containing the coordinate transformation - between the MEG head coordinates and MRI coordinates. If this file - is not present, the transformation will be replaced by a unit transform. - -``--out <*name*>`` - - Specifies the output file. This file has the same format as the - input file. - -``--hpts`` - - Output the data in the head points (hpts) - format accepted by tkmedit . In - this format, the coordinates are preceded by a point category (hpi, - cardinal or fiducial, eeg, extra) and a sequence number, see :ref:`CJADJEBH`. - -``--meters`` - - The coordinates are listed in meters rather than millimeters. - -``--tomri`` - - By default, the coordinates are transformed from MRI coordinates to - MEG head coordinates. This option reverses the transformation to - be from MEG head coordinates to MRI coordinates. - - -.. _mne_tufts2fiff: - -mne_tufts2fiff -============== - -``--raw <*filename*>`` - - Specifies the name of the raw data file to process. - -``--cal <*filename*>`` - - The name of the calibration data file. If calibration data are missing, the - calibration coefficients will be set to unity. - -``--elp <*filename*>`` - - The name of the electrode location file. If this file is missing, - the electrode locations will be unspecified. This file is in the "probe" file - format used by the *Source Signal Imaging, Inc.* software. - For description of the format, see http://www.sourcesignal.com/formats_probe.html. - The fiducial marker locations, optional in the "probe" file - format specification are mandatory for mne_tufts2fiff . Note - that some other software packages may produce electrode-position - files with the elp ending not - conforming to the above specification. - -.. note:: - - The conversion process includes a transformation from the Tufts head coordinate system convention to that used in the Neuromag systems. - -.. note:: - - The fiducial landmark locations, optional in the probe file format, must be present for mne_tufts2fiff . - - -.. _mne_view_manual: - -mne_view_manual -=============== - -This script shows you the manual in a PDF reader. - - -.. _mne_volume_data2mri: - -mne_volume_data2mri -=================== - -With help of the :ref:`mne_volume_source_space` utility -it is possible to create a source space which -is defined within a volume rather than a surface. If the ``--mri`` option -was used in :ref:`mne_volume_source_space`, the -source space file contains an interpolator matrix which performs -a trilinear interpolation into the voxel space of the MRI volume -specified. - -The purpose of the :ref:`mne_volume_data2mri` is -to produce MRI overlay data compatible with FreeSurfer MRI viewers -(in the mgh or mgz formats) from this type of w or stc files. - -The command-line options are: - -``--src <*filename*>`` - - The name of the volumetric source space file created with mne_volume_source_space . - The source space must have been created with the ``--mri`` option, - which adds the appropriate sparse trilinear interpolator matrix - to the source space. - -``--w <*filename*>`` - - The name of a w file to convert - into an MRI overlay. - -``--stc <*filename*>`` - - The name of the stc file to convert - into an MRI overlay. If this file has many time frames, the output - file may be huge. Note: If both ``-w`` and ``--stc`` are - specified, ``-w`` takes precedence. - -``--scale <*number*>`` - - Multiply the stc or w by - this scaling constant before producing the overlay. - -``--out <*filename*>`` - - Specifies the name of the output MRI overlay file. The name must end - with either ``.mgh`` or ``.mgz`` identifying the - uncompressed and compressed FreeSurfer MRI formats, respectively. - - -.. _mne_volume_source_space: - -mne_volume_source_space -======================= - -``--surf <*name*>`` - - Specifies a FreeSurfer surface file containing the surface which - will be used as the boundary for the source space. - -``--bem <*name*>`` - - Specifies a BEM file (ending in ``-bem.fif`` ). The inner - skull surface will be used as the boundary for the source space. - -``--origin <*x/mm*> : <*y/mm*> : <*z/mm*>`` - - If neither of the two surface options described above is present, - the source space will be spherical with the origin at this location, - given in MRI (RAS) coordinates. - -``--rad <*radius/mm*>`` - - Specifies the radius of a spherical source space. Default value - = 90 mm - -``--grid <*spacing/mm*>`` - - Specifies the grid spacing in the source space. - -``--mindist <*distance/mm*>`` - - Only points which are further than this distance from the bounding surface - are included. Default value = 5 mm. - -``--exclude <*distance/mm*>`` - - Exclude points that are closer than this distance to the center - of mass of the bounding surface. By default, there will be no exclusion. - -``--mri <*name*>`` - - Specifies a MRI volume (in mgz or mgh format). - If this argument is present the output source space file will contain - a (sparse) interpolation matrix which allows mne_volume_data2mri to - create an MRI overlay file, see :ref:`mne_volume_data2mri`. - -``--pos <*name*>`` - - Specifies a name of a text file containing the source locations - and, optionally, orientations. Each line of the file should contain - 3 or 6 values. If the number of values is 3, they indicate the source - location, in millimeters. The orientation of the sources will be - set to the z-direction. If the number of values is 6, the source - orientation will be parallel to the vector defined by the remaining - 3 numbers on each line. With ``--pos`` , all of the options - defined above will be ignored. By default, the source position and - orientation data are assumed to be given in MRI coordinates. - -``--head`` - - If this option is present, the source locations and orientations - in the file specified with the ``--pos`` option are assumed - to be given in the MEG head coordinates. - -``--meters`` - - Indicates that the source locations in the file defined with the ``--pos`` option - are give in meters instead of millimeters. - -``--src <*name*>`` - - Specifies the output file name. Use a name * <*dir*>/ <*name*>*-src.fif - -``--all`` - - Include all vertices in the output file, not just those in use. - This option is implied when the ``--mri`` option is present. - Even with the ``--all`` option, only those vertices actually - selected will be marked to be "in use" in the - output source space file. - - -.. _mne_watershed_bem: - -mne_watershed_bem -================= - -``--subject <*subject*>`` - - Defines the name of the subject. This can be also accomplished - by setting the SUBJECT environment variable. - -``--overwrite`` - - Overwrite the results of previous run of mne_watershed_bem . - -``--atlas`` - - Makes mri_watershed to employ - atlas information to correct the segmentation. diff -Nru python-mne-0.18.1+dfsg/doc/manual/datasets_index.rst python-mne-0.19.1+dfsg/doc/manual/datasets_index.rst --- python-mne-0.18.1+dfsg/doc/manual/datasets_index.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/datasets_index.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,302 +0,0 @@ -.. _datasets: - -Datasets -######## - -.. contents:: Contents - :local: - :depth: 2 - -All the dataset fetchers are available in :mod:`mne.datasets`. To download any of the datasets, -use the ``data_path`` (fetches full dataset) or the ``load_data`` (fetches dataset partially) functions. - -.. _sample-dataset: - -Sample -====== -:func:`mne.datasets.sample.data_path` - -:ref:`ch_sample_data` is recorded using a 306-channel Neuromag vectorview system. - -In this experiment, checkerboard patterns were presented to the subject -into the left and right visual field, interspersed by tones to the -left or right ear. The interval between the stimuli was 750 ms. Occasionally -a smiley face was presented at the center of the visual field. -The subject was asked to press a key with the right index finger -as soon as possible after the appearance of the face. - -Once the ``data_path`` is known, its contents can be examined using :ref:`IO functions `. - -fsaverage -========= -:func:`mne.datasets.fetch_fsaverage` - -For convenience, we provide a function to separately download and extract the -(or update an existing) fsaverage subject. - -.. topic:: Examples - - :ref:`tut-eeg-fsaverage-source-modeling` - -Brainstorm -========== -Dataset fetchers for three Brainstorm tutorials are available. Users must agree to the -license terms of these datasets before downloading them. These files are recorded in a CTF 275 system -and are provided in native CTF format (.ds files). - -Auditory -^^^^^^^^ -:func:`mne.datasets.brainstorm.bst_raw.data_path`. - -Details about the data can be found at the Brainstorm `auditory dataset tutorial`_. - -.. topic:: Examples - - * :ref:`tut-brainstorm-auditory`: Partially replicates the original Brainstorm tutorial. - -Resting state -^^^^^^^^^^^^^ -:func:`mne.datasets.brainstorm.bst_resting.data_path` - -Details can be found at the Brainstorm `resting state dataset tutorial`_. - -.. topic:: Examples - - * :ref:`ex-envelope-correlation` - -Median nerve -^^^^^^^^^^^^ -:func:`mne.datasets.brainstorm.bst_raw.data_path` - -Details can be found at the Brainstorm `median nerve dataset tutorial`_. - -.. topic:: Examples - - * :ref:`ex-brainstorm-raw` - -MEGSIM -====== -:func:`mne.datasets.megsim.load_data` - -This dataset contains experimental and simulated MEG data. To load data from this dataset, do:: - - from mne.io import Raw - from mne.datasets.megsim import load_data - raw_fnames = load_data(condition='visual', data_format='raw', data_type='experimental', verbose=True) - raw = Raw(raw_fnames[0]) - -Detailed description of the dataset can be found in the related publication [1]_. - -.. topic:: Examples - - * :ref:`ex-megsim` - -SPM faces -========= -:func:`mne.datasets.spm_face.data_path` - -The `SPM faces dataset`_ contains EEG, MEG and fMRI recordings on face perception. - -.. topic:: Examples - - * :ref:`ex-spm-faces` Full pipeline including artifact removal, epochs averaging, forward model computation and source reconstruction using dSPM on the contrast: "faces - scrambled". - -EEGBCI motor imagery -==================== -:func:`mne.datasets.eegbci.load_data` - -The EEGBCI dataset is documented in [2]_. The data set is available at PhysioNet [3]_. -The dataset contains 64-channel EEG recordings from 109 subjects and 14 runs on each subject in EDF+ format. -The recordings were made using the BCI2000 system. To load a subject, do:: - - from mne.io import concatenate_raws, read_raw_edf - from mne.datasets import eegbci - raw_fnames = eegbci.load_data(subject, runs) - raws = [read_raw_edf(f, preload=True) for f in raw_fnames] - raw = concatenate_raws(raws) - -.. topic:: Examples - - * :ref:`ex-decoding-csp-eeg` - -Do not hesitate to contact MNE-Python developers on the -`MNE mailing list `_ -to discuss the possibility to add more publicly available datasets. - -.. _auditory dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetAuditory -.. _resting state dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetResting -.. _median nerve dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetMedianNerveCtf -.. _SPM faces dataset: https://www.fil.ion.ucl.ac.uk/spm/data/mmfaces/ - -Somatosensory -============= -:func:`mne.datasets.somato.data_path` - -This dataset contains somatosensory data with event-related synchronizations -(ERS) and desynchronizations (ERD). - -.. topic:: Examples - - * :ref:`tut-sensors-time-freq` - -Multimodal -========== -:func:`mne.datasets.multimodal.data_path` - -This dataset contains a single subject recorded at Otaniemi (Aalto University) -with auditory, visual, and somatosensory stimuli. - -.. topic:: Examples - - * :ref:`ex-io-ave-fiff` - - -High frequency SEF -================== -:func:`mne.datasets.hf_sef.data_path()` - -This dataset contains somatosensory evoked fields (median nerve stimulation) -with thousands of epochs. It was recorded with an Elekta TRIUX MEG device at -a sampling frequency of 3 kHz. The dataset is suitable for investigating -high-frequency somatosensory responses. Data from two subjects are included -with MRI images in DICOM format and FreeSurfer reconstructions. - - -Visual 92 object categories -=========================== -:func:`mne.datasets.visual_92_categories.data_path`. - -This dataset is recorded using a 306-channel Neuromag vectorview system. - -Experiment consisted in the visual presentation of 92 images of human, animal -and inanimate objects either natural or artificial [4]_. Given the high number -of conditions this dataset is well adapted to an approach based on -Representational Similarity Analysis (RSA). - -.. topic:: Examples - - * :ref:`Representational Similarity Analysis (RSA) `: Partially replicates the results from Cichy et al. (2014). - - -mTRF Dataset -============ -:func:`mne.datasets.mtrf.data_path`. - -This dataset contains 128 channel EEG as well as natural speech stimulus features, -which is also available `here `_. - -The experiment consisted of subjects listening to natural speech. -The dataset contains several feature representations of the speech stimulus, -suitable for using to fit continuous regression models of neural activity. -More details and a description of the package can be found in [5]_. - -.. topic:: Examples - - * :ref:`Receptive Field Estimation and Prediction `: Partially replicates the results from Crosse et al. (2016). - -Miscellaneous Datasets -====================== -These datasets are used for specific purposes in the documentation and in -general are not useful for separate analyses. - -ECoG Dataset -^^^^^^^^^^^^ -:func:`mne.datasets.misc.data_path`. Data exists at ``/ecog/sample_ecog.mat``. - -This dataset contains a sample Electrocorticography (ECoG) dataset. It includes -a single grid of electrodes placed over the temporal lobe during an auditory -listening task. This dataset is primarily used to demonstrate visualization -functions in MNE and does not contain useful metadata for analysis. - -.. topic:: Examples - - * :ref:`How to convert 3D electrode positions to a 2D image. - `: Demonstrates - how to project a 3D electrode location onto a 2D image, a common procedure - in electrocorticography. - - -Kiloword dataset -================ -:func:`mne.datasets.kiloword.data_path`. - -This dataset consists of averaged EEG data from 75 subjects performing a lexical decision -task on 960 English words [6]_. The words are richly annotated, and can be used for e.g. -multiple regression estimation of EEG correlates of printed word processing. - - -4D Neuroimaging / BTi dataset -============================= -:func:`mne.datasets.phantom_4dbti.data_path`. - -This dataset was obtained with a phantom on a 4D Neuroimaging / BTi system at the MEG -center in La Timone hospital in Marseille. - - -OPM -=== -:func:`mne.datasets.opm.data_path` - -OPM data acquired using an Elekta DACQ, simply piping the data into Elekta -magnetometer channels. The FIF files thus appear to come from a TRIUX system -that is only acquiring a small number of magnetometer channels instead of the -whole array. - -The OPM ``coil_type`` is custom, requiring a custom ``coil_def.dat``. -The new ``coil_type`` is 9999. - -OPM co-registration differs a bit from the typical SQUID-MEG workflow. -No ``-trans.fif`` file is needed for the OPMs, the FIF files include proper -sensor locations in MRI coordinates and no digitization of RPA/LPA/Nasion. -Thus the MEG<->Head coordinate transform is taken to be an identity matrix -(i.e., everything is in MRI coordinates), even though this mis-identifies -the head coordinate frame (which is defined by the relationship of the -LPA, RPA, and Nasion). - -Triggers include: - -* Median nerve stimulation: trigger value 257. -* Magnetic trigger (in OPM measurement only): trigger value 260. - 1 second before the median nerve stimulation, a magnetic trigger is piped into the MSR. - This was to be able to check the synchronization between OPMs retrospectively, as each - sensor runs on an indepent clock. Synchronization turned out to be satisfactory - -.. topic:: Examples - - * :ref:`ex-opm-somatosensory` - * :ref:`ex-opm-resting-state` - -The Sleep PolySomnoGraphic Database -=================================== -:func:`mne.datasets.sleep_physionet.age.fetch_data` -:func:`mne.datasets.sleep_physionet.temazepam.fetch_data` - -The sleep PhysioNet database contains 197 whole-night PolySomnoGraphic sleep -recordings, containing EEG, EOG, chin EMG, and event markers. Some records also -contain respiration and body temperature. Corresponding hypnograms (sleep -patterns) were manually scored by well-trained technicians according to the -Rechtschaffen and Kales manual, and are also available. If you use these -data please cite [7]_ and [8]_. - -.. topic:: Examples - - * :ref:`tut-sleep-stage-classif` - -References -========== - -.. [1] Aine CJ, Sanfratello L, Ranken D, Best E, MacArthur JA, Wallace T, Gilliam K, Donahue CH, Montano R, Bryant JE, Scott A, Stephen JM (2012) MEG-SIM: A Web Portal for Testing MEG Analysis Methods using Realistic Simulated and Empirical Data. Neuroinform 10:141-158 - -.. [2] Schalk, G., McFarland, D.J., Hinterberger, T., Birbaumer, N., Wolpaw, J.R. (2004) BCI2000: A General-Purpose Brain-Computer Interface (BCI) System. IEEE TBME 51(6):1034-1043 - -.. [3] Goldberger AL, Amaral LAN, Glass L, Hausdorff JM, Ivanov PCh, Mark RG, Mietus JE, Moody GB, Peng C-K, Stanley HE. (2000) PhysioBank, PhysioToolkit, and PhysioNet: Components of a New Research Resource for Complex Physiologic Signals. Circulation 101(23):e215-e220 - -.. [4] Cichy, R. M., Pantazis, D., & Oliva, A. Resolving human object recognition in space and time. Nature Neuroscience (2014): 17(3), 455-462 - -.. [5] Crosse, M. J., Di Liberto, G. M., Bednar, A., & Lalor, E. C. The Multivariate Temporal Response Function (mTRF) Toolbox: A MATLAB Toolbox for Relating Neural Signals to Continuous Stimuli. Frontiers in Human Neuroscience (2016): 10. - -.. [6] Dufau, S., Grainger, J., Midgley, KJ., Holcomb, PJ. A thousand words are worth a picture: Snapshots of printed-word processing in an event-related potential megastudy. Psychological science, 2015 - -.. [7] B Kemp, AH Zwinderman, B Tuk, HAC Kamphuisen, JJL Oberyé. Analysis of a sleep-dependent neuronal feedback loop: the slow-wave microcontinuity of the EEG. IEEE-BME 47(9):1185-1194 (2000). https://ieeexplore.ieee.org/document/867928 - -.. [8] Goldberger AL, Amaral LAN, Glass L, Hausdorff JM, Ivanov PCh, Mark RG, Mietus JE, Moody GB, Peng C-K, Stanley HE. PhysioBank, PhysioToolkit, and PhysioNet: Components of a New Research Resource for Complex Physiologic Signals. Circulation 101(23):e215-e220 [Circulation Electronic Pages; http://circ.ahajournals.org/cgi/content/full/101/23/e215]; 2000 (June 13). diff -Nru python-mne-0.18.1+dfsg/doc/manual/gui/analyze.rst python-mne-0.19.1+dfsg/doc/manual/gui/analyze.rst --- python-mne-0.18.1+dfsg/doc/manual/gui/analyze.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/gui/analyze.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,2673 +0,0 @@ - -.. _c_legacy_ch_interactive_analysis: - -===================================== -Interactive analysis with mne_analyze -===================================== - -.. contents:: Contents - :local: - :depth: 2 - - -Overview -######## - -Interactive analysis of the MEG/EEG data and source estimates -is facilitated by the :ref:`mne_analyze` tool. -Its features include: - -- Viewing of evoked-response data or data - segments in a topographical layout. - -- Alignment of MEG and head coordinate frames. - -- Display of maps of the magnetic field and electric potentials. - -- Computation and display of cortically-constrained minimum-norm current - estimates and statistical maps derived from them. The solutions can - be displayed on folded and inflated cortical surfaces as well as - on curved and flattened surface patches. - -- Fitting of current dipoles to the data. - -- Connection to tkmedit (part - of FreeSurfer) to display data on MRI slices. - -- Production of QuickTime (TM) movies and graphics snapshots - in several image file formats. - -- Connection to cliplab (part of Elekta-Neuromag software) to - produce graphics reports, see :ref:`CACJEFAI`. - -- Inquiry and saving of source waveforms at selected surface - points or within ROIs defined by label files. - -- On-line morphing of the current distributions. - -- Output of snapshots in w file format. - -- Display of overlay data delivered in w and stc file formats. - -- Creation of ROI (label) files. - -- Viewing of continuous head-position data delivered by Elekta-Neuromag - software. - -See :ref:`mne_analyze` for command line options. - -.. note:: Before starting mne_analyze the ``SUBJECTS_DIR`` environment variable has to be set. - - -The main window -############### - -.. _CACJABJI: - -.. figure:: mne_analyze/main_window.png - :alt: main window of mne_analyze - - The main window of mne_analyze. - -The main window of mne_analyze shown -in :ref:`CACJABJI` has the following components: - -- The menu bar; - -- Display area for a sample response; - -- Display of the estimated SNR, see :ref:`CACJFFEE`; - -- Display of a source waveform; - -- Message area, time-point selection text field, an ECD fit - button, a text field for selecting a vertex on the surface, and - a message text label; - -- Display area for the current estimates; - -- Controls for the current estimate display; - -- Topographical display of data. - -The menus -######### - -The File menu -============= - -The File shown in :ref:`CACJCBFI` contains the following items: - -.. _CACJCBFI: - -.. figure:: mne_analyze/file_menu.png - :alt: the file menu - :align: center - :figwidth: 25% - - The file menu - -**Open...** - - Load a new data set and an inverse operator. For details, see :ref:`CACBACHB`. - -**Open raw...** - - Load epoch data from a raw data file. For details, see :ref:`CACDEDBI`. - -**Switch to data set...** - - If multiple data sets or epochs from a raw data file are loaded, - this menu item brings up a list to switch between the data sets - or epochs. - -**Change working directory...** - - Change the working directory of this program. This will usually - be the directory where your MEG/EEG data and inverse operator are located. - -**Load surface...** - - Load surface reconstructions for the subject whose data you are analyzing, - see :ref:`CACFJICC`. - -**Load morphing surface...** - - Load surface reconstructions of another subject for morphing, see :ref:`CACGBEIB`. - -**Load surface patch...** - - Load a curved or flattened surface patch, see :ref:`CACFJICC`. - -**Load morphing surface patch...** - - Load a curved or flattened surface patch for morphing, see :ref:`CACGBEIB`. - -**Load digitizer data...** - - Load digitizer data for coordinate frame alignment, see :ref:`CACEHGCD`. - -**View continuous HPI data...** - - Load a data file containing continuous head position information, see :ref:`CACIADAI`. - -**Manage overlays...** - - Bring up the overlay manager to import data from stc and w files, see :ref:`CACFCHEC`. - -**Save bad channel selection** - - Save the current bad channel selection created in the topographical data - display, see :ref:`CACEFBDE`. - -**Quit** - - Quit the program. - -The Adjust menu -=============== - -The contents of the Adjust menu -is shown in :ref:`CACFDIJJ`: - -.. _CACFDIJJ: - -.. figure:: mne_analyze/adjust_menu.png - :alt: The Adjust menu - - The Adjust menu. - -**Scales** - - Adjust the scales of the data display. - -**Estimates...** - - Adjust the properties of the displayed current estimates, see :ref:`CACBHDBF`. - -**Select trace layout...** - - Select the layout for the topographical display, see :ref:`CACEFBDE`. - -**Lights...** - - Adjust the lighting of the scenes in the main display and the viewer, see - :ref:`CACBHDBF` and :ref:`CACEFFJF`. - -**Field mapping...** - - Adjust the field mapping preferences, see :ref:`CACICDGA`. - -**Coordinate alignment...** - - Establish a coordinate transformation between the MEG and MRI coordinate - frames, see :ref:`CACEHGCD`. - -The View menu -============= - -The contents of the file menu is shown in :ref:`CACBFCGF`: - -.. _CACBFCGF: - -.. figure:: mne_analyze/view_menu.png - :alt: The View menu - - The View menu. - -**Show viewer...** - - Loads additional surfaces and pops up the viewer window. The functions - available in the viewer are discussed in :ref:`CACEFFJF`. - -**Show MRI viewer...** - - Bring up the tkmedit program - to view MRI slices, see :ref:`CACCHCBF`. - -**Show coordinates...** - - Show the coordinates of a vertex, see :ref:`CHDIEHDH`. - -**Show timecourse manager...** - - Brings up the timecourse manager if some timecourses are available. - Timecourses are discussed in :ref:`CACCCFHH`. - -The Labels menu -=============== - -The contents of the Labels menu -is shown in :ref:`CACHCDCF`. ROI analysis with help of labels -is discussed in detail in :ref:`CACCCFHH`. - -.. _CACHCDCF: - -.. figure:: mne_analyze/labels_menu.png - :alt: The Labels menu - - The Labels menu. - -The label menu contains the following -items: - -**Load label...** - - Loads one label file for ROI analysis. - -**Load all labels...** - - Loads all label files available in a directory for ROI analysis. - -**Load parcellation...** - - Load cortical parcellation data produced by FreeSurfer from - directory $SUBJECTS_DIR/$SUBJECT/label and add the cortical regions - defined to the label list. - -**Show label list...** - - Shows a list of all currently loaded labels for ROI analysis. - -**Discard all labels** - - Discard all labels loaded so far. The label list window will be - hidden. - -**Clear marked vertices** - - Clear the label outline or a label created interactively. - -The Dipoles menu -================ - -The contents of the dipoles menu is shown in :ref:`CACCJDAF`: - -.. _CACCJDAF: - -.. figure:: mne_analyze/dipoles_menu.png - :alt: The dipole fitting menu - - The dipole fitting menu. - -**Setup fitting...** - - Define the dipole fitting parameters, see :ref:`CACEDEGA`. - -**Show dipole list...** - - Show the list of imported and fitted dipoles, see :ref:`CACGGAIA`. - -**Manage channel selections...** - - Manage the selections of channels used in dipole fitting, see :ref:`CACIBHCI`. - -The Help menu -============= - -The contents of the Help menu is shown in :ref:`help_menu_analyze`: - -.. _help_menu_analyze: - -.. figure:: mne_analyze/help_menu.png - :alt: The Help menu - - The Help menu. - -**On version...** - - Displays the version and compilation date of the program. - -**On license...** - - Displays the license information. - -**On GLX...** - - Displays information about the OpenGL rendering context. If you experience - poor graphics performance, check that the window that pops up from - here says that you have a Direct rendering context . - If not, either your graphics card or driver software needs an update. - -**Why the beep?** - - In some simple error situations, mne_analyze does - not popup an error dialog but refuses the action and rings the bell. - The reason for this can be displayed through this help menu item. - -.. _CACBACHB: - -Loading data -############ - -When you select Open... from -the File menu the data loading -dialog shown in :ref:`CACFHAIH` appears. It has four sections: - -- A standard file selection box. - -- List of available data sets. This part is automatically filled - in when a proper data file is selected from the file list. You can - select one or more data sets from this list. Multiple selection - works with help of the shift and control keys. If multiple data - sets are selected, the data set to be analyzed can be changed from - the data set list accessible through Switch to data set... in the File menu. - -- List of available inverse operator decompositions in the current - directory and its subdirectory called ``inv`` . - -- List of options: - - - MRI/head transform source specifies a file to read the MRI/MEG coordinate - transformation information from. This is usually the inverse operator - file. However, you can also load data with inverse operator set - to <*none*> to view the data - as well as field and potential maps derived thereof. In this case - you need to specify the coordinate transformation file using the Select... button, - usually located in ``mri/T1-neuromag/sets`` under the subject's - FreeSurfer directory. The Default button - uses the default transformation file which must be called ``$SUBJECTS_DIR/$SUBJECT/bem/$SUBJECT-trans.fif`` . - This can be one of the MRI description files in ``mri/T1-neuromag/sets`` or - a transformation file stored from mne_analyze , - see :ref:`CACEHGCD`. - - - Use EEG average electrode ref. selects - whether the average electrode reference is applied to the data. - This is only available if the inverse operator is set to <*none*> . - - - nave specifies the effective - number of averages to compute the SNR correctly. Usually your measurement - file contains this information. - -.. _CACFHAIH: - -.. figure:: mne_analyze/open_dialog.png - :alt: The open dialog - - The open dialog. - -After the data set(s) has been selected, the following actions -will take place: - -- The inverse operator will be loaded. - -- Baselines will be applied as specified in the scales dialog. - -- Projection will be applied to the data. If no inverse operator - is specified, the source for the projection data will be the data - file and the average EEG reference setting in the options. If an - inverse operator is included, the projection will be read from the - data file. - -- If an inverse operator is loaded, whitened data will be computed. - -- If an inverse operator is loaded, the SNR estimate as well - as the effective SNR will be computed from the whitened data and - displayed in the SNR window. - -- Waveforms will be shown in the topographical display as well - as in the sample channel display. - -If multiple data sets are loaded each data set has the following -individual settings: - -- Amplitude and time scale settings, - -- Baseline, - -- Picked time point, - -- Sample channel to be displayed, and - -- MNE display preferences, see :ref:`CACHFFIJ`. - -If a data set has not been previously displayed, the currently -active settings are copied to the data set. - -.. note:: If you double click on an inverse operator file name displayed in the Inverse operator list, the command used to produced this file will be displayed in a message dialog. - -.. _CACDEDBI: - -Loading epochs from a raw data file -################################### - -Instead of an evoked-response data file it is possible to -load epochs of data (single trials) from a raw data file. This option -is invoked from File/Open raw... . -The file selection box is identical to the one used for evoked responses -(:ref:`CACFHAIH`) except that data set selector is replaced -by the epoch selector show in :ref:`CACDCGIB`. - -.. _CACDCGIB: - -.. figure:: mne_analyze/epoch_selector.png - :alt: The raw data epoch selector - - The raw data epoch selector. - -The epoch selector contains the following controls: - -- The event specifier. Only events matching - this number are going to be considered. - -- The event source specifier. The event source can be either - the data file, *i.e.,* the digital trigger channel or - a event data file produced with mne_browse_raw or mne_process_raw , - see :ref:`CACJGIFA`. Using an event data file is useful - if, *e.g.*, the epochs to be processed epileptic spikes. - -- The time range specification. This determines the length of - the epoch with respect to the selected event. - -Once the settings have been accepted by clicking OK , -the first matching epoch will be displayed. You can switch between -epochs using the data set list accessible through Switch to data set... in the File menu. - -.. _CACEFBDE: - -Data displays -############# - -The MEG and EEG signals can be viewed in two ways: - -- A selection of MEG or EEG channel is - shown in a topographical layout. - -- One representative channel can be selected to the Sample channel display by clicking on a channel in the - topographical display. - -In both the sample channel display and the topographical -display, current time point can be selected with a left mouse click. -In addition, time point of interest can be entered numerically in -the text box at the bottom left corner of the main display. - -.. _CACHBJAC: - -The topographical display -========================= - -A selection of channels is always shown in the right most -part of the main display. The topographical layout to use is selected -from Adjust/Select trace layout... , -which brings up a window with a list of available layouts. The system-wide -layouts reside in $MNE_ROOT/share/mne_analyze/lout. In addition -any layout files residing in $HOME/.mne/lout are listed. The format -of the layout files and selection of the default layout is discussed -in :ref:`CACFGGCF`. - -Several actions can be performed with the mouse in the topographical data -display: - -**Left button click** - - Selects a time point of interest. - -**Left button click with control key** - - Selects a time point of interest and selects the channel under the pointer - to the sample channel display. - -**Left button drag with shift key** - - Enlarges the view to contain only channels in the selected area. - -**Middle button click or drag** - - Marks this channel as bad and clears all previously marked bad channel. - This action is only available if an inverse operator is *not* loaded. - An inverse operator dictates the selection of bad channels. The - current bad channel selection can be applied to the data from File/Save bad channel selection . - -**Middle button click or drag with control key** - - Extends the bad channel selection without clearing the previously active - bad channels. - -**Right button** - - Adjusts the channel selection used for dipole fitting in the same - way as the middle button selects bad channels. For more information - on channel selections, see :ref:`CACIBHCI`. - -.. _CACFGHBJ: - -The sample channel display -========================== - -The sample channel display shows one of the measurement channels -at the upper left corner of the mne_analyze user -interface. A time point can be selected with a left mouse click. -In addition, the following keyboard functions are associated with -the sample channel display: - -**Down** - - Change the sample channel to the next channel in the scanning order. - -**Up** - - Change the sample channel to the previous channel in the scanning order. - -**Right** - - Move forward in time by 1 ms. - -**Control Right** - - Move forward in time by 5 ms. - -**Left** - - Move backward in time by 1 ms. - -**Control Left** - - Move backward in time by 5 ms. - -Scale settings -============== - -The scales of the topographical and sample channel display -can be adjusted from the Scales dialog -which is invoked by selecting Adjust/Scales... from -the menus. The Scales dialog -shown in :ref:`CACJJCGD` has the following entries: - -**Analyze range min [ms]** - - Specifies the lower limit of the time range of data to be shown. - -**Analyze range max [ms]** - - Specifies the upper limit of the time range of data to be shown. - -**Use full time range** - - If this box is checked, all data available in the data file will - be shown. - -**Baseline min [ms]** - - Specifies the lower time limit of the baseline. - -**Baseline max [ms]** - - Specifies the upper time limit of the baseline. - -**Baseline in use** - - Baseline subtraction can be switched on and off from this button. - -**MEG amp min [fT/cm]** - - Lower limit of the vertical scale of planar gradiometer MEG channels. - -**MEG amp max [fT/cm]** - - Upper limit of the vertical scale of planar gradiometer MEG channels. - -**MEG axmult [cm]** - - The vertical scale of MEG magnetometers and axial gradiometers will - be obtained by multiplying the planar gradiometer vertical scale - limits by this value, given in centimeters. - -**EEG amp min [muV]** - - Lower limit of the vertical scale of EEG channels. - -**EEG amp max [muV]** - - Upper limit of the vertical scale of EEG channels. - -**Show stimulus channel** - - Show the digital trigger channel data in the sample view together with - the sample channel. - -.. _CACJJCGD: - -.. figure:: mne_analyze/scales_dialog.png - :alt: The Scales dialog - - The Scales dialog. - -.. _CACFJICC: - -The surface display -################### - -In mne_analyze , the current -estimates are visualized on inflated or folded cortical surfaces. -There are two visualization displays: the surface display, which -is always visible, and the 3D viewer which is invoked from the Windows/Show viewer... menu selection, see :ref:`CACEFFJF`. - -A total of eight surfaces or patches can be assigned to the -surface display: - -- The left and right hemisphere cortical - surfaces for the subject whose data you are analyzing. These surfaces - can be the inflated, white-matter, or pial surfaces. They are loaded - through the File/Load surface... menu - selection, - -- The left and right hemisphere cortical surfaces of another - subject or an alternative representation of the cortical surface - of the actual subject. For example, you can switch between the inflated - and folded (pial or white matter) cortical surfaces very easily. - These surfaces are loaded from the File/Load morphing surface... menu selection. - -- Left and right hemisphere curved or flat cortical patches - for the subject you are analyzing. This patch is loaded from the File/Load surface patch... menu selection. The full cortical - surfaces must be loaded first before loading the patches. - -- Patches for an another subject or another pair of patches - for the same subject through the File/Load morphing surface patch... menu selection. Again, the full - cortical surfaces must have been loaded first. - -.. _CHDIFFHJ: - -The surface selection dialog -============================ - -When File/Load surface... or File/Load morphing surface... is invoked, the surface selection dialog -shown in :ref:`CACDGJDC` appears. - -.. _CACDGJDC: - -.. figure:: mne_analyze/surface_selection_dialog.png - :alt: The surface selection dialog - - The surface selection dialog. - -The dialog has the following components: - -**List of subjects** - - This list contains the subjects available in the directory set with - the ``SUBJECTS_DIR`` environment variable. - -**List of available surfaces for the selected subject** - - Lists the surfaces available for the current subject. When you click on - an item in this list, it appears in the Selected surface text field. - -**x-rotation (deg)** - - Specifies the initial rotation of the surface around the *x* (left - to right) axis. Positive angle means a counterclockwise rotation - when the surface is looked at from the direction of the positive *x* axis. - Sometimes a more pleasing visualization is obtained when this rotations are - specified when the surface is loaded. - -**y-rotation (deg)** - - Specifies the initial rotation of the surface around the *y* (back - to front) axis. - -**z-rotation (deg)** - - Specifies the initial rotation of the surface around the *z* (bottom - to up) axis. - -The patch selection dialog -========================== - -The surface patches are loaded with help of the patch selection -dialog, which appears when File/Load surface patch... or File/Load morphing surface patch... is selected. This dialog, -shown in :ref:`CACHEEJD`, contains a list of available patches -and the possibility to rotate the a flat patch counterclockwise -by the specified number of degrees from its original orientation. -The patch is automatically associated with the correct hemisphere -on the basis of the two first letters in the patch name (lh = left -hemisphere, rh = right hemisphere). - -.. _CACHEEJD: - -.. figure:: mne_analyze/patch_selection_dialog.png - :alt: patch selection dialog - - The patch selection dialog. - -.. _CACCABEA: - -Controlling the surface display -=============================== - -The main surface display has a section called Adjust view , which has the controls shown in :ref:`CACCFCGJ`: - -**L and R** - - Select the left or right hemisphere surface loaded through File/Load surface... . - -**B** - - Display the surfaces for both hemispheres. - -**M** - - Display the surfaces loaded File/Load morphing surface... according to the L, R, and B hemisphere - selectors - -**P** - - Select the patch associated with the currently selected surface. For this - to work, either L or R must be selected. - -**Option menu** - - Select one of the predefined view orientations, see :ref:`CACCCGDB`, below. - -**Arrow buttons** - - Rotate the surface by increments specified in degrees in the text - box next to the arrows. - -.. _CACCFCGJ: - -.. figure:: mne_analyze/surface_controls.png - :alt: Surface controls - - Surface controls. - -The display can be also adjusted -using keyboard shortcuts, which are available once you click in -the main surface display with the left mouse button to make it active: - -**Arrow keys** - - Rotate the surface by increments specified in degrees in the Adjust View section. - -**+** - - Enlarge the image. - -**-** - - Reduce the image. - -**=** - - Return to the default size. - -**r** - - Rotate the image one full revolution around z axis using the currently - specified rotation step. This is useful for producing a sequence - of images when automatic image saving is on, see :ref:`CACBEBGC`. - -**s** - - Produces a raster image file which contains a snapshot of the currently - displayed image. For information on snapshot mode, see :ref:`CACBEBGC`. - -**.** - - Stops the rotation invoked with the 'r' key, see - above. - -In addition, the mouse wheel or trackball can be used to -rotate the image. If a trackball is available, *e.g.*, -with the Apple MightyMouse, the image can be rotated up and down -or left and right with the trackball. With a mouse wheel the image -will rotated up and down when the wheel is rotated. Image rotation -in the left-right direction is achieved by holding down the shift key -when rotating the wheel. The shift key -has the same effect on trackball operation. - -.. note:: The trackball and mouse wheel functionality is dependent on your X server settings. On Mac OSX these settings are normally correct by default but on a LINUX system some adjustments to the X server settings maybe necessary. Consult your system administrator or Google for details. - -.. _CHDIEHDH: - -Selecting vertices -================== - -When you click on the surface with the left mouse button, -the corresponding vertex number and the associated value will be -displayed on the message line at the bottom of the display. In addition, -the time course at this vertex will be shown, see :ref:`CHDGHDGE`. -You can also select a vertex by entering the vertex number to the -text field at the bottom of the display. If the MRI viewer is displayed and Track surface location in MRI is selected in the MRI viewer control dialog, the cursor in the MRI slices -will also follow the vertex selection, see :ref:`CACCHCBF`. - -The View menu choice Show coordinates... brings up a window which shows -the coordinates of the selected vertex on the *white matter* surface, *i.e.*, -lh.white and rh.white FreeSurfer surfaces. If morphing surfaces -have been loaded, the coordinates of both the subject being analyzed -and those of the morphing subject will be shown. The Coordinates window -includes the following lines: - -**MEG head** - - Indicates the vertex location in the *MEG head* coordinates. - This entry will be present only if MEG/EEG data have been loaded. - -**Surface RAS (MRI)** - - Indicates the vertex location in the *Surface RAS* coordinates. - This is the native coordinate system of the surfaces and this entry - will always be present. - -**MNI Talairach** - - Shows the location in MNI Talairach coordinates. To be present, - the MRI data of the subject must be in the mgz format (usually true with - any recent FreeSurfer version) and the Talairach transformation - must be appropriately defined during the *FreeSurfer* reconstruction - workflow. - -**Talairach** - - Shows the location in the *FreeSurfer* Talairach - coordinates which give a better match to the Talairach atlas. - -The above coordinate systems are discussed in detail in :ref:`CHDEDFIB`. - -.. note:: By default, the tksurfer program, part of the FreeSurfer package, shows the vertex locations on the *orig* rather than *white* surfaces. Therefore, the coordinates shown in mne_analyze and tksurfer are by default slightly different (usually by < 1 mm). To make the two programs consistent, you can start tksurfer with the ``-orig white`` option. - -.. _CACCCGDB: - -Defining viewing orientations -============================= - -The list of viewing orientations available in the Adjust View section of the main surface display is controlled -by a text file. The system-wide defaults reside in ``$MNE_ROOT/share/mne/mne_analyze/eyes`` . -If the file ``$HOME/.mne/eyes`` exists, it is used instead. - -All lines in the eyes file starting with # are comments. -The view orientation definition lines have the format: - -<*name*>:<*Left*>:<*Right*>:<*Left up*>:<*Right up*> , - -where - -**<*name*>** - - is the name of this viewing orientation, - -**<*Left*>** - - specifies the coordinates of the viewing 'eye' location - for the left hemisphere, separated by spaces, - -**<*Right*>** - - specifies the coordinates of the viewing location for the right - hemisphere, - -**<*Left up*>** - - specifies the direction which is pointing up in the image for left hemisphere, - and - -**<*Right up*>** - - is the corresponding up vector for the right hemisphere. - -All values are given in a coordinate system where positive *x* points -to the right, positive *y* to the front, and -positive *z* up. The lengths of the vectors specified -for each of the four items do not matter, since parallel projection is -used and the up vectors will be automatically normalized. The up -vectors are usually 0 0 1, *i.e.*, pointing to -the positive *z* direction unless the view is -directly from above or below or if some special effect is desired. - -The names of viewing orientations should be less than 9 characters -long. Otherwise, the middle pane of the main display will not be -able to accommodate all the controls. The widths of the main window -panes can be adjusted from the squares at the vertical sashes separating -the panes. - -Adjusting lighting -================== - -The scenes shown in the main surface display and the viewer, -described in :ref:`CACEFFJF`, are lit by fixed diffuse ambient -lighting and a maximum of eight light sources. The states, locations, -and colors of these light sources can be adjusted from the lighting -adjustment dialog shown in :ref:`CACDDHAI`, which can be -accessed through the Adjust/Lights... menu -choice. The colors of the lights can be adjusted numerically or -using a color adjustment dialog accessible through the Color... buttons. - -.. _CACDDHAI: - -.. figure:: mne_analyze/adjust_lights.png - :alt: lighting adjustment dialog - - The lighting adjustment dialog. - -.. _CACBEBGC: - -Producing output files -====================== - -.. _CACFBIHD: - -.. figure:: mne_analyze/hardcopy_controls.png - :alt: Graphics output controls - - Graphics output controls. - -Three types of output files can be produced from the main -surface display using the graphics output buttons shown in :ref:`CACFBIHD`: - -**w files (w button)** - - These files are simple binary files, which contain a list of vertex numbers - on the cortical surface and their current data values. The w files - will be automatically tagged with ``-lh.w`` and ``-rh.w`` . - They will only contain vertices which currently have a nonzero value. - -**Graphics snapshots (img button)** - - These files will contain an exact copy of the image in tif or rgb - formats. The output format and the output mode is selected from - the image saving dialog shown in :ref:`CACCEFGI`. For more - details, see :ref:`CACIJFII`. If snapshot or automatic image - saving mode is in effect, thee img button - terminates this mode. - -**QuickTime (TM) movies (mov button)** - - These files will contain a sequence of images as a QuickTime (TM) movie - file. The movie saving dialog shown in :ref:`CACFFBBD` specifies the - time range and the interval between the frames as well as the quality - of the movies, which is restricted to the range 25...100. The size - of the QuickTime file produced is approximately proportional to - the quality. - -.. _CACCEFGI: - -.. figure:: mne_analyze/image_dialog.png - :alt: File type selection in the image saving dialog - - File type selection in the image saving dialog. - -.. _CACFFBBD: - -.. figure:: mne_analyze/movie_dialog.png - :alt: The controls in the movie saving dialog - - The controls in the movie saving dialog. - -.. _CACIJFII: - -Image output modes -================== - -The image saving dialog shown in :ref:`CACCEFGI` selects -the format of the image files produced and the image output mode. -The buttons associated with different image format change the file -name filter in the dialog to display files of desired type. However, -the final output format is defined by the ending of the file name -in the Selection text field as -follows: - -**jpg** - - JPEG (Joint Photographic Experts Group) format. Best quality jpeg is - always produced. - -**tif or tiff** - - Uncompressed TIFF (Tagged Image File Format). - -**rgb** - - RGB format. - -**pdf** - - Portable Document File format. - -**png** - - Portable Network Graphics format. - -.. note:: Only TIFF and RGB output routines are compiled into mne_analyze . For other output formats to work, the following programs must be present in your system: tifftopdf, tifftopnm, pnmtojpeg, and pnmtopng. - -There are three image saving modes which can be selected -from the option menu labelled Output mode : - -**Single** - - When OK is clicked one file containing - the present image is output. - -**Snapshot** - - A new image file is produced every time ``s`` is pressed - in the image window, see :ref:`CACCABEA` and :ref:`CACFDDCB`. The image file name is used as the stem of - the output files. For example, if the name is, ``sample.jpg`` , - the output files will be ``sample_shot_001.jpg`` , ``sample_shot_002.jpg`` , *etc.* - -**Automatic** - - A new image file is produced every time the image window changes. - The image file name is used as the stem of the output files. For - example, if the name is, ``sample.jpg`` , the output files - will be ``sample_001.jpg`` , ``sample_002.jpg`` , *etc.* - -.. _CACGBEIB: - -Morphing -######## - -The displayed surface distributions can be morphed to another -subject's brain using the spherical morphing procedure, -see :ref:`c_legacy_ch_morph`. In addition to the morphing surfaces loaded -through File/Load morphing surface... surface -patches for the same subject can be loaded through File/Load morphing surface patch... . Switching between main and morphing -surfaces is discussed in :ref:`CACCABEA`. - -Any labels displayed are visible on any of the surfaces displayed -in the main surface display. Time points can be picked in any of -the surfaces. As a result, the corresponding timecourses will be -shown in the MNE amplitude window, see :ref:`CACCCFHH`. - -.. _CACEFFJF: - -The viewer -########## - -.. _CACFDDCB: - -Overview -======== - -.. _CACJDFFH: - -.. figure:: mne_analyze/viewer.png - :alt: viewer window - - The viewer window with a visualization of MEG and EEG contour maps. - -When Windows/Show viewer... is -selected, the following additional surfaces will be loaded: - -- The left and right hemisphere pial surfaces, - -- The surface representing the inner helmet shaped wall of the - dewar on which the MEG sensors are located, - -- The scalp surface, and - -- The BEM surfaces. - -The scalp surface is loaded from the file ``bem/`` <*subject*>``-head.fif`` under -the subject's FreeSurfer directory. This surface is automatically -prepared if you use the watershed algorithm as described in :ref:`BABBDHAG`. -If you have another source for the head triangulation you can use -the utility mne_surf2bem to create -the fif format scalp surface file, see :ref:`c_legacy_BEHCACCJ`. - -If a file called ``bem/`` <*subject*>``-bem.fif`` under -the subject's FreeSurfer directory is present, mne_analyze tries -to load the BEM surface triangulations from there. This file can -be a symbolic link to one of the ``-bem.files`` created -by mne_prepare_bem_model , see :ref:`c_legacy_CHDJFHEB`. -If the BEM file contains a head surface triangulation, it will be -used instead of the one present in the ``bem/`` <*subject*>``-head.fif`` file. - -Once all required surfaces have been loaded, the viewer window -shown in :ref:`CACJDFFH` pops up. In addition to the display -canvas, the viewer has Adjust view controls -similar to the main surface display and options for graphics output. -The Adjust view controls do not -have the option menu for standard viewpoints and has two additional -buttons: - -The output options only include graphics output as snapshots -(img ) or as movies (mov ). - -**Options...** - - This button pops up the viewer options window which controls the appearance - of the viewer window. - -**Rescale** - - This button adjusts the contour level spacing in the magnetic field and - electric potential contour maps so that the number of contour lines - is reasonable. - -**Reload** - - Checks the modification dates of the surface files loaded to viewer and - reloads the data if the files have been changed. This is useful, *e.g.*, - for display of different BEM tessellations. - -The display can be also adjusted -using keyboard shortcuts, which are available once you click in -the viewer display with the left mouse button: - -**Arrow keys** - - Rotate the surface by increments specified in degrees in the Adjust View section. - -**+** - - Enlarge the image. - -**-** - - Reduce the image. - -**=** - - Return to the default size. - -**r** - - Rotate the image one full revolution around z axis using the currently - specified rotation step. This is useful for producing a sequence - of images when automatic image saving is on, see :ref:`CACBEBGC`. - -**s** - - Produces a image file which contains a snapshot of the currently displayed - image. For information on snapshot mode, see :ref:`CACBEBGC`. - -**.** - - Stops the rotation invoked with the 'r' key, see - above. - -The left mouse button can be also used to inquire estimated -magnetic field potential values on the helmet and head surfaces -if the corresponding maps have been calculated and displayed. - -In addition, the mouse wheel or trackball can be used to -rotate the image. If a trackball is available, *e.g.*, -with the Apple MightyMouse, the image can be rotated up and down -or left and right with the trackball. With a mouse wheel the image -will rotated up and down when the wheel is rotated. Image rotation -in the left-right direction is achieved by holding down the shift key -when rotating the wheel. The shift key -has the same effect on trackball operation. - -.. note:: The trackball and mouse wheel functionality is dependent on your X server settings. On Mac OSX these settings are normally correct by default but on a LINUX system some adjustments to the X server settings maybe necessary. Consult your system administrator or Google for details. - -.. _CACHGDEA: - -Viewer options -============== - -.. figure:: mne_analyze/viewer_options.png - :alt: viewer options - - The viewer options window - -The viewer options window shown above contains three main -sections to control the appearance of the viewer: - -- Selectors for various items to show, - -- Options for some of the items, and - -- Control of the color and transparency of the items, if applicable. - The color can be adjusted either by entering numeric values in the - range 0...1 or with help of a color editor which appears from the Color... button. - The transparency value has the same range as the other color components, - zero indicating a fully transparent (invisible) surface and one a - fully opaque one. - -The available items are: - -**Left hemi** - - The pial surface of the left hemisphere. This surface can be made transparent. - Naturally, this surface will only be visible if the scalp is made - transparent. - -**Right hemi** - - The pial surface of the right hemisphere. - -**Inner skull** - - The inner skull surface. This surface can be made transparent. If parts - of the pial surface are outside of the inner skull surface, they will - be visible, indicating that the inner skull surface is obviously inside - the inner skull. Note that this criterion is more conservative than - the one imposed during the computation of the forward solution since - the source space points are located on the white matter surface - rather than on the pial surface. This surface can be displayed only - if the BEM file is present, see :ref:`CACFDDCB`. - -**Outer skull** - - The outer skull surface. This surface can be made transparent. This surface can - be displayed only if the BEM file is present and contains the outer - skull surface, see :ref:`CACFDDCB`. - -**Scalp** - - The scalp surface. This surface can be made transparent. The display - of this surface requires that the scalp triangulation file is present, - see :ref:`CACFDDCB`. - -**Digitizer data** - - The 3D digitizer data collected before the MEG/EEG acquisition. These - data are loaded from File/Load digitizer data... . - The display can be restricted to HPI coil locations and cardinal - landmarks with the option. The digitizer points are shown as disks - whose radius is equal to the distance of the corresponding point - from the scalp surface. Points outside the scalp are shown in red - and those inside in blue. Distinct shades of cold and warm colors - are used for the fiducial landmarks. The HPI coils are shown in - green. Further information on these data and their use in coordinate - system alignment is given in :ref:`CACEHGCD`. - -**Helmet** - - The MEG measurement surface, *i.e.*, inner surface - of the dewar. - -**EEG electrodes** - - The EEG electrode locations. These will be only available if your data - set contains EEG channels. - -**MEG sensors** - - Outlines of MEG sensors. - -**MEG field map** - - Estimated contour map of the magnetic field component normal to the - helmet surface or normal to the scalp, see :ref:`CACICDGA`. - -**EEG potential map** - - Interpolated EEG potential map on the scalp surface, see :ref:`CACICDGA`. - -**Activity estimates** - - Current estimates on the pial surface. - -.. _CACICDGA: - -Magnetic field and electric potential maps -########################################## - -Overview -======== - -In mne_analyze , the magnetic -field and potential maps displayed in the viewer window are computed -using an MNE-based interpolation technique. This approach involves -the following steps: - -- Establish an inverse operator to compute - a minimum norm solution on a spherical surface using a spherically - symmetric forward model. Instead of assuming a discrete grid of - sources, a continuous distribution of tangential currents is employed. - In this case the lead field dot products can be computed in closed - form. Separate solutions are computed for MEG and EEG. - -- The normal component of the magnetic field or the electric - potential on the helmet or head surface is computed from the MEG-based - and EEG-based MNE. Since the MNE predicts the original measurements - accurately, it can also interpolate and extrapolate the data reliably. - The grid of interpolation or extrapolation points can be located - on the helmet or scalp surface for MEG and on the scalp surface - for EEG. - -The magnetic field and potential maps appear automatically -whenever they are enabled from the viewer options, see :ref:`CACHGDEA`. - -.. _CACGFBCI: - -Technical description -===================== - -Let :math:`x_k` be an MEG or an EEG -signal at channel :math:`k = 1 \dotso N`. This signal -is related to the primary current distribution :math:`J^p(r)` through -the lead field :math:`L_k(r)`: - -.. math:: x_k = \int_G {L_k(r) \cdot J^p(r)}\,dG\ , - -where the integration space :math:`G` in -our case is a spherical surface. The oblique boldface characters -denote three-component locations vectors and vector fields. - -The inner product of two leadfields is defined as: - -.. math:: \langle L_j \mid L_k \rangle = \int_G {L_j(r) \cdot L_k(r)}\,dG\ , - -These products constitute the Gram matrix :math:`\Gamma_{jk} = \langle L_j \mid L_k \rangle`. -The minimum -norm estimate can be expressed as a weighted sum of -the lead fields: - -.. math:: J^* = w^T L\ , - -where :math:`w` is a weight vector -and :math:`L` is a vector composed of the -continuous lead-field functions. The weights are determined by the -requirement - -.. math:: x = \langle L \mid J^* \rangle = \Gamma w\ , - -i.e., the estimate must predict the measured signals. Hence, - -.. math:: w = \Gamma^{-1} x\ . - -However, the Gram matrix is ill conditioned and regularization -must be employed to yield a stable solution. With help of the SVD - -.. math:: \Gamma = U \Lambda V^T - -a regularized minimum-norm can now found by replacing the -data matching condition by - -.. math:: x^{(p)} = \Gamma^{(p)} w^{(p)}\ , - -where - -.. math:: x^{(p)} = (U^{(p)})^T x \text{ and } \Gamma^{(p)} = (U^{(p)})^T \Gamma\ , - -respectively. In the above, the columns of :math:`U^{(p)}` are -the first *k* left singular vectors of :math:`\Gamma`. -The weights of the regularized estimate are - -.. math:: w^{(p)} = V \Lambda^{(p)} U^T x\ , - -where :math:`\Lambda^{(p)}` is diagonal with - -.. math:: \Lambda_{jj}^{(p)} = \Bigg\{ \begin{array}{l} - 1/{\lambda_j},j \leq p\\ - \text{otherwise} - \end{array} - -:math:`\lambda_j` being the :math:`j` th singular -value of :math:`\Gamma`. The truncation point :math:`p` is -selected in mne_analyze by specifying -a tolerance :math:`\varepsilon`, which is used to -determine :math:`p` such that - -.. math:: 1 - \frac{\sum_{j = 1}^p {\lambda_j}}{\sum_{j = 1}^N {\lambda_j}} < \varepsilon - -The extrapolated and interpolated magnetic field or potential -distribution estimates :math:`\hat{x'}` in a virtual -grid of sensors can be now easily computed from the regularized -minimum-norm estimate. With - -.. math:: \Gamma_{jk}' = \langle L_j' \mid L_k \rangle\ , - -where :math:`L_j'` are the lead fields -of the virtual sensors, - -.. math:: \hat{x'} = \Gamma' w^{(k)}\ . - -Field mapping preferences -========================= - -The parameters of the field maps can be adjusted from the Field mapping preferences dialog shown in :ref:`CACGDCGA` which is accessed through the Adjust/Field mapping... menu item. - -.. _CACGDCGA: - -.. figure:: mne_analyze/field_mapping_pref.png - :alt: Field mapping preferences dialog - - Field mapping preferences dialog. - -The Field mapping preferences dialog -has the following controls, arranged in MEG , EEG , -and common sections: - -**SVD truncation at** - - Adjusts the smoothing of the field and potential patterns. This parameter - specifies the eigenvalue truncation point as described in :ref:`CACGFBCI`. Smaller values correspond to noisier field - patterns with less smoothing. - -**Use default origin** - - The location of the origin of the spherical head model used in these computations - defaults to (0 0 40) mm. If this box is unchecked the origin coordinate - fields are enabled to enter a custom origin location. Usually the - default origin is appropriate. - -**Downsampling grade** - - This option only applies to EEG potential maps and MEG field maps - extrapolated to the head surface and controls the number of virtual - electrodes or point magnetometers used in the interpolation. Allowed - values are: 2 (162 locations), 3 (642 locations), and 4 (2562 locations). - Usually the default value 3 is appropriate. - -**Number of smoothsteps** - - This option controls how much smoothing, see :ref:`CHDEBAHH`, - is applied to the interpolated data before computing the contours. - Usually the default value is appropriate. - -**Reconstruction surface radius** - - Distance of the spherical reconstruction surface from the sphere model - origin. Usually default value is appropriate. For children it may - be necessary to make this value smaller. - -.. _CACBHDBF: - -Working with current estimates -############################## - -.. _CACHFFIJ: - -Preferences -=========== - -The characteristics of the current estimates displayed are -controlled from the MNE preferences dialog -which pops up from Adjust/Estimates... . - -This dialog, shown in :ref:`CACJGCDH`, has the following -controls: - -**SNR estimate** - - This controls the regularization of the estimate, i.e., the amount - of allowed mismatch between the measured data and those predicted by - the estimated current distribution. Smaller SNR means larger allowed - mismatch. Typical range of SNR values is 1...7. As discussed in :ref:`CBBDJFBJ`, - the SNR value can be translated to the current variance values expressed - in the source-covariance matrix R. This translation is presented - as the equivalent current standard-deviation value - -**Show** - - This radio button box selects the quantity to display. MNE is - the minimum norm estimate (estimated value of the current), dSPM is the - noise-normalized MNE, and sLORETA is - another version of the noise-normalized solution which is claimed - to have a smaller location bias than the dSPM. - -**Mask with** - - If MNE is selected in the Show radio - button box, it is possible to mask the solution with one of the - statistical maps. The masking map is thresholded at the value given - in the Threshold text field and - the MNE is only shown in areas with statistical values above this threshold. - -**Value histogram** - - This part of the dialog shows the distribution of the currently - shown estimate values over the surface. The histogram is colored - to reflect the current scale settings. The fthresh , fmid , - and fmax values are indicated - with vertical bars. The histogram is updated when the dialog is - popped up and when the estimate type to show changes, not at every - new time point selection. The Refresh button - makes the histogram current at any time. - -**Color scale** - - These text fields control the color scale as described in :ref:`CACGGICI`. - -**Options** - - Various options controlling the estimates. - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.45\linewidth}| -.. _CACGGICI: -.. table:: The color scale parameters. - - +------------+---------------------------------------------------------+ - | Parameter | Meaning | - +============+=========================================================+ - | fthresh | If the value is below this level, it will not be shown. | - +------------+---------------------------------------------------------+ - | fmid | Positive values at this level will show as red. | - | | Negative values will be dark blue. | - +------------+---------------------------------------------------------+ - | fmax | Positive values at and above this level will be bright | - | | yellow. Negative values will be bright blue. | - +------------+---------------------------------------------------------+ - | fmult | Apply this multiplier to the above thresholds. Default | - | | is :math:`1` for statistical maps and :math:`1^{-10}` | - | | for currents (MNE). The vertical bar locations in the | - | | histogram take this multiplier into account but the | - | | values indicated are the threshold parameters without | - | | the multiplier. | - +------------+---------------------------------------------------------+ - | tcmult | The upper limit of the timecourse vertical scale will | - | | be :math:`tc_{mult}f_{mult}f_{max}`. | - +------------+---------------------------------------------------------+ - - -.. _CACJGCDH: - -.. figure:: mne_analyze/MNE_preferences.png - :alt: MNE estimate preferences - - Estimate preferences dialog. - -The optional parameters are: - -**Retain sign** - - With this option, the sign of the dot product between the current direction - and the cortical surface normal will be used as the sign of the - values to be displayed. This option yields meaningful data only if - a strict or a loose orientation constraint was used in the computation - of the inverse operator decomposition. - -**Retain normal component only** - - Consider only the current component normal to the cortical mantle. This - option is not meaningful with completely free source orientations. - -**Show scale bar** - - Show the color scale bar at the lower right corner of the display. - -**Show comments** - - Show the standard comments at the lower left corner of the display. - -**Time integr. (ms)** - - Integration time for each frame (:math:`\Delta t`). - Before computing the estimates time integration will be performed - on sensor data. If the time specified for a frame is :math:`t_0`, - the integration range will be :math:`t_0 - ^{\Delta t}/_2 \leq t \leq t_0 + ^{\Delta t}/_2`. - -**# of smooth steps** - - Before display, the data will be smoothed using this number of steps, - see :ref:`CHDEBAHH`. - -**Opacity** - - The range of this parameter is 0...1. The default value 1 means - that the map overlaid on the cortical surface is completely opaque. - With lower opacities the color of the cortical surface will be visible - to facilitate understanding the underlying folding pattern from - the curvature data displayed. - -.. _CACJFFEE: - -The SNR display -=============== - -The SNR estimate display -shows the SNR estimated from the whitened data in red and the apparent -SNR inferred from the mismatch between the measured and predicted -data in green. - -The SNR estimate is computed from the whitened data :math:`\tilde{x}(t)`, -related to the measured data :math:`x(t)` by - -.. math:: \tilde{x}(t) = C^{-^1/_2} x(t)\ , - -where :math:`C^{-^1/_2}` is the whitening -operator, introduced in :ref:`CHDDHAGE`. - -The computation of the apparent SNR will be explained in -future revisions of this manual. - -.. _CACCCFHH: - -Inquiring timecourses -##################### - -.. _CHDGHDGE: - -Timecourses at vertices -======================= - -Timecourses at individual vertices can be inquired by clicking -on a desired point on the surface with the left mouse button. If -the control key was down at the time of a click, the timecourse -will be added to the timecourse manager but left off. With both -control and shift down, the timecourse will be added to the timecourse -manager and switched on. For more information on the timecourse -manager, see :ref:`CACDIAAD`. - -The timecourses are be affected by the Retain sign and Retain normal component only settings in the MNE preferences dialog , see :ref:`CACHFFIJ`. - -Timecourses at labels -===================== - -The labels provide means to interrogate timecourse information -from ROIs. The label files can be created in mne_analyze , -see :ref:`CACJCFJJ` or in tksurfer , -which is part of the FreeSurfer software. For mne_analyze left-hemisphere -and right-hemisphere label files should be named <*name*> ``-lh.label`` and <*name*> ``-rh.label`` , -respectively. - -Individual label files can be loaded from Labels/Load label... . All label files in a directory can be -loaded from Labels/Load all labels... . -Once labels are loaded, the label list shown in :ref:`CACJJGEF` appears. Each -time a new label is added to the list, the names will be reordered -to alphabetical order. This list can be also brought up from Labels/Show label list . The list can be cleared from Labels/Discard all labels . - -.. warning:: Because of the format of the label files mne_analyze can not certify that the label files loaded belong to the cortical surfaces of the present subject. - -When a label is selected from the label list, the corresponding -timecourse appears. The Keep button -stores the timecourse to the timecourse manager, :ref:`CACDIAAD`. - -.. _CACJJGEF: - -.. figure:: mne_analyze/label_list.png - :alt: label list - - The label list. - -The timecourse shown in the MNE amplitude window -is a compound measure of all timecourses within a label. Two measures -are available: - -**Average** - - Compute the average over all label vertices at each time point. - -**Maximum** - - Compute the maximum absolute value over all vertices at each time point. - If the data are signed, the value is assigned the sign of the value - at the maximum vertex. This may make the timecourse jump from positive - to negative abruptly if vertices with different signs are included - in the label. - -**L2 norm (sample by sample)** - - Compute the :math:`l_2` norm over the values - in the vertices at each time point. - -**Pick vertex with largest L2 norm over time** - - Compute the :math:`l_2` norm over time in - each vertex and show the time course at the vertex with the largest - norm. - -.. _CACDIAAD: - -The timecourse manager -====================== - -The timecourse manager shown in :ref:`CACEDEJI` has -the following controls for each timecourse stored: - -.. _CACEDEJI: - -.. figure:: mne_analyze/timecourse_manager.png - :alt: timecourse manager - - The timecourse manager. - -**Numbered checkbox** - - Switches the display of this timecourse on and off. - -**Color...** - - This button shows the color of the timecourse curve. The color can be - adjusted from the color editor which appears when the button is pressed. - -**Save...** - - Saves the timecourse. If a single vertex is selected, the time course file - will contain some comment lines starting with the the percent sign, - one row of time point values in seconds and another with the data - values. The format of the timecourse data is explained in :ref:`CACJJGFA`, below. - -**Forget** - - Delete this timecourse from memory. - -.. _CACJJGFA: - -Label timecourse files ----------------------- - -When timecourse corresponding to a label is saved, the default -is to save the displayed single timecourse in a format identical -to the vertex timecourses. If Save all timecourses within the label is selected, the Time-by-time output output changes the output to be listed -time by time rather than vertex by vertex, Include coordinates adds the vertex location information to -the output file, and Include vertex numbers adds -the indices of picked vertices to the output, see :ref:`CACHBBFD`. -The vertex-by-vertex output formats is summarized in :ref:`CACEFHIJ`. - -.. _CACHBBFD: - -.. figure:: mne_analyze/save_label_timecourse.png - :alt: Label timecourse saving options - - Label timecourse saving options. - -.. _CACEFHIJ: - -.. table:: Vertex-by-vertex output format. :math:`n_p` is the number of vertices, :math:`n_t` is the number of time points, :math:`n_{com}` is the number of comment lines, :math:`t_1 \dotso t_{n_t}` indicate the times in milliseconds, :math:`p` is a vertex number, :math:`x_p y_p z_p` are the coordinates of vertex :math:`p` in millimeters, and :math:`v_p^{(1)} \dotso v_p^{(n_t)}` are the values at vertex :math:`p`. Items in brackets are only included if *Include coordinates* is active. In the time-by-time output format the data portion of the file is transposed. - - =================================== ====================================================== - Line Contents - =================================== ====================================================== - :math:`1-n_{com}` Comment lines beginning with % - :math:`n_{com}+1` :math:`\{0.0\}[0.0\ 0.0\ 0.0] t_1 \dotso t_{n_t}` - :math:`(n_{com}+1)-(n_p+n_{com}+1)` :math:`\{p\}[x_p y_p z_p]v_p^{(1)} \dotso v_p^{(n_t)}` - =================================== ====================================================== - -.. _CACJCFJJ: - -Creating new label files -======================== - -It is easy to create new label files in mne_analyze. -For this purpose, an inflated surface should be visible in the main -display. Follow these steps: - -- Clear all previously selected vertices - either by choosing Labels/Clear marked vertices or - do a right button click on the surface display with the shift key - down. - -- Mark vertices on the surface with right button click or by - right button drag. The vertices should be defined in the desired - order on the new label outline. The outline will follow the shortest - path along the surface. The shortest path will be calculated along - the white matter surface.Note that sometimes the shortest paths - appear to be un-intuitive on the inflated surface. - -- Do a right button click with control key down inside the label. - The outline will be completed and shown as a yellow line. The inside - of the label will be filled and shown in green. A file selection - box will appear to save the label. Enter the stem of the file name - here. The file name will be augmented with ``-lh.label`` or ``-rh.label`` , - depending on the hemisphere on which the label is specified. - -.. _CACFCHEC: - -Overlays -######## - -.. _CACIGHEJ: - -.. figure:: mne_analyze/overlay_management.png - :alt: The overlay management dialog - - The overlay management dialog. - -In addition to source estimates derived from MEG and EEG -data, mne_analyze can be used -to display other surface-based data. These overlay data can be imported -from w and stc files containing single time slice (static) and dynamic -data (movies), respectively. These data files can be produced by mne_make_movie , -FreeSurfer software, and custom programs or Matlab scripts. - -The names of the files to be imported should end with ``-`` <*hemi*> .<*type*> , where <*hemi*> indicates -the hemisphere (``lh`` or ``rh`` and <*type*> is ``w`` or ``stc`` . - -Overlays are managed from the dialog shown in :ref:`CACIGHEJ` which is invoked from File/Manage overlays... . - -This dialog contains the following -controls: - -**List of overlays loaded** - - Lists the names of the overlays loaded so far. - -**Load w...** - - Load a static overlay from a w file. In the open dialog it is possible to - specify whether this file contains data for the cortical surface - or for scalp. Scalp overlays can be viewed in the viewer window. - -**Load stc...** - - Load a dynamic overlay from an stc file. In the open dialog it is - possible to specify whether this file contains data for the cortical - surface or for scalp. Scalp overlays can be viewed in the viewer window. - -**Delete** - - Delete the selected overlay from memory. - -**Time scale slider** - - Will be activated if a dynamic overlay is selected. Changes the - current time point. - -**Overlay type is** - - Selects the type of the data in the current overlay. Different default color - scales are provided each overlay type. - -**Value histogram** - - Shows the distribution of the values in the current overlay. For - large stc files this may take a while to compute since all time - points are included. The histogram is colored to reflect the current - scale settings. The fthresh , fmid , - and fmax values are indicated - with vertical bars. - -**Color scale** - - Sets the color scale of the current overlay. To activate the values, press Show . - For information on color scale settings, see :ref:`CACGGICI`. - -**Options** - - Display options. This a subset of the options in the MNE preferences dialog. For details, see :ref:`CACHFFIJ`. - -**Show** - - Show the selected overlay and assign the settings to the current overlay. - -**Apply to all** - - Apply the current settings to all loaded overlays. - -It is also possible to inquire timecourses of vertices and -labels from dynamic (stc) cortical overlays in the same way as from -original data and store the results in text files. If a static overlay -(w file) or a scalp overlay is selected, the timecourses are picked -from the data loaded, if available. - -.. _CHDGHIJJ: - -Fitting current dipoles -####################### - -Starting from MNE software version 2.6, mne_analyze includes -routines for fitting current dipoles to the data. At present mne_analyze is -limited to fitting single equivalent current dipole (ECD) at one -time point. The parameters affecting the dipole fitting procedure -are described in :ref:`CACEDEGA`. The results are shown in -the dipole list (:ref:`CACGGAIA`). The selection of channels -included can be adjusted interactively or by predefined selections -as described in :ref:`CACIBHCI`. - -.. warning:: The current dipole fitting has been added recently and has not been tested comprehensively. Especially fitting dipoles to EEG data may be unreliable. - -.. _CACEDEGA: - -Dipole fitting parameters -========================= - -Prior to fitting current dipoles, the fitting parameters -must be set with the Dipole fitting preferences dialog -shown in :ref:`CACFEDEJ`. The dialog is brought up from the Setup fitting... choice in the Dipoles menu. -This dialog contains three sections: Forward model , Modalities , -and Noise estimate . - -The Forward model section -specifies the forward model to be used: - -**Sphere model origin x/y/z [mm]** - - Specifies the origin of the spherically symmetric conductor model in - MEG/EEG head coordinates, see :ref:`BJEBIBAI`. - -**EEG scalp radius [mm]** - - Specifies the radius of the outermost shell in the EEG sphere model. For - details, see :ref:`CHDIAFIG`. - -**EEG sphere model name** - - Specifies the name of the EEG sphere model to use. For details, - see :ref:`CHDIAFIG`. - -**BEM model** - - Selects the boundary-element model to use. The button labeled with ... brings - up a file-selection dialog to select the BEM file. An existing selection - can be cleared with the Unset button. - If EEG data are included in fitting, this must be a three-compartment - model. Note that the sphere model is used even with a BEM model - in effect, see :ref:`CHDFGIEI`. - -**Accurate field calculation** - - Switches on the more accurate geometry definition of MEG coils, see :ref:`BJEIAEIE`. - In dipole fitting, there is very little difference between the *accurate* and *normal* coil - geometry definitions. - -The Modalities section -defines which kind of data (MEG/EEG) are used in fitting. If an -inverse operator is loaded with the data, this section is fixed and -greyed out. You can further restrict the selection of channels used -in dipole fitting with help of channel selections discussed in :ref:`CACIBHCI`. - -The Noise estimate section -of the dialog contains the following items: - -**Noise covariance** - - Selects the file containing the noise-covariance matrix. If an inverse operator - is loaded, the default is the inverse operator file. The button labeled - with ... brings up a file-selection - dialog to select the noise covariance matrix file. An existing selection - can be cleared with the Unset button. - -**Omit off-diagonal terms** - - If a noise covariance matrix is selected, this choice omits the - off-diagonal terms from it. This means that individual noise estimates for - each channel are used but correlations among channels are not taken - into account. - -**Regularization** - - Regularize the noise covariance before using it in whitening by - adding a multiple of an identity matrix to the diagonal. This is - discussed in more detail in :ref:`cov_regularization`. Especially if - EEG is included in fitting it is advisable to enter a non-zero value - (around 0.1) here. - -**Planar fixed [fT/cm]** - - In the absence of a noise covariance matrix selection, a diagonal noise - covariance with fixed values on the diagonal is used. This entry - specifies the fixed value of the planar gradiometers. - -**Axial fixed [fT]** - - If a noise covariance matrix file is not specified, this entry specifies a - fixed diagonal noise covariance matrix value for axial gradiometers - and magnetometers. - -**EEG fixed [muV]** - - If a noise covariance matrix file is not specified, this entry specifies a - fixed diagonal noise covariance matrix value for axial gradiometers - and magnetometers.. - -.. _CACFEDEJ: - -.. figure:: mne_analyze/dipole_parameters.png - :alt: The dipole fitting preferences dialog - - The dipole fitting preferences dialog. - -.. _CHDFGIEI: - -The dipole fitting algorithm -============================ - -When the dipole fitting preferences dialog is closed and -the values have been modified the following preparatory calculations -take place: - -- If EEG data are included in fitting - present, the EEG sphere model specification corresponding to EEG sphere model name is loaded and scaled to the - the EEG scalp radius . - -- If a boundary-element model is used, the additional data depending - on the sensor locations are computed. - -- The noise covariance matrix is composed according to the specifications - in the Dipole fitting preferences dialog. - -- The spatially whitened forward solution is computed in a grid - of locations to establish the initial guess when a dipole is fitted. - If a BEM is in use, the grid will be confined to the inner skull - volume. For a sphere model, a spherical volume with an 80-mm radius, - centered at the sphere model origin, will be employed. The dipole - grid will be rectangular with a 10-mm spacing between the closest - dipole locations. Any locations closer than 20 mm to the center - of mass of the grid volume will be excluded as well as those closer - than 10 mm to the surface. Note that this guess grid is only used - for establishing the initial guess; the actual dipole fitting procedure - does not constrain the solution to this grid. - -When the Fit ECD button -in the tool bar is clicked with a time point selected from the the -response, the optimal Equivalent Current Dipole parameters (location, -orientation, and amplitude) are determined using the following algorithm: - -- An initial guess for the location of - the dipole is determined using the grid of locations determined - in step 4., above. At each guess dipole location, the least squares - error between the measured data and a dipole at that location is - evaluated and the location corresponding to the smallest error is - used as the initial guess location. In this process, the dipole - amplitude parameters do not need to be explicitly calculated. - -- Using the Nelder-Mead simplex optimization algorithm, an optimal dipole - location is determined with the sphere model used as the forward - model. Again, the dipole amplitude parameters are not explicitly present - in the fitting procedure. - -- A second optimization iteration using the boundary-element - model (if available) or the sphere model as the forward model is - conducted. The reason for repeating the optimization even with the - sphere model is to reduce the likelihood of having been stuck in - a local minimum of the least squares error criterion. - -- The optimal dipole amplitude parameters are determined for - the optimal dipole location obtained in steps 2. and 3. - -- The dipole parameters are reported in the dipole list discussed - in :ref:`CACGGAIA`. - -Additional notes: - -- The noise covariance matrix is always - applied to the data and the forward solution as appropriate to correctly - weight the different types of MEG channels and EEG. Depending on - the dipole fitting settings, the noise covariance may be either - a diagonal matrix or a full matrix including the correlations. - -- Using the SVD of the whitened gain matrix of three dipole - components at a given location, the component producing the weakest - signal amplitude is omitted if the ratio of the smallest and largest - singular values is less than 0.2. - -- The present MNE software package also contains a batch-mode - dipole fitting program called mne_dipole_fit . - This piece of software is not yet documented here. However, ``mne_dipole_fit --help`` lists the command-line options which have direct correspondence - to the interactive dipole fitting options discussed here. - -.. _CACGGAIA: - -The dipole list -=============== - -.. _CACGGFEJ: - -.. figure:: mne_analyze/dipole_list.png - :alt: dipole list - - The dipole list. - -The dipole list dialog shown in :ref:`CACGGFEJ` contains -the parameters of the dipoles fitted. In addition, it is possible -to import current dipole locations from the Neuromag source modelling -program xfit to mne_analyze . Dipoles -can be imported in two ways: - -- Bring up the dipole list window from Windows/Show dipole list... . Drag and drop selected dipoles - from one of the xfit dipole list - to this list using the middle mouse button. - -- Drag and drop dipoles from one of the xfit dipole - lists over the main surface display. The dipole list will appear - and contain the dropped dipoles. - -The buttons at the bottom of the dialog perform the following -functions: - -**Done** - - Hide - the dialog. - -**Show** - - Show - the currently selected dipoles as specified in Display options , - see below. - -**Save** - - Save the selected (or all) dipoles. - If the file name specified in the file selection dialog that pops - up ends with ``.bdip`` , the dipole data will be saved in - the binary bdip format compatible with - the Neuromag xfit software, otherwise, - a text format output will be used. In the text file, comments will - be included on lines starting with the percent sign so that the - text format can be easily loaded into Matlab. - -**Clear** - - Clear - the selected dipoles from the list. - -When you double click on one of the dipoles or select several -dipoles and click Show points -on the surface displayed in the vicinity of the dipoles will be -painted according to the specifications given in the Options section of -the dialog: - -**Color** - - By the default, the dipoles are marked in green with transparency (alpha) - set to 0.5. I you click on one of the dipoles, you can adjust the - color of this dipole by editing the color values or from the color editor - appearing when you click Color... . - When you click Apply , the new - color values are attached to the selected dipole. - -**Max. distance for dipoles to show (mm)** - - If this option is on, only dipoles which are closer to the surface - than the distance specified in the adjacent text field are displayed. - -**Paint all point closer than (mm)** - - Instead of indicating the point closest to the dipole all points - closer than the distance given in the text field will be painted - if this option is on. This choice is useful for understanding the - shape of the neighborhood of a dipole on the cortical surface. - -**Number of smooth steps** - - This option spreads out the dipole marking by the given number of smooth - steps to make the dipoles more clearly visible. A suitable choice - is 3 or 4. - -**Keep previous dipoles** - - If this option is on, previously marked dipoles are not cleared - from the display before new ones are shown. - -.. note:: The surface must be loaded to display dipole locations. To calculate the distance from the dipoles to the white matter surface, the white matter tessellation is loaded as needed. Depending on the precise location of the fitted dipole, the spot indicating the dipole site may easily appear on a different wall of a fissure than could be expected. The fissural walls can be far apart from each other in the inflated view of the cortex even if they are physically separated by just a few millimeters. The size of the spots indicating the dipole locations do not relate to the dipole strengths or their confidence limits in any way. - -.. _CACIBHCI: - -Channel selections -================== - -As mentioned in :ref:`CACHBJAC`, the right mouse button -in the topographical display of channels can be used to restrict -the selection of channels taken into account in dipole fitting. -In addition, the channel selections can be manipulated in the channel -selection window, which pops up from Dipoles/Manage channel selections... . Initially this dialog contains -the selections defined in or $HOME/.mne/mne_analyze.sel or $MNE_ROOT/share/mne/mne_analyze/mne_analyze.sel, -the personal file taking precedence over the system wide default. -The Save button in this dialog -save the current set of channel selections to the personal selection -file. The format of this file is identical to the channel selection -file in mne_browse_raw . - -When a channel selection file is in effect. the variances -of the unselected channels are increased by a factor of 900. This -means that unselected channels receive virtually no weight in the -least-squares error function or, equivalently, that they are considered -to be 30 times more noisy than their true noise value. Since this -implementation of channel selections requires recomputation of the -initial guess candidate data discussed in :ref:`CHDFGIEI`, -above, changing the selection may take a finite amount of time, -especially if a BEM is used for the forward calculation. - -.. note:: Please note that when making a channel selection in the topographical displays, the channels not present in a particular layout are also affected. For example, if you select channels in a layout showing the Vectorview planar gradiometers, the magnetometer channels and EEG channels will be unselected. - -.. _CACEHGCD: - -Coordinate frame alignment -########################## - -The MRI-MEG coordinate frame alignment tools included in mne_analyze utilized -the 3D digitizer (Polhemus) data acquired in the beginning of each -MEG/EEG session and the scalp surface triangulation shown in the -viewer window. To access the coordinate frame alignment tools: - -- Load digitizer data. You can either - load a data set containing digitizer information or load digitizer - data from a file through the File/Load digitizer data... menu choice. - -- Set up the viewer window and make it visible, see :ref:`CACEFFJF`. The viewer options should be set to show the - digitizer data, see :ref:`CACHGDEA`. - -- Bring up the Adjust coordinate alignment dialog from Adjust/Coordinate alignment... . - -.. figure:: mne_analyze/adjust_alignment.png - :alt: The coordinate frame alignment dialog - - The coordinate frame alignment dialog. - -The coordinate frame alignment dialog contains the following -sections: - -- Buttons for picking the fiducial points - from the scalp surface and one for setting an initial alignment - using these points. When one of the fiducials is selected, the viewer - display automatically rotates to a suitable orientation to make - the corresponding fiducial accessible. - -- Controls for fine tuning the alignment. These include movements - along the three orthogonal coordinate axes and rotations around - them. The buttons marked L and R indicate - rotations in counterclockwise and clockwise directions, respectively. - The amount of movement (mm) or rotation (degrees) is given in the - text fields next to the adjustment buttons. - -- Access to an automatic alignment procedure, which employs - the Iterative Closest Point (ICP) algorithm. - -- Listing of the current coordinate transformation. - -- Buttons for discarding outlier points (Discard... ), and for - saving and loading the coordinate transformation. - -The saving and loading choices are: - -**Save default** - - Saves a file which contains the MEG/MRI coordinate transformation - only. The file name is generated from the name of the file from which - the digitization data were loaded by replacing the ending ``.fif`` with ``-trans.fif`` . - If this file already exists, it will be overwritten without any - questions asked. - -**Save MRI set** - - This option searches for a file called COR.fif in $SUBJECTS_DIR/$SUBJECT/mri/T1-neuromag/sets. - The file is copied to COR-<*username*>-<*date*>-<*time*>.fif - and the current MEG/MRI coordinate transformation as well as the - fiducial locations in MRI coordinates are inserted. - -**Save...** - - Saves a file which contains the MEG/MRI coordinate transformation - only. The ending ``-trans.fif`` is recommended. The file name - selection dialog as a button to overwrite. - -**Load...** - - Loads the MEG/MRI coordinate transformation from the file specified. - -The MEG/MRI coordinate transformation files are employed -in the forward calculations. The convenience script mne_do_forward solution described in :ref:`BABCHEJD` uses -a search sequence which is compatible with the file naming conventions -described above. It is recommended that -trans.fif file -saved with the Save default and Save... options -in the mne_analyze alignment -dialog are used because then the $SUBJECTS_DIR/$SUBJECT directory -will be composed of files which are dependent on the subjects's -anatomy only, not on the MEG/EEG data to be analyzed. - -Each iteration step of the Iterative Closest Point (ICP) algorithm consists of -two matching procedures: - -- For each digitizer point, transformed - from MEG to the MRI coordinate frame using the current coordinate - transformation, the closest point on the triangulated surface is - determined. - -- The best coordinate transformation aligning the digitizer - points with the closest points on the head surface is computed. - -These two steps are iterated the designated number of times. -If the Try to keep nasion in place option -is on, the present location of the nasion receives a strong weight -in the second part of each iteration step so that nasion movements -are discouraged. - -.. note:: One possible practical approach to coordinate frame alignment is discussed in :ref:`CHDIJBIG`. - -.. _CHDCGHIF: - -Using a high-resolution head surface tessellations -================================================== - -The newest version of FreeSurfer contains a script called mkheadsurf which -can be used for coordinate alignment purposes. For more information, -try ``mkheadsurf --help`` . This script produces a file -called ``surf/lh.smseghead`` , which can be converted into -a fif file using mne_surf2bem. - -Suggested usage: - -- Set the SUBJECTS_DIR correctly. - -- Run mkheadsurf: ``mkheadsurf -subjid`` <*subject*> . - -- Goto the directory ``$SUBJECTS_DIR/`` <*subject*> ``/bem`` . - -- Convert the head surface file: ``mne_surf2bem --surf ../surf/lh.smseghead --id 4 --check --fif`` <*subject*> ``-head-dense.fif`` - -- Rename the existing head surface file to <*subject*> ``-head-sparse.fif`` - -- Copy <*subject*> ``-head-dense.fif`` to <*subject*> ``-head.fif`` - -- Click Reload in the viewer - window. - -After this you can switch between the dense and smooth head -surface tessellations by copying either <*subject*> ``-head-dense.fif`` or <*subject*> ``-head-sparse.fif`` to <*subject*> ``-head.fif`` . - -If you have Matlab software available on your system, you -can also benefit from the script mne_make_scalp_surfaces . -This script invokes mkheadsurf and -subsequently decimates it using the mne_reduce_surface function -in the MNE Matlab toolbox, which in turn invokes the reducepatch -Matlab function. As a result, the $SUBJECTS_DIR/$SUBJECT/bem directory -will contain 'dense', 'medium', -and 'sparse' scalp surface tessellations. The -dense tessellation contains the output of mkheadsurf while -the medium and sparse tessellations comprise 30,000 and 2,500 triangles, -respectively. You can then make a symbolic link of one of these -to <*subject*> ``-head.fif`` . -The medium grade tessellation is an excellent compromise between -geometric accuracy and speed in the coordinate system alignment. - -.. note:: While the dense head surface tessellation may help in coordinate frame alignment, it will slow down the operation of the viewer window considerably. Furthermore, it cannot be used in forward modelling due to the huge number of triangles. For the BEM, the dense tessellation does not provide much benefit because the potential distributions are quite smooth and widespread on the scalp. - -.. _CACJJBGF: - -Using fiducial points identified by other software -================================================== - -If you have identified the three fiducial points in software -outside mne_analyze , it is possible -to display this information on the head surface visualization. To -do this, you need to copy the file containing the fiducial location -information in MRI (surface RAS) coordinates to $SUBJECTS_DIR/$SUBJECT/bem/$SUBJECT-fiducials.fif. -There a three supported ways to create this file: - -- Use the mne_make_fiducial_file.m Matlab - function (not yet written) to create this file. - -- Copy a MRI description file with the MEG-MRI coordinate transformation - created with MRIlab (typically $SUBJECTS_DIR/$SUBJECT/mri/T1-neuromag/sets/COR-<*date*>.fif - to $SUBJECTS_DIR/$SUBJECT/bem/$SUBJECT-fiducials.fif. - -- For the average subject, fsaverage , - copy the fsaverage-fiducials.fif file provided with mne_analyze - in place, see :ref:`CACGEAFI`. - -.. _CACIADAI: - -Viewing continuous HPI data -########################### - -.. _CACFHFGJ: - -.. figure:: mne_analyze/cont_hpi_data.png - :alt: Continuous HPI data overview - - Continuous HPI data overview. - -The newest versions of Neuromag software allow continuous -acquisition of signals from the HPI coils. On the basis of these -data the relative position of the dewar and the head can be computed -a few times per second. The resulting location data, expressed in -the form of unit quaternions (see http://en.wikipedia.org/wiki/Quaternion) -and a translation. - -The continuous HPI data can be through the File/View continuous HPI data... menu item, which pops up -a standard file selection dialog. If the file specified ends with ``.fif`` a -fif file containing the continuous coordinate transformation information -is expected. Otherwise, a text log file is read. Both files are -produced by the Neuromag maxfilter software. - -Once the data have been successfully loaded, the dialog shown -in :ref:`CACFHFGJ` appears. It contains the following information: - -- Currently selected time point and overview - of the data at the current time point, - -- MEG device to MEG head coordinate transformation at the current time - point and the incremental transformation from the initial timepoint - to the current file. - -- Graphical display of the data. - -- Controls for the graphical display. - -The overview items are: - -**GOF** - - Geometric mean of the goodness of fit values of the HPI coils at - this time point. - -**Origin movement** - - The distance between the head coordinate origins at the first and current - time points. - -**Angular velocity** - - Estimated current angular velocity of the head. - -**Coil movements** - - Comparison of the sensor locations between the first and current time - points. The minimum, maximum, average, and median sensor movements - are listed. - -The graphical display contains the following data: - -- The geometric mean of the HPI coil goodness - of fits (red curve). The scale for this curve is always 0.9...1.0. - -- The average coil (sensor) movement value (blue curve). The - scale is adjustable from the buttons below the display. - -- The estimated angular velocity (deg/s, green curve). The scale - is adjustable from the buttons below the display. - -- The current time point indicated with a black cursor. - -The slider below the display can be used to select the time -point. If you click on the slider, the current time can be adjusted -with the arrow keys. The current head position with respect to the -sensor array is show in the viewer window if it is visible, see :ref:`CACEFFJF`. Note that a complete set of items listed above -is only available if a data file has been previously loaded, see :ref:`CACBACHB`. - -.. _CACCHCBF: - -Working with the MRI viewer -########################### - -.. _CHDEGEHE: - -.. figure:: mne_analyze/mri_viewer.png - :alt: MRI viewer window - - The MRI viewer control window. - -Selecting Show MRI viewer... from -the View menu starts the FreeSurfer MRI -viewer program tkmedit to work -in conjunction with mne_analyze . After -a few moments, both tkmedit with -the current subject's T1 MRI data shown and the MRI viewer -control window shown in :ref:`CHDEGEHE` appear. Note that -the tkmedit user interface is -initially hidden. The surfaces of a subject must be loaded before -starting the MRI viewer. - -The MRI viewer control window contains -the following items: - -**Show MRI viewer user interface** - - If this item is checked, the tkmedit user - interface window will be show. - -**Track surface location in MRI** - - With this item checked, the cursor in the MRI data window follows the - current (clicked) location in surface display or viewer. Note that for - the *viewer* window the surface location will - inquired from the surface closest to the viewer. The MEG helmet - surface will not be considered. For example, if you click at an - EEG electrode location with the scalp surface displayed, the location - of that electrode on the scalp will be shown. The cortical surface - locations are inquired from the white matter surface. - -**Show dipole locations in MRI** - - If this option is selected, whenever a dipole is displayed in the - surface view using the dipole list dialog discussed in :ref:`CACGGAIA` the cursor will also move to the same location - in the MRI data window. - -**Show digitizer data in MRI** - - If digitizer data are loaded, this option shows the locations with green - diamonds in the MRI data. - -**Interpolate voxels** - - Toggles trilinear interpolation in the MRI data on and off. - -**Max. intensity projection** - - Shows a maximum-intensity projection of the MRI data. This is useful - in conjunction with the Show digitizer data in MRI option to evaluate the MEG/MRI coordinate - alignment - -**Recenter MRI display** - - Brings the cursor to the center of the MRI data. - -**Show surface data in MRI** - - This button creates an MRI data set containing the surface data - displayed and overlays in with the MRI slices shown in the MRI viewer. - -**Show segmentation data in MRI** - - If available, the standard automatically generated segmentation - volume (mri/aparc+aseg) is overlaid on the MRI using the standard FreeSurfer - color lookup table ($FREESURFER_HOME/FreeSurferColorLUT.txt). As - a result, the name of the brain structure or region of corex at - the current location of the cursor will be reported if the tkmedit user - interface is visible. After the segmentation is loaded this button - toggles the display of the segmentation on and off. - -**Show command input and output** - - Allows sending tcl commands to tkmedit and - shows the responses received. The tkmedit tcl scripting - commands are discussed at https://surfer.nmr.mgh.harvard.edu/fswiki/TkMeditGuide/TkMeditReference/TkMeditScripting. - -.. _CACGEAFI: - -Working with the average brain -############################## - -The FreeSurfer software includes an average subject (fsaverage) -with a cortical surface reconstruction. In some cases, the average -subject can be used as a surrogate if the MRIs of a subject are -not available. - -The MNE software comes with additional files which facilitate -the use of the average subject in conjunction with mne_analyze . -These files are located in the directory $MNE_ROOT/mne/setup/mne_analyze/fsaverage: - -**fsaverage_head.fif** - - The approximate head surface triangulation for fsaverage. - -**fsaverage_inner_skull-bem.fif** - - The approximate inner skull surface for fsaverage. - -**fsaverage-fiducials.fif** - - The locations of the fiducial points (LPA, RPA, and nasion) in MRI coordinates, - see :ref:`CACJJBGF`. - -**fsaverage-trans.fif** - - Contains a default MEG-MRI coordinate transformation suitable for fsaverage. - For details of using the default transformation, see :ref:`CACBACHB`. - -.. _CACJEFAI: - -Compatibility with cliplab -########################## - -The following graphics displays are compatible with the Elekta-Neuromag -report composer cliplab : - -- The main surface display area in the - main window, see :ref:`CACFJICC`. - -- The viewer, see :ref:`CACEFFJF`. - -- The sample channel display, see :ref:`CACFGHBJ`. - -- The topographical data display, see :ref:`CACHBJAC`. - -- The SNR time course display, see :ref:`CACJFFEE`. - -- The source time course display, see:ref:`CACCCFHH` - -The graphics can be dragged and dropped from these windows -to one of the cliplab view areas -using the middle mouse button. Because the topographical display -area has another function (bed channel selection) tied to the middle -mouse button, the graphics is transferred by doing a middle mouse -button drag and drop from the label showing the current time underneath -the display area itself. - -.. note:: The cliplab drag-and-drop functionality requires that you have the proprietary Elekta-Neuromag analysis software installed. mne_analyze is compatible with cliplab versions 1.2.13 and later. - -.. _CHDEDFAE: - -Visualizing the head position -############################# - -When mne_analyze is invoked -with the ``--visualizehpi`` option, a simplified user interface shown -in :ref:`CHDJJGII` is displayed. This interface consists only -of the viewer window. This *head position visualization* mode -can be used with existing data files but is most useful for showing -immediate feedback of the head position during experiments with -an Elekta-Neuromag MEG system. - -.. _CHDJJGII: - -.. figure:: mne_analyze/visualize_hpi.png - :alt: Snapshot of mne_analyze in the head position visualization mode - - Snapshot of mne_analyze in the head position visualization mode. - -As described in :ref:`mne_analyze`, the head position -visualization mode can be customized with the --dig, --hpi, --scalehead, -and --rthelmet options. For this mode to be useful, the --dig and ---hpi options are mandatory. If existing saved data are viewed, -both of these can point to a average or raw data file. For on-line -operation with the Elekta-Neuromag systems, the following files -in should be used: - -``--dig /neuro/dacq/meas_info/isotrak --hpi /neuro/dacq/meas_info/hpi_result`` - -.. note:: Since MNE software runs only on LINUX and Mac OS X platforms, one usually needs to NFS mount the volume containing /neuro directory to another system and access these files remotely. However, Neuromag has indicated that future versions of their acquisition software will run on the LINUX platform as well and the complication of remote operation can then be avoided. - -When mne_analyze starts -in the head position visualization mode and the --dig and --hpi -options have been specified, the following sequence operations takes -place: - -- The digitizer data, the coordinate transformation - between the MEG device and head coordinate frames, as well as the - average head surface provided with the MNE software are loaded. - -- If the ``--scalehead`` option is invoked, the average head surface - is scaled to the approximate size of the subject's head - by fitting a sphere to the digitizer and to the head surface points - lying above the plane of the fiducial landmarks, respectively. The - standard head surface is then scaled by the ration of the radiuses - of these two best-fitting spheres. Without --scalehead, the standard - head surface is used as is without scaling. - -- The known positions of (scaled) fiducial landmarks are matched - with those available in the digitizer data. This initial alignment - is then refined using the ICP algorithm, see :ref:`CACEHGCD`. - This automatic procedure is found to be accurate enough for the - visualization purposes. - -- Using the coordinate transformation thus established between - the coordinate system of the scalp surface (MRI coordinates) and - the MEG head coordinates together with the coordinate transformation - between the MEG head and device coordinate frames established with - HPI, the position of the MEG helmet surface is shown in the viewer - window. - -If the ``--rthelmet`` option was present, the room-temperature -helmet surface is shown instead of the MEG sensor surface. The digitizer -and HPI data files are reloaded and the above steps 1. - 4. are -repeated when the Reload HPI button -is pressed. The comment lines in the viewer window show information -about the digitizer and HPI data files as well as the location of the -MEG device coordinate origin in the MEG head coordinate system. - -.. note:: The appearance of the viewer visualization can be customized using the Options... button, see :ref:`CACHGDEA`. Since only the scalp and MEG device surfaces are loaded, only a limited number of options is active. The display can also be saved as an image from the img button, see :ref:`CACBEBGC`. diff -Nru python-mne-0.18.1+dfsg/doc/manual/gui/browse.rst python-mne-0.19.1+dfsg/doc/manual/gui/browse.rst --- python-mne-0.18.1+dfsg/doc/manual/gui/browse.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/gui/browse.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,2238 +0,0 @@ - -.. _ch_browse: - -===================================== -Browsing raw data with mne_browse_raw -===================================== - -.. contents:: Contents - :local: - :depth: 2 - - -Overview -######## - -The raw data processor :ref:`mne_browse_raw` is -designed for simple raw data viewing and processing operations. In -addition, the program is capable of off-line averaging and estimation -of covariance matrices. :ref:`mne_browse_raw` can -be also used to view averaged data in the topographical layout. -Finally, :ref:`mne_browse_raw` can communicate -with :ref:`mne_analyze` described in :ref:`c_legacy_ch_interactive_analysis` to -calculate current estimates from raw data interactively. - -:ref:`mne_browse_raw` has also -an alias, :ref:`mne_process_raw`. If :ref:`mne_process_raw` is -invoked, no user interface appears. Instead, command line options -are used to specify the filtering parameters as well as averaging -and covariance-matrix estimation command files for batch processing. This -chapter discusses both :ref:`mne_browse_raw` and :ref:`mne_process_raw`. - -See command-line documentation of :ref:`mne_browse_raw` and `mne_process_raw`. - - -The user interface -################## - -.. figure:: mne_browse_raw/windows_menu-7.png - :alt: The user interface of mne_browse_raw - :figwidth: 100% - :width: 100% - - The user interface of mne_browse_raw - -The mne_browse_raw user -interface contains the following areas: - -- The menu bar. - -- The data display area. - -- Viewing and averaging tools. - -- Message line. - -The viewing and averaging tools allow quick browsing of the -raw data with triggers, adding new triggers, and averaging on a -single trigger. - -The File menu -############# - -.. _CACDCHAJ: - -Open -==== - -Selecting Open from file -menu pops up the dialog shown in :ref:`CACBHGFE`. - -The Raw files and Maxfilter output buttons change the file name filter to include -names which end with ``_raw.fif`` or ``sss.fif`` , -respectively, to facilitate selection of original raw files or those -processed with the Neuromag Maxfilter (TM) software - -The options under Software gradient compensation allow -selection of the compensation grade for the data. These selections -apply to the CTF data only. The standard choices are No compensation and Third-order gradient. If -other than No compensation is -attempted for non-CTF data, an error will be issued. The compensation -selection affects the averages and noise-covariance matrices subsequently -computed. The desired compensation takes effect independent of the -compensation state of the data in the file, *i.e.*, -already compensated data can be uncompensated and vice versa. For more -information on software gradient compensation please consult :ref:`BEHDDFBI`. - -The Keep the initial skip button -controls how the initial segment of data not stored in the raw data -file is handled. During the MEG acquisition data are collected continuously -but saving to the raw data file is controlled by the Record raw button. Initial skip refers to the segment -of data between the start of the recording and the first activation -of Record raw . If Keep initial skip is set, this empty segment is taken into -account in timing, otherwise time zero is set to the beginning of -the data stored to disk. - -When a raw data file is opened, the digital trigger channel -is scanned for events. For large files this may take a while. - -.. note:: After scanning the trigger channel for events, mne_browse_raw and mne_process_raw produce a fif file containing the event information. This file will be called <*raw data file name without fif extension*> ``-eve.fif`` . If the same raw data file is opened again, this file will be consulted for event information thus making it unnecessary to scan through the file for trigger line events. - -.. note:: You can produce the fif event file by running mne_process_raw as follows: ``mne_process_raw --raw`` <*raw data file*> . The fif format event files can be read and written with the mne_read_events and mne_write_events functions in the MNE Matlab toolbox, see :ref:`ch_matlab`. - -.. _CACBHGFE: - -.. figure:: mne_browse_raw/open_dialog.png - :alt: Open dialog - - The Open dialog. - -.. _BABJEJDG: - -Open evoked -=========== - -This menu item brings up a standard file selection dialog -to load evoked-response data from files. All data sets from a file -are loaded automatically and display in the average view window, -see :ref:`CACDADBA`. The data loaded are affected by the -scale settings, see, :ref:`CACBEHCD`, the filter, see :ref:`CACCDBBG`, and the options selected in the Manage averages dialog, see :ref:`CACJFADF`. - -.. _CACBDDIE: - -Save -==== - -It is possible to save filtered and projected data into a -new raw data file. When you invoke the save option from the file -menu, you will be prompted for the output file name and a down-sampling -factor. The sampling frequency after down-sampling must be at least -three times the lowpass filter corner frequency. The output will -be split into files which are just below 2 GB so that the fif file -maximum size is not exceed. - -If <*filename*> ends -with ``.fif`` or ``_raw.fif`` , these endings are -deleted. After these modifications, ``_raw.fif`` is inserted -after the remaining part of the file name. If the file is split -into multiple parts, the additional parts will be called <*name*> ``-`` <*number*> ``_raw.fif`` . -For downsampling and saving options in mne_process_raw , -see :ref:`mne_process_raw`. - -Change working directory -======================== - -Brings up a file selection dialog which allows changing of -the working directory. - -.. _CACDFJDA: - -Read projection -=============== - -Selecting Read projection... from -the File menu, pops up a dialog -to enter a name of a file containing a signal-space projection operator -to be applied to the data. There is an option to keep existing projection -items. - -.. note:: Whenever EEG channels are present in the data, a projection item corresponding to the average EEG reference is automatically added. - -Save projection -=============== - -The Save projection... item -in the File menu pops up a dialog -to save the present projection operator into a file. Normally, the -EEG average reference projection is not included. If you want to -include it, mark the Include EEG average reference option. -If your MEG projection includes items for both magnetometers and -gradiometers and you want to use the projection operator file output -from here in the Neuromag Signal processor (graph) software, -mark the Enforce compatibility with graph option. - -Apply bad channels -================== - -Applies the current selection of bad channels to the currently -open raw file. - -Load events (text) -================== - -Reads a text format event file. For more information on events, -see :ref:`BABDFAHA`. - -Load events (fif) -================= - -Reads a fif format event file. For more information on events, -see :ref:`BABDFAHA`. - -.. _CACJGIFA: - -Save events (text) -================== - -Brings up a a dialog to save all or selected types of events -into a text file. This file can be edited and used in the averaging -and covariance matrix estimation as an input file to specify the -time points of events, see :ref:`CACBCEGC`. For more information -on events, see :ref:`BABDFAHA`. - -Save events (fif) -================= - -Save the events in fif format. These binary event files can -be read and written with the mne_read_events and mne_write_events functions -in the MNE Matlab toolbox, see :ref:`ch_matlab`. For more information -on events, see :ref:`BABDFAHA`. - -.. _CACFHAFH: - -Load derivations -================ - -This menu choice allows loading of channel derivation data -files created with the mne_make_derivations utility, -see :ref:`mne_make_derivations`, or using the interactive derivations -editor in mne_browse_raw , see :ref:`CACJIEHI`, Most common use of derivations is to calculate -differences between EEG channels, *i.e.*, bipolar -EEG data. Since any number of channels can be included in a derivation -with arbitrary weights, other applications are possible as well. -Before a derivation is accepted to use, the following criteria have -to be met: - -- All channels to be combined into a single - derivation must have identical units of measure. - -- All channels in a single derivation have to be of the same - kind, *e.g.*, MEG channels or EEG channels. - -- All channels specified in a derivation have to be present - in the currently loaded data set. - -Multiple derivation data files can be loaded by specifying -the Keep previous derivations option in -the dialog that specifies the derivation file to be loaded. After -a derivation file has been successfully loaded, a list of available -derivations will be shown in a message dialog. - -Each of the derived channels has a name specified when the -derivation file was created. The derived channels can be included -in channel selections, see :ref:`CACCJEJD`. At present, derived -channels cannot be displayed in topographical data displays. Derived -channels are not included in averages or noise covariance matrix -estimation. - -.. note:: If the file ``$HOME/.mne/mne_browse_raw-deriv.fif`` exists and contains derivation data, it is loaded automatically when mne_browse_raw starts unless the ``--deriv`` option has been used to specify a nonstandard derivation file, see :ref:`mne_browse_raw`. - -Save derivations -================ - -Saves the current derivations into a file. - -Load channel selections -======================= - -This choice loads a new set of channel selections. The default -directory for the selections is $HOME/.mne. If this directory does -not exist, it will be created before bringing up the file selection -dialog to load the selections. - -.. _CACDDCGF: - -Save channel selections -======================= - -This choice brings up a dialog to save the current channel -selections. This is particularly useful if the standard set of selections -has been modified as explained in :ref:`CACCJEJD`. The default -directory for the selections is $HOME/.mne. If this directory does -not exist, it will be created before bringing up the file selection -dialog to save the selections. Note that all currently existing -selections will be saved, not just those added to the ones initially -loaded. - -Quit -==== - -Exits the program without questions asked. - -The Adjust menu -############### - -.. _CACCDBBG: - -Filter -====== - -Selecting Filter... from -the Adjust menu pops up the dialog -shown in :ref:`CACCEEGI`. - -.. _CACCEEGI: - -.. figure:: mne_browse_raw/filter_dialog.png - :alt: filter adjustment dialog - :align: center - :figwidth: 55% - :width: 400 - - The filter adjustment dialog. - -The items in the dialog have the following functions: - -**Highpass (Hz)** - - The half-amplitude point of the highpass filter. The width of the transition - from zero to one can be specified with the ``--highpassw`` command-line - option, see :ref:`mne_browse_raw`. Lowest feasible highpass value - is constrained by the length of the filter and sampling frequency. - You will be informed when you press OK or Apply if - the selected highpass could not be realized. The default value zero means - no highpass filter is applied in addition to the analog highpass - present in the data. - -**Lowpass (Hz)** - - The half-amplitude point of the lowpass filter. - -**Lowpass transition (Hz)** - - The width of the :math:`\cos^2`-shaped transition - from one to zero, centered at the Lowpass value. - -**Filter active** - - Selects whether or not the filter is applied to the data. - -The filter is realized in the frequency domain and has a -zero phase shift. When a filter is in effect, the value of the first -sample in the file is subtracted from the data to correct for an -initial dc offset. This procedure also eliminates any filter artifacts -in the beginning of the data. - -.. note:: The filter affects both the raw data and evoked-response data loaded from files. However, the averages computed in mne_browse_raw and shown in the topographical display are not refiltered if the filter is changed after the average was computed. - -.. _CACBEHCD: - -Scales -====== - -Selecting Scales... from -the Adjust menu pops up the dialog -shown in :ref:`CACBJGBA`. - -.. _CACBJGBA: - -.. figure:: mne_browse_raw/scales_dialog.png - :alt: Scales dialog - :figwidth: 100% - :width: 100% - - The Scales dialog. - -The items in the dialog have the following functions: - -**MEG (fT/cm)** - - Sets the scale for MEG planar gradiometer channels in fT/cm. All scale - values are defined from zero to maximum, *i.e.*, - the viewport where signals are plotted in have the limits ± <*scale value*> . - -**MEG axmult (cm)** - - The scale for MEG magnetometers and axial gradiometers is defined - by multiplying the gradiometer scale by this number, yielding units - of fT. - -**EEG** (:math:`\mu V`) - - The scale for EEG channels in :math:`\mu V`. - -**EOG** (:math:`\mu V`) - - The scale for EOG channels in :math:`\mu V`. - -**ECG (mV)** - - The scale for ECG channels in mV. - -**EMG (mV)** - - The scale for EMG channels in mV. - -**MISC (V)** - - The scale for MISC channels in V. - -**Time span (s)** - - The length of raw data displayed in the main window at a time. - -**Show stimulus markers** - - Draw vertical lines at time points where the digital trigger channel has - a transition from zero to a nonzero value. - -**Segment min. time (s)** - - It is possible to show data segments in the topographical (full - view) layout, see below. This parameter sets the starting time point, - relative to the selected time, to be displayed. - -**Segment max. time (s)** - - This parameter sets the ending time point, relative to the current time, - to be displayed in the topographical layout. - -**Show segments in full view** - - Switches on the display of data segments in the topographical layout. - -**Show segments in sample view** - - Switches on the display of data segments in a "sidebar" to - the right of the main display. - -**Show channel names** - - Show the names of the channels in the topographical displays. - -**Text size** - - Size of the channel number text as a fraction of the height of each viewport. - -**Show viewport frames** - - Show the boundaries of the viewports in the topographical displays. - -**Show zeroline and zerolevel** - - Show the zero level, *i.e.*, the baseline level - in the topographical displays. In addition, the zero time point - is indicated in the average views if it falls to the time range, *i.e.*, - if the minimum of the time scale is negative and the maximum is - positive. - -**Scale magnification for averages** - - For average displays, the scales are made more sensitive by this - factor. - -**Average display baseline min (ms)** - - Sets the lower time limit for the average display baseline. This - setting does not affect the averages stored. - -**Average display baseline max (ms)** - - Sets the upper time limit for the average display baseline. This - setting does not affect the averages stored. - -**Use average display baseline** - - Switches the application of a baseline to the displayed averages - on and off. - -**Average time range min (ms)** - - Sets the minimum time for the average display. This setting is inactive - if Autoscale time range is on. - -**Average time range max (ms)** - - Sets the maximum time for the average data display. This setting - is inactive if Autoscale time range is - on. - -**Autoscale time range** - - Set the average display time range automatically to be long enough to - accommodate all data. - -Colors -====== - -Shows a dialog which allows changes to the default colors -of various display items. - -.. _CACJIEHI: - -Derivations -=========== - -Brings up the interactive derivations editor. This editor -can be used to add or modify derived channels, *i.e.*, -linear combinations of signals actually recorded. Channel derivations -can be also created and modified using the mne_make_derivations tool, -see :ref:`mne_make_derivations`. The interactive editor contains two main -areas: - -- Interactive tools for specifying a channel - linear combination. This tool is limited to combining up to five - channels in each of the derivations. Clicking Add after - defining the name of the new derivation, the weights of the component - channels and their names, adds the corresponding arithmetic expression - to the text area. - -- Text area which contains the currently defined derivations - as arithmetic expressions in a format identical to that used by mne_make_derivations . - These expressions can be manually edited before accepting the new - set of derivations. Initially, the text area will contain the derivations - already defined. - -The Define button interprets -the arithmetic expressions in the text area as new derivations and -closes the dialog. The Cancel button -closes the dialog without any change in the derivations. - -Recommended workflow for defining derived EEG channels and -associated selections interactively involves the following steps: - -- If desired, EEG channels can be relabeled - with descriptive names using the mne_rename_channels utility, - see :ref:`mne_rename_channels`. It is strongly recommended that you - keep a copy of the channel alias file used by mne_rename_channels . - If necessary, you can then easily return to the original channel - names by running mne_rename_channels again - with the ``--revert`` option. - -- Load the data file into mne_browse_raw and - use the interactive derivations editor to create the desired derived - channels. These are usually differences between the signals in two - EEG electrodes. - -- Save the derivations from the file menu. - -- If desired, move the derivations file to the standard location - (``$HOME/.mne/mne_browse_raw-deriv.fif`` ). - -- Create new channel selections employing the original and derived channels - using the channel selection tool described in :ref:`CACCJEJD`. - -- Save the new channel selections from the file menu. - -- If desired, change the order of the channels in the selections - in the selection file by editing it in a text editor and move it - to the standard location ``$HOME/.mne/mne_browse_raw.sel`` . - -.. _CACCJEJD: - -Selection -========= - -Brings up a dialog to select channels to be shown in the -main raw data display. This dialog also allows modification of the -set of channel selections as described below. - -By default, the available selections are defined by the file ``$MNE_ROOT/share/mne/mne_browse_raw/mne_browse_raw.sel`` . -This default channel selection file can be modified by copying the -file into ``$HOME/.mne/mne_browse_raw.sel`` . The format -of this text file should be self explanatory. - -.. _CACIHFFH: - -.. figure:: mne_browse_raw/channel_selection.png - :alt: channel selection dialog - - The channel selection dialog. - -The channel selection dialog is shown in :ref:`CACIHFFH`. -The number of items in the selection list depends on the contents -of your selection file. If the list has the keyboard focus you can -easily move from one selection to another with the up and down arrow -keys. - -The two buttons below the channel selection buttons facilitate -the modification of the selections: - -**Add...** - - Brings up the selection dialog shown in :ref:`CACFECED` to - create new channel selections. - -**Omit current** - - Delete the current channel selection. Deletion only affects the - selections in the memory of the program. To save the changes permanently - into a file, use Save channel selections... in - the File menu, see :ref:`CACDDCGF`. - -.. _CACFECED: - -.. figure:: mne_browse_raw/new_selection.png - :alt: Dialog to create a new channel selection - - Dialog to create a new channel selection. - -The components of the selection creation dialog shown in :ref:`CACFECED` have the following functions: - -**List of channel names** - - The channels selected from this list will be included in the new channel - selection. A selection can be extended with the control key. A range - of channels can be selected with the shift key. The list contains - both the original channels actually present in the file and the names - of the channels in currently loaded derivation data, see :ref:`CACFHAFH`. - -**Regexp:** - - This provides another way to select channels. By entering here a regular - expression as defined in IEEE Standard 1003.2 (POSIX.2), all channels - matching it will be selected and added to the present selection. - An empty expression deselects all items in the channel list. Some - useful regular expressions are listed in :ref:`CACHCHDJ`. - In the present version, regular matching does not look at the derived - channels. - -**Name:** - - This text field specifies the name of the new selection. - -**Select** - - Select the channels specified by the regular expression. The same effect - can be achieved by entering return in the Regexp: . - -**Add** - - Add a new channel selection which contains the channels selected from - the channel name list. The name of the selection is specified with - the Name: text field. - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.45\linewidth}| -.. _CACHCHDJ: -.. table:: Examples of regular expressions for channel selections - - +--------------------+----------------------------------------------+ - | Regular expression | Meaning | - +====================+==============================================+ - | ``MEG`` | Selects all MEG channels. | - +--------------------+----------------------------------------------+ - | ``EEG`` | Selects all EEG channels. | - +--------------------+----------------------------------------------+ - | ``MEG.*1$`` | Selects all MEG channels whose names end | - | | with the number 1, *i.e.*, all magnetometer | - | | channels. | - +--------------------+----------------------------------------------+ - | ``MEG.*[2,3]$`` | Selects all MEG gradiometer channels. | - +--------------------+----------------------------------------------+ - | ``EEG|STI 014`` | Selects all EEG channels and stimulus | - | | channel STI 014. | - +--------------------+----------------------------------------------+ - | ``^M`` | Selects all channels whose names begin with | - | | the letter M. | - +--------------------+----------------------------------------------+ - -.. note:: The interactive tool for creating the channel selections does not allow you to change the order of the selected channels from that given by the list of channels. However, the ordering can be easily changed by manually editing the channel selection file in a text editor. - -.. _CACFGGCF: - -Full view layout -================ - -Shows a selection of available layouts for the topographical -views (full view and average display). The system-wide layout files -reside in ``$MNE_ROOT/share/mne/mne_analyze/lout`` . In -addition any layout files residing in ``$HOME/.mne/lout`` are -listed. The default layout is Vectorview-grad. If there is a layout -file in the user's private layout directory ending with ``-default.lout`` , -that layout will be used as the default instead. The Default button -returns to the default layout. - -The format of the layout files is: - - | <*plot area limits*> - | <*viewport definition #1*> - | ... - | <*viewport definition #N*> - -The <*plot area limits*> define -the size of the plot area (:math:`x_{min}\ x_{max}\ y_{min}\ y_{max}`) which should accommodate all view ports. When the layout is used, the -plot area will preserve its aspect ratio; if the plot window has -a different aspect ratio, there will be empty space on the sides. - -The viewports define the locations of the individual channels -in the plot. Each viewport definition consists of - - <*number*> :math:`x_0\ y_0` <*width*> <*height*> <*name*> [: <*name*> ] ... - -where number is a viewport number (not used by the MNE software), :math:`x_0` and :math:`y_0` are -the coordinates of the lower-left corner of the viewport, <*width*> and <*height*> are -the viewport dimensions, and <*name*> is -a name of a channel. Multiple channel names can be specified by -separating them with a colon. - -When a measurement channel name is matched to a layout channel -name, all spaces are removed from the channel names and the both -the layout channel name and the data channel name are converted -to lower case. In addition anything including and after a hyphen -(-) is omitted. The latter convention facilitates using CTF MEG -system data, which has the serial number of the system appended -to the channel name with a dash. Removal of the spaces is important -for the Neuromag Vectorview data because newer systems do not have -spaces in the channel names like the original Vectorview systems -did. - -.. note:: The mne_make_eeg_layout utility can be employed to create a layout file matching the positioning of EEG electrodes, see :ref:`mne_make_eeg_layout`. - -.. _CACDDIDH: - -Projection -========== - -Lists the currently available signal-space projection (SSP) -vectors and allows the activation and deactivation of items. For -more information on SSP, see :ref:`CACCHABI`. - -Compensation -============ - -Brings up a dialog to select software gradient compensation. -This overrides the choice made at the open time. For details, see :ref:`CACDCHAJ`, above. - -.. _CACBIAHD: - -Averaging preferences -===================== - - -.. _CACCFFAH: - -.. figure:: mne_browse_raw/average_pref.png - :alt: Averaging preferences - :figwidth: 35% - :width: 300 - - Averaging preferences. - -Selecting Averaging preferences... from -the Adjust menu pops up the dialog -shown in :ref:`CACCFFAH`. These settings apply only to the -simple averages calculated with help of tools residing just below -the main raw data display, see :ref:`CACDFGAE`. These settings -are also applied when a covariance matrix is computed to create -a SSP operator as described in :ref:`CACEAHEI` and in the -computation of a covariance matrix from raw data, see :ref:`BABJEIGJ`. - -The items in the dialog have the following functions: - -**Starting time (ms)** - - Beginning time of the epoch to be averaged (relative to the trigger). - -**Ending time (ms)** - - Ending time of the epoch to be averaged. - -**Ignore around stimulus (ms)** - - Ignore this many milliseconds on both sides of the trigger when considering - the epoch. This parameter is useful for ignoring large stimulus - artifacts, *e.g.*, from electrical somatosensory - stimulation. - -**MEG grad rejection (fT/cm)** - - Rejection criterion for MEG planar gradiometers. If the peak-to-peak - value of any planar gradiometer epoch exceed this value, it will - be omitted. A negative value turns off rejection for a particular channel - type. - -**MEG mag rejection (fT)** - - Rejection criterion for MEG magnetometers and axial gradiometers. - -**EEG rejection** (:math:`\mu V`) - - Rejection criterion for EEG channels. - -**EOG rejection** (:math:`\mu V`) - - Rejection criterion for EOG channels. - -**ECG rejection (mV)** - - Rejection criterion for ECG channels. - -**MEG grad no signal (fT/cm)** - - Signal detection criterion for MEG planar gradiometers. The peak-to-peak - value of all planar gradiometer signals must exceed this value, - for the epoch to be included. This criterion allows rejection of data - with saturated or otherwise dysfunctional channels. - -**MEG mag no signal (fT)** - - Signal detection criterion for MEG magnetometers and axial gradiometers. - -**EEG no signal** (:math:`\mu V`) - - Signal detection criterion for EEG channels. - -**EOG no signal** (:math:`\mu V`) - - Signal detection criterion for EOG channels. - -**ECG no signal (mV)** - - Signal detection criterion for ECG channels. - -**Fix trigger skew** - - This option has the same effect as the FixSkew parameter - in averaging description files, see :ref:`BABIHFBI`. - -**Trace color** - - The color assigned for the averaged traces in the display can be adjusted - by pressing this button. - -The Process menu -################ - -Averaging -========= - -The Average... menu item -pops up a file selection dialog to access a description file for -batch-mode averaging. The structure of these files is described -in :ref:`CACBBDGC`. All parameters for the averaging are -taken from the description file, *i.e.*, the -parameters set in the averaging preferences dialog (:ref:`CACBIAHD`) do not effect the result. - -Estimation of a covariance matrix -================================= - -The Compute covariance... menu -item pops up a file selection dialog to access a description file -which specifies the options for the estimation of a covariance matrix. -The structure of these files is described in :ref:`CACEBACG`. - -.. _BABJEIGJ: - -Estimation of a covariance matrix from raw data -=============================================== - -The Compute raw data covariance... menu -item pops up a dialog which specifies a time range for raw data -covariance matrix estimation and the file to hold the result. If -a covariance matrix is computed in this way, the rejection parameters -specified in averaging preferences are in effect. For description -of the rejection parameters, see :ref:`CACBIAHD`. The time -range can be also selected interactively from the main raw data -display by doing a range selection with shift left button drag. - -.. _CACEAHEI: - -Creating a new SSP operator -=========================== - -The Create a new SSP operator... menu -choice computes a new SSP operator as discussed in :ref:`BABFFCHF`. - -.. _BABHAGHF: - -.. figure:: mne_browse_raw/new_ssp.png - :alt: Time range specification for SSP operator calculation - - Time range specification for SSP operator calculation - -When Create a new SSP operator... selected, -a window shown in :ref:`BABHAGHF` is popped up. It allows -the specification of a time range to be employed in the calculation -of a raw data covariance matrix. The time range can be also selected -interactively from the main raw data display by doing a range selection -with shift left button drag. Normally, you should use empty room -data for this computation. For the estimation of the covariance -matrix any existing projection will be temporarily switched off. Remember -to inspect your data for bad channels and select an appropriate filter -setting before creating a new SSP operator. The artifact rejection parameters -specified averaging preferences will be applied in the covariance -matrix calculation, see :ref:`CACBIAHD`. - -Instead of using continuous raw data, it is also possible -to employ short epochs around triggers (events) in the calculation -of the new SSP operator by specifying a positive event number in -the time specification dialog. This option is very useful, *e.g.*, -to remove MCG/ECG artifacts from the data to facilitate detection -of epileptic spikes: - -- Select left or right temporal channels - to the display. - -- Mark several peaks of the MCG signal in the data: click on - the first one and control click on the subsequent ones to extend - the selection. - -- Select an event number next to the Picked to button in the tool bar, see :ref:`CACDFGAE`, - and click Picked to . As a result - the lines marking the events will change color (by default from - green to blue) indicating transition to user-created events. - -- Specify an epoch time range to be employed and the event number selected - in the previous step for the SSP operator calculation. - -Once the parameters are set, click Compute to -calculate a covariance matrix according to you your specifications. -Once the covariance matrix is ready, the parts corresponding to -magnetometer or axial gradiometer, planar gradiometer, and EEG channels -are separated and the corresponding eigenvectors and eigenvalues -are computed. Once complete, a projection selector with eight magnetometer -eigenvectors, five planar gradiometer eigenvectors, three EEG eigenvectors, -as well as the existing projection items is displayed. - -Using the projection selector, you can experiment which vectors -have a significant effect on the noise level of the data. You should -strive for using a minimal number of vectors. When the selection -is complete, you can click Accept to -introduce this selection of vectors as the new projection operator. Discard abandons -the set of calculated vectors. Whenever EEG channels are present -in the data, a projection item corresponding to the average EEG -reference is automatically added when a new projection operator -is introduced. More information on the SSP method can be found in :ref:`CACCHABI`. - -.. note:: The new projection data created in mne_browse_raw is not automatically copied to the data file. You need to create a standalone projection file from File/Save projection... to save the new projection data and load it manually after the data file has been loaded if you want to include in any subsequent analysis. - -.. note:: The command-line options for mne_process_raw allow calculation of the SSP operator from continuous data in the batch mode, see :ref:`mne_process_raw`. - -.. _BABDJGGJ: - -The Windows menu -################ - -The Windows menu contains -the following items: - -**Show full view...** - - Brings up the topographical display of epochs extracted from the raw - data, see :ref:`CACDADBA`. - -**Show averages...** - - Brings up the topographical display showing averaged data. These data - may include data averaged in the current mne_browse_raw session - or those loaded from files, see :ref:`BABJEJDG`. - -**Show event list...** - - Brings up a window containing a list of the currently defined events. Clicking - on an event in the list, the event is selected, a green cursor appears - at the event, and the event is brought to the middle of the raw - data display. The event list displayed can be also restricted to user-defined - events (annotations) and user-defined events can be deleted. For - further information, see :ref:`BABDFAHA`. - -**Show annotator...** - - Brings up a window which allows adding new events to the data with - annotations or comments. For details, see :ref:`BABDFAHA`. - -**Manage averages...** - - Brings up a dialog to control the averaged data sets, see :ref:`CACJFADF`. - -**Start mne_analyze...** - - Start interaction between mne_browse_raw and mne_analyze . - For details, see :ref:`CACGHEGC`. - -**Show head position** - - Starts mne_analyze in the head position visualization mode and shows - the relative position of the MEG sensor array and the head using - the data in the presently open raw data file. For more details on - the head position visualization mode, see Section 7.21.**what?? does not exist!** - -**Quit mne_analyze...** - - Quits the mne_analyze program - started with Start mne_analyze... - -The Help menu -############# - -The contents of the Help menu -is shown in :ref:`help_menu_browse`: - -.. _help_menu_browse: - -.. figure:: mne_browse_raw/help_menu.png - :alt: Help menu - - The Help menu. - -**On version...** - - Displays the version and compilation date of the program. - -**On license...** - - Displays the license information. - -**About current data...** - - Displays essential information about the currently loaded data set. - -**Why the beep?** - - In some simple error situations, mne_browse_raw does - not pop up an error dialog but refuses the action and rings the - bell. The reason for this can be displayed through this help menu - item. - -The raw data display -#################### - -The main data displays shows a section of the raw data in -a strip-chart recorder format. The names of the channels displayed -are shown on the left. The selection of channels is controlled from -the selection dialog, see :ref:`CACCJEJD`. The length of -the data section displayed is controlled from the scales dialog -(:ref:`CACBEHCD`) and the filtering from the filter dialog (:ref:`CACCDBBG`). A signal-space projection can be applied -to the data by loading a projection operator (:ref:`CACDFJDA`). -The selection of the projection operator items is controlled from -the projection dialog described in :ref:`CACDDIDH`. - -The control and browsing functions of the main data display -are: - -**Selection of bad channels** - - If you click on a channel name the corresponding channel is marked bad - or reinstated as an acceptable one. A channel marked bad is not considered - in the artifact rejection procedures in averaging and it is omitted - from the signal-space projection operations. - -**Browsing** - - Browsing through the data. The section of data displayed can be selected - from the scroll bar at the bottom of the display. Additional browsing - functionality will be discussed n In addition, if the strip-chart - display has the keyboard focus, you can scroll back and forth with - the page up and page down keys. - -**Selection of time points** - - When you click on the data with the left button, a vertical marker appears. - If Show segments in full view and/or Show segments in sample view is active in the scales - dialog (see :ref:`CACBEHCD`), a display of an epoch of data - specified in the scales dialog will appear. For more information - on full view, see :ref:`CACDADBA`. Multiple time points can - be selected by holding the control key down when clicking. If multiple - time points are selected several samples will be shown in the sample - and/or full view, aligned at the picked time point. The tool bar - offers functions to operate on the selected time points, see :ref:`CACDFGAE`. - -**Range selection** - - Range selection. If you drag on the signals with the left mouse - button and the shift key down, a range of times will be selected - and displayed in the sample and/or full view. Note: All previous - selections are cleared by this operation. - -**Saving a copy of the display** - - The right mouse button invokes a popup menu which allows saving of - the display in various formats. Best quality is achieved with the Illustrator - format. This format has the benefit that it is object oriented and - can be edited in Adobe Illustrator. - -**Drag and drop** - - Graphics can be moved to one of the Elekta-Neuromag report composer - (cliplab ) view areas with the - middle mouse button. - -.. note:: When selecting bad channels, switch the signal-space projection off from the projection dialog. Otherwise bad channels may not be easily recognizable. - -.. note:: The cliplab drag-and-drop functionality requires that you have the proprietary Elekta-Neuromag analysis software installed. mne_browse_raw is compatible with cliplab versions 1.2.13 and later. - -.. _BABIDADB: - -Browsing data -============= - -If the strip-chart display has -the input focus (click on it, if you are unsure) the keyboard and -mouse can be used to browse the data as follows: - -**Up and down arrow keys** - - Activate the previous or next selection in the selection list. - -**Left and right arrow keys** - - If a single time point is selected (green line), move the time point forward - and backward by :math:`\pm 1` ms. If the shift - key is down, the time point is moved by :math:`\pm 10` ms. - If the control key is down (with or without shift), the time point - is moved by :math:`\pm 100` ms. If mne_browse_raw is - controlling mne_analyze (see :ref:`CACGHEGC`), the mne_analyze displays - will be updated accordingly. If the picked time point falls outside - the currently displayed section of data, the display will be automatically - scrolled backwards or forwards as needed. - -**Rotate the mouse wheel or rotate the trackball up/down** - - Activate the previous or next selection in the selection list. - -**Rotate the trackball left/right or rotate the wheel with shift down** - - Scroll backward or forward in the data by one screen. With Alt key (Command or Apple key - in the Mac keyboard), the amount of scrolling will be :math:`1` s instead - of the length of one screen. If shift key is held down with the - trackball, both left/right and up/down movements scroll the data - in time. - -.. note:: The trackball and mouse wheel functionality is dependent on your X server settings. On Mac OSX these settings are normally correct by default but on a LINUX system some adjustments to the X server settings maybe necessary. Consult your system administrator or Google for details. - -.. _BABDFAHA: - -Events and annotations -###################### - -.. _BABJGEDF: - -Overview -======== - -In mne_browse_raw and mne_process_raw *events* mark -interesting time points in the data. When a raw data file is opened, -a standard event file is consulted for the list of events. If this -file is not present, the digital trigger channel, defined by the --digtrig option -or the ``MNE_TRIGGER_CH_NAME`` environment variable is -scanned for events. For more information, see the command-line references -for :ref:`mne_browse_raw` and :ref:`mne_process_raw`. - -In addition to the events detected on the trigger channel, -it is possible to associate user-defined events to the data, either -by marking data points interactively as described in :ref:`BABCIGGH` or by loading event data from files, see :ref:`BABDGBHI`. Especially if there is a comment associated -with a user-defined event, we will sometimes call it an *annotation*. - -If a data files has annotations (user-defined events) associated -with it in mne_browse_raw , information -about them is automatically saved to an annotation file when a data file is closed, *i.e.*, -when you quit mne_browse_raw or -load a new data file. This annotation file is called <*raw data file name without fif extension*> ``-annot.fif`` and -will be stored in the same directory as the raw data file. Therefore, -write permission to this directory is required to save the annotation -file. - -Both the events defined by the trigger channel and the user-defined -events have three properties: - -- The *time* when the - event occurred. - -- The *value* on the trigger channel just - before the change and now. For user-defined events the value before - is always zero and the current value is user defined and does not - necessarily reflect a change on the trigger channel. The trigger - channel events may also indicate changes between two non-zero values - and from a non-zero to zero. The event list described in :ref:`BABFDICC` shows only transitions from zero to a non-zero - value. Similarly, the Jump to item - in the tool bar, described in :ref:`CACDFGAE`, only detects - transitions from zero to a nonzero value. - -- An optional *comment* text, which is especially - helpful in associating user-defined events with real-world activity, *e.g.*, - the subject closing or opening his/her eyes or an epileptic patient - showing indications of a seizure. - -.. _BABFDICC: - -The event list -============== - -The Windows/Show event list... menu -choice shows a window containing a list of currently defined events. -The list can be restricted to user-defined events by checking User-defined events only . When an event is selected from the -list, the main display jumps to the corresponding time. If a user-defined -event is selected, it can be deleted with the Delete a user-defined event button. - -.. _BABDGBHI: - -Loading and saving event files -============================== - -Using the Load/Save events choices in the file menu, events -can be saved in text and fif formats, see :ref:`CACBCEGC`, -below. The loading dialogs have the following options: - -**Match comment with** - - Only those events which will contain comments and in which the comment - matches the entered text are loaded. This filtering option is useful, *e.g.*, - in loading averaging or covariance matrix computation log files, - see :ref:`BABIHFBI` and :ref:`BABCGEJE`. - If the word *omit* is entered as the filter, - only events corresponding to discarded epochs are loaded and the - reason for rejection can be investigated in detail. - -**Add as user events** - - Add the events as if they were user-defined events. As a result, - the annotation file saved next time mne_browse_raw closes - this raw file will contain these events. - -**Keep existing events** - - By default, the events loaded will replace the currently defined - ones. With this option checked, the loaded event will be merged - with the currently existing ones. - -The event saving dialogs have the -following options controlling the data saved: - -**Save events read from the data file** - - Save only those event which are not designated as user defined. These - are typically the events corresponding to changes in the digital - trigger channel. Another possible source for these events is an event - file manually loaded *without* the Add as user events option. - -**Save events created here** - - Save the user-defined events. - -**Save all trigger line transitions** - - By default only those events which are associate with a transition from - zero to non-zero value are saved. These include the user-defined - events and leading edges of pulses on the trigger line. When this - option is present, all events included with the two above options are - saved, regardless the type of transition indicated (zero to non-zero, - non-zero to another non-zero value, and non-zero value to zero). - -.. note:: If you have a text format event file whose content you want to include as user-defined events and create the automatic annotation file described in :ref:`BABJGEDF`, proceed as follows: - -- Load the event file with the option Add as user events set. - -- Open another data file or quit mne_browse_raw . - -- Optionally remove unnecessary events using the event list - dialog. - -The directory in which the raw data file resides now contains -an annotation file which will be automatically loaded each time -the data file is opened. A text format event file suitable for this -purpose can be created manually, extracted from an EDF+ file using -the ``--tal`` option in :ref:`mne_edf2fiff`, or produced by custom -software used during data acquisition. - -.. _BABCIGGH: - -Defining annotated events -========================= - -The Windows/Show annotator... shows -a window to add annotated user-defined events. In this window, the -buttons in first column mark one or more selected time points with -the event number shown in the second column with an associated comment -specified in the third column. Marking also occurs when return is -pressed on any of the second and third column text fields. - -When the dialog is brought up for the first time, the file -$HOME/.mne/mne_browse_raw.annot is consulted for the definitions -of the second and third column values, *i.e.*, -event numbers and comments. You can save the current definitions -with the Save defs button and -reload the annotation definition file with Load defs . The annotation definition file may contain comment -lines starting with '%' or '#' and -data lines which contain an event number and an optional comment, -separated from the event number by a colon. - -.. note:: If you want to add a user-defined event without an a comment, you can use the Picked to item in the tool bar, described in :ref:`CACDFGAE`. - -.. _CACBCEGC: - -Event files -=========== - -A text format event file contains information about transitions -on the digital trigger line in a raw data file. Any lines beginning -with the pound sign (``#`` ) are considered as comments. -The format of the event file data is: - - <*sample*> <*time*> <*from*> <*to*> <*text*> - -where - -** <*sample*>** - - is - the sample number. This sample number takes into account the initial - empty space in a raw data file as indicated by the FIFF_FIRST_SAMPLE - and/or FIFF_DATA_SKIP tags in the beginning of raw data. Therefore, - the event file contents are independent of the Keep initial skip setting in the open dialog. - -** <*time*>** - - is - the time from the beginning of the file to this sample in seconds. - -** <*from*>** - - is - the value of the digital trigger channel at <*sample*> -1. - -** <*to*>** - - is - the value of the digital trigger channel at <*sample*> . - -** <*text*>** - - is - an optional annotation associated with the event. This comment will - be displayed in the event list and on the message line when you - move to an event. - -When an event file is read back, the <*sample*> value -will be primarily used to specify the time. If you want the <*time*> to -be converted to the sample number instead, specify a negative value -for <*sample*> . - -Each event file starts with a "pseudo event" where -both <*from*> and <*to*> fields -are equal to zero. - -.. warning:: In previous versions of the MNE software, the event files did not contain the initial empty pseudo event. In addition the sample numbers did not take into account the initial empty space in the raw data files. The present version of MNE software is still backwards compatible with the old version of the event files and interprets the sample numbers appropriately. However, the recognition of the old and new event file formats depends on the initial pseudo event and, therefore, this first event should never be removed from the new event files. Likewise, if an initial pseudo event with <*from*> and <*to*> fields equal to zero is added to and old event file, the results will be unpredictable. - -.. note:: If you have created Matlab, Excel or other scripts to process the event files, they may need revision to include the initial pseudo event in order for mne_browse_raw and mne_process_raw to recognize the edited event files correctly. - -.. note:: Events can be also stored in fif format. This format can be read and written with the Matlab toolbox functions mne_read_events and mne_write_events . - -.. _CACDFGAE: - -The tool bar -############ - -.. _CACCFEGH: - -.. figure:: mne_browse_raw/toolbar.png - :alt: tool bar controls - :figwidth: 100% - :width: 100% - - The tool bar controls. - -The tool bar controls are shown in :ref:`CACCFEGH`. -They perform the following functions: - -**start/s** - - Allows specification of the starting time of the display as a numeric value. - Note that this value will be rounded to the time of the nearest sample - when you press return. If you click on this text field, you can also - change the time with the up and down cursor keys (1/10 of the window - size), and the page up and down (or control up and down cursor) - keys (one window size). - -**Remove dc** - - Remove the dc offset from the signals for display. This does not affect - the data used for averaging and noise-covariance matrix estimation. - -**Keep dc** - - Return to the original true dc levels. - -**Jump to** - - Enter a value of a trigger to be searched for. The arrow buttons - jump to the next event of this kind. A selection is also automatically - created and displayed as requested in the scales dialog, see :ref:`CACBEHCD`. If the '+' button is active, - previous selections are kept, otherwise they are cleared. - -**Picked to** - - Make user events with this event number at all picked time points. - It is also possible to add annotated user events with help of the - annotation dialog. For further information, see :ref:`BABDFAHA`. - -**Forget** - - Forget desired user events. - -**Average** - - Compute an average to this event. - -The tool bar status line shows the starting time and the -length of the window in seconds as well as the cursor time point. -The dates and times in parenthesis show the corresponding wall-clock -times in the time zone where mne_browse_raw is -run. - -.. note:: The wall-clock times shown are based on the information in the fif file and may be offset from the true acquisition time by about 1 second. This offset is constant throughout the file. The times reflect the time zone setting of the computer used to analyze the data rather than the one use to acquire them. - -.. _CACDADBA: - -Topographical data displays -########################### - -Segments of data can shown in a topographical layout in the Full view window, which can be requested from the Scale dialog -or from the Windows menu. Another -similar display is available to show the averaged data. The topographical -layout to use is selected from Adjust/Full view layout... , -which brings up a window with a list of available layouts. The default -layouts reside in ``$MNE_ROOT/share/mne/mne_analyze/lout`` . -In addition any layout files residing in ``$HOME/.mne/lout`` are listed. -The format of the layout files is the same as for the Neuromag programs xplotter and xfit . -A custom EEG layout can be easily created with the mne_make_eeg_layout utility, -see :ref:`mne_make_eeg_layout`. - -Several actions can be performed with the mouse in the topographical data -display: - -**Left button** - - Shows the time and the channel name at the cursor at the bottom - of the window. - -**Left button drag with shift key** - - Enlarge the view to contain only channels in the selected area. - -**Right button** - - Brings up a popup menu which gives a choice of graphics output formats - for the current topographical display. Best quality is achieved - with the Illustrator format. This format has the benefit that it - is object oriented and can be edited in Adobe Illustrator. - -**Middle button** - - Drag and drop graphics to one of the cliplab view - areas. - -.. note:: The cliplab drag-and-drop functionality requires that you have the proprietary Elekta-Neuromag analysis software installed. mne_browse_raw is compatible with cliplab versions 1.2.13 and later. - -.. note:: The graphics output files will contain a text line stating of the time and vertical scales if the zero level/time and/or viewport frames have been switched on in the scales dialog, see :ref:`CACBEHCD`. - -.. _CACBBDGC: - -Description files for off-line averaging -######################################## - -For averaging tasks more complex than those involving only -one trigger, the averaging parameters are specified with help of -a text file. This section describes the format of this file. A sample -averaging file can be found in ``$MNE_ROOT/share/mne/mne_browse_raw/templates`` . - -Overall format -============== - -Any line beginning with the pound sign (#) in this description -file is a comment. Each parameter in the description file is defined -by a keyword usually followed by a value. Text values consisting -of multiple words, separated by spaces, must be included in quotation -marks. The case of the keywords in the file does not matter. The -ending ``.ave`` is suggested for the average description -files. - -The general format of the description file is:: - - average { - - category { - - } - - ... - } - -The file may contain arbitrarily many categories. The word ``category`` interchangeable -with ``condition`` . - -.. warning:: Due to a bug that existed in some versions of the Neuromag acquisition software, the trigger line 8 is incorrectly decoded on trigger channel STI 014. This can be fixed by running mne_fix_stim14 on the raw data file before using mne_browse_raw or mne_process_raw . The bug has been fixed on Nov. 10, 2005. - -.. _BABIHFBI: - -Common parameters -================= - -The average definition starts with the common parameters. -They include: - -**outfile <*name*>** - - The name of the file where the averages are to be stored. In interactive - mode, this can be omitted. The resulting average structure can be - viewed and stored from the Manage averages window. - -**eventfile <*name*>** - - Optional file to contain event specifications. If this file is present, the - trigger events in the raw data file are ignored and this file is - consulted instead. The event file format is recognized from the - file name: if it ends with ``.fif`` , the file is assumed - to be in fif format, otherwise a text file is expected. The text event - file format is described in :ref:`CACBCEGC`. - -**logfile <*name*>** - - This optional file will contain detailed information about the averaging - process. In the interactive mode, the log information can be viewed - from the Manage averages window. - -**gradReject <*value / T/m*>** - - Rejection limit for MEG gradiometer channels. If the peak-to-peak amplitude - within the extracted epoch exceeds this value on any of the gradiometer - channels, the epoch will be omitted from the average. - -**magReject <*value / T*>** - - Rejection limit for MEG magnetometer and axial gradiometer channels. - If the peak-to-peak amplitude within the extracted epoch exceeds - this value on any of the magnetometer or axial gradiometer channels, - the epoch will be omitted from the average. - -**eegReject <*value / V*>** - - Rejection limit for EEG channels. If the peak-to-peak amplitude within - the extracted epoch exceeds this value on any of the EEG channels, - the epoch will be omitted from the average. - -**eogReject <*value / V*>** - - Rejection limit for EOG channels. If the peak-to-peak amplitude within - the extracted epoch exceeds this value on any of the EOG channels, - the epoch will be omitted from the average. - -**ecgReject <*value / V*>** - - Rejection limit for ECG channels. If the peak-to-peak amplitude within - the extracted epoch exceeds this value on any of the ECG channels, - the epoch will be omitted from the average. - -**gradFlat <*value / T/m*>** - - Signal detection criterion for MEG planar gradiometers. The peak-to-peak - value of all planar gradiometer signals must exceed this value, - for the epoch to be included. This criterion allows rejection of data - with saturated or otherwise dysfunctional channels. The default value - is zero, *i.e.*, no rejection. - -**magFlat <*value / T*>** - - Signal detection criterion for MEG magnetometers and axial gradiometers - channels. - -**eegFlat <*value / V*>** - - Signal detection criterion for EEG channels. - -**eogFlat <*value / V*>** - - Signal detection criterion for EOG channels. - -**ecgFlat <*value / V*>** - - Signal detection criterion for ECG channels. - -**stimIgnore <*time / s*>** - - Ignore this many seconds on both sides of the trigger when considering - the epoch. This parameter is useful for ignoring large stimulus artifacts, *e.g.*, - from electrical somatosensory stimulation. - -**fixSkew** - - Since the sampling of data and the stimulation devices are usually not - synchronized, all trigger input bits may not turn on at the same sample. - If this option is included in the off-line averaging description - file, the following procedure is used to counteract this: if there is - a transition from zero to a nonzero value on the digital trigger channel - at sample :math:`n`, the following sample - will be checked for a transition from this nonzero value to another - nonzero value. If such an event pair is found, the two events will - be jointly considered as a transition from zero to the second non-zero - value. With the fixSkew option, mne_browse_raw/mne_process_raw behaves - like the Elekta-Neuromag on-line averaging and Maxfilter (TM) software. - -**name <*text*>** - - A descriptive name for this set of averages. If the name contains multiple - words, enclose it in quotation marks "like this". - The name will appear in the average manager window listing in the - interactive version of the program and as a comment in the processed - data section in the output file. - -.. _CACHACHH: - -Category definition -=================== - -A category (condition) is defined by the parameters listed -in this section. - -**event <*number*>** - - The zero time point of an epoch to be averaged is defined by a transition - from zero to this number on the digital trigger channel. The interpretation - of the values on the trigger channel can be further modified by - the ignore and mask keywords. If multiple event parameters are present - for a category, all specified events will be included in the average. - -**ignore <*number*>** - - If this parameter is specified the selected bits on trigger channel - values can be mask (set to zero) out prior to checking for an existence of - an event. For example, to ignore the values of trigger input lines three - and eight, specify ``ignore 132`` (:math:`2^2 + 2^7 = 132`). - -**mask <*number*>** - - Works similarly to ignore except that a mask specifies the trigger channel - bits to be included. For example, to look at trigger input lines - one to three only, ignoring others, specify ``mask 7`` - (:math:`2^0 + 2^1 + 2^2 = 7`). - -**prevevent <*number*>** - - Specifies the event that is required to occur immediately before - the event(s) specified with event parameter(s) - in order for averaging to occur. Only one previous event number - can be specified. - -**prevignore <*number*>** - - Works like ignore but for the - events specified with prevevent . - If prevignore and prevmask are - missing, the mask implied by ignore and mask is - applied to prevevent as well. - -**prevmask <*number*>** - - Works like mask but for the events - specified with prevevent . If prevignore and prevmask are - missing, the mask implied by ignore and mask is - applied to prevevent as well. - -**nextevent <*number*>** - - Specifies the event that is required to occur immediately after - the event(s) specified with event parameter(s) - in order for averaging to occur. Only one next event number can - be specified. - -**nextignore <*number*>** - - Works like ignore but for the - events specified with nextevent . - If nextgnore and nextmask are - missing, the mask implied by ignore and mask is - applied to nextevent as well. - -**nextmask <*number*>** - - Works like mask but for the events - specified with nextevent . If nextignore and nextmask are - missing, the mask implied by ignore and mask is - applied to nextevent as well. - -**delay <*time / s*>** - - Adds a delay to the time of the occurrence of an event. Therefore, - if this parameter is positive, the zero time point of the epoch - will be later than the time of the event and, correspondingly, if - the parameter is negative, the zero time point of the epoch will - be earlier than the event. By default, there will be no delay. - -**tmin <*time / s*>** - - Beginning time point of the epoch. - -**tmax <*time / s*>** - - End time point of the epoch. - -**bmin <*time / s*>** - - Beginning time point of the baseline. If both ``bmin`` and ``bmax`` parameters - are present, the baseline defined by this time range is subtracted - from each epoch before they are added to the average. - -**basemin <*time / s*>** - - Synonym for bmin. - -**bmax <*time / s*>** - - End time point of the baseline. - -**basemax <*time / s*>** - - Synonym for bmax. - -**name <*text*>** - - A descriptive name for this category. If the name contains multiple words, - enclose it in quotation marks "like this". The - name will appear in the average manager window listing in the interactive - version of the program and as a comment averaging category section - in the output file. - -**abs** - - Calculate the absolute values of the data in the epoch before adding it to - the average. - -**stderr** - - The standard error of mean will be computed for this category and included - in the output fif file. - -.. note:: Specification of the baseline limits does not any more imply the estimation of the standard error of mean. Instead, the stderr parameter is required to invoke this option. - -.. _CACEBACG: - -Description files for covariance matrix estimation -################################################## - -Covariance matrix estimation is controlled by a another description -file, very similar to the average definition. A example of a covariance -description file can be found in the directory ``$MNE_ROOT/share/mne/mne_browse_raw/templates`` . - -Overall format -============== - -Any line beginning with the pound sign (#) in this description -file is a comment. Each parameter in the description file is defined -by a keyword usually followed by a value. Text values consisting -of multiple words, separated by spaces, must be included in quotation -marks. The case of the keywords in the file does not matter. The -ending ``.cov`` is suggested for the covariance-matrix -description files. - -The general format of the description file is:: - - cov { - <*common parameters*> - def { - <*covariance definition parameters*> - } - ... - } - -The file may contain arbitrarily many covariance definitions, -starting with ``def`` . - -.. warning:: Due to a bug that existed in some versions of the Neuromag acquisition software, the trigger line 8 is incorrectly decoded on trigger channel STI 014. This can be fixed by running mne_fix_stim14 on the raw data file before using mne_browse_raw or mne_process_raw . This bug has been fixed in the acquisition software at the Martinos Center on Nov. 10, 2005. - -.. _BABCGEJE: - -Common parameters -================= - -The average definition starts with the common parameters. -They include: - -**outfile <*name*>** - - The name of the file where the covariance matrix is to be stores. This - parameter is mandatory. - -**eventfile <*name*>** - - Optional file to contain event specifications. This file can be - either in fif or text format (see :ref:`CACBCEGC`). The event - file format is recognized from the file name: if it ends with ``.fif`` , - the file is assumed to be in fif format, otherwise a text file is - expected. If this parameter is present, the trigger events in the - raw data file are ignored and this event file is consulted instead. - The event file format is described in :ref:`CACBCEGC`. - -**logfile <*name*>** - - This optional file will contain detailed information about the averaging - process. In the interactive mode, the log information can be viewed - from the Manage averages window. - -**gradReject <*value / T/m*>** - - Rejection limit for MEG gradiometer channels. If the peak-to-peak amplitude - within the extracted epoch exceeds this value on any of the gradiometer - channels, the epoch will be omitted from the average. - -**magReject <*value / T*>** - - Rejection limit for MEG magnetometer and axial gradiometer channels. - If the peak-to-peak amplitude within the extracted epoch exceeds - this value on any of the magnetometer or axial gradiometer channels, - the epoch will be omitted from the average. - -**eegReject <*value / V*>** - - Rejection limit for EEG channels. If the peak-to-peak amplitude within - the extracted epoch exceeds this value on any of the EEG channels, - the epoch will be omitted from the average. - -**eogReject <*value / V*>** - - Rejection limit for EOG channels. If the peak-to-peak amplitude within - the extracted epoch exceeds this value on any of the EOG channels, - the epoch will be omitted from the average. - -**ecgReject <*value / V*>** - - Rejection limit for ECG channels. If the peak-to-peak amplitude within - the extracted epoch exceeds this value on any of the ECG channels, - the epoch will be omitted from the average. - -**gradFlat <*value / T/m*>** - - Signal detection criterion for MEG planar gradiometers. The peak-to-peak - value of all planar gradiometer signals must exceed this value, - for the epoch to be included. This criterion allows rejection of data - with saturated or otherwise dysfunctional channels. The default value - is zero, *i.e.*, no rejection. - -**magFlat <*value / T*>** - - Signal detection criterion for MEG magnetometers and axial gradiometers - channels. - -**eegFlat <*value / V*>** - - Signal detection criterion for EEG channels. - -**eogFlat <*value / V*>** - - Signal detection criterion for EOG channels. - -**ecgFlat <*value / V*>** - - Signal detection criterion for ECG channels. - -**stimIgnore <*time / s*>** - - Ignore this many seconds on both sides of the trigger when considering - the epoch. This parameter is useful for ignoring large stimulus artifacts, *e.g.*, - from electrical somatosensory stimulation. - -**fixSkew** - - Since the sampling of data and the stimulation devices are usually not - synchronized, all trigger input bits may not turn on at the same sample. - If this option is included in the off-line averaging description - file, the following procedure is used to counteract this: if there is - a transition from zero to a nonzero value on the digital trigger channel - at sample :math:`n`, the following sample - will be checked for a transition from this nonzero value to another - nonzero value. If such an event pair is found, the two events will - be jointly considered as a transition from zero to the second non-zero - value. - -**keepsamplemean** - - The means at individual samples will *not* be - subtracted in the estimation of the covariance matrix. For details, - see :ref:`BABHJDEJ`. This parameter is effective only for - estimating the covariance matrix from epochs. It is recommended - to specify this option. However, for compatibility with previous - MNE releases, keepsamplemean is - not on by default. - -.. _BABECIAH: - -Covariance definitions -====================== - -The covariance definitions starting with def specify the -epochs to be included in the estimation of the covariance matrix. - -**event <*number*>** - - The zero time point of an epoch to be averaged is defined by a transition - from zero to this number on the digital trigger channel. The interpretation - of the values on the trigger channel can be further modified by - the ignore and mask keywords. If multiple event parameters are present - in a definition, all specified events will be included. If the event - parameter is missing or set to zero, the covariance matrix is computed - over a section of the raw data, defined by the ``tmin`` and ``tmax`` parameters. - -**ignore <*number*>** - - If this parameter is specified the selected bits on trigger channel - values can be mask (set to zero) out prior to checking for an existence of - an event. For example, to ignore the values of trigger input lines three - and eight, specify ``ignore 132`` (:math:`2^2 + 2^7 = 132`). - -**mask <*number*>** - - Works similarly to ignore except that a mask specifies the trigger channel - bits to be included. For example, to look at trigger input lines - one to three only, ignoring others, specify ``mask 7`` - (:math:`2^0 + 2^1 + 2^2 = 7`). - -**delay <*time / s*>** - - Adds a delay to the time of the occurrence of an event. Therefore, - if this parameter is positive, the zero time point of the epoch - will be later than the time of the event and, correspondingly, if - the parameter is negative, the zero time point of the epoch will - be earlier than the time of the event. By default, there will be - no delay. - -**tmin <*time / s*>** - - Beginning time point of the epoch. If the ``event`` parameter - is zero or missing, this defines the beginning point of the raw - data range to be included. - -**tmax <*time / s*>** - - End time point of the epoch. If the ``event`` parameter - is zero or missing, this defines the end point of the raw data range - to be included. - -**bmin <*time / s*>** - - It is possible to remove a baseline from the epochs before they - are included in the covariance matrix estimation. This parameter - defines the starting point of the baseline. This feature can be - employed to avoid overestimation of noise in the presence of low-frequency drifts. - Setting of ``bmin`` and ``bmax`` is always recommended - for epoch-based covariance matrix estimation. - -**basemin <*time / s*>** - - Synonym for bmin. - -**bmax <*time / s*>** - - End time point of the baseline, see above. - -**basemax <*time / s*>** - - Synonym for bmax. - -.. _CACJFADF: - -Managing averages -################# - -This selection pops up a dialog which allows the management -of computed averages. The controls in the dialog, shown in :ref:`CACEFABD`, allow the following: - -- Select which categories (conditions) - are displayed in the average view. - -- Select the colors of the traces. - -- Viewing the log information accumulated in the averaging process. - -- Saving of averaged data. - -- Setting the active vectors for signal-space projection if - the data were loaded from a file. - -- Setting the current software gradient compensation for data - loaded from a file. - -.. _CACEFABD: - -.. figure:: mne_browse_raw/manage_averages_dialog.png - :alt: dialog for managing available averages - - The dialog for managing available averages. - -In the example of :ref:`CACEFABD`, the first item -is an average computed within mne_browse_raw , -the second one contains data loaded from a file with signal-space -projection data available, the third one demonstrates multiple data -sets loaded from a file with neither projection nor software gradient -compensation available, and the last one is a data set loaded from file -with software gradient compensation data present. Note that this -is now a scrolled window and some of the loaded data may be below -or above the current view area. - -.. _CACCHABI: - -The Signal-Space Projection (SSP) method -######################################## - -The Signal-Space Projection (SSP) is one approach to rejection -of external disturbances in software. The section presents some -relevant details of this method. - -General concepts -================ - -Unlike many other noise-cancellation approaches, SSP does -not require additional reference sensors to record the disturbance -fields. Instead, SSP relies on the fact that the magnetic field -distributions generated by the sources in the brain have spatial -distributions sufficiently different from those generated by external -noise sources. Furthermore, it is implicitly assumed that the linear -space spanned by the significant external noise patters has a low -dimension. - -Without loss of generality we can always decompose any :math:`n`-channel -measurement :math:`b(t)` into its signal and -noise components as - -.. math:: b(t) = b_s(t) + b_n(t) - -Further, if we know that :math:`b_n(t)` is -well characterized by a few field patterns :math:`b_1 \dotso b_m`, -we can express the disturbance as - -.. math:: b_n(t) = Uc_n(t) + e(t)\ , - -where the columns of :math:`U` constitute -an orthonormal basis for :math:`b_1 \dotso b_m`, :math:`c_n(t)` is -an :math:`m`-component column vector, and -the error term :math:`e(t)` is small and does -not exhibit any consistent spatial distributions over time, *i.e.*, :math:`C_e = E \{e e^T\} = I`. -Subsequently, we will call the column space of :math:`U` the -noise subspace. The basic idea of SSP is that we can actually find -a small basis set :math:`b_1 \dotso b_m` such that the -conditions described above are satisfied. We can now construct the -orthogonal complement operator - -.. math:: P_{\perp} = I - UU^T - -and apply it to :math:`b(t)` yielding - -.. math:: b(t) = P_{\perp}b_s(t)\ , - -since :math:`P_{\perp}b_n(t) = P_{\perp}Uc_n(t) \approx 0`. The projection operator :math:`P_{\perp}` is -called the signal-space projection operator and generally provides -considerable rejection of noise, suppressing external disturbances -by a factor of 10 or more. The effectiveness of SSP depends on two -factors: - -- The basis set :math:`b_1 \dotso b_m` should - be able to characterize the disturbance field patterns completely - and - -- The angles between the noise subspace space spanned by :math:`b_1 \dotso b_m` and the - signal vectors :math:`b_s(t)` should be as close - to :math:`\pi / 2` as possible. - -If the first requirement is not satisfied, some noise will -leak through because :math:`P_{\perp}b_n(t) \neq 0`. If the any -of the brain signal vectors :math:`b_s(t)` is -close to the noise subspace not only the noise but also the signal -will be attenuated by the application of :math:`P_{\perp}` and, -consequently, there might by little gain in signal-to-noise ratio. -:ref:`CACFGIEC` demonstrates the effect of SSP on the Vectorview -magnetometer data. After the elimination of a three-dimensional -noise subspace, the absolute value of the noise is dampened approximately -by a factor of 10 and the covariance matrix becomes diagonally dominant. - -Since the signal-space projection modifies the signal vectors -originating in the brain, it is necessary to apply the projection -to the forward solution in the course of inverse computations. This -is accomplished by mne_inverse_operator as -described in :ref:`c_legacy_inverse_operator`. For more information on SSP, -please consult the references listed in :ref:`CEGIEEBB`. - -EEG average electrode reference -=============================== - -In the computation of EEG-based source estimates, the MNE -software employs the average-electrode reference, which means that -the average over all electrode signals :math:`v_1 \dotso v_p` is -subtracted from each :math:`v_j`: - -.. math:: v_{j}' = v_j - \frac{1}{p} \sum_{k} v_k\ . - -It is easy to see that the above equation actually corresponds -to the projection: - -.. math:: v' = (I - uu^T)v\ , - -where - -.. math:: u = \frac{1}{\sqrt{p}}[1\ ...\ 1]^T\ . - -.. _CACHAAEG: - -Covariance matrix estimation -############################ - -This section describes how the covariance matrices are computed -for raw data and epochs. - -Continuous raw data -=================== - -If a covariance matrix of a raw data is computed the data -are checked for artifacts in 200-sample pieces. Let us collect the -accepted :math:`M` samples from all channels to -the vectors :math:`s_j,\ j = 1, \dotsc ,M`. The estimate of the covariance -matrix is then computed as: - -.. math:: \hat{C} = \frac{1}{M - 1} \sum_{j = 1}^M {(s_j - \bar{s})(s_j - \bar{s})}^T - -where - -.. math:: \bar{s} = \frac{1}{M} \sum_{j = 1}^M s_j - -is the average of the signals over all times. Note that no -attempt is made to correct for low frequency drifts in the data. -If the contribution of any frequency band is not desired in the -covariance matrix estimate, suitable band-pass filter should be -applied. - -For actual computations, it is convenient to rewrite the -expression for the covariance matrix as - -.. math:: \hat{C} = \frac{1}{M - 1} \sum_{j = 1}^M {s_j s_j^T} - \frac{M}{M - 1} \bar{s} \bar{s}^T - -.. _BABHJDEJ: - -Epochs -====== - -The calculation of the covariance matrix is slightly more -complicated in the epoch mode. If the bmin and bmax parameters -are specified in the covariance matrix description file (see :ref:`BABECIAH`), baseline correction is first applied to each -epoch. - -Let the vectors - -.. math:: s_{rpj}\ ;\ p = 1 \dotsc P_r\ ;\ j = 1 \dotsc N_r\ ;\ r = 1 \dotsc R - -be the samples from all channels in the baseline corrected epochs -used to calculate the covariance matrix. In the above, :math:`P_r` is -the number of accepted epochs in category :math:`r`, :math:`N_r` is -the number of samples in the epochs of category :math:`r`, -and :math:`R` is the number of categories. - -If the recommended ``--keepsamplemean`` option -is specified in the covariance matrix definition file, the baseline -correction is applied to the epochs but the means at individual -samples are not subtracted. Thus the covariance matrix will be computed -as: - -.. math:: \hat{C} = \frac{1}{N_C} \sum_{r,p,j} {s_{rpj} s_{rpj}^T}\ , - -where - -.. math:: N_C = \sum_{r = 1}^R N_r P_r\ . - -If keepsamplemean is *not* specified, -we estimate the covariance matrix as - -.. math:: \hat{C} = \frac{1}{N_C} \sum_{r = 1}^R \sum_{j = 1}^{N_r} \sum_{p = 1}^{P_r} {(s_{rpj} - \bar{s_{rj}}) ((s_{rpj} - \bar{s_{rj}})^T}\ , - -where - -.. math:: \bar{s_{rj}} = \frac{1}{P_r} \sum_{p = 1}^{P_r} s_{rpj} - -and - -.. math:: N_C = \sum_{r = 1}^R {N_r (P_r - 1)}\ , - -which reflects the fact that :math:`N_r` means -are computed for category :math:`r`. It -is easy to see that the expression for the covariance matrix estimate -can be cast into a more convenient form - -.. math:: \hat{C} = \frac{1}{N_C} \sum_{r,p,j} {s_{rpj} s_{rpj}^T} - \frac{1}{N_C} \sum_r P_r \sum_j {\bar{s_{rj}} \bar{s_rj}^T}/ . - -Subtraction of the means at individual samples is useful -if it can be expected that the evoked response from previous stimulus -extends to part of baseline period of the next one. - -Combination of covariance matrix estimates -========================================== - -Let us assume that we have computed multiple covariance matrix -estimates :math:`\hat{C_1} \dotso \hat{C_Q}` with corresponding degrees -of freedom :math:`N_1 \dotso N_Q`. We can combine these -matrices together as - -.. math:: C = \sum_q {\alpha_q \hat{C}_q}\ , - -where - -.. math:: \alpha_q = \frac{N_q}{\sum_q {N_q}}\ . - -SSP information included with covariance matrices -================================================= - -If a signal space projection was on when a covariance matrix -was calculated, information about the projections applied is included -with the covariance matrix when it is saved. These projection data -are read by mne_inverse_operator and -applied to the forward solution as well as appropriate. Inclusion -of the projections into the covariance matrix limits the possibilities -to use the ``--bad`` and ``--proj`` options in mne_inverse_operator , -see :ref:`c_legacy_inverse_operator`. - -.. _CACGHEGC: - -Interacting with mne_analyze -############################ - -To facilitate interactive analysis of raw data, mne_browse_raw can -run mne_analyze as a child process. -In this mode, mne_analyze is "remote controlled" by mne_browse_raw and -will also send replies to mne_browse_raw to -keep the two programs synchronized. A practical application of this -communication is to view field or potential maps and cortically-constrained -source estimates computed from raw data instantly. - -The subordinate mne_analyze is -started and stopped from Start mne_analyze and Quit mne_analyze in the Windows menu, -respectively. The following settings are communicated between the -two processes: - -**The raw data file** - - If a new raw data file is opened and a subordinate mne_analyze is active, - the name of the raw data file is communicated to mne_analyze and - a simplified version of the open dialog appears in mne_analyze allowing - selection of an inverse operator or are MEG/MRI coordinate transformation. - If a raw data file is already open in mne_browse_raw when mne_analyze is - started, the open dialog appears immediately. - -**Time point** - - When a new time point is selected in mne_browse_raw the mne_analyze time - point selection is updated accordingly. Time point selection in mne_analyze is - not transferred to mne_browse_raw . - -**Scales** - - The vertical scales are kept synchronized between the two programs. - In addition, the settings of the sample time limits are communicated - from mne_browse_raw to mne_analyze . - -**Filter** - - The filter settings are kept synchronized. Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/adjust_alignment.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/adjust_alignment.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/adjust_lights.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/adjust_lights.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/adjust_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/adjust_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/cont_hpi_data.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/cont_hpi_data.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/dipole_list.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/dipole_list.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/dipole_parameters.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/dipole_parameters.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/dipoles_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/dipoles_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/epoch_selector.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/epoch_selector.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/field_mapping_pref.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/field_mapping_pref.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/file_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/file_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/hardcopy_controls.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/hardcopy_controls.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/help_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/help_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/image_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/image_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/label_list.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/label_list.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/labels_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/labels_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/main_window.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/main_window.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/MNE_preferences.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/MNE_preferences.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/movie_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/movie_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/mri_viewer.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/mri_viewer.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/open_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/open_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/overlay_management.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/overlay_management.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/patch_selection_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/patch_selection_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/save_label_timecourse.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/save_label_timecourse.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/scales_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/scales_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/surface_controls.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/surface_controls.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/surface_selection_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/surface_selection_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/timecourse_manager.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/timecourse_manager.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/viewer_options.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/viewer_options.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/viewer.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/viewer.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/view_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/view_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/visualize_hpi.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/visualize_hpi.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_analyze/windows_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_analyze/windows_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/adjust_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/adjust_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/adust_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/adust_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/average_pref.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/average_pref.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/channel_selection.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/channel_selection.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/file_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/file_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/filter_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/filter_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/help_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/help_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/main.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/main.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/manage_averages_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/manage_averages_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/new_selection.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/new_selection.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/new_ssp.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/new_ssp.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/open_dialog copy.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/open_dialog copy.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/open_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/open_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/process_menu2.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/process_menu2.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/process_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/process_menu.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/scales_dialog2.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/scales_dialog2.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/scales_dialog.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/scales_dialog.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/toolbar.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/toolbar.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-0.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-0.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-10.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-10.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-11.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-11.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-12.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-12.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-13.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-13.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-14.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-14.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-15.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-15.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-16.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-16.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-17.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-17.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-1.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-1.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-2.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-2.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-3.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-3.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-4.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-4.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-5.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-5.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-6.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-6.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-7.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-7.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-8.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-8.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-9.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu-9.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/gui/mne_browse_raw/windows_menu.png differ diff -Nru python-mne-0.18.1+dfsg/doc/manual/io.rst python-mne-0.19.1+dfsg/doc/manual/io.rst --- python-mne-0.18.1+dfsg/doc/manual/io.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/io.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,524 +0,0 @@ -.. _ch_convert: - -Importing data into MNE -~~~~~~~~~~~~~~~~~~~~~~~ - -This guide describes how to import data into MNE. It includes instructions for -importing from files generated by common MEG/EEG recording equipment, as well -as importing raw data from NumPy arrays. - -.. contents:: Contents - :local: - :depth: 2 - -.. _data-formats: - -Cheatsheet -########## - -The cheatsheet below summarizes the supported file formats. - -=================== ============================ ========= ================================================================= -Datatype File format Extension MNE-Python function -=================== ============================ ========= ================================================================= -MEG Elekta Neuromag .fif :func:`mne.io.read_raw_fif` -MEG 4-D Neuroimaging / BTI dir :func:`mne.io.read_raw_bti` -MEG CTF dir :func:`mne.io.read_raw_ctf` -MEG KIT sqd :func:`mne.io.read_raw_kit` and :func:`mne.read_epochs_kit` -EEG Brainvision .vhdr :func:`mne.io.read_raw_brainvision` -EEG Neuroscan CNT .cnt :func:`mne.io.read_raw_cnt` -EEG European data format .edf :func:`mne.io.read_raw_edf` -EEG Biosemi data format .bdf :func:`mne.io.read_raw_bdf` -EEG General data format .gdf :func:`mne.io.read_raw_gdf` -EEG EGI simple binary .egi :func:`mne.io.read_raw_egi` -EEG EGI MFF format .mff :func:`mne.io.read_raw_egi` -EEG EEGLAB .set :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab` -EEG eXimia .nxe :func:`mne.io.read_raw_eximia` -Electrode locations elc, txt, csd, sfp, htps Misc :func:`mne.channels.read_montage` -Electrode locations EEGLAB loc, locs, eloc Misc :func:`mne.channels.read_montage` -MEG and EEG FieldTrip raw/epochs/avg .mat :func:`mne.io.read_raw_fieldtrip`, :func:`mne.read_epochs_fieldtrip` and :func:`mne.read_evoked_fieldtrip` -MEG and EEG arbitrary data (from memory) xxxx :class:`mne.io.RawArray`, :class:`mne.EpochsArray`, :class:`mne.EvokedArray` and :func:`mne.create_info` -=================== ============================ ========= ================================================================= - - -Importing data from MEG devices -############################### - -This section describes the data reading and conversion utilities included -with MNE. - -.. note:: - All IO functions in MNE-Python performing reading/conversion of MEG and - EEG data can be found in :mod:`mne.io` and start with `read_raw_`. All - supported data formats can be read in MNE-Python directly without first - saving it to fif. - -.. note:: - Irrespective of the units used in your manufacturer's format, MNE-Python - will always use the units listed below and perform conversions during the - IO procedure if necessary. - - * V: eeg, eog, seeg, emg, ecg, bio, ecog - * T: mag - * T/m: grad - * M: hbo, hbr - * Am: dipole - * AU: misc - -.. note:: - MNE-Python performs all computations in memory using the double-precision - 64-bit floating point format. This means that the data is cast into the - `float64` format as soon as it is read into memory. The reason for this is - that operations such as filtering, preprocessing, etc. are more accurate when - using double precision. However, for backward compatibility, MNE - writes `fif` files in a 32-bit format by default. This is advantageous - when saving data to disk as it consumes less space. - - However, if you save intermediate results to disk, you should be aware - that this may lead to loss in precision. The reason is that writing to disk is - 32-bit by default, and type-casting to 64-bit does not recover the lost - precision. If you would like to retain the 64-bit accuracy, there are two - possibilities: - - * Chain the operations in memory and do not save intermediate results - * Save intermediate results, but change the ``dtype`` used for saving. However, - this may render the files unreadable in other software packages. - -Elekta NeuroMag (.fif) -====================== - -Neuromag Raw FIF files can be loaded using :func:`mne.io.read_raw_fif`. - -.. note:: - If the data were recorded with MaxShield on and have not been processed - with MaxFilter, they may need to be loaded with - ``mne.io.read_raw_fif(..., allow_maxshield=True)``. - -Importing 4-D Neuroimaging / BTI data -===================================== - -MNE-Python provides :func:`mne.io.read_raw_bti` to read and convert 4D / BTI data. -This reader function will by default replace the original channel names, -typically composed of the letter `A` and the channel number with Neuromag. -To import the data, the following input files are mandatory: - -- A data file (typically c,rfDC) - containing the recorded MEG time series. - -- A hs_file - containing the digitizer data. - -- A config file - containing acquisition information and metadata. - -By default :func:`mne.io.read_raw_bti` assumes that these three files are located -in the same folder. - -.. note:: While reading the reference or compensation channels, - the compensation weights are currently not processed. - As a result, the :class:`mne.io.Raw` object and the corresponding fif - file does not include information about the compensation channels - and the weights to be applied to realize software gradient - compensation. To augment the Magnes fif files with the necessary - information, the command line tools include the utilities - :ref:`mne_create_comp_data` and :ref:`mne_add_to_meas_info`. - Including the compensation channel data is recommended but not - mandatory. If the data are saved in the Magnes system are already - compensated, there will be a small error in the forward calculations, - whose significance has not been evaluated carefully at this time. - - -Creating software gradient compensation data --------------------------------------------- - -The utility :ref:`mne_create_comp_data` was -written to create software gradient compensation weight data for -4D Magnes fif files. This utility takes a text file containing the -compensation data as input and writes the corresponding fif file -as output. This file can be merged into the fif file containing -4D Magnes data with the utility :ref:`mne_add_to_meas_info`. -See :ref:`mne_create_comp_data` for command-line options. - - -Importing CTF data -================== - -The function :func:`mne.io.read_raw_ctf` can be used to read CTF data. - - -Importing CTF Polhemus data -=========================== - -The CTF MEG systems store the Polhemus digitization data -in text files. The utility :ref:`mne_ctf_dig2fiff` was -created to convert these data files into the fif and hpts formats. - - -.. _BEHDDFBI: - -Applying software gradient compensation ---------------------------------------- - -Since the software gradient compensation employed in CTF -systems is a reversible operation, it is possible to change the -compensation status of CTF data in the data files as desired. This -section contains information about the technical details of the -compensation procedure and a description of mne_compensate_data , -which is a utility to change the software gradient compensation -state in evoked-response data files. - -The fif files containing CTF data converted using the utility mne_ctf2fiff contain -several compensation matrices which are employed to suppress external disturbances -with help of the reference channel data. The reference sensors are -located further away from the brain than the helmet sensors and -are thus measuring mainly the external disturbances rather than magnetic -fields originating in the brain. Most often, a compensation matrix -corresponding to a scheme nicknamed *Third-order gradient -compensation* is employed. - -Let us assume that the data contain :math:`n_1` MEG -sensor channels, :math:`n_2` reference sensor -channels, and :math:`n_3` other channels. -The data from all channels can be concatenated into a single vector - -.. math:: x = [x_1^T x_2^T x_3^T]^T\ , - -where :math:`x_1`, :math:`x_2`, -and :math:`x_3` are the data vectors corresponding -to the MEG sensor channels, reference sensor channels, and other -channels, respectively. The data before and after compensation, -denoted here by :math:`x_{(0)}` and :math:`x_{(k)}`, respectively, -are related by - -.. math:: x_{(k)} = M_{(k)} x_{(0)}\ , - -where the composite compensation matrix is - -.. math:: M_{(k)} = \begin{bmatrix} - I_{n_1} & C_{(k)} & 0 \\ - 0 & I_{n_2} & 0 \\ - 0 & 0 & I_{n_3} - \end{bmatrix}\ . - -In the above, :math:`C_{(k)}` is a :math:`n_1` by :math:`n_2` compensation -data matrix corresponding to compensation "grade" :math:`k`. -It is easy to see that - -.. math:: M_{(k)}^{-1} = \begin{bmatrix} - I_{n_1} & -C_{(k)} & 0 \\ - 0 & I_{n_2} & 0 \\ - 0 & 0 & I_{n_3} - \end{bmatrix}\ . - -To convert from compensation grade :math:`k` to :math:`p` one -can simply multiply the inverse of one compensate compensation matrix -by another and apply the product to the data: - -.. math:: x_{(k)} = M_{(k)} M_{(p)}^{-1} x_{(p)}\ . - -This operation is performed by :meth:`mne.io.Raw.apply_gradient_compensation`. - - -Importing KIT MEG system data -============================= - -MNE-Python includes the :func:`mne.io.read_raw_kit` and -:func:`mne.read_epochs_kit` to read and convert KIT MEG data. -This reader function will by default replace the original channel names, -which typically with index starting with zero, with ones with an index starting with one. - -To import continuous data, only the input .sqd or .con file is needed. For epochs, -an Nx3 matrix containing the event number/corresponding trigger value in the -third column is needed. - -The following input files are optional: - -- A KIT marker file (mrk file) or an array-like - containing the locations of the HPI coils in the MEG device coordinate system. - These data are used together with the elp file to establish the coordinate - transformation between the head and device coordinate systems. - -- A Polhemus points file (elp file) or an array-like - containing the locations of the fiducials and the head-position - indicator (HPI) coils. These data are usually given in the Polhemus - head coordinate system. - -- A Polhemus head shape data file (hsp file) or an array-like - containing locations of additional points from the head surface. - These points must be given in the same coordinate system as that - used for the elp file. - - -.. note:: The output fif file will use the Neuromag head coordinate system convention, see :ref:`BJEBIBAI`. A coordinate transformation between the Polhemus head coordinates and the Neuromag head coordinates is included. - - -By default, KIT-157 systems assume the first 157 channels are the MEG channels, -the next 3 channels are the reference compensation channels, and channels 160 -onwards are designated as miscellaneous input channels (MISC 001, MISC 002, etc.). -By default, KIT-208 systems assume the first 208 channels are the MEG channels, -the next 16 channels are the reference compensation channels, and channels 224 -onwards are designated as miscellaneous input channels (MISC 001, MISC 002, etc.). - -In addition, it is possible to synthesize the digital trigger channel (STI 014) -from available analog trigger channel data by specifying the following parameters: - -- A list of trigger channels (stim) or default triggers with order: '<' | '>' - Channel-value correspondence when converting KIT trigger channels to a - Neuromag-style stim channel. By default, we assume the first eight miscellaneous - channels are trigger channels. For '<', the largest values are assigned - to the first channel (little endian; default). For '>', the largest values are - assigned to the last channel (big endian). Can also be specified as a list of - trigger channel indexes. -- The trigger channel slope (slope) : '+' | '-' - How to interpret values on KIT trigger channels when synthesizing a - Neuromag-style stim channel. With '+', a positive slope (low-to-high) - is interpreted as an event. With '-', a negative slope (high-to-low) - is interpreted as an event. -- A stimulus threshold (stimthresh) : float - The threshold level for accepting voltage changes in KIT trigger - channels as a trigger event. - -The synthesized trigger channel data value at sample :math:`k` will -be: - -.. math:: s(k) = \sum_{p = 1}^n {t_p(k) 2^{p - 1}}\ , - -where :math:`t_p(k)` are the thresholded -from the input channel data d_p(k): - -.. math:: t_p(k) = \Bigg\{ \begin{array}{l} - 0 \text{ if } d_p(k) \leq t\\ - 1 \text{ if } d_p(k) > t - \end{array}\ . - -The threshold value :math:`t` can -be adjusted with the ``stimthresh`` parameter, see below. - - -Importing data from EEG devices -############################### - -MNE includes various functions and utilities for reading EEG -data and electrode locations. - -BrainVision (.vhdr, .vmrk, .eeg) -================================ - -The BrainVision file format consists of three separate files: - -1. A text header file (``.vhdr``) containing meta data -2. A text marker file (``.vmrk``) containing information about events in the - data -3. A binary data file (``.eeg``) containing the voltage values of the EEG - -Both text files are based on the -`Microsoft Windows INI format `_ -consisting of: - -* sections marked as ``[square brackets]`` -* comments marked as ``; comment`` -* key-value pairs marked as ``key=value`` - -A documentation for core BrainVision file format is provided by Brain Products. -You can view the specification -`here `_ - -BrainVision EEG files can be read in using :func:`mne.io.read_raw_brainvision` -with the .vhdr header file as an input. - -.. warning:: Renaming BrainVision files can be problematic due to their - multifile structure. See this - `example `_ - for an instruction. - - -European data format (.edf) -=========================== - -EDF and EDF+ files can be read using :func:`mne.io.read_raw_edf`. - -`EDF (European Data Format) `_ and -`EDF+ `_ are 16-bit formats. - -The EDF+ files may contain an annotation channel which can be used to store -trigger information. These annotations are available in ``raw.annotations``. - -Saving EDF files is not supported natively yet. -This `gist `__ -can be used to save any mne.io.Raw into EDF/EDF+/BDF/BDF+. - -BioSemi data format (.bdf) -========================== - -The `BDF format `_ is a 24-bit -variant of the EDF format used by EEG systems manufactured by BioSemi. It can -be imported with :func:`mne.io.read_raw_bdf`. - -BioSemi amplifiers do not perform "common mode noise rejection" automatically. -The signals in the EEG file are the voltages between each electrode and CMS -active electrode, which still contain some CM noise (50 Hz, ADC reference noise, -etc., see `the BioSemi FAQ `__ -for further detail). -Thus, it is advisable to choose a reference (e.g., a single channel like Cz, -average of linked mastoids, average of all electrodes, etc.) on import of BioSemi -data to avoid losing signal information. The data can be re-referenced later after -cleaning if desired. - -.. warning:: The data samples in a BDF file are represented in a 3-byte (24-bit) format. Since 3-byte raw data buffers are not presently supported in the fif format these data will be changed to 4-byte integers in the conversion. - -General data format (.gdf) -========================== - -GDF files can be read in using :func:`mne.io.read_raw_gdf`. - -`GDF (General Data Format) `_ is a flexible -format for biomedical signals that overcomes some of the limitations of the -EDF format. The original specification (GDF v1) includes a binary header -and uses an event table. An updated specification (GDF v2) was released in -2011 and adds fields for additional subject-specific information (gender, -age, etc.) and allows storing several physical units and other properties. -Both specifications are supported in MNE. - -Neuroscan CNT data format (.cnt) -================================ - -CNT files can be read in using :func:`mne.io.read_raw_cnt`. -The channel locations can be read from a montage or the file header. If read -from the header, the data channels (channels that are not assigned to EOG, ECG, -EMG or misc) are fit to a sphere and assigned a z-value accordingly. If a -non-data channel does not fit to the sphere, it is assigned a z-value of 0. -See :ref:`BJEBIBAI` - -.. warning:: - Reading channel locations from the file header may be dangerous, as the - x_coord and y_coord in ELECTLOC section of the header do not necessarily - translate to absolute locations. Furthermore, EEG-electrode locations that - do not fit to a sphere will distort the layout when computing the z-values. - If you are not sure about the channel locations in the header, use of a - montage is encouraged. - -EGI simple binary (.egi) -======================== - -EGI simple binary files can be read in using :func:`mne.io.read_raw_egi`. -The EGI raw files are simple binary files with a header and can be exported -from using the EGI Netstation acquisition software. - - -EEGLAB set files (.set) -======================= - -EEGLAB .set files can be read in using :func:`mne.io.read_raw_eeglab` -and :func:`mne.read_epochs_eeglab`. - -Importing EEG data saved in the Tufts University format -======================================================= - -The command line utility :ref:`mne_tufts2fiff` was -created in collaboration with Phillip Holcomb and Annette Schmid -from Tufts University to import their EEG data to the MNE software. - -The Tufts EEG data is included in three files: - -- The raw data file containing the acquired - EEG data. The name of this file ends with the suffix ``.raw`` . - -- The calibration raw data file. This file contains known calibration - signals and is required to bring the data to physical units. The - name of this file ends with the suffix ``c.raw`` . - -- The electrode location information file. The name of this - file ends with the suffix ``.elp`` . - -See the options for the command-line utility :ref:`mne_tufts2fiff`. - -eXimia EEG data -=============== - -EEG data from the Nexstim eXimia system can be read in using the -:func:`mne.io.read_raw_eximia` function. - -Setting EEG references -###################### - -The preferred method for applying an EEG reference in MNE is -:func:`mne.set_eeg_reference`, or equivalent instance methods like -:meth:`raw.set_eeg_reference() `. By default, -an average reference is used. - -There are also other functions that can be useful for other referencing -operations. See :func:`mne.set_bipolar_reference` and -:func:`mne.add_reference_channels` for more information. - - -Reading electrode locations and head shapes for EEG recordings -############################################################## - -Some EEG formats (EGI, EDF/EDF+, BDF) neither contain electrode location -information nor head shape digitization information. Therefore, this information -has to be provided separately. For that purpose all readers have a montage -parameter to read locations from standard electrode templates or a Polhemus -digitizer file. This can also be done post-hoc using the -:func:`mne.io.Raw.set_montage` method of the Raw object in memory. - - -When using the locations of the fiducial points the digitization data -are converted to the MEG head coordinate system employed in the -MNE software, see :ref:`BJEBIBAI`. - - -Creating MNE data structures from arbitrary data (from memory) -############################################################## - -Arbitrary (e.g., simulated or manually read in) raw data can be constructed -from memory by making use of :class:`mne.io.RawArray`, :class:`mne.EpochsArray` -or :class:`mne.EvokedArray` in combination with :func:`mne.create_info`. - -This functionality is illustrated in :ref:`sphx_glr_auto_examples_io_plot_objects_from_arrays.py`. -Using 3rd party libraries such as NEO (https://github.com/NeuralEnsemble/python-neo) in combination -with these functions abundant electrophysiological file formats can be easily loaded -into MNE. - - -Importing MEG/EEG data from FieldTrip -##################################### - -MNE-Python includes :func:`mne.io.read_raw_fieldtrip`, :func:`mne.read_epochs_fieldtrip` and :func:`mne.read_evoked_fieldtrip` to read data coming from FieldTrip. - -The data is imported directly from a ``.mat`` file. - -The ``info`` parameter can be explicitly set to ``None``. The import functions will still work but: - -#. All channel locations will be in head coordinates. -#. Channel orientations cannot be guaranteed to be accurate. -#. All channel types will be set to generic types. - -This is probably fine for anything that does not need that information, but if you intent to do things like interpolation of missing channels, source analysis or look at the RMS pairs of planar gradiometers, you most likely run into problems. - -It is **highly recommended** to provide the ``info`` parameter as well. The ``info`` dictionary can be extracted by loading the original raw data file with the corresponding MNE-Python functions:: - - original_data = mne.io.read_raw_fiff('original_data.fif', preload=False) - original_info = original_data.info - data_from_ft = mne.read_evoked_fieldtrip('evoked_data.mat', original_info) - -The imported data can have less channels than the original data. Only the information for the present ones is extracted from the ``info`` dictionary. - -As of version 0.17, importing FieldTrip data has been tested on a variety of systems with the following results: - -+----------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+ -| System | Read Raw Data | Read Epoched Data | Read Evoked Data | -+==========+==============================================================================+==============================================================================+==============================================================================+ -| BTI | Works | Untested | Untested | -+----------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+ -| CNT | Data imported as microvolts. Otherwise fine. | Data imported as microvolts. Otherwise fine. | Data imported as microvolts. Otherwise fine. | -+----------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+ -| CTF | Works | Works | Works | -+----------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+ -| EGI | Mostly Ok.Data imported as microvolts. FieldTrip does not apply calibration. | Mostly Ok.Data imported as microvolts. FieldTrip does not apply calibration. | Mostly Ok.Data imported as microvolts. FieldTrip does not apply calibration. | -+----------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+ -| KIT | Does not work. Channel names are different in MNE-Python and FieldTrip | Does not work. Channel names are different in MNE-Python and FieldTrip | Does not work. Channel names are different in MNE-Python and FieldTrip | -+----------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+ -| Neuromag | Works | Works | Works | -+----------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+ -| eximia | Work | Untested | Untested | -+----------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------------+ diff -Nru python-mne-0.18.1+dfsg/doc/manual/matlab.rst python-mne-0.19.1+dfsg/doc/manual/matlab.rst --- python-mne-0.18.1+dfsg/doc/manual/matlab.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/matlab.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,1216 +0,0 @@ - -.. _ch_matlab: - -================== -MNE-MATLAB toolbox -================== - -.. contents:: Contents - :local: - :depth: 2 - -Overview -######## - -The MNE software contains a collection Matlab m-files to -facilitate interfacing with binary file formats of the MNE software. -The toolbox is located at ``$MNE_ROOT/share/matlab`` . The -names of the MNE Matlab toolbox functions begin either with `mne_` or -with `fiff_` . When you source the mne_setup script -as described in :ref:`user_environment`, one of the following actions -takes place: - -- If you do not have the Matlab startup.m - file, it will be created and lines allowing access to the MNE Matlab - toolbox are added. - -- If you have startup.m and it does not have the standard MNE - Matlab toolbox setup lines, you will be instructed to add them manually. - -- If you have startup.m and the standard MNE Matlab toolbox - setup lines are there, nothing happens. - -A summary of the available routines is provided in Tables :ref:`BGBCGHAG` - :ref:`BGBEFADJ`. The toolbox -also contains a set of examples which may be useful starting points -for your own development. The names of these functions start with mne_ex and -they are listed in :ref:`BGBEFADJ`. - -.. note:: The MNE Matlab Toolbox is compatible with Matlab versions 7.0 or later. - -.. note:: The matlab function fiff_setup_read_raw has a significant change. The sample numbers now take into account possible initial skip in the file, *i.e.*, the time between the start of the data acquisition and the start of saving the data to disk. The first_samp member of the returned structure indicates the initial skip in samples. If you want your own routines, which assume that initial skip has been removed, perform identically with the previous version, subtract first_samp from the sample numbers you specify to fiff_read_raw_segment . Furthermore, fiff_setup_read_raw has an optional argument to allow reading of unprocessed MaxShield data acquired with the Elekta MEG systems. - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. _BGBCGHAG: -.. table:: High-level reading routines. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | fiff_find_evoked | Find all evoked data sets from a file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_bad_channels | Read the bad channel list. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_ctf_comp | Read CTF software gradient compensation data. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_evoked | Read evoked-response data. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_evoked_all | Read all evoked-response data from a file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_meas_info | Read measurement information. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_mri | Read an MRI description file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_proj | Read signal-space projection data. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_raw_segment | Read a segment of raw data with time limits are specified | - | | in samples. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_raw_segment_times | Read a segment of raw data with time limits specified | - | | in seconds. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_setup_read_raw | Set up data structures before using fiff_read_raw_segment | - | | or fiff_read_raw_segment_times. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: Channel selection utilities. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | fiff_pick_channels | Create a selector to pick desired channels from data | - | | according to include and exclude lists. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_pick_channels_evoked | Pick desired channels from evoked-response data according | - | | to include and exclude lists. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_pick_info | Modify measurement info to include only selected channels. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_pick_types | Create a selector to pick desired channels from data | - | | according to channel types (MEG, EEG, STIM) in combination | - | | with include and exclude lists. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_pick_types_evoked | Pick desired channels from evoked-response data according | - | | to channel types (MEG, EEG, STIM) in combination with | - | | include and exclude lists. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: Coordinate transformation utilities. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | fiff_invert_transform | Invert a coordinate transformation structure. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_reset_ch_pos | Reset channel position transformation to the default values | - | | present in the file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_transform_eeg_chs | Transform electrode positions to another coordinate frame. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_transform_meg_chs | Apply a coordinate transformation to the sensor location | - | | data to bring the integration points to another coordinate | - | | frame. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: Basic reading routines. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | fiff_define_constants | Define a structure which contains the constant relevant | - | | to fif files. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_dir_tree_find | Find nodes of a given type in a directory tree structure. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_list_dir_tree | List a directory tree structure. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_make_dir_tree | Create a directory tree structure. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_open | Open a fif file and create the directory tree structure. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_named_matrix | Read a named matrix from a fif file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_tag | Read one tag from a fif file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_read_tag_info | Read the info of one tag from a fif file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_split_name_list | Split a colon-separated list of names into a cell array | - | | of strings. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: Writing routines. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | fiff_end_block | Write a FIFF_END_BLOCK tag. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_end_file | Write the standard closing. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_start_block | Write a FIFF_START_BLOCK tag. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_start_file | Write the appropriate beginning of a file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_ch_info | Write a channel information structure. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_coord_trans | Write a coordinate transformation structure. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_ctf_comp | Write CTF compensation data. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_dig_point | Write one digitizer data point. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_complex | Write single-precision complex numbers. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_complex_matrix | Write a single-precision complex matrix. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_double | Write double-precision floats. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_double_complex | Write double-precision complex numbers. | - +--------------------------------+--------------------------------------------------------------+ - |fiff_write_double_complex_matrix| Write a double-precision complex matrix. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_double_matrix | Write a double-precision matrix. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_evoked | Write an evoked-reponse data file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_float | Write single-precision floats. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_float_matrix | Write a single-precision matrix. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_id | Write an id tag. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_int | Write 32-bit integers. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_int_matrix | Write a matrix of 32-bit integers. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_name_list | Write a name list. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_named_matrix | Write a named matrix. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_proj | Write SSP data. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_short | Write 16-bit integers. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_string | Write a string. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: High-level data writing routines. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | fiff_write_evoked | Write an evoked-response data file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_finish_writing_raw | Write the closing tags to a raw data file. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_start_writing_raw | Start writing raw data file, *i.e.*, write the measurement | - | | information. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_dig_file | Write a fif file containing digitization data. | - +--------------------------------+--------------------------------------------------------------+ - | fiff_write_raw_buffer | Write one raw data buffer. This is used after a call to | - | | fiff_start_writing_raw. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: Coil definition utilities. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | mne_add_coil_defs | Add coil definitions to an array of channel information | - | | structures. | - +--------------------------------+--------------------------------------------------------------+ - | mne_load_coil_def | Load a coil definition file. | - +--------------------------------+--------------------------------------------------------------+ - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: Routines for software gradient compensation and signal-space projection. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | mne_compensate_to | Apply or remove CTF software gradient compensation from | - | | evoked-response data. | - +--------------------------------+--------------------------------------------------------------+ - | mne_get_current_comp | Get the state of software gradient compensation from | - | | measurement info. | - +--------------------------------+--------------------------------------------------------------+ - | mne_make_compensator | Make a compensation matrix which switches the status of | - | | CTF software gradient compensation from one state to another.| - +--------------------------------+--------------------------------------------------------------+ - | mne_make_projector_info | Create a signal-space projection operator with the | - | | projection item definitions and cell arrays of channel names | - | | and bad channel names as input. | - +--------------------------------+--------------------------------------------------------------+ - | mne_make_projector_info | Like mne_make_projector but uses the measurement info | - | | structure as input. | - +--------------------------------+--------------------------------------------------------------+ - | mne_set_current_comp | Change the information about the compensation status in | - | | measurement info. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: High-level routines for reading MNE data files. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | mne_pick_channels_cov | Pick desired channels from a sensor covariance matrix. | - +--------------------------------+--------------------------------------------------------------+ - | mne_pick_channels_forward | Pick desired channels (rows) from a forward solution. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_bem_surfaces | Read triangular tessellations of surfaces for | - | | boundary-element models. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_cov | Read a covariance matrix. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_epoch | Read an epoch of data from the output file of mne_epochs2mat.| - +--------------------------------+--------------------------------------------------------------+ - | mne_read_events | Read an event list from a fif file produced by | - | | mne_browse_raw or mne_process_raw. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_forward_solution | Read a forward solution from a fif file. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_inverse_operator | Read an inverse operator from a fif file. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_morph_map | Read an morphing map produced with mne_make_morph_maps, see | - | | :ref:`CHDBBHDH`. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_noise_cov | Read a noise-covariance matrix from a fif file. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_source_spaces | Read source space information from a fif file. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: High-level routines for writing MNE data files. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | mne_write_cov | Write a covariance matrix to an open file. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_cov_file | Write a complete file containing just a covariance matrix. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_events | Write a fif format event file compatible with mne_browse_raw | - | | and mne_process_raw. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_inverse_sol_stc | Write stc files containing an inverse solution or other | - | | dynamic data on the cortical surface. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_inverse_sol_w | Write w files containing an inverse solution or other static | - | | data on the cortical surface. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. _BABBDDAI: -.. table:: Routines related to stc, w, and label files. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | mne_read_stc_file | Read data from one stc file. The vertex numbering in the | - | | returned structure will start from 0. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_stc_file1 | Read data from one stc file. The vertex numbering in the | - | | returned structure will start from 1. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_w_file | Read data from one w file. The vertex numbering in the | - | | returned structure will start from 0. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_w_file1 | Read data from one w file. The vertex numbering in the | - | | returned structure will start from 1. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_stc_file | Write a new stc file. It is assumed the the vertex numbering | - | | in the input data structure containing the stc information | - | | starts from 0. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_stc_file1 | Write a new stc file. It is assumed the the vertex numbering | - | | in the input data structure containing the stc information | - | | starts from 1. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_w_file | Write a new w file. It is assumed the the vertex numbering | - | | in the input data structure containing the w file | - | | information starts from 0. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_w_file1 | Write a new w file. It is assumed the the vertex numbering | - | | in the input data structure containing the w file | - | | information starts from 1. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_label_file | Read a label file (ROI). | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_label_file | Write a label file (ROI). | - +--------------------------------+--------------------------------------------------------------+ - | mne_label_time_courses | Extract time courses corresponding to a label from an | - | | stc file. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. table:: Routines for reading FreeSurfer surfaces. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | mne_read_curvature | Read a curvature file. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_surface | Read one surface, return the vertex locations and | - | | triangulation info. | - +--------------------------------+--------------------------------------------------------------+ - | mne_read_surfaces | Read surfaces corresponding to one or both hemispheres. | - | | Optionally read curvature information and add derived | - | | surface data. | - +--------------------------------+--------------------------------------------------------------+ - | mne_reduce_surface | Reduce the number of triangles on a surface using the | - | | reducepatch Matlab function. | - +--------------------------------+--------------------------------------------------------------+ - | mne_write_surface | Write a FreeSurfer surface file. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. _BGBEGFBD: -.. table:: Utility functions. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | mne_block_diag | Create a sparse block-diagonal matrix out of a vector. | - +--------------------------------+--------------------------------------------------------------+ - | mne_combine_xyz | Calculate the square sum of the three Cartesian components | - | | of several vectors listed in one row or column vector. | - +--------------------------------+--------------------------------------------------------------+ - | mne_file_name | Compose a file name relative to $MNE_ROOT. | - +--------------------------------+--------------------------------------------------------------+ - | mne_find_channel | Find a channel by name from measurement info. | - +--------------------------------+--------------------------------------------------------------+ - | mne_find_source_space_hemi | Determine whether a given source space belongs to the left | - | | or right hemisphere. | - +--------------------------------+--------------------------------------------------------------+ - | mne_fread3 | Read a three-byte integer. | - +--------------------------------+--------------------------------------------------------------+ - | mne_fwrite3 | Write a three-byte integer. | - +--------------------------------+--------------------------------------------------------------+ - | mne_make_combined_event_file | Combine data from several trigger channels into one event | - | | file. | - +--------------------------------+--------------------------------------------------------------+ - | mne_omit_first_line | Omit first line from a multi-line message. This routine is | - | | useful for formatting error messages. | - +--------------------------------+--------------------------------------------------------------+ - | mne_prepare_inverse_operator | Prepare inverse operator data for calculating L2 | - | | minimum-norm solutions and dSPM. | - +--------------------------------+--------------------------------------------------------------+ - | mne_setup_toolbox | Set up the MNE Matlab toolbox. | - +--------------------------------+--------------------------------------------------------------+ - | mne_transform_coordinates | Transform locations between different coordinate systems. | - | | This function uses the output file from | - | | mne_collect_transforms described in | - | | :ref:`mne_collect_transforms` as input. | - +--------------------------------+--------------------------------------------------------------+ - | mne_transpose_named_matrix | Create a transpose of a named matrix. | - +--------------------------------+--------------------------------------------------------------+ - | mne_transform_source_space_to | Transform source space data to another coordinate frame. | - +--------------------------------+--------------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| -.. _BGBEFADJ: -.. table:: Examples demonstrating the use of the toolbox. - - +--------------------------------+--------------------------------------------------------------+ - | Function | Purpose | - +================================+==============================================================+ - | mne_ex_average_epochs | Example of averaging epoch data produced by mne_epochs2mat, | - | | see :ref:`mne_epochs2mat`. | - +--------------------------------+--------------------------------------------------------------+ - | mne_ex_cancel_noise | Example of noise cancellation procedures. | - +--------------------------------+--------------------------------------------------------------+ - | mne_ex_compute_inverse | Example of computing a L2 minimum-norm estimate or a dSPM | - | | solution. | - +--------------------------------+--------------------------------------------------------------+ - | mne_ex_data_sets | Example of listing evoked-response data sets. | - +--------------------------------+--------------------------------------------------------------+ - | mne_ex_evoked_grad_amp | Compute tangential gradient amplitudes from planar | - | | gradiometer data. | - +--------------------------------+--------------------------------------------------------------+ - | mne_ex_read_epochs | Read epoch data from a raw data file. | - +--------------------------------+--------------------------------------------------------------+ - | mne_ex_read_evoked | Example of reading evoked-response data. | - +--------------------------------+--------------------------------------------------------------+ - | mne_ex_read_raw | Example of reading raw data. | - +--------------------------------+--------------------------------------------------------------+ - | mne_ex_read_write_raw | Example of processing raw data (read and write). | - +--------------------------------+--------------------------------------------------------------+ - - -.. note:: In order for the inverse operator calculation to work correctly with data processed with the Elekta-Neuromag Maxfilter (TM) software, the so-called *processing history* block must be included in data files. Previous versions of the MNE Matlab functions did not copy processing history to files saved. As of March 30, 2009, the Matlab toolbox routines fiff_start_writing_raw and fiff_write_evoked have been enhanced to include these data to the output file as appropriate. If you have older raw data files created in Matlab from input which has been processed Maxfilter, it is necessary to copy the *processing history* block from the original to modified raw data file using the :ref:`mne_copy_processing_history` utility. The raw data processing programs mne_browse_raw and mne_process_raw have handled copying of the processing history since revision 2.5 of the MNE software. - -Some data structures -#################### - -The MNE Matlab toolbox relies heavily on structures to organize -the data. This section gives detailed information about fields in -the essential data structures employed in the MNE Matlab toolbox. -In the structure definitions, data types referring to other MNE -Matlab toolbox structures are shown in italics. In addition, :ref:`BGBJHCGD` -lists the values of various FIFF constants defined by fiff_define_constants.m . -The documented structures are: - -**tag** - - Contains one tag from the fif file, see :ref:`BGBGIIGD`. - -**taginfo** - - Contains the information about one tag, see :ref:`BGBBJBJJ`. - -**directory** - - Contains the tag directory as a tree structure, see :ref:`BGBEDHBG`. - -**id** - - A fif ID, see :ref:`BGBDAHHJ`. - -**named matrix** - - Contains a matrix with names for rows and/or columns, see :ref:`BGBBEDID`. - A named matrix is used to store, *e.g.*, SSP vectors and forward solutions. - -**trans** - - A 4 x 4 coordinate-transformation matrix operating on augmented column - vectors. Indication of the coordinate frames to which this transformation - relates is included, see :ref:`BGBDHBIF`. - -**dig** - - A Polhemus digitizer data point, see :ref:`BGBHDEDG`. - -**coildef** - - The coil definition structure useful for forward calculations and array - visualization, see :ref:`BGBGBEBH`. For more detailed information on - coil definitions, see :ref:`c_legacy_BJEIAEIE`. - -**ch** - - Channel information structure, see :ref:`BGBIABGD`. - -**proj** - - Signal-space projection data, see :ref:`BGBCJHJB`. - -**comp** - - Software gradiometer compensation data, see :ref:`BGBJDIFD`. - -**measurement info** - - Translation of the FIFFB_MEAS_INFO entity, see :ref:`BGBFHDIJ`. This - data structure is returned by fiff_read_meas_info . - -**surf** - - Used to represent triangulated surfaces and cortical source spaces, see :ref:`BGBEFJCB`. - -**cov** - - Used for storing covariance matrices, see :ref:`BGBJJIED`. - -**fwd** - - Forward solution data returned by mne_read_forward_solution , - see :ref:`BGBFJIBJ`. - -**inv** - - Inverse operator decomposition data returned by mne_read_inverse_operator , - see :ref:`BGBIEIJE`. For more information on inverse operator - decomposition, see :ref:`c_legacy_CBBDJFBJ`. For an example on how to - compute inverse solution using this data, see the sample routine mne_ex_compute_inverse . - -.. note:: The MNE Matlab toolbox tries it best to employ vertex numbering starting from 1 as opposed to 0 as recorded in the data files. There are, however, two exceptions where explicit attention to the vertex numbering convention is needed. First, the standard stc and w file reading and writing routines return and assume zero-based vertex numbering. There are now versions with names ending with '1', which return and assume one-based vertex numbering, see :ref:`BABBDDAI`. Second, the logno field of the channel information in the data files produced by mne_compute_raw_inverse is the zero-based number of the vertex whose source space signal is contained on this channel. - - -.. tabularcolumns:: |p{0.38\linewidth}|p{0.06\linewidth}|p{0.46\linewidth}| -.. _BGBJHCGD: -.. table:: FIFF constants. - - +-------------------------------+-------+----------------------------------------------------------+ - | Name | Value | Purpose | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MEG_CH | 1 | This is a MEG channel. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_REF_MEG_CH | 301 | This a reference MEG channel, located far away from the | - | | | head. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_EEF_CH | 2 | This is an EEG channel. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MCG_CH | 201 | This a MCG channel. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_STIM_CH | 3 | This is a digital trigger channel. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_EOG_CH | 202 | This is an EOG channel. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_EMG_CH | 302 | This is an EMG channel. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ECG_CH | 402 | This is an ECG channel. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MISC_CH | 502 | This is a miscellaneous analog channel. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_RESP_CH | 602 | This channel contains respiration monitor output. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_UNKNOWN | 0 | Unknown coordinate frame. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_DEVICE | 1 | The MEG device coordinate frame. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_ISOTRAK | 2 | The Polhemus digitizer coordinate frame (does not appear | - | | | in data files). | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_HPI | 3 | HPI coil coordinate frame (does not appear in data | - | | | files). | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_HEAD | 4 | The MEG head coordinate frame (Neuromag convention). | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_MRI | 5 | The MRI coordinate frame. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_MRI_SLICE | 6 | The coordinate frame of a single MRI slice. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_MRI_DISPLAY | 7 | The preferred coordinate frame for displaying the MRIs | - | | | (used by MRIlab). | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_DICOM_DEVICE | 8 | The DICOM coordinate frame (does not appear in files). | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_COORD_IMAGING_DEVICE | 9 | A generic imaging device coordinate frame (does not | - | | | appear in files). | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_COORD_TUFTS_EEG | 300 | The Tufts EEG data coordinate frame. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_COORD_CTF_DEVICE | 1001 | The CTF device coordinate frame (does not appear in | - | | | files). | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_COORD_CTF_HEAD | 1004 | The CTF/4D head coordinate frame. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ASPECT_AVERAGE | 100 | Data aspect: average. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ASPECT_STD_ERR | 101 | Data aspect: standard error of mean. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ASPECT_SINGLE | 102 | Single epoch. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ASPECT_SUBAVERAGE | 103 | One subaverage. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ASPECT_ALTAVERAGE | 104 | One alternating (plus-minus) subaverage. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ASPECT_SAMPLE | 105 | A sample cut from raw data. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ASPECT_POWER_DENSITY | 106 | Power density spectrum. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_ASPECT_DIPOLE_WAVE | 200 | The time course of an equivalent current dipole. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_BEM_SURF_ID_UNKNOWN | -1 | Unknown BEM surface. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_BEM_SURF_ID_BRAIN | 1 | The inner skull surface | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_BEM_SURF_ID_SKULL | 3 | The outer skull surface | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_BEM_SURF_ID_HEAD | 4 | The scalp surface | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_SURF_LEFT_HEMI | 101 | Left hemisphere cortical surface | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_SURF_RIGHT_HEMI | 102 | Right hemisphere cortical surface | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_POINT_CARDINAL | 1 | Digitization point which is a cardinal landmark aka. | - | | | fiducial point | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_POINT_HPI | 2 | Digitized HPI coil location | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_POINT_EEG | 3 | Digitized EEG electrode location | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_POINT_ECG | 3 | Digitized ECG electrode location | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_POINT_EXTRA | 4 | Additional head surface point | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_POINT_LPA | 1 | Identifier for left auricular landmark | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_POINT_NASION | 2 | Identifier for nasion | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_POINT_RPA | 3 | Identifier for right auricular landmark | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_FIXED_ORI | 1 | Fixed orientation constraint used in the computation of | - | | | a forward solution. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_FREE_ORI | 2 | No orientation constraint used in the computation of | - | | | a forward solution | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_MEG | 1 | Indicates an inverse operator based on MEG only | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_EEG | 2 | Indicates an inverse operator based on EEG only. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_MEG_EEG | 3 | Indicates an inverse operator based on both MEG and EEG. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_UNKNOWN_COV | 0 | An unknown covariance matrix | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_NOISE_COV | 1 | Indicates a noise covariance matrix. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_SENSOR_COV | 1 | Synonym for FIFFV_MNE_NOISE_COV | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_SOURCE_COV | 2 | Indicates a source covariance matrix | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_FMRI_PRIOR_COV | 3 | Indicates a covariance matrix associated with fMRI priors| - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_SIGNAL_COV | 4 | Indicates the data (signal + noise) covariance matrix | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_DEPTH_PRIOR_COV | 5 | Indicates the depth prior (depth weighting) covariance | - | | | matrix | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_MNE_ORIENT_PRIOR_COV | 6 | Indicates the orientation (loose orientation constrain) | - | | | prior covariance matrix | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_PROJ_ITEM_NONE | 0 | The nature of this projection item is unknown | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_PROJ_ITEM_FIELD | 1 | This is projection item is a generic field pattern or | - | | | field patters. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_PROJ_ITEM_DIP_FIX | 2 | This projection item is the field of one dipole | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_PROJ_ITEM_DIP_ROT | 3 | This projection item corresponds to the fields of three | - | | | or two orthogonal dipoles at some location. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_PROJ_ITEM_HOMOG_GRAD | 4 | This projection item contains the homogeneous gradient | - | | | fields as seen by the sensor array. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_PROJ_ITEM_HOMOG_FIELD | 5 | This projection item contains the three homogeneous field| - | | | components as seen by the sensor array. | - +-------------------------------+-------+----------------------------------------------------------+ - | FIFFV_PROJ_ITEM_EEG_AVREF | 10 | This projection item corresponds to the average EEG | - | | | reference. | - +-------------------------------+-------+----------------------------------------------------------+ - -.. _BGBGIIGD: - -.. table:: The tag structure. - - ======= =========== ============================================ - Field Data type Description - ======= =========== ============================================ - kind int32 The kind of the data item. - type uint32 The data type used to represent the data. - size int32 Size of the data in bytes. - next int32 Byte offset of the next tag in the file. - data various The data itself. - ======= =========== ============================================ - -.. _BGBBJBJJ: - -.. table:: The taginfo structure. - - ======= =========== ============================================ - Field Data type Description - ======= =========== ============================================ - kind double The kind of the data item. - type double The data type used to represent the data. - size double Size of the data in bytes. - pos double Byte offset to this tag in the file. - ======= =========== ============================================ - -.. _BGBEDHBG: - -.. table:: The directory structure. - - ============ ============ ================================================================ - Field Data type Description - ============ ============ ================================================================ - block double The block id of this directory node. - id id The unique identifier of this node. - parent_id id The unique identifier of the node this node was derived from. - nent double Number of entries in this node. - nchild double Number of children to this node. - dir taginfo Information about tags in this node. - children directory The children of this node. - ============ ============ ================================================================ - -.. _BGBDAHHJ: - -.. table:: The id structure. - - ========== =========== ============================================================ - Field Data type Description - ========== =========== ============================================================ - version int32 The fif file version (major < < 16 | minor). - machid int32(2) Unique identifier of the computer this id was created on. - secs int32 Time since January 1, 1970 (seconds). - usecs int32 Time since January 1, 1970 (microseconds past secs ). - ========== =========== ============================================================ - -.. _BGBBEDID: - -.. table:: The named matrix structure. - - ============ =========== ====================================================================== - Field Data type Description - ============ =========== ====================================================================== - nrow int32 Number of rows. - ncol int32 Number of columns. - row_names cell(*) The names of associated with the rows. This member may be empty. - col_names cell(*) The names of associated with the columns. This member may be empty. - data various The matrix data, usually of type single or double. - ============ =========== ====================================================================== - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBDHBIF: -.. table:: The trans structure. - - +---------------------------+-----------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===========================+===========+==========================================================+ - | from | int32 | The source coordinate frame, see :ref:`BGBJHCGD`. Look | - | | | for entries starting with FIFFV_COORD or FIFFV_MNE_COORD.| - +---------------------------+-----------+----------------------------------------------------------+ - | to | int32 | The destination coordinate frame. | - +---------------------------+-----------+----------------------------------------------------------+ - | trans |double(4,4)| The 4-by-4 coordinate transformation matrix. This | - | | | operates from augmented position column vectors given in | - | | | *from* coordinates to give results in *to* coordinates. | - +---------------------------+-----------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBHDEDG: -.. table:: The dig structure. - - +---------------------------+-----------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===========================+===========+==========================================================+ - | kind | int32 | The type of digitizing point. Possible values are listed | - | | | in :ref:`BGBJHCGD`. Look for entries starting with | - | | | FIFF_POINT. | - +---------------------------+-----------+----------------------------------------------------------+ - | ident | int32 | Identifier for this point. | - +---------------------------+-----------+----------------------------------------------------------+ - | r | single(3) | The location of this point. | - +---------------------------+-----------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBGBEBH: -.. table:: The coildef structure. For more detailed information, see :ref:`c_legacy_BJEIAEIE`. - - +-------------------+-------------------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===================+===================+==========================================================+ - | class | double | The coil (or electrode) class. | - +-------------------+-------------------+----------------------------------------------------------+ - | id | double | The coil (or electrode) id. | - +-------------------+-------------------+----------------------------------------------------------+ - | accuracy | double | Representation accuracy. | - +-------------------+-------------------+----------------------------------------------------------+ - | num_points | double | Number of integration points. | - +-------------------+-------------------+----------------------------------------------------------+ - | size | double | Coil size. | - +-------------------+-------------------+----------------------------------------------------------+ - | baseline | double | Coil baseline. | - +-------------------+-------------------+----------------------------------------------------------+ - | description | char(*) | Coil description. | - +-------------------+-------------------+----------------------------------------------------------+ - | coildefs | double | Each row contains the integration point weight, followed | - | | (num_points,7) | by location [m] and normal. | - +-------------------+-------------------+----------------------------------------------------------+ - | FV | struct | Contains the faces and vertices which can be used to | - | | | draw the coil for visualization. | - +-------------------+-------------------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBIABGD: -.. table:: The ch structure. - - +---------------------------+-----------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===========================+===========+==========================================================+ - | scanno | int32 | Scanning order number, starting from 1. | - +---------------------------+-----------+----------------------------------------------------------+ - | logno | int32 | Logical channel number, conventions in the usage of this | - | | | number vary. | - +---------------------------+-----------+----------------------------------------------------------+ - | kind | int32 | The channel type (FIFFV_MEG_CH, FIFF_EEG_CH, etc., see | - | | | :ref:`BGBJHCGD` ). | - +---------------------------+-----------+----------------------------------------------------------+ - | range | double | The hardware-oriented part of the calibration factor. | - | | | This should be only applied to the continuous raw data. | - +---------------------------+-----------+----------------------------------------------------------+ - | cal | double | The calibration factor to bring the channels to physical | - | | | units. | - +---------------------------+-----------+----------------------------------------------------------+ - | loc | double(12)| The channel location. The first three numbers indicate | - | | | the location [m], followed by the three unit vectors of | - | | | the channel-specific coordinate frame. These data contain| - | | | the values saved in the fif file and should not be | - | | | changed. The values are specified in device coordinates | - | | | for MEG and in head coordinates for EEG channels, | - | | | respectively. | - +---------------------------+-----------+----------------------------------------------------------+ - | coil_trans |double(4,4)| Initially, transformation from the channel coordinates | - | | | to device coordinates. This transformation is updated by | - | | | calls to fiff_transform_meg_chs and | - | | | fiff_transform_eeg_chs. | - +---------------------------+-----------+----------------------------------------------------------+ - | eeg_loc | double(6) | The location of the EEG electrode in coord_frame | - | | | coordinates. The first three values contain the location | - | | | of the electrode [m]. If six values are present, the | - | | | remaining ones indicate the location of the reference | - | | | electrode for this channel. | - +---------------------------+-----------+----------------------------------------------------------+ - | coord_frame | int32 | Initially, the coordinate frame is FIFFV_COORD_DEVICE | - | | | for MEG channels and FIFFV_COORD_HEAD for EEG channels. | - +---------------------------+-----------+----------------------------------------------------------+ - | unit | int32 | Unit of measurement. Relevant values are: 201 = T/m, | - | | | 112 = T, 107 = V, and 202 = Am. | - +---------------------------+-----------+----------------------------------------------------------+ - | unit_mul | int32 | The data are given in unit s multiplied by 10unit_mul. | - | | | Presently, unit_mul is always zero. | - +---------------------------+-----------+----------------------------------------------------------+ - | ch_name | char(*) | Name of the channel. | - +---------------------------+-----------+----------------------------------------------------------+ - | coil_def | coildef | The coil definition structure. This is present only if | - | | | mne_add_coil_defs has been successfully called. | - +---------------------------+-----------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBCJHJB: -.. table:: The proj structure. - - +---------------------------+-----------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===========================+===========+==========================================================+ - | kind | int32 | The type of the projection item. Possible values are | - | | | listed in :ref:`BGBJHCGD`. Look for entries starting | - | | | with FIFFV_PROJ_ITEM or FIFFV_MNE_PROJ_ITEM. | - +---------------------------+-----------+----------------------------------------------------------+ - | active | int32 | Is this item active, i.e., applied or about to be | - | | | applied to the data. | - +---------------------------+-----------+----------------------------------------------------------+ - | data | named | The projection vectors. The column names indicate the | - | | matrix | names of the channels associated to the elements of the | - | | | vectors. | - +---------------------------+-----------+----------------------------------------------------------+ - - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBJDIFD: -.. table:: The comp structure. - - +---------------------------+-----------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===========================+===========+==========================================================+ - | ctfkind | int32 | The kind of the compensation as stored in file. | - +---------------------------+-----------+----------------------------------------------------------+ - | kind | int32 | ctfkind mapped into small integer numbers. | - +---------------------------+-----------+----------------------------------------------------------+ - | save_calibrated | logical | Were the compensation data saved in calibrated form. If | - | | | this field is false, the matrix will be decalibrated | - | | | using the fields row_cals and col_cals when the | - | | | compensation data are saved by the toolbox. | - +---------------------------+-----------+----------------------------------------------------------+ - | row_cals | double(*) | Calibration factors applied to the rows of the | - | | | compensation data matrix when the data were read. | - +---------------------------+-----------+----------------------------------------------------------+ - | col_cals | double(*) | Calibration factors applied to the columns of the | - | | | compensation data matrix when the data were read. | - +---------------------------+-----------+----------------------------------------------------------+ - | data | named | The compensation data matrix. The row_names list the | - | | matrix | names of the channels to which this compensation applies | - | | | and the col_names the compensation channels. For more | - | | | information, see :ref:`BEHDDFBI`. | - +---------------------------+-----------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBFHDIJ: -.. table:: The meas info structure. - - +---------------------------+-----------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===========================+===========+==========================================================+ - | file_id | id | The fif ID of the measurement file. | - +---------------------------+-----------+----------------------------------------------------------+ - | meas_id | id | The ID assigned to this measurement by the acquisition | - | | | system or during file conversion. | - +---------------------------+-----------+----------------------------------------------------------+ - | nchan | int32 | Number of channels. | - +---------------------------+-----------+----------------------------------------------------------+ - | sfreq | double | Sampling frequency. | - +---------------------------+-----------+----------------------------------------------------------+ - | highpass | double | Highpass corner frequency [Hz]. Zero indicates a DC | - | | | recording. | - +---------------------------+-----------+----------------------------------------------------------+ - | lowpass | double | Lowpass corner frequency [Hz]. | - +---------------------------+-----------+----------------------------------------------------------+ - | chs | ch(nchan) | An array of channel information structures. | - +---------------------------+-----------+----------------------------------------------------------+ - | ch_names |cell(nchan)| Cell array of channel names. | - +---------------------------+-----------+----------------------------------------------------------+ - | dev_head_t | trans | The device to head transformation. | - +---------------------------+-----------+----------------------------------------------------------+ - | ctf_head_t | trans | The transformation from 4D/CTF head coordinates to | - | | | Neuromag head coordinates. This is only present in | - | | | 4D/CTF data. | - +---------------------------+-----------+----------------------------------------------------------+ - | dev_ctf_t | trans | The transformation from device coordinates to 4D/CTF | - | | | head coordinates. This is only present in 4D/CTF data. | - +---------------------------+-----------+----------------------------------------------------------+ - | dig | dig(*) | The Polhemus digitization data in head coordinates. | - +---------------------------+-----------+----------------------------------------------------------+ - | bads | cell(*) | Bad channel list. | - +---------------------------+-----------+----------------------------------------------------------+ - | projs | proj(*) | SSP operator data. | - +---------------------------+-----------+----------------------------------------------------------+ - | comps | comp(*) | Software gradient compensation data. | - +---------------------------+-----------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBEFJCB: - -.. table:: The surf structure. - - +---------------------------+-----------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===========================+===========+==========================================================+ - | id | int32 | The surface ID. | - +---------------------------+-----------+----------------------------------------------------------+ - | sigma | double | The electrical conductivity of the compartment bounded by| - | | | this surface. This field is present in BEM surfaces only.| - +---------------------------+-----------+----------------------------------------------------------+ - | np | int32 | Number of vertices on the surface. | - +---------------------------+-----------+----------------------------------------------------------+ - | ntri | int32 | Number of triangles on the surface. | - +---------------------------+-----------+----------------------------------------------------------+ - | coord_frame | int32 | Coordinate frame in which the locations and orientations | - | | | are expressed. | - +---------------------------+-----------+----------------------------------------------------------+ - | rr | double | The vertex locations. | - | | (np,3) | | - +---------------------------+-----------+----------------------------------------------------------+ - | nn | double | The vertex normals. If derived surface data was not | - | | (np,3) | requested, this is empty. | - +---------------------------+-----------+----------------------------------------------------------+ - | tris | int32 | Vertex numbers of the triangles in counterclockwise | - | | (ntri,3) | order as seen from the outside. | - +---------------------------+-----------+----------------------------------------------------------+ - | nuse | int32 | Number of active vertices, *i.e.*, vertices included in | - | | | a decimated source space. | - +---------------------------+-----------+----------------------------------------------------------+ - | inuse | int32(np) | Which vertices are in use. | - +---------------------------+-----------+----------------------------------------------------------+ - | vertno |int32(nuse)| Indices of the vertices in use. | - +---------------------------+-----------+----------------------------------------------------------+ - | curv | double(np)| Curvature values at the vertices. If curvature | - | | | information was not requested, this field is empty or | - | | | absent. | - +---------------------------+-----------+----------------------------------------------------------+ - | tri_area | double | The triangle areas in m2.If derived surface data was not | - | | (ntri) | requested, this field will be missing. | - +---------------------------+-----------+----------------------------------------------------------+ - | tri_cent | double | The triangle centroids. If derived surface data was not | - | | (ntri,3) | requested, this field will be missing. | - +---------------------------+-----------+----------------------------------------------------------+ - | tri_nn | double | The triangle normals. If derived surface data was not | - | | (ntri,3) | requested, this field will be missing. | - +---------------------------+-----------+----------------------------------------------------------+ - | nuse_tri | int32 | Number of triangles in use. This is present only if the | - | | | surface corresponds to a source space created with the | - | | | ``--ico`` option. | - +---------------------------+-----------+----------------------------------------------------------+ - | use_tris | int32 | The vertices of the triangles in use in the complete | - | | (nuse_tri)| triangulation. This is present only if the surface | - | | | corresponds to a source space created with the | - | | | ``--ico`` option. | - +---------------------------+-----------+----------------------------------------------------------+ - | nearest | int32(np) | This field is present only if patch information has been | - | | | computed for a source space. For each vertex in the | - | | | triangulation, these values indicate the nearest active | - | | | source space vertex. | - +---------------------------+-----------+----------------------------------------------------------+ - | nearest_dist | double(np)| This field is present only if patch information has been | - | | | computed for a source space. For each vertex in the | - | | | triangulation, these values indicate the distance to the | - | | | nearest active source space vertex. | - +---------------------------+-----------+----------------------------------------------------------+ - | dist | double | Distances between vertices on this surface given as a | - | | (np,np) | sparse matrix. A zero off-diagonal entry in this matrix | - | | | indicates that the corresponding distance has not been | - | | | calculated. | - +---------------------------+-----------+----------------------------------------------------------+ - | dist_limit | double | The value given to mne_add_patch_info with the ``--dist``| - | | | option, see :ref:`CJAGCDCC`. This value is presently | - | | | always negative, indicating that only distances between | - | | | active source space vertices, as indicated by the vertno | - | | | field of this structure, have been calculated. | - +---------------------------+-----------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBJJIED: - -.. table:: The cov structure. - - +---------------------------+-----------+----------------------------------------------------------+ - | Field | Data Type | Description | - +===========================+===========+==========================================================+ - | kind | double | What kind of a covariance matrix (1 = noise covariance, | - | | | 2 = source covariance). | - +---------------------------+-----------+----------------------------------------------------------+ - | diag | double | Is this a diagonal matrix. | - +---------------------------+-----------+----------------------------------------------------------+ - | dim | int32 | Dimension of the covariance matrix. | - +---------------------------+-----------+----------------------------------------------------------+ - | names | cell(*) | Names of the channels associated with the entries | - | | | (may be empty). | - +---------------------------+-----------+----------------------------------------------------------+ - | data | double | The covariance matrix. This a double(dim) vector for a | - | | (dim,dim) | diagonal covariance matrix. | - +---------------------------+-----------+----------------------------------------------------------+ - | projs | proj(*) | The SSP vectors applied to these data. | - +---------------------------+-----------+----------------------------------------------------------+ - | bads | cell(*) | Bad channel names. | - +---------------------------+-----------+----------------------------------------------------------+ - | nfree | int32 | Number of data points used to compute this matrix. | - +---------------------------+-----------+----------------------------------------------------------+ - | eig |double(dim)| The eigenvalues of the covariance matrix. This field may | - | | | be empty for a diagonal covariance matrix. | - +---------------------------+-----------+----------------------------------------------------------+ - | eigvec | double | The eigenvectors of the covariance matrix. | - | | (dim,dim) | | - +---------------------------+-----------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBFJIBJ: - -.. table:: The fwd structure. - - +-------------------------+-------------+----------------------------------------------------------+ - | Field | Data Type | Description | - +=========================+=============+==========================================================+ - | source_ori | int32 | Has the solution been computed for the current component | - | | | normal to the cortex only (1) or all three source | - | | | orientations (2). | - +-------------------------+-------------+----------------------------------------------------------+ - | coord_frame | int32 | Coordinate frame in which the locations and orientations | - | | | are expressed. | - +-------------------------+-------------+----------------------------------------------------------+ - | nsource | int32 | Total number of source space points. | - +-------------------------+-------------+----------------------------------------------------------+ - | nchan | int32 | Number of channels. | - +-------------------------+-------------+----------------------------------------------------------+ - | sol | named | The forward solution matrix. | - | | matrix | | - +-------------------------+-------------+----------------------------------------------------------+ - | sol_grad | named | The derivatives of the forward solution with respect to | - | | matrix | the dipole location coordinates, see | - | | | :ref:`c_legacy_BJEFEJJG`. | - | | | This field is present only if the forward solution was | - | | | computed with the ``--grad`` option, see | - | | | :ref:`mne_forward_solution`. | - +-------------------------+-------------+----------------------------------------------------------+ - | mri_head_t | trans | Transformation from the MRI coordinate frame to the | - | | | (Neuromag) head coordinate frame. | - +-------------------------+-------------+----------------------------------------------------------+ - | src | surf(:) | The description of the source spaces. | - +-------------------------+-------------+----------------------------------------------------------+ - | source_rr | double | The source locations. | - | | (nsource,3) | | - +-------------------------+-------------+----------------------------------------------------------+ - | source_nn | double(:,3) | The source orientations. Number of rows is either | - | | | nsource (fixed source orientations) or 3*nsource | - | | | (all source orientations). | - +-------------------------+-------------+----------------------------------------------------------+ - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| -.. _BGBIEIJE: - -.. table:: The inv structure. Note: The fields proj, whitener, reginv, and noisenorm are filled in by the routine mne_prepare_inverse_operator. - - +---------------------+-------------+----------------------------------------------------------+ - | Field | Data Type | Description | - +=====================+=============+==========================================================+ - | methods | int32 | Has the solution been computed using MEG data (1), EEG | - | | | data (2), or both (3). | - +---------------------+-------------+----------------------------------------------------------+ - | source_ori | int32 | Has the solution been computed for the current component | - | | | normal to the cortex only (1) or all three source | - | | | orientations (2). | - +---------------------+-------------+----------------------------------------------------------+ - | nsource | int32 | Total number of source space points. | - +---------------------+-------------+----------------------------------------------------------+ - | nchan | int32 | Number of channels. | - +---------------------+-------------+----------------------------------------------------------+ - | coord_frame | int32 | Coordinate frame in which the locations and orientations | - | | | are expressed. | - +---------------------+-------------+----------------------------------------------------------+ - | source_nn | double(:,3) | The source orientations. Number of rows is either | - | | | nsource (fixed source orientations) or 3*nsource (all | - | | | source orientations). | - +---------------------+-------------+----------------------------------------------------------+ - | sing | double | The singular values, *i.e.*, the diagonal values of | - | | (nchan) | :math:`\Lambda`, see :ref:`mne_solution`. | - +---------------------+-------------+----------------------------------------------------------+ - | eigen_leads | double | The matrix :math:`V`, see :ref:`mne_solution`. | - | | (:,nchan) | | - +---------------------+-------------+----------------------------------------------------------+ - | eigen_fields | double | The matrix :math:`U^T`, see :ref:`mne_solution`. | - | | (nchan, | | - | | nchan) | | - +---------------------+-------------+----------------------------------------------------------+ - | noise_cov | cov | The noise covariance matrix :math:`C`. | - +---------------------+-------------+----------------------------------------------------------+ - | source_cov | cov | The source covariance matrix :math:`R`. | - +---------------------+-------------+----------------------------------------------------------+ - | src | surf(:) | The description of the source spaces. | - +---------------------+-------------+----------------------------------------------------------+ - | mri_head_t | trans | Transformation from the MRI coordinate frame to the | - | | | (Neuromag) head coordinate frame. | - +---------------------+-------------+----------------------------------------------------------+ - | nave | double | The number of averages. | - +---------------------+-------------+----------------------------------------------------------+ - | projs | proj(:) | The SSP vectors which were active when the decomposition | - | | | was computed. | - +---------------------+-------------+----------------------------------------------------------+ - | proj | double | The projection operator computed using projs. | - | | (nchan) | | - +---------------------+-------------+----------------------------------------------------------+ - | whitener | | A sparse matrix containing the noise normalization | - | | | factors. Dimension is either nsource (fixed source | - | | | orientations) or 3*nsource (all source orientations). | - +---------------------+-------------+----------------------------------------------------------+ - | reginv | double | The diagonal matrix :math:`\Gamma`, see | - | | (nchan) | :ref:`mne_solution`. | - +---------------------+-------------+----------------------------------------------------------+ - | noisenorm | double(:) | A sparse matrix containing the noise normalization | - | | | factors. Dimension is either nsource (fixed source | - | | | orientations) or 3*nsource (all source orientations). | - +---------------------+-------------+----------------------------------------------------------+ - - -On-line documentation for individual routines -############################################# - -Each of the routines listed in Tables :ref:`BGBCGHAG` - :ref:`BGBEFADJ` has on-line documentation accessible by saying ``help`` <*routine name*> in Matlab. diff -Nru python-mne-0.18.1+dfsg/doc/manual/memory.rst python-mne-0.19.1+dfsg/doc/manual/memory.rst --- python-mne-0.18.1+dfsg/doc/manual/memory.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/memory.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,54 +0,0 @@ - -.. contents:: Contents - :local: - :depth: 3 - -.. _memory: - -Memory-efficient IO -################### - -Preloading -========== - -Raw -^^^ -MNE-Python can read data on-demand using the ``preload`` option provided in :ref:`IO functions `. For example:: - - from mne import io - from mne.datasets import sample - data_path = sample.data_path() - raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif' - raw = io.read_raw_fif(raw_fname, preload=False) - -.. note:: Filtering, resampling and dropping or selecting channels does not work with ``preload=False``. - -Epochs -^^^^^^ -Similarly, epochs can also be be read from disk on-demand. For example:: - - import mne - events = mne.find_events(raw) - event_id, tmin, tmax = 1, -0.2, 0.5 - picks = mne.pick_types(raw.info, meg=True, eeg=True, stim=False, eog=True) - epochs = mne.Epochs(raw, events, event_id, tmin, tmax, picks=picks, baseline=(None, 0), reject=dict(eeg=80e-6, eog=150e-6), - preload=False) - -When ``preload=False``, the epochs data is loaded from the disk on-demand. Note that ``preload=False`` for epochs will work even if the ``raw`` object -has been loaded with ``preload=True``. Preloading is also supported for :func:`mne.read_epochs`. - -.. warning:: This comes with a caveat. When ``preload=False``, data rejection based on peak-to-peak thresholds is executed when the data is loaded from disk, *not* when the ``Epochs`` object is created. - -To explicitly reject artifacts with ``preload=False``, use the function :func:`mne.Epochs.drop_bad`. - -Loading data explicitly -======================= -To load the data if ``preload=False`` was initially selected, use the functions :func:`mne.io.Raw.load_data` and :func:`mne.Epochs.load_data`. - -Simplest way to access data -=========================== -If you just want your raw data as a numpy array to work with it in a different framework you can use slicing syntax:: - - first_channel_data, times = raw[0, :] - channel_3_5, times_3_5 = raw[3:5, :] - diff -Nru python-mne-0.18.1+dfsg/doc/manual/migrating.rst python-mne-0.19.1+dfsg/doc/manual/migrating.rst --- python-mne-0.18.1+dfsg/doc/manual/migrating.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/migrating.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,56 +0,0 @@ -.. _migrating: - -Migrating from EEGLAB -===================== - -To read in data exported from EEGLAB, MNE offers an EDF reader :func:`mne.io.read_raw_edf` and a ``set`` file reader. -To read in `set` files containing ``raw`` data, use :func:`mne.io.read_raw_eeglab` and to read in ``set`` files containing -``epochs`` data, use :func:`mne.read_epochs_eeglab`. - -Here is a cheatsheet to help users migrate painlessly from EEGLAB. For the sake of clarity, let us assume -that the following are already defined or known: the file name ``fname``, time interval of the epochs ``tmin`` and ``tmax``, -and the conditions ``cond1`` and ``cond2``. The variables ``l_freq`` and ``h_freq`` are the frequencies (in Hz) below which -and above which to filter out data. - -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| Processing step | EEGLAB function | MNE | -+===================+==============================================================+================================================================================================+ -| Get started | | addpath(...); | | import mne | -| | | eeglab; | | from mne import io, :class:`Epochs ` | -| | | | from mne.preprocessing import :class:`ICA ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| Import data | EEG = pop_fileio(fname); | | :func:`raw = io.read_raw_fif(fname) ` | -| | | | :func:`raw = io.read_raw_edf(fname) ` | -| | | | :func:`raw = io.read_raw_eeglab(fname) ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| Filter data | EEG = pop_eegfiltnew(EEG, l_freq, h_freq); | :func:`raw.filter(l_freq, h_freq) ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| Run ICA | EEG = pop_runica(EEG); | :func:`ica.fit(raw) ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| Epoch data | | event_id = {'cond1', 'cond2'}; | | :func:`events = mne.find_events(raw) ` | -| | | Epochs = pop_epochs(EEG, event_id, [tmin, tmax]); | | :py:class:`event_id = dict(cond1=32, cond2=64) ` | -| | | | | :class:`epochs = Epochs(raw, events, event_id, tmin, tmax) ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| Selecting epochs | Epochs = pop_epochs(EEG_epochs, {cond2}); | :class:`epochs[cond2] ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| ERP butterfly plot| pop_timtopo(EEG_epochs, ...); | | :func:`evoked.plot() ` | -| | | | :func:`evoked.plot_joint() ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| Contrast ERPs | pop_compareerps(EEG_epochs1, EEG_epochs2); | | :func:`mne.combine_evoked([evoked1, -evoked2], weights='equal').plot() ` | -| | | | :func:`mne.viz.plot_compare_evokeds([evoked1, evoked2]) ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ -| Save data | EEG = pop_saveset(EEG, fname); | | :func:`raw.save(fname) ` | -| | | | :func:`epochs.save(fname) ` | -| | | | :func:`evoked.save(fname) ` | -+-------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------+ - -Note that MNE has functions to read a variety of file formats, not just :func:`mne.io.Raw`. The interested user is directed to the :ref:`IO documentation `. - -Pitfalls --------- - -* Python methods often operate in-place. This means the object the method is called on is modified in-place (e.g., see the filter example above). - This can be confusing to new users migrating from Matlab. However, it is also possible to ask MNE functions not to modify the input. - To do this, call the ``copy`` method of the object (.e.g, use :func:`raw_filtered = raw.copy().filter(l_freq, h_freq) `). -* The concept of channel types is critical in MNE because it supports analysis of multimodal data (e.g., EEG, MEG, EOG, Stim channel) - whereas most EEGLAB functions assume the same channel type (EEG). Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/CoordinateSystems.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/CoordinateSystems.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/cover.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/cover.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/Digitizer-example.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/Digitizer-example.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/flat.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/flat.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/Flowchart.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/Flowchart.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/HeadCS.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/HeadCS.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/ICA_primer.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/ICA_primer.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/morphed.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/morphed.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/neuromag.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/neuromag.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/orig.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/orig.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/proj-off-on.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/proj-off-on.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/manual/pics/title_page.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/manual/pics/title_page.png differ diff -Nru python-mne-0.18.1+dfsg/doc/manual/preprocessing/bads.rst python-mne-0.19.1+dfsg/doc/manual/preprocessing/bads.rst --- python-mne-0.18.1+dfsg/doc/manual/preprocessing/bads.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/preprocessing/bads.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,5 +0,0 @@ -:orphan: - -============ -Bad channels -============ diff -Nru python-mne-0.18.1+dfsg/doc/manual/preprocessing/ica.rst python-mne-0.19.1+dfsg/doc/manual/preprocessing/ica.rst --- python-mne-0.18.1+dfsg/doc/manual/preprocessing/ica.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/preprocessing/ica.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,118 +0,0 @@ -.. _ica: - -Independent Component Analysis (ICA) -#################################### - -.. contents:: Contents - :local: - :depth: 2 - -Many M/EEG signals including biological artifacts reflect non-Gaussian -processes. Therefore PCA-based artifact rejection will likely perform worse at -separating the signal from noise sources. -MNE-Python supports identifying artifacts and latent components using temporal ICA. -MNE-Python implements the :class:`mne.preprocessing.ICA` class that facilitates applying ICA -to MEG and EEG data. It supports FastICA, the infomax, and the extended informax algorithm. -It allows whitening the data using a fast randomized PCA algorithmd. Furthermore, -multiple sensor types are supported by pre-whitening / rescaling. Bad data segments can be excluded -from the model fitting by `reject` parameter in :class:`mne.preprocessing.ICA.fit`. - -For convenience, :class:`mne.preprocessing.ICA` implements methods for - - automated detection of ECG and EOG artifacts - - :meth:`mne.preprocessing.ICA.find_bads_ecg` - - :meth:`mne.preprocessing.ICA.find_bads_eog` - - visualization - - :meth:`mne.preprocessing.ICA.plot_components` for mapping the spatial sensitvity of a comopnent - - :meth:`mne.preprocessing.ICA.plot_sources` for component related time series - - :meth:`mne.preprocessing.ICA.plot_scores` for scores on which component detection is based upon - - :meth:`mne.preprocessing.ICA.plot_overlay` for showing differences between raw and processed data - - persistence - :meth:`mne.preprocessing.ICA.save` for writing the ICA solution into a fif file. - - integration with MNE-Python object system - :meth:`mne.preprocessing.ICA.get_sources` for putting component related time series in MNE data structures. - -Concepts -======== - -ICA finds directions in the feature space corresponding to projections with high non-Gaussianity. - -- not necessarily orthogonal in the original feature space, but orthogonal in the whitened feature space. -- In contrast, PCA finds orthogonal directions in the raw feature - space that correspond to directions accounting for maximum variance. -- or differently, if data only reflect Gaussian processes ICA and PCA are equivalent. - - -**Example**: Imagine 3 instruments playing simultaneously and 3 microphones -recording mixed signals. ICA can be used to recover the sources ie. what is played by each instrument. - -ICA employs a very simple model: $X = AS$ where $X$ is our observations, $A$ is the mixing matrix and $S$ is the vector of independent (latent) sources. - -The challenge is to recover A and S from X. - - -First generate simulated data ------------------------------ - -.. code:: python - - import numpy as np - import matplotlib.pyplot as plt - from scipy import signal - - from sklearn.decomposition import FastICA, PCA - - np.random.seed(0) # set seed for reproducible results - n_samples = 2000 - time = np.linspace(0, 8, n_samples) - - s1 = np.sin(2 * time) # Signal 1 : sinusoidal signal - s2 = np.sign(np.sin(3 * time)) # Signal 2 : square signal - s3 = signal.sawtooth(2 * np.pi * time) # Signal 3: sawtooth signal - - S = np.c_[s1, s2, s3] - S += 0.2 * np.random.normal(size=S.shape) # Add noise - - S /= S.std(axis=0) # Standardize data - # Mix data - A = np.array([[1, 1, 1], [0.5, 2, 1.0], [1.5, 1.0, 2.0]]) # Mixing matrix - X = np.dot(S, A.T) # Generate observations - -Now try to recover the sources ------------------------------- - -.. code:: python - - # compute ICA - ica = FastICA(n_components=3) - S_ = ica.fit_transform(X) # Get the estimated sources - A_ = ica.mixing_ # Get estimated mixing matrix - - # compute PCA - pca = PCA(n_components=3) - H = pca.fit_transform(X) # estimate PCA sources - - plt.figure(figsize=(9, 6)) - - models = [X, S, S_, H] - names = ['Observations (mixed signal)', - 'True Sources', - 'ICA estimated sources', - 'PCA estimated sources'] - colors = ['red', 'steelblue', 'orange'] - - for ii, (model, name) in enumerate(zip(models, names), 1): - plt.subplot(4, 1, ii) - plt.title(name) - for sig, color in zip(model.T, colors): - plt.plot(sig, color=color) - - plt.tight_layout() - plt.show() - - - -.. image:: ../pics/ICA_primer.png - - -:math:`\rightarrow` PCA fails at recovering our "instruments" since the -related signals reflect non-Gaussian processes. diff -Nru python-mne-0.18.1+dfsg/doc/manual/preprocessing/maxwell.rst python-mne-0.19.1+dfsg/doc/manual/preprocessing/maxwell.rst --- python-mne-0.18.1+dfsg/doc/manual/preprocessing/maxwell.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/preprocessing/maxwell.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,76 +0,0 @@ -.. _maxwell: - -Maxwell filtering -################# - -.. contents:: Contents - :local: - :depth: 2 - -Maxwell filtering in mne-python can be used to suppress sources of external -interference and compensate for subject head movements. - -About Maxwell filtering ------------------------ -The principles behind Maxwell filtering are covered in relevant references -[1]_ [2]_ as well as the Elekta MaxFilter manual; see those materials -for basic principles and algorithm descriptions. - -In mne-python Maxwell filtering of raw data can be done using the -:func:`mne.preprocessing.maxwell_filter` function. - -.. warning:: Automatic bad channel detection is not currently implemented. - It is critical to mark bad channels before running Maxwell - filtering, so data should be inspected and marked accordingly - prior to running this algorithm. - -Our Maxwell filtering algorithm currently provides multiple features, -including: - - * Bad channel reconstruction - * Cross-talk cancellation - * Fine calibration correction - * tSSS - * Coordinate frame translation - * Regularization of internal components using information theory - * Raw movement compensation - (using head positions estimated by MaxFilter) - * cHPI subtraction (see :func:`mne.chpi.filter_chpi`) - * Handling of 3D (in addition to 1D) fine calibration files - * Epoch-based movement compensation as described in [1]_ through - :func:`mne.epochs.average_movements` - * **Experimental** processing of data from (un-compensated) - non-Elekta systems - -Movement compensation ---------------------- -When subject head movements are recorded continuously using continuous HPI -(cHPI) and subjects are expected to move during the recording (e.g., when -recording data in children), movement compensation can be performed to -correct for head movements. Movement compensation can be performed two ways: - -1. Raw movement compensation: :func:`mne.preprocessing.maxwell_filter` using - the ``pos`` argument. - -2. Evoked movement compensation: :func:`mne.epochs.average_movements`. - -Each of these requires time-varying estimates of head positions, which can -currently be obtained from MaxFilter using the ``-headpos`` and ``-hp`` -arguments (see the MaxFilter manual for details). The resulting -MaxFilter-style head position information can be read using -:func:`mne.chpi.read_head_pos` and passed to mne-python's movement -compensation algorithms. - -References ----------- -.. [1] Taulu S. and Kajola M. "Presentation of electromagnetic - multichannel data: The signal space separation method," - Journal of Applied Physics, vol. 97, pp. 124905 1-10, 2005. - - http://lib.tkk.fi/Diss/2008/isbn9789512295654/article2.pdf - -.. [2] Taulu S. and Simola J. "Spatiotemporal signal space separation - method for rejecting nearby interference in MEG measurements," - Physics in Medicine and Biology, vol. 51, pp. 1759-1768, 2006. - - http://lib.tkk.fi/Diss/2008/isbn9789512295654/article3.pdf diff -Nru python-mne-0.18.1+dfsg/doc/manual/preprocessing/overview.rst python-mne-0.19.1+dfsg/doc/manual/preprocessing/overview.rst --- python-mne-0.18.1+dfsg/doc/manual/preprocessing/overview.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/preprocessing/overview.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,5 +0,0 @@ -:orphan: - -======== -Overview -======== diff -Nru python-mne-0.18.1+dfsg/doc/manual/preprocessing/ssp.rst python-mne-0.19.1+dfsg/doc/manual/preprocessing/ssp.rst --- python-mne-0.18.1+dfsg/doc/manual/preprocessing/ssp.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/preprocessing/ssp.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,199 +0,0 @@ -.. _ssp: - -Signal-Space Projection (SSP) -############################# - -.. contents:: Contents - :local: - :depth: 3 - -The SSP method -============== - -The Signal-Space Projection (SSP) is one approach to rejection -of external disturbances in software. Unlike many other noise-cancellation -approaches, SSP does not require additional reference sensors to record the disturbance -fields. Instead, SSP relies on the fact that the magnetic field -distributions generated by the sources in the brain have spatial -distributions sufficiently different from those generated by external -noise sources. Furthermore, it is implicitly assumed that the linear -space spanned by the significant external noise patters has a low -dimension. - -What is SSP? ------------- - -Without loss of generality we can always decompose any :math:`n`-channel -measurement :math:`b(t)` into its signal and -noise components as - -.. math:: b(t) = b_s(t) + b_n(t) - :label: additive_model - -Further, if we know that :math:`b_n(t)` is -well characterized by a few field patterns :math:`b_1 \dotso b_m`, -we can express the disturbance as - -.. math:: b_n(t) = Uc_n(t) + e(t)\ , - :label: pca - -where the columns of :math:`U` constitute -an orthonormal basis for :math:`b_1 \dotso b_m`, :math:`c_n(t)` is -an :math:`m`-component column vector, and -the error term :math:`e(t)` is small and does -not exhibit any consistent spatial distributions over time, *i.e.*, :math:`C_e = E \{e e^T\} = I`. -Subsequently, we will call the column space of :math:`U` the -noise subspace. The basic idea of SSP is that we can actually find -a small basis set :math:`b_1 \dotso b_m` such that the -conditions described above are satisfied. We can now construct the -orthogonal complement operator - -.. math:: P_{\perp} = I - UU^T - :label: projector - -and apply it to :math:`b(t)` in Equation :eq:`additive_model` yielding - -.. math:: b_{s}(t) \approx P_{\perp}b(t)\ , - :label: result - -since :math:`P_{\perp}b_n(t) = P_{\perp}(Uc_n(t) + e(t)) \approx 0` and :math:`P_{\perp}b_{s}(t) \approx b_{s}(t)`. The projection operator :math:`P_{\perp}` is -called the **signal-space projection operator**. - -Why SSP? --------- - -It provides considerable rejection of noise, suppressing external disturbances -by a factor of 10 or more. The effectiveness of SSP depends on two -factors: - -- The basis set :math:`b_1 \dotso b_m` should - be able to characterize the disturbance field patterns completely - and - -- The angles between the noise subspace space spanned by :math:`b_1 \dotso b_m` and the - signal vectors :math:`b_s(t)` should be as close - to :math:`\pi / 2` as possible. - -If the first requirement is not satisfied, some noise will -leak through because :math:`P_{\perp}b_n(t) \neq 0`. If the any -of the brain signal vectors :math:`b_s(t)` is -close to the noise subspace not only the noise but also the signal -will be attenuated by the application of :math:`P_{\perp}` and, -consequently, there might by little gain in signal-to-noise ratio. -:ref:`CACFGIEC` demonstrates the effect of SSP on the Vectorview -magnetometer data. After the elimination of a three-dimensional -noise subspace, the absolute value of the noise is dampened approximately -by a factor of 10 and the covariance matrix becomes diagonally dominant. - -Since the signal-space projection modifies the signal vectors -originating in the brain, it is necessary to apply the projection -to the forward solution in the course of inverse computations. This -is accomplished by mne_inverse_operator as -described in :ref:`inverse_operator`. For more information on SSP, -please consult the references listed in :ref:`CEGIEEBB`. - -.. _CACFGIEC: - -.. figure:: ../pics/proj-off-on.png - :alt: example of the effect of SSP - :align: center - - An example of the effect of SSP - - The covariance matrix :math:`C_n` of noise data on the 102 Vectorview magnetometers was computed (a) before and (b) after the application of SSP with three-dimensional noise subspace. The plotted quantity is :math:`\sqrt {|(C_n)_{jk}|}`. Note that the vertical scale in (b) is ten times smaller than in (a). - -.. _BABFFCHF: - -Estimation of the noise subspace --------------------------------- - -As described above, application of SSP requires the estimation -of the signal vectors :math:`b_1 \dotso b_m` constituting -the noise subspace. The most common approach, also implemented in mne_browse_raw is -to compute a covariance matrix of empty room data, compute its eigenvalue -decomposition, and employ the eigenvectors corresponding to the -highest eigenvalues as basis for the noise subspace. It is also -customary to use a separate set of vectors for magnetometers and -gradiometers in the Vectorview system. - -Average reference ------------------ - -The EEG average reference is the mean signal over all the sensors. It is typical in EEG analysis to subtract the average reference from all the sensor signals :math:`b^{1}(t), ..., b^{n}(t)`. That is: - -.. math:: {b}^{j}_{s}(t) = b^{j}(t) - \frac{1}{n}\sum_{k}{b^k(t)} - :label: eeg_proj - -where the noise term :math:`b_{n}^{j}(t)` is given by - -.. math:: b_{n}^{j}(t) = \frac{1}{n}\sum_{k}{b^k(t)} - :label: noise_term - -Thus, the projector vector :math:`P_{\perp}` will be given by :math:`P_{\perp}=\frac{1}{n}[1, 1, ..., 1]` - -.. Warning:: When applying SSP, the signal of interest can also be sometimes removed. Therefore, it's always a good idea to check how much the effect of interest is reduced by applying SSP. SSP might remove *both* the artifact and signal of interest. - -The API -======= - -Once a projector is applied on the data, it is said to be `active`. - -The proj attribute ------------------- - -It is available in all the basic data containers: ``Raw``, ``Epochs`` and ``Evoked``. It is ``True`` if at least one projector is present and all of them are `active`. - -Computing projectors --------------------- - -In MNE-Python SSP vectors can be computed using general -purpose functions :func:`mne.compute_proj_epochs`, -:func:`mne.compute_proj_evoked`, and :func:`mne.compute_proj_raw`. -The general assumption these functions make is that the data passed contains -raw, epochs or averages of the artifact. Typically this involves continues raw -data of empty room recordings or averaged ECG or EOG artifacts. - -A second set of highlevel convenience functions is provided to compute projection vector for typical usecases. This includes :func:`mne.preprocessing.compute_proj_ecg` and :func:`mne.preprocessing.compute_proj_eog` for computing the ECG and EOG related artifact components, respectively. For computing the EEG reference signal, the function :func:`mne.set_eeg_reference` can be used. - -.. warning:: It is best to compute projectors only on channels that will be - used (e.g., excluding bad channels). This ensures that - projection vectors will remain ortho-normalized and that they - properly capture the activity of interest. - -.. _remove_projector: - -Adding/removing projectors --------------------------- - -To explicitly add a ``proj``, use ``add_proj``. For example:: - - >>> projs = mne.read_proj('proj_a.fif') # doctest: +SKIP - >>> evoked.add_proj(projs) # doctest: +SKIP - -If projectors are already present in the raw `fif` file, it will be added to the ``info`` dictionary automatically. To remove existing projectors, you can do:: - - >>> evoked.add_proj([], remove_existing=True) # doctest: +SKIP - -Applying projectors -------------------- - -Projectors can be applied at any stage of the pipeline. When the ``raw`` data is read in, the projectors are not applied by default but this flag can be turned on. However, at the ``epochs`` stage, the projectors are applied by default. - -To apply explicitly projs at any stage of the pipeline, use ``apply_proj``. For example:: - - >>> evoked.apply_proj() # doctest: +SKIP - -The projectors might not be applied if data are not :ref:`preloaded `. In this case, it's the ``_projector`` attribute that indicates if a projector will be applied when the data is loaded in memory. If the data is already in memory, then the projectors applied to it are the ones marked as `active`. As soon as you've applied the projectors, it will stay active in the remaining pipeline. - -.. Warning:: Once a projection operator is applied, it cannot be reversed. -.. Warning:: Projections present in the info are applied during inverse computation whether or not they are `active`. Therefore, if a certain projection should not be applied, remove it from the info as described in Section :ref:`remove_projector` - -Delayed projectors ------------------- - -The suggested pipeline is ``proj=True`` in epochs (it's computationally cheaper than for raw). When you use delayed SSP in ``Epochs``, projectors are applied when you call :func:`mne.Epochs.get_data` method. They are not applied to the ``evoked`` data unless you call ``apply_proj()``. The reason is that you want to reject epochs with projectors although it's not stored in the projector mode. - -.. topic:: Examples: - - * :ref:`tut-artifact-ssp`: SSP sensitivities in sensor space - * :ref:`ex-sensitivity-maps`: SSP sensitivities in source space diff -Nru python-mne-0.18.1+dfsg/doc/manual/sample_dataset.rst python-mne-0.19.1+dfsg/doc/manual/sample_dataset.rst --- python-mne-0.18.1+dfsg/doc/manual/sample_dataset.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/sample_dataset.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,708 +0,0 @@ -:orphan: - -.. _ch_sample_data: - -=================== -The sample data set -=================== - -.. contents:: Contents - :local: - :depth: 2 - -Purpose -####### - -This Chapter gives a detailed description of the processing -of a sample data set, which can be employed to familiarize with -the workflow described in :ref:`cookbook`. - -.. note:: Going through the analysis exercise in this chapter is not a substitute for reading other chapters of this manual and understanding the concepts underlying MNE software. - -.. _sample_data_overview: - -Overview -######## - -The MNE software is accompanied by a sample data set which -includes the MRI reconstructions created with FreeSurfer and the -an MEG/EEG data set. These data were acquired with the Neuromag -Vectorview system at MGH/HMS/MIT Athinoula A. Martinos Center Biomedical -Imaging. EEG data from a 60-channel electrode cap was acquired simultaneously with -the MEG. The original MRI data set was acquired with a Siemens 1.5 T -Sonata scanner using an MPRAGE sequence. - -.. note:: These data are provided solely for the purpose of getting familiar - with the MNE software. They should not be redistributed to third - parties. The data should not be used to evaluate the performance - of the MEG or MRI system employed. - -In the MEG/EEG experiment, checkerboard patterns were presented -into the left and right visual field, interspersed by tones to the -left or right ear. The interval between the stimuli was 750 ms. Occasionally -a smiley face was presented at the center of the visual field. -The subject was asked to press a key with the right index finger -as soon as possible after the appearance of the face. A listing -of the corresponding trigger codes is provided in :ref:`BABDHIFJ` - -.. _BABDHIFJ: - -.. table:: Trigger codes for the sample data set. - - ========= ===== ========================================== - Name #Contents - ========= ===== ========================================== - LA 1 Response to left-ear auditory stimulus - RA 2 Response to right-ear auditory stimulus - LV 3 Response to left visual field stimulus - RV 4 Response to right visual field stimulus - smiley 5 Response to the smiley face - button 32 Response triggered by the button press - ========= ===== ========================================== - -Setting up -########## - -The sample dataset can be downloaded automatically by doing:: - - >>> mne.datasets.sample.data_path(verbose=True) # doctest: +SKIP - -Contents of the data set -######################## - -The sample data set contains two main directories: ``MEG/sample`` (the MEG/EEG -data) and ``subjects/sample`` (the MRI reconstructions). -An overview of the data provided is given in Tables :ref:`CHDDDIHE` and :ref:`CHDDEGGC`. In addition to -subject sample , the MRI surface -reconstructions from another subject, morph , -are provided to demonstrate the morphing capabilities of the MNE software. - -.. _CHDDDIHE: - -.. table:: Contents of the MEG/sample directory. - - ======================== ===================================================================== - File Contents - ======================== ===================================================================== - sample/audvis_raw.fif The raw MEG/EEG data - audvis.ave A template script for off-line averaging - auvis.cov A template script for the computation of a noise-covariance matrix - ======================== ===================================================================== - -.. _CHDDEGGC: - -.. table:: Overview of the contents of the subjects/sample directory. - - ======================= ====================================================================== - File / directory Contents - ======================= ====================================================================== - bem Directory for the forward modelling data - bem/watershed BEM surface segmentation data computed with the watershed algorithm - bem/inner_skull.surf Inner skull surface for BEM - bem/outer_skull.surf Outer skull surface for BEM - bem/outer_skin.surf Skin surface for BEM - sample-head.fif Skin surface in fif format for mne_analyze visualizations - surf Surface reconstructions - mri/T1 The T1-weighted MRI data employed in visualizations - ======================= ====================================================================== - -The following preprocessing steps have been already accomplished -in the sample data set: - -- The MRI surface reconstructions have - been computed using the FreeSurfer software. - -- The BEM surfaces have been created with the watershed algorithm, - see :ref:`BABBDHAG`. - -- The MEG/EEG raw data file has been checked with the utilities described - in :ref:`BABCDBDI` and :ref:`BABCDFJH`. - -Setting up subject-specific data -################################ - -.. _CHDBBAEJ: - -Structural MRIs -=============== - -To set up the structural MRIs for processing with the Neuromag -MRI viewer, MRIlab, say - -``mne_setup_mri`` - -This command sets up the directories ``subjects/sample/mri/T1-neuromag`` and ``subjects/sample/mri/brain-neuromag`` . -For more information, see :ref:`BABCCEHF`. - -.. _CHDIGEJG: - -Source space -============ - -The source space with a 5-mm grid spacing is set up by saying: - -``mne_setup_source_space --ico -6`` - -This command sets up the source-space related files in directory ``subjects/sample/bem`` as -described in :ref:`setting_up_source_space`. - -.. _CHDJDGBD: - -Boundary-element models -======================= - -The geometry calculations for the single-layer boundary-element -model are accomplished with the command: - -``mne_setup_forward_model --homog --surf --ico 4`` - -This command sets up the homogeneous BEM-model related files -in directory ``subjects/sample/bem`` as described in :ref:`CIHDBFEG`. In -addition to the homogeneous BEM, you also need the three-layer BEM model, -which can be used for both EEG and MEG: - -``mne_setup_forward_model --surf --ico 4`` - -The above commands employ the ``inner_skull.surf`` , ``outer_skull.surf`` , -and ``outer_skin.surf`` triangulation files located in ``subjects/sample/bem`` . -The option ``--ico 4`` will create a model with 5120 triangles -on each surface. Depending on the speed of your computer, the three-layer -model may take quite a while to set up. - -Setting up a custom EEG layout -############################## - -A data specific EEG layout will facilitate viewing of the -EEG data. The MNE programs mne_browse_raw and mne_analyze look -for user-specific layouts in ``$HOME/.mne/lout`` . Thus, -you can create an EEG layout for the sample data set with the following -commands: - -``mkdir -p $HOME/.mne/lout`` - -``cd $SAMPLE/MEG/sample`` - -``mne_make_eeg_layout --fif sample_audvis_raw.fif --lout $HOME/.mne/lout/sample-EEG.lout`` - -Please refer to :ref:`mne_make_eeg_layout` for more information -on mne_make_eeg_layout . - -.. note:: It is usually sufficient to create one EEG layout for each electrode cap you are using in your experiment rather than using a different layout file for each data file generated using the same cap. - -Previewing the data -################### - -Previewing your raw data before proceeding to averaging and -computation of the current estimates is most important to avoid -unintentional errors caused by noisy or dysfunctional channels, -frequent eye blinks, inappropriate bandpass filtering etc. - -One possible routemap for the preview session is outlined -below: - -- Go to the MEG/EEG data directory: ``cd $SAMPLE/MEG/sample`` . - -- Launch mne_browse_raw . - -- Open the raw data file ``sample_audvis_raw.fif`` from File/Open... . - -- Switch all SSP vectors off from Adjust/Projection... . - -- Set the lowpass filter corner to a high value, e.g., 150 Hz - from Adjust/Filter... . - -- Browse through all channels using the selections available - under Adjust/Selection... and - look for very noisy or flat channels. You should be able to readily - identify two such channels among all MEG and EEG channels. You may - need to click Remove DC to reliably - associate the noisy or flat waveform with the channel name on the - left. Also, experiment with switching the EEG average reference - projection on and off and you will notice that the EEG bad channel - cannot be seen after the projection. - -- Mark the channels you identified in step 6. bad for this viewing - session by clicking on their channel names on the left. You can - save the bad channel selection to the file from File/Apply bad channels . Bad channel marking can be removed - by clicking on their channel names again and selecting File/Apply bad channels . Alternatively, you can use the utility mne_mark_bad_channels to - set a bad channel selection, see :ref:`mne_mark_bad_channels`. - -- Switch the projections back on and change filter to a 40-Hz - lowpass. - -- Compute a preliminary average for the left-ear auditory stimulus: - - - Open the averaging preferences dialog - (Adjust/Averaging preferences... . - - - Set the time scale to -100...300 ms. - - - Click on the text next to Average: in - the main window and press return. After a while, a topographical - display appears with the averaged responses. Notice that the bad - channels are not displayed. - - - Change to different layouts from Adjust/Full view layout... . Inspect both the MEG and EEG waveforms. - -- Compute a preliminary average for the right-ear auditory stimulus: - - - Open the averaging preferences. - - - Click on the Trace color... button - and change the trace color to something different from the default - yellow. - - - Change the text next to Average: to - 2 and press return. Average to the right-ear tones will be computed. - Compare the to sets of averages and verify that all channels show - reasonable data. - -- Go to Windows/Manage averages... and - delete the preliminary averages just computed. - -After these steps, you are ready to proceed to the actual -analysis. - -Off-line averaging -################## - -Go to directory ``$SAMPLE/MEG/sample`` . With help -of :ref:`CACBBDGC`, familiarize yourself with the averaging -script ``audvis.ave`` . - -Using the averaging script interactively -======================================== - -You can invoke an averaging script in mne_browse_raw from Process/Average... . -Select the ``audvis.ave`` script from the file selection -box that appears. Once averaging is complete, you can inspect the -details of the averaged responses in the Averages window, -which appears automatically. You can redisplay it from Windows/Show averages... . The window, which appears when you -select Adjust/Manage averages... allows -you to: - -- Select which conditions (categories) - are displayed. - -- Change the trace colors. - -- Inspect the averaging log. - -- Save the averaged data. - -- Delete this set of averages. - -.. note:: If you decide to save the averages in the interactive mode, use the name ``sample_audvis-ave.fif`` for the result. - -Using the averaging script in batch mode -======================================== - -The batch-mode version of mne_browse_raw , mne_process_raw can -be used for averaging as well. Batch mode averaging can be done -with the command: - -``mne_process_raw --raw sample_audvis_raw.fif `` ``--lowpass 40 --projoff `` ``--saveavetag -ave --ave audvis.ave`` - -See :ref:`mne_process_raw` for command-line options. - -As a result of running the averaging script a file called ``sample_audvis-ave.fif`` is -created. It contains averages to the left and right ear auditory -as well as to the left and right visual field stimuli. - -.. _CHDHBGGH: - -Viewing the off-line average -############################ - -The average file computed in the previous section can be -viewed in mne_browse_raw . - -To view the averaged signals, invoke mne_browse_raw : - -``cd $SAMPLE/MEG/sample`` - -``mne_browse_raw &`` - -This Section gives only very basic information about the -use of mne_browse_raw for viewing -evoked-response data. Please consult :ref:`ch_browse` for more -comprehensive information. - -Loading the averages -==================== - -mne_browse_raw loads all -the available data from an average file at once: - -- Select Open evoked... from - the File menu. - -- Select the average file ``sample_audvis-ave.fif`` file - from the list and click OK . - -- A topographical display of the waveforms with gradiometer - channels included appears. - -Inspecting the auditory data -============================ - -Select the left and right ear auditory stimulus responses -for display: - -- Select Manage averages... from - the Adjust menu. - -- Click off all other conditions except the auditory ones. - -Set the time scale and baseline: - -- Select Scales... from - the Adjust menu. - -- Switch off Autoscale time range and - set the Average time range from -200 - to 500 ms. - -- Switch on Use average display baseline and - set Average display baseline from - -200 to 0 ms. - -- Click OK . - -You can display a subset of responses from the topographical display -by holding the shift key down and dragging with the mouse, left -button down. When you drag on the response with just the left button -down, the signal timing, and channel name are displayed at the bottom. If -the left mouse button is down and you press shift down the time -is give both in absolute units and relative to the point where shift -was pressed down. - -Observe the following: - -- The main deflection occurs around 100 ms - over the left and right temporal areas. - -- The left-ear response (shown in yellow) is stronger on the - right than on the left. The opposite is true for the right-ear response, - shown in red. - -Inspecting the visual data -========================== - -Go back to the Manage averages... dialog -and switch all other conditions except the visual ones. - -Observe the following: - -- The left and right visual field responses - are quite different in spatial distribution in the occipital area. - -- There is a later response in the right parietal area, almost - identical to both visual stimuli. - -.. note:: If you have the Neuromag software available, the averaged data can be also viewed in the Neuromag data plotter (xplotter ). See :ref:`BABGFDJG` for instructions on how to use the Neuromag software at the MGH Martinos Center. - -Computing the noise-covariance matrix -##################################### - -Another piece of information derived from the raw data file -is the estimate for the noise-covariance matrix, which can be computed -with the command: - -``mne_process_raw --raw sample_audvis_raw.fif --lowpass 40 --projon --savecovtag -cov --cov audvis.cov`` - -Using the definitions in ``audvis.cov`` , this command -will create the noise-covariance matrix file ``sample_audvis-cov.fif`` . -In this case the projections are set on. The projection information -is then attached to the noise-covariance matrix and will be automatically -loaded when the inverse-operator decomposition is computed. - -.. note:: You can study the contents of the covariance matrix computation description file ``audvis.cov`` with the help of :ref:`CACEBACG`. - -.. _CHDIJBIG: - -MEG-MRI coordinate system alignment -################################### - -The mne_analyze module -of the MNE is one option for the coordinate alignment. It uses a -triangulated scalp surface to facilitate the alignment. - -.. _CHDEDCAE: - -Initial alignment -================= - -Follow these steps to make an initial approximation for the -coordinate alignment. - -- Go to directory ``MEG/sample`` . - -- Launch mne_analyze - -- Select File/Load digitizer data... and - load the digitizer data from ``sample_audvis_raw.fif`` . - -- Load an inflated surface for subject sample from File/Load surface... - -- Bring up the viewer window from View/Show viewer... - -- Click Options... in the - viewer window. Make the following selections: - - - Switch left and right cortical surface - display off. - - - Make the scalp transparent. - - - Switch Digitizer data on. - -- After a while, the digitizer points will be shown. The color - of the circles indicates whether the point is inside (blue) or outside - (red) of the scalp. The HPI coils are shown in green and the landmark - locations in light blue or light red color. The initial alignment - is way off! - -- Switch the Digitizer data off - to get the big circles out of the way. - -- Bring up the coordinate alignment window from Adjust/Coordinate alignment... - -- Click on the RAP (Right - Auricular Point) button. It turns red, indicating that you should - select the point from the viewer window. Click at the approximate - location of this point in the viewer. The button jumps up, turns - to normal color, and the MRI coordinates of the point appear in - the text fields next to the button. - -- Proceed similarly for the other two landmark points: Nasion - and LAP (Left Auricular Point). - -- Press Align using fiducials . - Notice that the coordinate transformation changes from a unit transformation - (no rotation, no origin translation) to a one determined by the - identified landmark locations. The rotation matrix (upper left 3 - x 3 part of the transformation) should have positive values close - to one on the diagonal. Three is a significant rotation around the - x axis as indicated by elements (3,2) and (2,3) of the rotation - matrix. The *x* and *y* values - of the translation should be small and the *z* value - should be negative, around -50 mm. An example of an initial - coordinate transformation is shown in :ref:`CHDFIHAC`. - -- Make the Digitizer data again - visible from the options of the viewer window. Note that the points - are now much closer to the scalp surface. - -.. _CHDFIHAC: - -.. figure:: pics/Digitizer-example.png - :alt: Example of an initial coordinate alignment - - Example of an initial coordinate alignment. - -Refining the coordinate transformation -====================================== - -Before proceeding to the refinement procedure, it is useful -to remove outlier digitizer points. When you rotate the image in -the viewer window, you will notice that there is at least one such -point over the right cheek. To discard this point: - -- Click on Discard in - the Adjust coordinate alignment window. - -- Enter 10 for the distance of the points to be discarded. - -- Click done. The outlier point disappears. - -The coordinate transformation can be adjusted manually with -the arrow buttons in the middle part of the Adjust coordinate alignment dialog. These buttons move -the digitizer points in the directions indicated by the amount listed -next to each of the buttons. - -An automatic iterative procedure, Iterative Closest Point -(ICP) matching is also provided. At each iteration step - -- For each digitizer point, transformed - from MEG to the MRI coordinate frame, the closest point on the triangulated - surface is determined. - -- The best coordinate transformation aligning the digitizer - points with the closest points on the head surface is computed. - -In step 2 of the iteration, the nasion is assigned five times -the weight of the other points since it can be assumed that the -nasion is the easiest point to identify reliably from the surface -image. - -The ICP alignment can be invoked by entering the desired -number of iterations next to the ICP align button -followed by return or simply pressing the ICP align button. -The iteration will converge in 10 to 20 steps. - -.. warning:: Use the ICP alignment option in mne_analyze with caution. The iteration will not converge to a reasonable solution unless and initial alignment is performed first according to :ref:`CHDEDCAE`. Outlier points should be excluded as described above. No attempt is made to compensate for the possible distance of the digitized EEG electrode locations from the scalp. - -Saving the transformation -========================= - -To create a MRI fif description file which incorporates the -coordinate transformation click Save MRI set in -the Adjust coordinate alignment dialog. -This will create the MRI set file in the ``$SUBJECTS_DIR/sample/mri/T1-neuromag/sets`` directory, -which was created by mne_setup_mri_data , -see :ref:`CHDBBAEJ`. The file will be called - -``COR-`` <*username*>- <*date*>- <*time*> .fif - -where <*username*> is -your login name. - -You can also save transformation to a fif file through the Save... button. -If the file does not exist, it will only contain the coordinate -transformation. If the file exists it will be inserted to the appropriate -context. An existing transformation will not be replaced unless Overwrite existing transform is checked in the save dialog. - -Once you have saved the coordinate transformation, press Done and -quit mne_analyze (File/Quit ). - -.. note:: If you dismiss the alignment dialog before saving the transformation, it will be lost. - -The forward solution -#################### - -To compute the forward solution, say: - -``cd $SAMPLE/MEG/sample`` - -``mne_do_forward_solution --mindist 5 --spacing oct-6 --bem sample-5120-5120-5120 --meas sample_audvis-ave.fif`` - -This produces an EEG and MEG forward solution with source -space points closer than 5 mm to the inner skull surface omitted. -The source space created in :ref:`CHDIGEJG` will be employed. -As the output from this command will indicate The forward solution -will be stored in file ``sample_audvis-ave-oct-6-fwd.fif`` . - -This command uses the three-layer BEM model ``sample-5120-5120-5120-bem-sol.fif`` created -in :ref:`CHDJDGBD`. If you want to use the single-compartment -BEM ``sample-5120-bem-sol.fif`` usable for MEG data only -say: - -``cd $SAMPLE/MEG/sample`` - -``mne_do_forward_solution --mindist 5 --spacing oct-6 --meas sample_audvis-ave.fif --bem sample-5120 --megonly`` - -The inverse operator decomposition -################################## - -The inverse operator information, necessary for the computation -of the MNEs and dSPMs is accomplished by the command: - -``mne_do_inverse_operator --fwd sample_audvis-ave-oct-6-fwd.fif --depth --loose 0.2 --meg --eeg`` - -This produces a depth-weighted inverse operator decomposition -with 'loose' orientation constraint applied. More -details on the convenience script mne_do_inverse_operator are -provided in :ref:`CIHCFJEI`. - -The above command employs both EEG and MEG data. To create -separate solution for EEG and MEG, run the commands: - -``mne_do_inverse_operator --fwd sample_audvis-ave-oct-6-fwd.fif --depth --loose 0.2 --meg`` - -and - -``mne_do_inverse_operator --fwd sample_audvis-ave-oct-6-fwd.fif --depth --loose 0.2 --eeg`` - -.. note:: If you were using a single-compartment BEM to compute the forward solution, you can only compute the MEG inverse operator. - -Interactive analysis -#################### - -The most exciting part of this exercise is to explore the -data and the current estimates in mne_analyze . -This section contains some useful steps to get you started. A lot -of information about the capabilities of mne_analyze is -given in :ref:`c_legacy_ch_interactive_analysis`. Batch-mode processing with -mne_make_movie is discussed in :ref:`c_legacy_movies_and_snapshots`. Cross-subject -averaging is covered in :ref:`c_legacy_ch_morph`. - -Before launching mne_analyze it -is advisable to go to the directory ``MEG/sample`` . The -current working directory can be also changed from mne_analyze . - -Getting started -=============== - -Launch mne_analyze . Select Help/On GLX... , which brings up a window containing Open -GL rendering context information. If first line in the information -dialog that pops up says Nondirect rendering context instead of Direct rendering context you will experience slow graphics -performance. To fix this, your system software, graphics adapter -or both need to be updated. Consult a computer support person for -further information. - -Load surfaces -============= - -It is reasonable to start the analysis by loading the display -surfaces: choose the inflated surface for subject sample from -the dialog that appears when you select File/Load surface... . - -Load the data -============= - -Select File/Open... . Select ``sample_audvis-ave.fif`` as -your data file and select the Left auditory data -set. Select the inverse operator ``sample_audvis-ave-oct-6-meg-eeg-inv.fif`` and -press OK . After a while the signals -appear in the sample waveform and topographical displays. Click -on the N100m peak in the auditory response. A dSPM map appears in -the main surface display. - -Show field and potential maps -============================= - -Select Windows/Show viewer... . -After a while the viewer window appears. Click on the N100m peak -again. Once the field map preparation computations are complete, -the magnetic field and potential maps appear. Investigate the viewer -window options with help of :ref:`CACEFFJF`. - -Show current estimates -====================== - -The options affecting the current estimates are accessible -from Adjust/Estimate parameters... . -With help of :ref:`CACBHDBF`, investigate the effects of the -parameter settings. - -Labels and timecourses -====================== - -While in directory ``MEG/sample`` , create a directory -called ``label`` : - -``mkdir label`` - -Using the information in :ref:`CACJCFJJ`, create two -labels ``A-lh.label`` and ``A-rh.label`` in the -approximate location of the left and right auditory cortices. Save -these labels in the newly created ``label`` directory. - -Load all labels from the ``label`` directory and -investigate the timecourses in these two labels as well as at individual -vertices. Information on label processing can be found from :ref:`CACCCFHH`. - -Morphing -======== - -Goto to ``$SUBJECTS_DIR`` and create the directory ``morph-maps`` . -Load the inflated surface for subject morph as -the morphing surfaces. Try switching between the original and morphing -surfaces. More information about morphing is available in :ref:`CACGBEIB` and -in :ref:`c_legacy_ch_morph`. - -There is also a left-hemisphere occipital patch file available -for subject morph . Load a righ-hemifield -visual response instead of the auditory one and investigate mapping -of the current estimates on the patch. diff -Nru python-mne-0.18.1+dfsg/doc/manual/source_localization/c_forward.rst python-mne-0.19.1+dfsg/doc/manual/source_localization/c_forward.rst --- python-mne-0.18.1+dfsg/doc/manual/source_localization/c_forward.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/source_localization/c_forward.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,891 +0,0 @@ -.. _c_legacy_ch_forward: - -==================== -The forward solution -==================== - -.. contents:: Contents - :local: - :depth: 2 - - -Overview -######## - -This Chapter covers the definitions of different coordinate -systems employed in MNE software and FreeSurfer, the details of -the computation of the forward solutions, and the associated low-level -utilities. - -.. _c_legacy_CHDEDFIB: - -MEG/EEG and MRI coordinate systems -################################## - -The coordinate systems used in MNE software (and FreeSurfer) -and their relationships are depicted in :ref:`c_legacy_CHDFFJIJ`. -Except for the *Sensor coordinates*, all of the -coordinate systems are Cartesian and have the "RAS" (Right-Anterior-Superior) -orientation, *i.e.*, the :math:`x` axis -points to the right, the :math:`y` axis -to the front, and the :math:`z` axis up. - -.. _c_legacy_CHDFFJIJ: - -.. figure:: ../pics/CoordinateSystems.png - :alt: MEG/EEG and MRI coordinate systems - - MEG/EEG and MRI coordinate systems - - The coordinate transforms present in the fif files in MNE and the FreeSurfer files as well as those set to fixed values are indicated with :math:`T_x`, where :math:`x` identifies the transformation. - -The coordinate systems related -to MEG/EEG data are: - -**Head coordinates** - - This is a coordinate system defined with help of the fiducial landmarks - (nasion and the two auricular points). In fif files, EEG electrode - locations are given in this coordinate system. In addition, the head - digitization data acquired in the beginning of an MEG, MEG/EEG, - or EEG acquisition are expressed in head coordinates. For details, - see :ref:`c_legacy_CHDEDFIB`. - -**Device coordinates** - - This is a coordinate system tied to the MEG device. The relationship - of the Device and Head coordinates is determined during an MEG measurement - by feeding current to three to five head-position - indicator (HPI) coils and by determining their locations with respect - to the MEG sensor array from the magnetic fields they generate. - -**Sensor coordinates** - - Each MEG sensor has a local coordinate system defining the orientation - and location of the sensor. With help of this coordinate system, - the numerical integration data needed for the computation of the - magnetic field can be expressed conveniently as discussed in :ref:`c_legacy_BJEIAEIE`. The channel information data in the fif files - contain the information to specify the coordinate transformation - between the coordinates of each sensor and the MEG device coordinates. - -The coordinate systems related -to MRI data are: - -**Surface RAS coordinates** - - The FreeSurfer surface data are expressed in this coordinate system. The - origin of this coordinate system is at the center of the conformed - FreeSurfer MRI volumes (usually 256 x 256 x 256 isotropic 1-mm3 voxels) - and the axes are oriented along the axes of this volume. The BEM - surface and the locations of the sources in the source space are - usually expressed in this coordinate system in the fif files. In - this manual, the *Surface RAS coordinates* are - usually referred to as *MRI coordinates* unless - there is need to specifically discuss the different MRI-related - coordinate systems. - -**RAS coordinates** - - This coordinate system has axes identical to the Surface RAS coordinates but the location of the origin - is different and defined by the original MRI data, i.e. , - the origin is in a scanner-dependent location. There is hardly any - need to refer to this coordinate system explicitly in the analysis - with the MNE software. However, since the Talairach coordinates, - discussed below, are defined with respect to *RAS coordinates* rather - than the *Surface RAS coordinates*, the RAS coordinate - system is implicitly involved in the transformation between Surface RAS coordinates and the two *Talairach* coordinate - systems. - -**MNI Talairach coordinates** - - The definition of this coordinate system is discussed, e.g. , - in http://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach. This - transformation is determined during the FreeSurfer reconstruction - process. - -**FreeSurfer Talairach coordinates** - - The problem with the MNI Talairach coordinates is that the linear MNI - Talairach transform does matched the brains completely to the Talairach - brain. This is probably because the Talairach atlas brain is a rather - odd shape, and as a result, it is difficult to match a standard brain - to the atlas brain using an affine transform. As a result, the MNI - brains are slightly larger (in particular higher, deeper and longer) - than the Talairach brain. The differences are larger as you get - further from the middle of the brain, towards the outside. The FreeSurfer - Talairach coordinates mitigate this problem by additing a an additional - transformation, defined separately for negatice and positive MNI - Talairach :math:`z` coordinates. These two - transformations, denoted by :math:`T_-` and :math:`T_+` in :ref:`c_legacy_CHDFFJIJ`, are fixed as discussed in http://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach - (*Approach 2*). - -The different coordinate systems are related by coordinate -transformations depicted in :ref:`c_legacy_CHDFFJIJ`. The arrows and -coordinate transformation symbols (:math:`T_x`) -indicate the transformations actually present in the FreeSurfer -files. Generally, - -.. math:: \begin{bmatrix} - x_2 \\ - y_2 \\ - z_2 \\ - 1 - \end{bmatrix} = T_{12} \begin{bmatrix} - x_1 \\ - y_1 \\ - z_1 \\ - 1 - \end{bmatrix} = \begin{bmatrix} - R_{11} & R_{12} & R_{13} & x_0 \\ - R_{13} & R_{13} & R_{13} & y_0 \\ - R_{13} & R_{13} & R_{13} & z_0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} \begin{bmatrix} - x_1 \\ - y_1 \\ - z_1 \\ - 1 - \end{bmatrix}\ , - -where :math:`x_k`,:math:`y_k`,and :math:`z_k` are the location -coordinates in two coordinate systems, :math:`T_{12}` is -the coordinate transformation from coordinate system "1" to "2", -:math:`x_0`, :math:`y_0`,and :math:`z_0` is the location of the origin -of coordinate system "1" in coordinate system "2", -and :math:`R_{jk}` are the elements of the rotation -matrix relating the two coordinate systems. The coordinate transformations -are present in different files produced by FreeSurfer and MNE as -summarized in :ref:`c_legacy_CHDJDEDJ`. The fixed transformations :math:`T_-` and :math:`T_+` are: - -.. math:: T_{-} = \begin{bmatrix} - 0.99 & 0 & 0 & 0 \\ - 0 & 0.9688 & 0.042 & 0 \\ - 0 & -0.0485 & 0.839 & 0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} - -and - -.. math:: T_{+} = \begin{bmatrix} - 0.99 & 0 & 0 & 0 \\ - 0 & 0.9688 & 0.046 & 0 \\ - 0 & -0.0485 & 0.9189 & 0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} - -.. note:: This section does not discuss the transformation between the MRI voxel indices and the different MRI coordinates. However, it is important to note that in FreeSurfer, MNE, as well as in Neuromag software an integer voxel coordinate corresponds to the location of the center of a voxel. Detailed information on the FreeSurfer MRI systems can be found at https://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems. - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.3\linewidth}|p{0.5\linewidth}| -.. _c_legacy_CHDJDEDJ: -.. table:: Coordinate transformations in FreeSurfer and MNE software packages. - - +------------------------------+-------------------------------+--------------------------------------+ - | Transformation | FreeSurfer | MNE | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_1` | Not present | | Measurement data files | - | | | | Forward solution files (`*fwd.fif`)| - | | | | Inverse operator files (`*inv.fif`)| - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_{s_1}\dots T_{s_n}` | Not present | Channel information in files | - | | | containing :math:`T_1`. | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_2` | Not present | | MRI description files Separate | - | | | | coordinate transformation files | - | | | | saved from mne_analyze | - | | | | Forward solution files | - | | | | Inverse operator files | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_3` | `mri/*mgz` files | MRI description files saved with | - | | | mne_make_cor_set if the input is in | - | | | mgz or mgh format. | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_4` | mri/transforms/talairach.xfm | MRI description files saved with | - | | | mne_make_cor_set if the input is in | - | | | mgz or mgh format. | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_-` | Hardcoded in software | MRI description files saved with | - | | | mne_make_cor_set if the input is in | - | | | mgz or mgh format. | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_+` | Hardcoded in software | MRI description files saved with | - | | | mne_make_cor_set if the input is in | - | | | mgz or mgh format. | - +------------------------------+-------------------------------+--------------------------------------+ - -.. note:: The symbols :math:`T_x` are defined in :ref:`c_legacy_CHDFFJIJ`. mne_make_cor_set /mne_setup_mri prior to release 2.6 did not include transformations :math:`T_3`, :math:`T_4`, :math:`T_-`, and :math:`T_+` in the fif files produced. - -.. _c_legacy_BJEBIBAI: - -The head and device coordinate systems -###################################### - -.. figure:: ../pics/HeadCS.png - :alt: Head coordinate system - - The head coordinate system - -The MEG/EEG head coordinate system employed in the MNE software -is a right-handed Cartesian coordinate system. The direction of :math:`x` axis -is from left to right, that of :math:`y` axis -to the front, and the :math:`z` axis thus -points up. - -The :math:`x` axis of the head coordinate -system passes through the two periauricular or preauricular points -digitized before acquiring the data with positive direction to the -right. The :math:`y` axis passes through -the nasion and is normal to the :math:`x` axis. -The :math:`z` axis points up according to -the right-hand rule and is normal to the :math:`xy` plane. - -The origin of the MEG device coordinate system is device -dependent. Its origin is located approximately at the center of -a sphere which fits the occipital section of the MEG helmet best -with :math:`x` axis axis going from left to right -and :math:`y` axis pointing front. The :math:`z` axis -is, again, normal to the :math:`xy` plane -with positive direction up. - -.. note:: The above definition is identical to that of the Neuromag MEG/EEG (head) coordinate system. However, in 4-D Neuroimaging and CTF MEG systems the head coordinate frame definition is different. The origin of the coordinate system is at the midpoint of the left and right auricular points. The :math:`x` axis passes through the nasion and the origin with positive direction to the front. The :math:`y` axis is perpendicular to the :math:`x` axis on the and lies in the plane defined by the three fiducial landmarks, positive direction from right to left. The :math:`z` axis is normal to the plane of the landmarks, pointing up. Note that in this convention the auricular points are not necessarily located on :math:`y` coordinate axis. The file conversion utilities take care of these idiosyncrasies and convert all coordinate information to the MNE software head coordinate frame. - -.. _c_legacy_BEHCGJDD: - -Creating a surface-based source space -##################################### - -The fif format source space files containing the dipole locations -and orientations are created with the utility :ref:`mne_make_source_space`. -This utility is usually invoked by the convenience script :ref:`mne_setup_source_space`, -see :ref:`setting_up_source_space`. - - -.. _c_legacy_BJEFEHJI: - -Creating a volumetric or discrete source space -############################################## - -In addition to source spaces confined to a surface, the MNE -software provides some support for three-dimensional source spaces -bounded by a surface as well as source spaces comprised of discrete, -arbitrarily located source points. The :ref:`mne_volume_source_space` utility -assists in generating such source spaces. - - -.. _c_legacy_BEHCACCJ: - -Creating the BEM meshes -####################### - -The :ref:`mne_surf2bem` utility -converts surface triangle meshes from ASCII and FreeSurfer binary -file formats to the fif format. The resulting fiff file also contains -conductivity information so that it can be employed in the BEM calculations. -See command-line options in :ref:`mne_surf2bem`. - -.. note:: The utility ``mne_tri2fiff`` previously used for this task has been replaced by :ref:`mne_surf2bem`. - -.. note:: The convenience script :ref:`mne_setup_forward_model` described in :ref:`CIHDBFEG` calls :ref:`mne_surf2bem` with the appropriate options. - -.. note:: The vertices of all surfaces should be given in the MRI coordinate system. - - -.. _c_legacy_BEHDEFCD: - -Tessellation file format -======================== - -The format of the text format surface files is the following: - - | <*nvert*> - | <*vertex 1*> - | <*vertex 2*> - | ... - | <*vertex nvert*> - | <*ntri*> - | <*triangle 1*> - | <*triangle 2*> - | ... - | <*triangle ntri*> , - -where <*nvert*> and <*ntri*> are -the number of vertices and number of triangles in the tessellation, -respectively. - -The format of a vertex entry is -one of the following: - -**x y z** - - The x, y, and z coordinates of the vertex location are given in - mm. - -**number x y z** - - A running number and the x, y, and z coordinates are given. The running - number is not considered by mne_tri2fiff. The nodes must be thus - listed in the correct consecutive order. - -**x y z nx ny nz** - - The x, y, and z coordinates as well as the approximate vertex normal direction - cosines are given. - -**number x y z nx ny nz** - - A running number is given in addition to the vertex location and vertex - normal. - -Each triangle entry consists of the numbers of the vertices -belonging to a triangle. The vertex numbering starts from one. The -triangle list may also contain running numbers on each line describing -a triangle. - -.. _c_legacy_BEHCBDDE: - -Topology checks -=============== - -If the ``--check`` option is specified, the following -topology checks are performed: - -- The completeness of each surface is - confirmed by calculating the total solid angle subtended by all - triangles from a point inside the triangulation. The result should - be very close to :math:`4 \pi`. If the result - is :math:`-4 \pi` instead, it is conceivable - that the ordering of the triangle vertices is incorrect and the - ``--swap`` option should be specified. - -- The correct ordering of the surfaces is verified by checking - that the surfaces are inside each other as expected. This is accomplished - by checking that the sum solid angles subtended by triangles of - a surface :math:`S_k` at all vertices of another - surface :math:`S_p` which is supposed to be - inside it equals :math:`4 \pi`. Naturally, this - check is applied only if the model has more than one surface. Since - the surface relations are transitive, it is enough to check that - the outer skull surface is inside the skin surface and that the - inner skull surface is inside the outer skull one. - -- The extent of each of the triangulated volumes is checked. - If the extent is smaller than 50mm, an error is reported. This - may indicate that the vertex coordinates have been specified in - meters instead of millimeters. - - -.. _c_legacy_CHDJFHEB: - -Computing the BEM geometry data -############################### - -The utility :ref:`mne_prepare_bem_model` computes -the geometry information for BEM. This utility is usually invoked -by the convenience script :ref:`mne_setup_forward_model`, -see :ref:`CIHDBFEG`. The command-line options are listed under -:ref:`mne_prepare_bem_model`. - - -.. _c_legacy_BJEIAEIE: - -Coil geometry information -######################### - -This Section explains the presentation of MEG detection coil -geometry information the approximations used for different detection -coils in MNE software. Two pieces of information are needed to characterize -the detectors: - -- The location and orientation a local - coordinate system for each detector. - -- A unique identifier, which has an one-to-one correspondence - to the geometrical description of the coil. - -The sensor coordinate system -============================ - -The sensor coordinate system is completely characterized -by the location of its origin and the direction cosines of three -orthogonal unit vectors pointing to the directions of the x, y, -and z axis. In fact, the unit vectors contain redundant information -because the orientation can be uniquely defined with three angles. -The measurement fif files list these data in MEG device coordinates. -Transformation to the MEG head coordinate frame can be easily accomplished -by applying the device-to-head coordinate transformation matrix -available in the data files provided that the head-position indicator -was used. Optionally, the MNE software forward calculation applies -another coordinate transformation to the head-coordinate data to -bring the coil locations and orientations to the MRI coordinate system. - -If :math:`r_0` is a row vector for -the origin of the local sensor coordinate system and :math:`e_x`, :math:`e_y`, and :math:`e_z` are the row vectors for the -three orthogonal unit vectors, all given in device coordinates, -a location of a point :math:`r_C` in sensor coordinates -is transformed to device coordinates (:math:`r_D`) -by - -.. math:: [r_D 1] = [r_C 1] T_{CD}\ , - -where - -.. math:: T = \begin{bmatrix} - e_x & 0 \\ - e_y & 0 \\ - e_z & 0 \\ - r_{0D} & 1 - \end{bmatrix}\ . - -Calculation of the magnetic field -================================= - -The forward calculation in the MNE software computes the -signals detected by each MEG sensor for three orthogonal dipoles -at each source space location. This requires specification of the -conductor model, the location and orientation of the dipoles, and -the location and orientation of each MEG sensor as well as its coil -geometry. - -The output of each SQUID sensor is a weighted sum of the -magnetic fluxes threading the loops comprising the detection coil. -Since the flux threading a coil loop is an integral of the magnetic -field component normal to the coil plane, the output of the k :sup:`th` -MEG channel, :math:`b_k` can be approximated by: - -.. math:: b_k = \sum_{p = 1}^{N_k} {w_{kp} B(r_{kp}) \cdot n_{kp}} - -where :math:`r_{kp}` are a set of :math:`N_k` integration -points covering the pickup coil loops of the sensor, :math:`B(r_{kp})` is -the magnetic field due to the current sources calculated at :math:`r_{kp}`, :math:`n_{kp}` are -the coil normal directions at these points, and :math:`w_{kp}` are -the weights associated to the integration points. This formula essentially -presents numerical integration of the magnetic field over the pickup -loops of sensor :math:`k`. - -There are three accuracy levels for the numerical integration -expressed above. The *simple* accuracy means -the simplest description of the coil. This accuracy is not used -in the MNE forward calculations. The *normal* or *recommended* accuracy typically uses -two integration points for planar gradiometers, one in each half -of the pickup coil and four evenly distributed integration points -for magnetometers. This is the default accuracy used by MNE. If -the ``--accurate`` option is specified, the forward calculation typically employs -a total of eight integration points for planar gradiometers and -sixteen for magnetometers. Detailed information about the integration -points is given in the next section. - -Implemented coil geometries -=========================== - -This section describes the coil geometries currently implemented -in Neuromag software. The coil types fall in two general categories: - -- Axial gradiometers and planar gradiometers - and - -- Planar magnetometers. - -For axial sensors, the *z* axis of the -local coordinate system is parallel to the field component detected, *i.e.*, -normal to the coil plane.For circular coils, the orientation of -the *x* and *y* axes on the -plane normal to the z axis is irrelevant. In the square coils employed -in the Vectorview (TM) system the *x* axis -is chosen to be parallel to one of the sides of the magnetometer -coil. For planar sensors, the *z* axis is likewise -normal to the coil plane and the x axis passes through the centerpoints -of the two coil loops so that the detector gives a positive signal -when the normal field component increases along the *x* axis. - -:ref:`c_legacy_BGBBHGEC` lists the parameters of the *normal* coil -geometry descriptions :ref:`c_legacy_CHDBDFJE` lists the *accurate* descriptions. For simple accuracy, -please consult the coil definition file, see :ref:`c_legacy_BJECIGEB`. -The columns of the tables contain the following data: - -- The number identifying the coil id. - This number is used in the coil descriptions found in the FIF files. - -- Description of the coil. - -- Number of integration points used - -- The locations of the integration points in sensor coordinates. - -- Weights assigned to the field values at the integration points. - Some formulas are listed instead of the numerical values to demonstrate - the principle of the calculation. For example, in the normal coil - descriptions of the planar gradiometers the weights are inverses - of the baseline of the gradiometer to show that the output is in - T/m. - -.. note:: The coil geometry information is stored in the file $MNE_ROOT/share/mne/coil_def.dat, which is automatically created by the utility mne_list_coil_def , see :ref:`c_legacy_BJEHHJIJ`. - -.. XXX : table of normal coil description is missing - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.1\linewidth}|p{0.25\linewidth}|p{0.2\linewidth}| -.. _c_legacy_BGBBHGEC: -.. table:: Normal coil descriptions. - - +------+-------------------------+----+----------------------------------+----------------------+ - | Id | Description | n | r/mm | w | - +======+=========================+====+==================================+======================+ - | 2 | Neuromag-122 | 2 | (+/-8.1, 0, 0) mm | +/-1 ⁄ 16.2mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 2000 | A point magnetometer | 1 | (0, 0, 0)mm | 1 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3012 | Vectorview type 1 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3013 | Vectorview type 2 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3022 | Vectorview type 1 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3023 | Vectorview type 2 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3024 | Vectorview type 3 | 4 | (+/-5.25, +/-5.25, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 2000 | An ideal point | 1 | (0.0, 0.0, 0.0)mm | 1 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4001 | Magnes WH | 4 | (+/-5.75, +/-5.75, 0.0)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4002 | Magnes WH 3600 | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | - | | axial gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4003 | Magnes reference | 4 | (+/-7.5, +/-7.5, 0.0)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4004 | Magnes reference | 8 | (+/-20, +/-20, 0.0)mm | 1/4 | - | | gradiometer measuring | | (+/-20, +/-20, 135)mm | -1/4 | - | | diagonal gradients | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4005 | Magnes reference | 8 | (87.5, +/-20, 0.0)mm | 1/4 | - | | gradiometer measuring | | (47.5, +/-20, 0.0)mm | -1/4 | - | | off-diagonal gradients | | (-87.5, +/-20, 0.0)mm | 1/4 | - | | | | (-47.5, +/-20, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5001 | CTF 275 axial | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | - | | gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5002 | CTF reference | 4 | (+/-4, +/-4, 0.0)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5003 | CTF reference | 8 | (+/-8.6, +/-8.6, 0.0)mm | 1/4 | - | | gradiometer measuring | | (+/-8.6, +/-8.6, 78.6)mm | -1/4 | - | | diagonal gradients | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - -.. note:: If a plus-minus sign occurs in several coordinates, all possible combinations have to be included. - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.05\linewidth}|p{0.25\linewidth}|p{0.15\linewidth}| -.. _c_legacy_CHDBDFJE: -.. table:: Accurate coil descriptions - - +------+-------------------------+----+----------------------------------+----------------------+ - | Id | Description | n | r/mm | w | - +======+=========================+====+==================================+======================+ - | 2 | Neuromag-122 planar | 8 | +/-(8.1, 0, 0) mm | +/-1 ⁄ 16.2mm | - | | gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 2000 | A point magnetometer | 1 | (0, 0, 0) mm | 1 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3012 | Vectorview type 1 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3013 | Vectorview type 2 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3022 | Vectorview type 1 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3023 | Vectorview type 2 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3024 | Vectorview type 3 | 4 | (+/-5.25, +/-5.25, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4001 | Magnes WH magnetometer | 4 | (+/-5.75, +/-5.75, 0.0)mm | 1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4002 | Magnes WH 3600 | 4 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | - | | axial gradiometer | | (+/-4.5, +/-4.5, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4004 | Magnes reference | 8 | (+/-20, +/-20, 0.0)mm | 1/4 | - | | gradiometer measuring | | (+/-20, +/-20, 135)mm | -1/4 | - | | diagonal gradients | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4005 | Magnes reference | 8 | (87.5, +/-20, 0.0)mm | 1/4 | - | | gradiometer measuring | | (47.5, +/-20, 0.0)mm | -1/4 | - | | off-diagonal gradients | | (-87.5, +/-20, 0.0)mm | 1/4 | - | | | | (-47.5, +/-20, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5001 | CTF 275 axial | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | - | | gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5002 | CTF reference | 4 | (+/-4, +/-4, 0.0)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5003 | CTF 275 reference | 8 | (+/-8.6, +/-8.6, 0.0)mm | 1/4 | - | | gradiometer measuring | | (+/-8.6, +/-8.6, 78.6)mm | -1/4 | - | | diagonal gradients | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5004 | CTF 275 reference | 8 | (47.8, +/-8.5, 0.0)mm | 1/4 | - | | gradiometer measuring | | (30.8, +/-8.5, 0.0)mm | -1/4 | - | | off-diagonal gradients | | (-47.8, +/-8.5, 0.0)mm | 1/4 | - | | | | (-30.8, +/-8.5, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 6001 | MIT KIT system axial | 8 | (+/-3.875, +/-3.875, 0.0)mm | 1/4 | - | | gradiometer | | (+/-3.875, +/-3.875, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - - -.. _c_legacy_BJECIGEB: - -The coil definition file -======================== - -The coil geometry information is stored in the text file -$MNE_ROOT/share/mne/coil_def.dat. In this file, any lines starting -with the pound sign (#) are comments. A coil definition starts with -a description line containing the following fields: - -** <*class*>** - - This is a number indicating class of this coil. Possible values - are listed in :ref:`c_legacy_BJEFABHA`. - -** <*id*>** - - Coil id value. This value is listed in the first column of Tables :ref:`c_legacy_BGBBHGEC` and :ref:`c_legacy_CHDBDFJE`. - -** <*accuracy*>** - - The coil representation accuracy. Possible values and their meanings - are listed in :ref:`c_legacy_BJEHIBJC`. - -** <*np*>** - - Number of integration points in this representation. - -** <*size/m*>** - - The size of the coil. For circular coils this is the diameter of - the coil and for square ones the side length of the square. This - information is mainly included to facilitate drawing of the coil - geometry. It should not be employed to infer a coil approximation - for the forward calculations. - -** <*baseline/m*>** - - The baseline of a this kind of a coil. This will be zero for magnetometer - coils. This information is mainly included to facilitate drawing - of the coil geometry. It should not be employed to infer a coil - approximation for the forward calculations. - -** <*description*>** - - Short description of this kind of a coil. If the description contains several - words, it is enclosed in quotes. - -.. _c_legacy_BJEFABHA: - -.. table:: Coil class values - - ======= ======================================================= - Value Meaning - ======= ======================================================= - 1 magnetometer - 2 first-order axial gradiometer - 3 planar gradiometer - 4 second-order axial gradiometer - 1000 an EEG electrode (used internally in software only). - ======= ======================================================= - - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.5\linewidth}| -.. _c_legacy_BJEHIBJC: -.. table:: Coil representation accuracies. - - ======= ===================================================================== - Value Meaning - ======= ===================================================================== - 1 The simplest representation available - 2 The standard or *normal* representation (see :ref:`c_legacy_BGBBHGEC`) - 3 The most *accurate* representation available (see :ref:`c_legacy_CHDBDFJE`) - ======= ===================================================================== - -Each coil description line is followed by one or more integration -point lines, consisting of seven numbers: - -** <*weight*>** - - Gives the weight for this integration point (last column in Tables :ref:`c_legacy_BGBBHGEC` and :ref:`c_legacy_CHDBDFJE`). - -** <*x/m*> <*y/m*> <*z/m*>** - - Indicates the location of the integration point (fourth column in Tables :ref:`c_legacy_BGBBHGEC` and :ref:`c_legacy_CHDBDFJE`). - -** <*nx*> <*ny*> <*nz*>** - - Components of a unit vector indicating the field component to be selected. - Note that listing a separate unit vector for each integration points - allows the implementation of curved coils and coils with the gradiometer - loops tilted with respect to each other. - -.. _c_legacy_BJEHHJIJ: - -Creating the coil definition file -================================= - -The standard coil definition file $MNE_ROOT/share/mne/coil_def.dat -is included with the MNE software package. The coil definition file -can be recreated with the utility mne_list_coil_def -as follows: - -mne_list_coil_def --out $MNE_ROOT/share/mne/coil_def.dat - -.. _c_legacy_CHDDIBAH: - -Computing the forward solution -############################## - -Purpose -======= - -Instead of using the convenience script :ref:`mne_do_forward_solution` it -is also possible to invoke the forward solution computation program :ref:`mne_forward_solution` directly. -In this approach, the convenience of the automatic file naming conventions -present in :ref:`mne_do_forward_solution` are -lost. However, there are some special-purpose options available -in :ref:`mne_forward_solution` only. -Please refer to :ref:`BABCHEJD` for information on :ref:`mne_do_forward_solution`. -See :ref:`mne_forward_solution` for command-line options. - -Implementation of software gradient compensation -================================================ - -As described in :ref:`BEHDDFBI` the CTF and 4D Neuroimaging -data may have been subjected to noise cancellation employing the -data from the reference sensor array. Even though these sensor are -rather far away from the brain sources, mne_forward_solution takes -them into account in the computations. If the data file specified -with the ``--meas`` option has software gradient compensation -activated, mne_forward_solution computes -the field of at the reference sensors in addition to the main MEG -sensor array and computes a compensated forward solution using the -methods described in :ref:`BEHDDFBI`. - -.. warning:: If a data file specified with the ``--meas`` option and that used in the actual inverse computations with mne_analyze and mne_make_movie have different software gradient compensation states., the forward solution will be in mismatch with the data to be analyzed and the current estimates will be slightly erroneous. - -.. _c_legacy_CHDIAFIG: - -The EEG sphere model definition file -==================================== - -For the computation of the electric potential distribution -on the surface of the head (EEG) it is necessary to define the conductivities -(:math:`\sigma`) and radiuses of the spherically -symmetric layers. Different sphere models can be specified with -the ``--eegmodels`` option. - -The EEG sphere model definition files may contain comment -lines starting with a # and model -definition lines in the following format: - - <*name*>: <*radius1*>: <*conductivity1*>: <*radius2*>: <*conductivity2*>:... - -When the file is loaded the layers are sorted so that the -radiuses will be in ascending order and the radius of the outermost -layer is scaled to 1.0. The scalp radius specified with the ``--eegrad`` option -is then consulted to scale the model to the correct dimensions. -Even if the model setup file is not present, a model called Default is -always provided. This model has the structure given in :ref:`c_legacy_BABEBGDA` - - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.25\linewidth}|p{0.2\linewidth}| -.. _c_legacy_BABEBGDA: -.. table:: Structure of the default EEG model - - ======== ======================= ======================= - Layer Relative outer radius :math:`\sigma` (S/m) - ======== ======================= ======================= - Head 1.0 0.33 - Skull 0.97 0.04 - CSF 0.92 1.0 - Brain 0.90 0.33 - ======== ======================= ======================= - -EEG forward solution in the sphere model -======================================== - -When the sphere model is employed, the computation of the -EEG solution can be substantially accelerated by using approximation -methods described by Mosher, Zhang, and Berg, see :ref:`CEGEGDEI` (Mosher *et -al.* and references therein). mne_forward_solution approximates -the solution with three dipoles in a homogeneous sphere whose locations -and amplitudes are determined by minimizing the cost function: - -.. math:: S(r_1,\dotsc,r_m\ ,\ \mu_1,\dotsc,\mu_m) = \int_{scalp} {(V_{true} - V_{approx})}\,dS - -where :math:`r_1,\dotsc,r_m` and :math:`\mu_1,\dotsc,\mu_m` are -the locations and amplitudes of the approximating dipoles and :math:`V_{true}` and :math:`V_{approx}` are -the potential distributions given by the true and approximative -formulas, respectively. It can be shown that this integral can be -expressed in closed form using an expansion of the potentials in -spherical harmonics. The formula is evaluated for the most superficial -dipoles, *i.e.*, those lying just inside the -inner skull surface. - -.. _c_legacy_BJEFEJJG: - -Field derivatives -================= - -If the ``--grad`` option is specified, mne_forward_solution includes -the derivatives of the forward solution with respect to the dipole -location coordinates to the output file. Let - -.. math:: G_k = [g_{xk} g_{yk} g_{zk}] - -be the :math:`N_{chan} \times 3` matrix containing -the signals produced by three orthogonal dipoles at location :math:`r_k` making -up :math:`N_{chan} \times 3N_{source}` the gain matrix - -.. math:: G = [G_1 \dotso G_{N_{source}}]\ . - -With the ``--grad`` option, the output from mne_forward_solution also -contains the :math:`N_{chan} \times 9N_{source}` derivative matrix - -.. math:: D = [D_1 \dotso D_{N_{source}}]\ , - -where - -.. math:: D_k = [\frac{\delta g_{xk}}{\delta x_k} \frac{\delta g_{xk}}{\delta y_k} \frac{\delta g_{xk}}{\delta z_k} \frac{\delta g_{yk}}{\delta x_k} \frac{\delta g_{yk}}{\delta y_k} \frac{\delta g_{yk}}{\delta z_k} \frac{\delta g_{zk}}{\delta x_k} \frac{\delta g_{zk}}{\delta y_k} \frac{\delta g_{zk}}{\delta z_k}]\ , - -where :math:`x_k`, :math:`y_k`, and :math:`z_k` are the location -coordinates of the :math:`k^{th}` dipole. If -the dipole orientations are to the cortical normal with the ``--fixed`` -option, the dimensions of :math:`G` and :math:`D` are :math:`N_{chan} \times N_{source}` and :math:`N_{chan} \times 3N_{source}`, -respectively. Both :math:`G` and :math:`D` can -be read with the mne_read_forward_solution Matlab -function, see Table 10.1. - -.. _c_legacy_CHDBBFCA: - -Averaging forward solutions -########################### - -Purpose -======= - -One possibility to make a grand average over several runs -of a experiment is to average the data across runs and average the -forward solutions accordingly. For this purpose, :ref:`mne_average_forward_solutions` computes a -weighted average of several forward solutions. The program averages both -MEG and EEG forward solutions. Usually the EEG forward solution is -identical across runs because the electrode locations do not change. diff -Nru python-mne-0.18.1+dfsg/doc/manual/source_localization/c_inverse.rst python-mne-0.19.1+dfsg/doc/manual/source_localization/c_inverse.rst --- python-mne-0.18.1+dfsg/doc/manual/source_localization/c_inverse.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/source_localization/c_inverse.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,534 +0,0 @@ -.. _c_legacy_ch_mne: - -================================== -The minimum-norm current estimates -================================== - -.. contents:: Contents - :local: - :depth: 2 - -Overview -######## - -This page describes the mathematical concepts and the -computation of the minimum-norm estimates. -Using the UNIX commands this is accomplished with two programs: -:ref:`mne_inverse_operator` and :ref:`mne_make_movie` or in Python -using :func:`mne.minimum_norm.make_inverse_operator` -and the ``apply`` functions. The use of these functions is -presented in the tutorial :ref:`tut-inverse-methods`. - -The page starts with a mathematical description of the method. -The interactive program for inspecting data and inverse solutions, -:ref:`mne_analyze`, is covered in :ref:`c_legacy_ch_interactive_analysis`. - -.. _c_legacy_CBBDJFBJ: - -Minimum-norm estimates -###################### - -This section describes the mathematical details of the calculation -of minimum-norm estimates. In Bayesian sense, the ensuing current -distribution is the maximum a posteriori (MAP) estimate under the -following assumptions: - -- The viable locations of the currents - are constrained to the cortex. Optionally, the current orientations - can be fixed to be normal to the cortical mantle. - -- The amplitudes of the currents have a Gaussian prior distribution - with a known source covariance matrix. - -- The measured data contain additive noise with a Gaussian distribution with - a known covariance matrix. The noise is not correlated over time. - -The linear inverse operator -=========================== - -The measured data in the source estimation procedure consists -of MEG and EEG data, recorded on a total of N channels. The task -is to estimate a total of M strengths of sources located on the -cortical mantle. If the number of source locations is P, M = P for -fixed-orientation sources and M = 3P if the source orientations -are unconstrained. The regularized linear inverse operator following -from the Bayesian approach is given by the :math:`M \times N` matrix - -.. math:: M = R' G^T (G R' G^T + C)^{-1}\ , - -where G is the gain matrix relating the source strengths -to the measured MEG/EEG data, :math:`C` is the data noise-covariance matrix -and :math:`R'` is the source covariance matrix. -The dimensions of these matrices are :math:`N \times M`, :math:`N \times N`, -and :math:`M \times M`, respectively. The :math:`M \times 1` source-strength -vector is obtained by multiplying the :math:`N \times 1` data -vector by :math:`M`. - -The expected value of the current amplitudes at time *t* is -then given by :math:`\hat{j}(t) = Mx(t)`, where :math:`x(t)` is -a vector containing the measured MEG and EEG data values at time *t*. - -.. _c_legacy_mne_regularization: - -Regularization -============== - -The a priori variance of the currents is, in practise, unknown. -We can express this by writing :math:`R' = R/ \lambda^2`, -which yields the inverse operator - -.. math:: M = R G^T (G R G^T + \lambda^2 C)^{-1}\ , - -where the unknown current amplitude is now interpreted in -terms of the regularization parameter :math:`\lambda^2`. -Small :math:`\lambda^2` corresponds to large current amplitudes -and complex estimate current patterns while a large :math:`\lambda^2` means the -amplitude of the current is limited and a simpler, smooth, current -estimate is obtained. - -We can arrive in the regularized linear inverse operator -also by minimizing the cost function - -.. math:: S = \tilde{e}^T \tilde{e} + \lambda^2 j^T R^{-1} j\ , - -where the first term consists of the difference between the -whitened measured data (see :ref:`c_legacy_CHDDHAGE`) and those predicted -by the model while the second term is a weighted-norm of the current -estimate. It is seen that, with increasing :math:`\lambda^2`, -the source term receive more weight and larger discrepancy between -the measured and predicted data is tolerable. - -.. _c_legacy_CHDDHAGE: - -Whitening and scaling -===================== - -The MNE software employs data whitening so that a 'whitened' inverse operator -assumes the form - -.. math:: \tilde{M} = R \tilde{G}^T (\tilde{G} R \tilde{G}^T + I)^{-1}\ , - -where :math:`\tilde{G} = C^{-^1/_2}G` is the spatially -whitened gain matrix. The expected current values are :math:`\hat{j} = Mx(t)`, -where :math:`x(t) = C^{-^1/_2}x(t)` is a the whitened measurement -vector at *t*. The spatial whitening operator -is obtained with the help of the eigenvalue decomposition :math:`C = U_C \Lambda_C^2 U_C^T` as :math:`C^{-^1/_2} = \Lambda_C^{-1} U_C^T`. -In the MNE software the noise-covariance matrix is stored as the -one applying to raw data. To reflect the decrease of noise due to -averaging, this matrix, :math:`C_0`, is scaled -by the number of averages, :math:`L`, *i.e.*, :math:`C = C_0 / L`. - -As shown above, regularization of the inverse solution is -equivalent to a change in the variance of the current amplitudes -in the Bayesian *a priori* distribution. - -Convenient choice for the source-covariance matrix :math:`R` is -such that :math:`\text{trace}(\tilde{G} R \tilde{G}^T) / \text{trace}(I) = 1`. With this choice we -can approximate :math:`\lambda^2 \sim 1/SNR`, where SNR is -the (power) signal-to-noise ratio of the whitened data. - -.. note:: - The definition of the signal to noise-ratio/ :math:`\lambda^2` relationship - given above works nicely for the whitened forward solution. In the - un-whitened case scaling with the trace ratio - :math:`\text{trace}(GRG^T) / \text{trace}(C)` - does not make sense, since the diagonal elements summed have, in general, - different units of measure. For example, the MEG data are expressed - in T or T/m whereas the unit of EEG is Volts. - -See :ref:`tut_compute_covariance` for example of noise covariance -computation and whitening. - -.. _c_legacy_cov_regularization: - -Regularization of the noise-covariance matrix -============================================= - -Since finite amount of data is usually available to compute -an estimate of the noise-covariance matrix :math:`C`, -the smallest eigenvalues of its estimate are usually inaccurate -and smaller than the true eigenvalues. Depending on the seriousness -of this problem, the following quantities can be affected: - -- The model data predicted by the current estimate, - -- Estimates of signal-to-noise ratios, which lead to estimates - of the required regularization, see :ref:`c_legacy_mne_regularization`, - -- The estimated current values, and - -- The noise-normalized estimates, see :ref:`c_legacy_noise_normalization`. - -Fortunately, the latter two are least likely to be affected -due to regularization of the estimates. However, in some cases especially -the EEG part of the noise-covariance matrix estimate can be deficient, *i.e.*, -it may possess very small eigenvalues and thus regularization of -the noise-covariance matrix is advisable. - -Historically, the MNE software accomplishes the regularization by replacing -a noise-covariance matrix estimate :math:`C` with - -.. math:: C' = C + \sum_k {\varepsilon_k \bar{\sigma_k}^2 I^{(k)}}\ , - -where the index :math:`k` goes across -the different channel groups (MEG planar gradiometers, MEG axial -gradiometers and magnetometers, and EEG), :math:`\varepsilon_k` are -the corresponding regularization factors, :math:`\bar{\sigma_k}` are -the average variances across the channel groups, and :math:`I^{(k)}` are -diagonal matrices containing ones at the positions corresponding -to the channels contained in each channel group. - -Using the UNIX tools :ref:`mne_inverse_operator`, the values -:math:`\varepsilon_k` can be adjusted with the regularization options -``--magreg`` , ``--gradreg`` , and ``--eegreg`` specified at the time of the -inverse operator decomposition, see :ref:`c_legacy_inverse_operator`. The convenience script -:ref:`mne_do_inverse_operator` has the ``--magreg`` and ``--gradreg`` combined to -a single option, ``--megreg`` , see :ref:`CIHCFJEI`. -Suggested range of values for :math:`\varepsilon_k` is :math:`0.05 \dotso 0.2`. - -.. _c_legacy_mne_solution: - -Computation of the solution -=========================== - -The most straightforward approach to calculate the MNE is -to employ expression for the original or whitened inverse operator -directly. However, for computational convenience we prefer to take -another route, which employs the singular-value decomposition (SVD) -of the matrix - -.. math:: A = \tilde{G} R^{^1/_2} = U \Lambda V^T - -where the superscript :math:`^1/_2` indicates a -square root of :math:`R`. For a diagonal matrix, -one simply takes the square root of :math:`R` while -in the more general case one can use the Cholesky factorization :math:`R = R_C R_C^T` and -thus :math:`R^{^1/_2} = R_C`. - -With the above SVD it is easy to show that - -.. math:: \tilde{M} = R^{^1/_2} V \Gamma U^T - -where the elements of the diagonal matrix :math:`\Gamma` are - -.. math:: \gamma_k = \frac{1}{\lambda_k} \frac{\lambda_k^2}{\lambda_k^2 + \lambda^2}\ . - -With :math:`w(t) = U^T C^{-^1/_2} x(t)` the expression for -the expected current is - -.. math:: \hat{j}(t) = R^C V \Gamma w(t) = \sum_k {\bar{v_k} \gamma_k w_k(t)}\ , - -where :math:`\bar{v_k} = R^C v_k`, :math:`v_k` being -the :math:`k` th column of :math:`V`. It is thus seen that the current estimate is -a weighted sum of the 'modified' eigenleads :math:`v_k`. - -It is easy to see that :math:`w(t) \propto \sqrt{L}`. -To maintain the relation :math:`(\tilde{G} R \tilde{G}^T) / \text{trace}(I) = 1` when :math:`L` changes -we must have :math:`R \propto 1/L`. With this approach, :math:`\lambda_k` is -independent of :math:`L` and, for fixed :math:`\lambda`, -we see directly that :math:`j(t)` is independent -of :math:`L`. - -.. _c_legacy_noise_normalization: - -Noise normalization -=================== - -The noise-normalized linear estimates introduced by Dale -et al. require division of the expected current amplitude by its -variance. Noise normalization serves three purposes: - -- It converts the expected current value - into a dimensionless statistical test variable. Thus the resulting - time and location dependent values are often referred to as dynamic - statistical parameter maps (dSPM). - -- It reduces the location bias of the estimates. In particular, - the tendency of the MNE to prefer superficial currents is eliminated. - -- The width of the point-spread function becomes less dependent - on the source location on the cortical mantle. The point-spread - is defined as the MNE resulting from the signals coming from a point - current source (a current dipole) located at a certain point on - the cortex. - -In practice, noise normalization requires the computation -of the diagonal elements of the matrix - -.. math:: M C M^T = \tilde{M} \tilde{M}^T\ . - -With help of the singular-value decomposition approach we -see directly that - -.. math:: \tilde{M} \tilde{M}^T\ = \bar{V} \Gamma^2 \bar{V}^T\ . - -Under the conditions expressed at the end of :ref:`c_legacy_mne_solution`, it follows that the *t*-statistic values associated -with fixed-orientation sources) are thus proportional to :math:`\sqrt{L}` while -the *F*-statistic employed with free-orientation sources is proportional -to :math:`L`, correspondingly. - -.. note:: A section discussing statistical considerations related to the noise normalization procedure will be added to this manual in one of the subsequent releases. - -.. note:: The MNE software usually computes the square roots of the F-statistic to be displayed on the inflated cortical surfaces. These are also proportional to :math:`\sqrt{L}`. - -.. _c_legacy_CHDCACDC: - -Predicted data -============== - -Under noiseless conditions the SNR is infinite and thus leads -to :math:`\lambda^2 = 0` and the minimum-norm estimate -explains the measured data perfectly. Under realistic conditions, -however, :math:`\lambda^2 > 0` and there is a misfit -between measured data and those predicted by the MNE. Comparison -of the predicted data, here denoted by :math:`x(t)`, -and measured one can give valuable insight on the correctness of -the regularization applied. - -In the SVD approach we easily find - -.. math:: \hat{x}(t) = G \hat{j}(t) = C^{^1/_2} U \Pi w(t)\ , - -where the diagonal matrix :math:`\Pi` has -elements :math:`\pi_k = \lambda_k \gamma_k` The predicted data is -thus expressed as the weighted sum of the 'recolored eigenfields' in :math:`C^{^1/_2} U`. - -.. _c_legacy_patch_stats: - -Cortical patch statistics -========================= - -If the ``--cps`` option was used in source space -creation (see :ref:`setting_up_source_space`) or if mne_add_patch_info described -in :ref:`mne_add_patch_info` was run manually the source space file -will contain for each vertex of the cortical surface the information -about the source space point closest to it as well as the distance -from the vertex to this source space point. The vertices for which -a given source space point is the nearest one define the cortical -patch associated with with the source space point. Once these data -are available, it is straightforward to compute the following cortical -patch statistics (CPS) for each source location :math:`d`: - -- The average over the normals of at the - vertices in a patch, :math:`\bar{n_d}`, - -- The areas of the patches, :math:`A_d`, - and - -- The average deviation of the vertex normals in a patch from - their average, :math:`\sigma_d`, given in degrees. - -The orientation constraints -=========================== - -The principal sources of MEG and EEG signals are generally -believed to be postsynaptic currents in the cortical pyramidal neurons. -Since the net primary current associated with these microscopic -events is oriented normal to the cortical mantle, it is reasonable -to use the cortical normal orientation as a constraint in source -estimation. In addition to allowing completely free source orientations, -the MNE software implements three orientation constraints based -of the surface normal data: - -- Source orientation can be rigidly fixed - to the surface normal direction (the ``--fixed`` option). - If cortical patch statistics are available the average normal over - each patch, :math:`\bar{n_d}`, are used to define - the source orientation. Otherwise, the vertex normal at the source - space location is employed. - -- A *location independent or fixed loose orientation - constraint* (fLOC) can be employed (the ``--loose`` option). - In this approach, a source coordinate system based on the local - surface orientation at the source location is employed. By default, - the three columns of the gain matrix G, associated with a given - source location, are the fields of unit dipoles pointing to the - directions of the x, y, and z axis of the coordinate system employed - in the forward calculation (usually the MEG head coordinate frame). - For LOC the orientation is changed so that the first two source - components lie in the plane normal to the surface normal at the source - location and the third component is aligned with it. Thereafter, the - variance of the source components tangential to the cortical surface are - reduced by a factor defined by the ``--loose`` option. - -- A *variable loose orientation constraint* (vLOC) - can be employed (the ``--loosevar`` option). This is similar - to fLOC except that the value given with the ``--loosevar`` option - will be multiplied by :math:`\sigma_d`, defined above. - -.. _c_legacy_depth_weighting: - -Depth weighting -=============== - -The minimum-norm estimates have a bias towards superficial -currents. This tendency can be alleviated by adjusting the source -covariance matrix :math:`R` to favor deeper source locations. In the depth -weighting scheme employed in MNE analyze, the elements of :math:`R` corresponding -to the :math:`p` th source location are be -scaled by a factor - -.. math:: f_p = (g_{1p}^T g_{1p} + g_{2p}^T g_{2p} + g_{3p}^T g_{3p})^{-\gamma}\ , - -where :math:`g_{1p}`, :math:`g_{2p}`, and :math:`g_{3p}` are the three columns -of :math:`G` corresponding to source location :math:`p` and :math:`\gamma` is -the order of the depth weighting, specified with the ``--weightexp`` option -to mne_inverse_operator . The -maximal amount of depth weighting can be adjusted ``--weightlimit`` option. - -.. _c_legacy_mne_fmri_estimates: - -fMRI-guided estimates -===================== - -The fMRI weighting in MNE software means that the source-covariance matrix -is modified to favor areas of significant fMRI activation. For this purpose, -the fMRI activation map is thresholded first at the value defined by -the ``--fmrithresh`` option to mne_do_inverse_operator or mne_inverse_operator . -Thereafter, the source-covariance matrix values corresponding to -the the sites under the threshold are multiplied by :math:`f_{off}`, set -by the ``--fmrioff`` option. - -It turns out that the fMRI weighting has a strong influence -on the MNE but the noise-normalized estimates are much less affected -by it. - -.. _c_legacy_CBBDGIAE: - -Effective number of averages -############################ - -It is often the case that the epoch to be analyzed is a linear -combination over conditions rather than one of the original averages -computed. As stated above, the noise-covariance matrix computed -is originally one corresponding to raw data. Therefore, it has to -be scaled correctly to correspond to the actual or effective number -of epochs in the condition to be analyzed. In general, we have - -.. math:: C = C_0 / L_{eff} - -where :math:`L_{eff}` is the effective -number of averages. To calculate :math:`L_{eff}` for -an arbitrary linear combination of conditions - -.. math:: y(t) = \sum_{i = 1}^n {w_i x_i(t)} - -we make use of the the fact that the noise-covariance matrix - -.. math:: C_y = \sum_{i = 1}^n {w_i^2 C_{x_i}} = C_0 \sum_{i = 1}^n {w_i^2 / L_i} - -which leads to - -.. math:: 1 / L_{eff} = \sum_{i = 1}^n {w_i^2 / L_i} - -An important special case of the above is a weighted average, -where - -.. math:: w_i = L_i / \sum_{i = 1}^n {L_i} - -and, therefore - -.. math:: L_{eff} = \sum_{i = 1}^n {L_i} - -Instead of a weighted average, one often computes a weighted -sum, a simplest case being a difference or sum of two categories. -For a difference :math:`w_1 = 1` and :math:`w_2 = -1` and -thus - -.. math:: 1 / L_{eff} = 1 / L_1 + 1 / L_2 - -or - -.. math:: L_{eff} = \frac{L_1 L_2}{L_1 + L_2} - -Interestingly, the same holds for a sum, where :math:`w_1 = w_2 = 1`. -Generalizing, for any combination of sums and differences, where :math:`w_i = 1` or :math:`w_i = -1`, :math:`i = 1 \dotso n`, -we have - -.. math:: 1 / L_{eff} = \sum_{i = 1}^n {1/{L_i}} - -.. _c_legacy_inverse_operator: - -Inverse-operator decomposition -############################## - -The program :ref:`mne_inverse_operator` calculates -the decomposition :math:`A = \tilde{G} R^C = U \Lambda \bar{V^T}`, -described in :ref:`c_legacy_mne_solution`. It is normally invoked from the convenience -script :ref:`mne_do_inverse_operator`. - - -.. _c_legacy_movies_and_snapshots: - -Producing movies and snapshots -############################## - -:ref:`mne_make_movie` is a program -for producing movies and snapshot graphics frames without any graphics -output to the screen. In addition, :ref:`mne_make_movie` can -produce stc or w files which contain the numerical current estimate -data in a simple binary format for postprocessing. These files can -be displayed in :ref:`mne_analyze`, -see :ref:`c_legacy_ch_interactive_analysis`, utilized in the cross-subject averaging -process, see :ref:`c_legacy_ch_morph`, -and read into Matlab using the MNE Matlab toolbox, see :ref:`ch_matlab`. - - -.. _c_legacy_computing_inverse: - -Computing inverse from raw and evoked data -########################################## - -The purpose of the utility :ref:`mne_compute_raw_inverse` is -to compute inverse solutions from either evoked-response or raw -data at specified ROIs (labels) and to save the results in a fif -file which can be viewed with :ref:`mne_browse_raw`, -read to Matlab directly using the MNE Matlab Toolbox, see :ref:`ch_matlab`, -or converted to Matlab format using either :ref:`mne_convert_mne_data`, -:ref:`mne_raw2mat`, or :ref:`mne_epochs2mat`. See -:ref:`mne_compute_raw_inverse` for command-line options. - -.. _c_legacy_implementation_details: - -Implementation details -====================== - -The fif files output from mne_compute_raw_inverse have -various fields of the channel information set to facilitate interpretation -by postprocessing software as follows: - -**channel name** - - Will be set to J[xyz] <*number*> , - where the source component is indicated by the coordinat axis name - and number is the vertex number, starting from zero, in the complete - triangulation of the hemisphere in question. - -**logical channel number** - - Will be set to is the vertex number, starting from zero, in the - complete triangulation of the hemisphere in question. - -**sensor location** - - The location of the vertex in head coordinates or in MRI coordinates, - determined by the ``--mricoord`` flag. - -**sensor orientation** - - The *x*-direction unit vector will point to the - direction of the current. Other unit vectors are set to zero. Again, - the coordinate system in which the orientation is expressed depends - on the ``--mricoord`` flag. - -The ``--align_z`` flag tries to align the signs -of the signals at different vertices of the label. For this purpose, -the surface normals within the label are collected into a :math:`n_{vert} \times 3` matrix. -The preferred orientation will be taken as the first right singular -vector of this matrix, corresponding to its largest singular value. -If the dot product of the surface normal of a vertex is negative, -the sign of the estimates at this vertex are inverted. The inversion -is reflected in the current direction vector listed in the channel -information, see above. - -.. note:: The raw data files output by :ref:`mne_compute_raw_inverse` can be converted to mat files with :ref:`mne_raw2mat`. Alternatively, the files can be read directly from Matlab using the routines in the MNE Matlab toolbox, see :ref:`ch_matlab`. The evoked data output can be easily read directly from Matlab using the fiff_load_evoked routine in the MNE Matlab toolbox. Both raw data and evoked output files can be loaded into :ref:`mne_browse_raw`, see :ref:`ch_browse`. diff -Nru python-mne-0.18.1+dfsg/doc/manual/source_localization/c_morph.rst python-mne-0.19.1+dfsg/doc/manual/source_localization/c_morph.rst --- python-mne-0.18.1+dfsg/doc/manual/source_localization/c_morph.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/source_localization/c_morph.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,142 +0,0 @@ -:orphan: - -.. _c_legacy_ch_morph: - -====================== -Morphing and averaging -====================== - -.. contents:: Contents - :local: - :depth: 2 - -Overview -######## - -The spherical morphing of the surfaces accomplished by FreeSurfer can be -employed to bring data from different subjects into a common anatomical -frame. This chapter describes utilities which make use of the spherical morphing -procedure. mne_morph_labels morphs -label files between subjects allowing the definition of labels in -a one brain and transforming them to anatomically analogous labels -in another. mne_average_estimates offers -the capability to compute averages of data computed with the MNE software -across subjects. - -.. _CHDJDHII: - -The morphing maps -################# - -The MNE software accomplishes morphing with help of morphing -maps which can be either computed on demand or precomputed using mne_make_morph_maps , -see :ref:`CHDBBHDH`. The morphing is performed with help -of the registered spherical surfaces (``lh.sphere.reg`` and ``rh.sphere.reg`` ) -which must be produced in FreeSurfer . -A morphing map is a linear mapping from cortical surface values -in subject A (:math:`x^{(A)}`) to those in another -subject B (:math:`x^{(B)}`) - -.. math:: x^{(B)} = M^{(AB)} x^{(A)}\ , - -where :math:`M^{(AB)}` is a sparse matrix -with at most three nonzero elements on each row. These elements -are determined as follows. First, using the aligned spherical surfaces, -for each vertex :math:`x_j^{(B)}`, find the triangle :math:`T_j^{(A)}` on the -spherical surface of subject A which contains the location :math:`x_j^{(B)}`. -Next, find the numbers of the vertices of this triangle and set -the corresponding elements on the *j* th row of :math:`M^{(AB)}` so that :math:`x_j^{(B)}` will -be a linear interpolation between the triangle vertex values reflecting -the location :math:`x_j^{(B)}` within the triangle :math:`T_j^{(A)}`. - -It follows from the above definition that in general - -.. math:: M^{(AB)} \neq (M^{(BA)})^{-1}\ , - -*i.e.*, - -.. math:: x_{(A)} \neq M^{(BA)} M^{(AB)} x^{(A)}\ , - -even if - -.. math:: x^{(A)} \approx M^{(BA)} M^{(AB)} x^{(A)}\ , - -*i.e.*, the mapping is *almost* a -bijection. - -.. _CHDEBAHH: - -About smoothing -############### - -The current estimates are normally defined only in a decimated -grid which is a sparse subset of the vertices in the triangular -tessellation of the cortical surface. Therefore, any sparse set -of values is distributed to neighboring vertices to make the visualized -results easily understandable. This procedure has been traditionally -called smoothing but a more appropriate name -might be smudging or blurring in -accordance with similar operations in image processing programs. - -In MNE software terms, smoothing of the vertex data is an -iterative procedure, which produces a blurred image :math:`x^{(N)}` from -the original sparse image :math:`x^{(0)}` by applying -in each iteration step a sparse blurring matrix: - -.. math:: x^{(p)} = S^{(p)} x^{(p - 1)}\ . - -On each row :math:`j` of the matrix :math:`S^{(p)}` there -are :math:`N_j^{(p - 1)}` nonzero entries whose values -equal :math:`1/N_j^{(p - 1)}`. Here :math:`N_j^{(p - 1)}` is -the number of immediate neighbors of vertex :math:`j` which -had non-zero values at iteration step :math:`p - 1`. -Matrix :math:`S^{(p)}` thus assigns the average -of the non-zero neighbors as the new value for vertex :math:`j`. -One important feature of this procedure is that it tends to preserve -the amplitudes while blurring the surface image. - -Once the indices non-zero vertices in :math:`x^{(0)}` and -the topology of the triangulation are fixed the matrices :math:`S^{(p)}` are -fixed and independent of the data. Therefore, it would be in principle -possible to construct a composite blurring matrix - -.. math:: S^{(N)} = \prod_{p = 1}^N {S^{(p)}}\ . - -However, it turns out to be computationally more effective -to do blurring with an iteration. The above formula for :math:`S^{(N)}` also -shows that the smudging (smoothing) operation is linear. - -.. _CHDBBHDH: - -Precomputing the morphing maps -############################## - -The utility mne_make_morph_maps was -created to assist mne_analyze and mne_make_movie in -morphing. Since the morphing maps described above take a while to -compute, it is beneficial to construct all necessary maps in advance -before using mne_make_movie . - -The precomputed morphing maps are located in ``$SUBJECTS_DIR/morph-maps`` . mne_make_morph_maps creates -this directory automatically if it does not exist. If this directory -exists when mne_analyze or mne_make_movie is run -and morphing is requested, the software first looks for already -existing morphing maps there. Also, if mne_analyze or mne_make_movie have -to recompute any morphing maps, they will be saved to ``$SUBJECTS_DIR/morph-maps`` if -this directory exists. - -The names of the files in ``$SUBJECTS_DIR/morph-maps`` are -of the form: - - <*A*> - <*B*> -``morph.fif`` , - -where <*A*> and <*B*> are -names of subjects. These files contain the maps for both hemispheres, -and in both directions, *i.e.*, both :math:`M^{(AB)}` and :math:`M^{(BA)}`, as -defined above. Thus the files <*A*> - <*B*> -``morph.fif`` or <*B*> - <*A*> -``morph.fif`` are -functionally equivalent. The name of the file produced by mne_analyze or mne_make_movie depends -on the role of <*A*> and <*B*> in -the analysis. - -If you choose to compute the morphing maps in batch in advance, -use :ref:`mne_make_morph_maps`. diff -Nru python-mne-0.18.1+dfsg/doc/manual/source_localization/coil_geometries.rst python-mne-0.19.1+dfsg/doc/manual/source_localization/coil_geometries.rst --- python-mne-0.18.1+dfsg/doc/manual/source_localization/coil_geometries.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/source_localization/coil_geometries.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,266 +0,0 @@ -:orphan: - -.. _implemented_coil_geometries: - -Implemented coil geometries -=========================== - -This section describes the coil geometries currently implemented -in MNE. The coil types fall in two general categories: - -- Axial gradiometers and planar gradiometers - and - -- Planar magnetometers. - -For axial sensors, the *z* axis of the -local coordinate system is parallel to the field component detected, *i.e.*, -normal to the coil plane.For circular coils, the orientation of -the *x* and *y* axes on the -plane normal to the z axis is irrelevant. In the square coils employed -in the Vectorview (TM) system the *x* axis -is chosen to be parallel to one of the sides of the magnetometer -coil. For planar sensors, the *z* axis is likewise -normal to the coil plane and the x axis passes through the centerpoints -of the two coil loops so that the detector gives a positive signal -when the normal field component increases along the *x* axis. - -:ref:`BGBBHGEC` lists the parameters of the *normal* coil -geometry descriptions :ref:`CHDBDFJE` lists the *accurate* descriptions. For simple accuracy, -please consult the coil definition file, see :ref:`BJECIGEB`. -The columns of the tables contain the following data: - -- The number identifying the coil id. - This number is used in the coil descriptions found in the FIF files. - -- Description of the coil. - -- Number of integration points used - -- The locations of the integration points in sensor coordinates. - -- Weights assigned to the field values at the integration points. - Some formulas are listed instead of the numerical values to demonstrate - the principle of the calculation. For example, in the normal coil - descriptions of the planar gradiometers the weights are inverses - of the baseline of the gradiometer to show that the output is in - T/m. - -.. note:: The coil geometry information is stored in the file ``mne/data/coil_def.dat`` - -.. XXX : table of normal coil description is missing - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.1\linewidth}|p{0.25\linewidth}|p{0.2\linewidth}| -.. _BGBBHGEC: -.. table:: Normal coil descriptions. - - +------+-------------------------+----+----------------------------------+----------------------+ - | Id | Description | n | r/mm | w | - +======+=========================+====+==================================+======================+ - | 2 | Neuromag-122 | 2 | (+/-8.1, 0, 0) mm | +/-1 ⁄ 16.2mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 2000 | A point magnetometer | 1 | (0, 0, 0)mm | 1 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3012 | Vectorview type 1 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3013 | Vectorview type 2 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3022 | Vectorview type 1 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3023 | Vectorview type 2 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3024 | Vectorview type 3 | 4 | (+/-5.25, +/-5.25, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 2000 | An ideal point | 1 | (0.0, 0.0, 0.0)mm | 1 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4001 | Magnes WH | 4 | (+/-5.75, +/-5.75, 0.0)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4002 | Magnes WH 3600 | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | - | | axial gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4003 | Magnes reference | 4 | (+/-7.5, +/-7.5, 0.0)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4004 | Magnes reference | 8 | (+/-20, +/-20, 0.0)mm | 1/4 | - | | gradiometer measuring | | (+/-20, +/-20, 135)mm | -1/4 | - | | diagonal gradients | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4005 | Magnes reference | 8 | (87.5, +/-20, 0.0)mm | 1/4 | - | | gradiometer measuring | | (47.5, +/-20, 0.0)mm | -1/4 | - | | off-diagonal gradients | | (-87.5, +/-20, 0.0)mm | 1/4 | - | | | | (-47.5, +/-20, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5001 | CTF 275 axial | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | - | | gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5002 | CTF reference | 4 | (+/-4, +/-4, 0.0)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5003 | CTF reference | 8 | (+/-8.6, +/-8.6, 0.0)mm | 1/4 | - | | gradiometer measuring | | (+/-8.6, +/-8.6, 78.6)mm | -1/4 | - | | diagonal gradients | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - -.. note:: If a plus-minus sign occurs in several coordinates, all possible combinations have to be included. - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.3\linewidth}|p{0.05\linewidth}|p{0.25\linewidth}|p{0.15\linewidth}| -.. _CHDBDFJE: -.. table:: Accurate coil descriptions - - +------+-------------------------+----+----------------------------------+----------------------+ - | Id | Description | n | r/mm | w | - +======+=========================+====+==================================+======================+ - | 2 | Neuromag-122 planar | 8 | +/-(8.1, 0, 0) mm | +/-1 ⁄ 16.2mm | - | | gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 2000 | A point magnetometer | 1 | (0, 0, 0) mm | 1 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3012 | Vectorview type 1 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3013 | Vectorview type 2 | 2 | (+/-8.4, 0, 0.3) mm | +/-1 ⁄ 16.8mm | - | | planar gradiometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3022 | Vectorview type 1 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3023 | Vectorview type 2 | 4 | (+/-6.45, +/-6.45, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 3024 | Vectorview type 3 | 4 | (+/-5.25, +/-5.25, 0.3)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4001 | Magnes WH magnetometer | 4 | (+/-5.75, +/-5.75, 0.0)mm | 1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4002 | Magnes WH 3600 | 4 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | - | | axial gradiometer | | (+/-4.5, +/-4.5, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4004 | Magnes reference | 8 | (+/-20, +/-20, 0.0)mm | 1/4 | - | | gradiometer measuring | | (+/-20, +/-20, 135)mm | -1/4 | - | | diagonal gradients | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 4005 | Magnes reference | 8 | (87.5, +/-20, 0.0)mm | 1/4 | - | | gradiometer measuring | | (47.5, +/-20, 0.0)mm | -1/4 | - | | off-diagonal gradients | | (-87.5, +/-20, 0.0)mm | 1/4 | - | | | | (-47.5, +/-20, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5001 | CTF 275 axial | 8 | (+/-4.5, +/-4.5, 0.0)mm | 1/4 | - | | gradiometer | | (+/-4.5, +/-4.5, 50.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5002 | CTF reference | 4 | (+/-4, +/-4, 0.0)mm | 1/4 | - | | magnetometer | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5003 | CTF 275 reference | 8 | (+/-8.6, +/-8.6, 0.0)mm | 1/4 | - | | gradiometer measuring | | (+/-8.6, +/-8.6, 78.6)mm | -1/4 | - | | diagonal gradients | | | | - +------+-------------------------+----+----------------------------------+----------------------+ - | 5004 | CTF 275 reference | 8 | (47.8, +/-8.5, 0.0)mm | 1/4 | - | | gradiometer measuring | | (30.8, +/-8.5, 0.0)mm | -1/4 | - | | off-diagonal gradients | | (-47.8, +/-8.5, 0.0)mm | 1/4 | - | | | | (-30.8, +/-8.5, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - | 6001 | MIT KIT system axial | 8 | (+/-3.875, +/-3.875, 0.0)mm | 1/4 | - | | gradiometer | | (+/-3.875, +/-3.875, 0.0)mm | -1/4 | - +------+-------------------------+----+----------------------------------+----------------------+ - - -.. _BJECIGEB: - -The coil definition file -======================== - -The coil geometry information is stored in the text file -``mne/data/coil_def.dat``. In this file, any lines starting -with the pound sign (#) are comments. A coil definition starts with -a description line containing the following fields: - -** <*class*>** - - This is a number indicating class of this coil. Possible values - are listed in :ref:`BJEFABHA`. - -** <*id*>** - - Coil id value. This value is listed in the first column of Tables :ref:`BGBBHGEC` and :ref:`CHDBDFJE`. - -** <*accuracy*>** - - The coil representation accuracy. Possible values and their meanings - are listed in :ref:`BJEHIBJC`. - -** <*np*>** - - Number of integration points in this representation. - -** <*size/m*>** - - The size of the coil. For circular coils this is the diameter of - the coil and for square ones the side length of the square. This - information is mainly included to facilitate drawing of the coil - geometry. It should not be employed to infer a coil approximation - for the forward calculations. - -** <*baseline/m*>** - - The baseline of a this kind of a coil. This will be zero for magnetometer - coils. This information is mainly included to facilitate drawing - of the coil geometry. It should not be employed to infer a coil - approximation for the forward calculations. - -** <*description*>** - - Short description of this kind of a coil. If the description contains several - words, it is enclosed in quotes. - -.. _BJEFABHA: - -.. table:: Coil class values - - ======= ======================================================= - Value Meaning - ======= ======================================================= - 1 magnetometer - 2 first-order axial gradiometer - 3 planar gradiometer - 4 second-order axial gradiometer - 1000 an EEG electrode (used internally in software only). - ======= ======================================================= - - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.5\linewidth}| -.. _BJEHIBJC: -.. table:: Coil representation accuracies. - - ======= ===================================================================== - Value Meaning - ======= ===================================================================== - 1 The simplest representation available - 2 The standard or *normal* representation (see :ref:`BGBBHGEC`) - 3 The most *accurate* representation available (see :ref:`CHDBDFJE`) - ======= ===================================================================== - -Each coil description line is followed by one or more integration -point lines, consisting of seven numbers: - -** <*weight*>** - - Gives the weight for this integration point (last column in Tables :ref:`BGBBHGEC` and :ref:`CHDBDFJE`). - -** <*x/m*> <*y/m*> <*z/m*>** - - Indicates the location of the integration point (fourth column in Tables :ref:`BGBBHGEC` and :ref:`CHDBDFJE`). - -** <*nx*> <*ny*> <*nz*>** - - Components of a unit vector indicating the field component to be selected. - Note that listing a separate unit vector for each integration points - allows the implementation of curved coils and coils with the gradiometer - loops tilted with respect to each other. diff -Nru python-mne-0.18.1+dfsg/doc/manual/source_localization/forward.rst python-mne-0.19.1+dfsg/doc/manual/source_localization/forward.rst --- python-mne-0.18.1+dfsg/doc/manual/source_localization/forward.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/source_localization/forward.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,436 +0,0 @@ - - -.. _ch_forward: - -==================== -The forward solution -==================== - -.. contents:: Contents - :local: - :depth: 2 - - -Overview -######## - -This page covers the definitions of different coordinate -systems employed in MNE software and FreeSurfer, the details of -the computation of the forward solutions, and the associated low-level -utilities. - -.. _CHDEDFIB: - -MEG/EEG and MRI coordinate systems -################################## - -The coordinate systems used in MNE software (and FreeSurfer) -and their relationships are depicted in :ref:`CHDFFJIJ`. -Except for the *Sensor coordinates*, all of the -coordinate systems are Cartesian and have the "RAS" (Right-Anterior-Superior) -orientation, *i.e.*, the :math:`x` axis -points to the right, the :math:`y` axis -to the front, and the :math:`z` axis up. - -.. _CHDFFJIJ: - -.. figure:: ../pics/CoordinateSystems.png - :alt: MEG/EEG and MRI coordinate systems - - MEG/EEG and MRI coordinate systems - - The coordinate transforms present in the fif files in MNE and the FreeSurfer files as well as those set to fixed values are indicated with :math:`T_x`, where :math:`x` identifies the transformation. - -The coordinate systems related -to MEG/EEG data are: - -**Head coordinates** - - This is a coordinate system defined with help of the fiducial landmarks - (nasion and the two auricular points). In fif files, EEG electrode - locations are given in this coordinate system. In addition, the head - digitization data acquired in the beginning of an MEG, MEG/EEG, - or EEG acquisition are expressed in head coordinates. For details, - see :ref:`CHDEDFIB`. - -**Device coordinates** - - This is a coordinate system tied to the MEG device. The relationship - of the Device and Head coordinates is determined during an MEG measurement - by feeding current to three to five head-position - indicator (HPI) coils and by determining their locations with respect - to the MEG sensor array from the magnetic fields they generate. - -**Sensor coordinates** - - Each MEG sensor has a local coordinate system defining the orientation - and location of the sensor. With help of this coordinate system, - the numerical integration data needed for the computation of the - magnetic field can be expressed conveniently as discussed in :ref:`BJEIAEIE`. The channel information data in the fif files - contain the information to specify the coordinate transformation - between the coordinates of each sensor and the MEG device coordinates. - -The coordinate systems related -to MRI data are: - -**Surface RAS coordinates** - - The FreeSurfer surface data are expressed in this coordinate system. The - origin of this coordinate system is at the center of the conformed - FreeSurfer MRI volumes (usually 256 x 256 x 256 isotropic 1-mm3 voxels) - and the axes are oriented along the axes of this volume. The BEM - surface and the locations of the sources in the source space are - usually expressed in this coordinate system in the fif files. In - this manual, the *Surface RAS coordinates* are - usually referred to as *MRI coordinates* unless - there is need to specifically discuss the different MRI-related - coordinate systems. - -**RAS coordinates** - - This coordinate system has axes identical to the Surface RAS coordinates but the location of the origin - is different and defined by the original MRI data, i.e. , - the origin is in a scanner-dependent location. There is hardly any - need to refer to this coordinate system explicitly in the analysis - with the MNE software. However, since the Talairach coordinates, - discussed below, are defined with respect to *RAS coordinates* rather - than the *Surface RAS coordinates*, the RAS coordinate - system is implicitly involved in the transformation between Surface RAS coordinates and the two *Talairach* coordinate - systems. - -**MNI Talairach coordinates** - - The definition of this coordinate system is discussed, e.g. , - in http://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach. This - transformation is determined during the FreeSurfer reconstruction - process. - -**FreeSurfer Talairach coordinates** - - The problem with the MNI Talairach coordinates is that the linear MNI - Talairach transform does matched the brains completely to the Talairach - brain. This is probably because the Talairach atlas brain is a rather - odd shape, and as a result, it is difficult to match a standard brain - to the atlas brain using an affine transform. As a result, the MNI - brains are slightly larger (in particular higher, deeper and longer) - than the Talairach brain. The differences are larger as you get - further from the middle of the brain, towards the outside. The FreeSurfer - Talairach coordinates mitigate this problem by additing a an additional - transformation, defined separately for negatice and positive MNI - Talairach :math:`z` coordinates. These two - transformations, denoted by :math:`T_-` and :math:`T_+` in :ref:`CHDFFJIJ`, are fixed as discussed in http://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach - (*Approach 2*). - -The different coordinate systems are related by coordinate -transformations depicted in :ref:`CHDFFJIJ`. The arrows and -coordinate transformation symbols (:math:`T_x`) -indicate the transformations actually present in the FreeSurfer -files. Generally, - -.. math:: \begin{bmatrix} - x_2 \\ - y_2 \\ - z_2 \\ - 1 - \end{bmatrix} = T_{12} \begin{bmatrix} - x_1 \\ - y_1 \\ - z_1 \\ - 1 - \end{bmatrix} = \begin{bmatrix} - R_{11} & R_{12} & R_{13} & x_0 \\ - R_{13} & R_{13} & R_{13} & y_0 \\ - R_{13} & R_{13} & R_{13} & z_0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} \begin{bmatrix} - x_1 \\ - y_1 \\ - z_1 \\ - 1 - \end{bmatrix}\ , - -where :math:`x_k`,:math:`y_k`,and :math:`z_k` are the location -coordinates in two coordinate systems, :math:`T_{12}` is -the coordinate transformation from coordinate system "1" to "2", -:math:`x_0`, :math:`y_0`,and :math:`z_0` is the location of the origin -of coordinate system "1" in coordinate system "2", -and :math:`R_{jk}` are the elements of the rotation -matrix relating the two coordinate systems. The coordinate transformations -are present in different files produced by FreeSurfer and MNE as -summarized in :ref:`CHDJDEDJ`. The fixed transformations :math:`T_-` and :math:`T_+` are: - -.. math:: T_{-} = \begin{bmatrix} - 0.99 & 0 & 0 & 0 \\ - 0 & 0.9688 & 0.042 & 0 \\ - 0 & -0.0485 & 0.839 & 0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} - -and - -.. math:: T_{+} = \begin{bmatrix} - 0.99 & 0 & 0 & 0 \\ - 0 & 0.9688 & 0.046 & 0 \\ - 0 & -0.0485 & 0.9189 & 0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} - -.. note:: This section does not discuss the transformation between the MRI voxel indices and the different MRI coordinates. However, it is important to note that in FreeSurfer, MNE, as well as in Neuromag software an integer voxel coordinate corresponds to the location of the center of a voxel. Detailed information on the FreeSurfer MRI systems can be found at https://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems. - - -.. tabularcolumns:: |p{0.2\linewidth}|p{0.3\linewidth}|p{0.5\linewidth}| -.. _CHDJDEDJ: -.. table:: Coordinate transformations in FreeSurfer and MNE software packages. - - +------------------------------+-------------------------------+--------------------------------------+ - | Transformation | FreeSurfer | MNE | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_1` | Not present | | Measurement data files | - | | | | Forward solution files (`*fwd.fif`)| - | | | | Inverse operator files (`*inv.fif`)| - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_{s_1}\dots T_{s_n}` | Not present | Channel information in files | - | | | containing :math:`T_1`. | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_2` | Not present | | MRI description files Separate | - | | | | coordinate transformation files | - | | | | saved from mne_analyze | - | | | | Forward solution files | - | | | | Inverse operator files | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_3` | `mri/*mgz` files | MRI description files saved with | - | | | mne_make_cor_set if the input is in | - | | | mgz or mgh format. | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_4` | mri/transforms/talairach.xfm | MRI description files saved with | - | | | mne_make_cor_set if the input is in | - | | | mgz or mgh format. | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_-` | Hardcoded in software | MRI description files saved with | - | | | mne_make_cor_set if the input is in | - | | | mgz or mgh format. | - +------------------------------+-------------------------------+--------------------------------------+ - | :math:`T_+` | Hardcoded in software | MRI description files saved with | - | | | mne_make_cor_set if the input is in | - | | | mgz or mgh format. | - +------------------------------+-------------------------------+--------------------------------------+ - -.. note:: The symbols :math:`T_x` are defined in :ref:`CHDFFJIJ`. mne_make_cor_set /mne_setup_mri prior to release 2.6 did not include transformations :math:`T_3`, :math:`T_4`, :math:`T_-`, and :math:`T_+` in the fif files produced. - -.. _BJEBIBAI: - -The head and device coordinate systems -###################################### - -.. figure:: ../pics/HeadCS.png - :alt: Head coordinate system - - The head coordinate system - -The MEG/EEG head coordinate system employed in the MNE software -is a right-handed Cartesian coordinate system. The direction of :math:`x` axis -is from left to right, that of :math:`y` axis -to the front, and the :math:`z` axis thus -points up. - -The :math:`x` axis of the head coordinate -system passes through the two periauricular or preauricular points -digitized before acquiring the data with positive direction to the -right. The :math:`y` axis passes through -the nasion and is normal to the :math:`x` axis. -The :math:`z` axis points up according to -the right-hand rule and is normal to the :math:`xy` plane. - -The origin of the MEG device coordinate system is device -dependent. Its origin is located approximately at the center of -a sphere which fits the occipital section of the MEG helmet best -with :math:`x` axis axis going from left to right -and :math:`y` axis pointing front. The :math:`z` axis -is, again, normal to the :math:`xy` plane -with positive direction up. - -.. note:: The above definition is identical to that of the Neuromag MEG/EEG - (head) coordinate system. However, in 4-D Neuroimaging and CTF MEG - systems the head coordinate frame definition is different. The origin - of the coordinate system is at the midpoint of the left and right - auricular points. The :math:`x` axis passes through the nasion and the - origin with positive direction to the front. The :math:`y` axis is - perpendicular to the :math:`x` axis on the and lies in the plane - defined by the three fiducial landmarks, positive direction from right - to left. The :math:`z` axis is normal to the plane of the landmarks, - pointing up. Note that in this convention the auricular points are not - necessarily located on :math:`y` coordinate axis. The file conversion - utilities take care of these idiosyncrasies and convert all coordinate - information to the MNE software head coordinate frame. - -.. _BJEIAEIE: - -Coil geometry information -######################### - -This Section explains the presentation of MEG detection coil -geometry information the approximations used for different detection -coils in MNE software. Two pieces of information are needed to characterize -the detectors: - -- The location and orientation a local - coordinate system for each detector. - -- A unique identifier, which has an one-to-one correspondence - to the geometrical description of the coil. - -.. note:: MNE ships with several coil geometry configurations. - They can be found in ``mne/data``. - See :ref:`sphx_glr_auto_examples_visualization_plot_meg_sensors.py` - for a comparison between different coil geometries, and - :ref:`implemented_coil_geometries` for detailed information regarding - the files describing Neuromag coil geometries. - -The sensor coordinate system -============================ - -The sensor coordinate system is completely characterized -by the location of its origin and the direction cosines of three -orthogonal unit vectors pointing to the directions of the x, y, -and z axis. In fact, the unit vectors contain redundant information -because the orientation can be uniquely defined with three angles. -The measurement fif files list these data in MEG device coordinates. -Transformation to the MEG head coordinate frame can be easily accomplished -by applying the device-to-head coordinate transformation matrix -available in the data files provided that the head-position indicator -was used. Optionally, the MNE software forward calculation applies -another coordinate transformation to the head-coordinate data to -bring the coil locations and orientations to the MRI coordinate system. - -If :math:`r_0` is a row vector for -the origin of the local sensor coordinate system and :math:`e_x`, :math:`e_y`, -and :math:`e_z` are the row vectors for the -three orthogonal unit vectors, all given in device coordinates, -a location of a point :math:`r_C` in sensor coordinates -is transformed to device coordinates (:math:`r_D`) -by - -.. math:: [r_D 1] = [r_C 1] T_{CD}\ , - -where - -.. math:: T = \begin{bmatrix} - e_x & 0 \\ - e_y & 0 \\ - e_z & 0 \\ - r_{0D} & 1 - \end{bmatrix}\ . - -Calculation of the magnetic field -================================= - -The forward calculation in the MNE software computes the -signals detected by each MEG sensor for three orthogonal dipoles -at each source space location. This requires specification of the -conductor model, the location and orientation of the dipoles, and -the location and orientation of each MEG sensor as well as its coil -geometry. - -The output of each SQUID sensor is a weighted sum of the -magnetic fluxes threading the loops comprising the detection coil. -Since the flux threading a coil loop is an integral of the magnetic -field component normal to the coil plane, the output of the k :sup:`th` -MEG channel, :math:`b_k` can be approximated by: - -.. math:: b_k = \sum_{p = 1}^{N_k} {w_{kp} B(r_{kp}) \cdot n_{kp}} - -where :math:`r_{kp}` are a set of :math:`N_k` integration -points covering the pickup coil loops of the sensor, :math:`B(r_{kp})` is -the magnetic field due to the current sources calculated at :math:`r_{kp}`, -:math:`n_{kp}` are the coil normal directions at these points, and -:math:`w_{kp}` are the weights associated to the integration points. This -formula essentially presents numerical integration of the magnetic field over -the pickup loops of sensor :math:`k`. - - -.. _CHDDIBAH: - -Computing the forward solution -############################## - -Examples on how to compute the forward solution using -:func:`mne.make_forward_solution` can be found -:ref:`plot_forward_compute_forward_solution` and :ref:`BABCHEJD`. - -.. note:: Notice that systems such as CTF and 4D Neuroimaging - data may have been subjected to noise cancellation employing the - data from the reference sensor array. Even though these sensor are - rather far away from the brain sources, this can be taken into account - using :meth:`mne.io.Raw.apply_gradient_compensation`. - See :ref:`plot_brainstorm_phantom_ctf`. - -.. _CHDIAFIG: -.. _ch_forward_spherical_model: - -EEG forward solution in the sphere model -======================================== - -For the computation of the electric potential distribution -on the surface of the head (EEG) it is necessary to define the conductivities -(:math:`\sigma`) and radiuses of the spherically -symmetric layers. Different sphere models can be specified with -through :func:`mne.make_sphere_model`. -Here follows the default structure given when calling ``sphere = mne.make_sphere_model()`` - -.. tabularcolumns:: |p{0.1\linewidth}|p{0.25\linewidth}|p{0.2\linewidth}| -.. _BABEBGDA: -.. table:: Structure of the default EEG model - - ======== ======================= ======================= - Layer Relative outer radius :math:`\sigma` (S/m) - ======== ======================= ======================= - Head 1.0 0.33 - Skull 0.97 0.04 - CSF 0.92 1.0 - Brain 0.90 0.33 - ======== ======================= ======================= - -Although it is not BEM model per se the ``sphere`` structure -describes the head geometry so it can be passed as ``bem`` parameter in -functions such as :func:`mne.fit_dipole`, :func:`mne.viz.plot_alignment` -or :func:`mne.make_forward_solution`. - -When the sphere model is employed to compute the forward model using -:func:`mne.make_forward_solution`, the computation of the -EEG solution can be substantially accelerated by using approximation -methods described by Mosher, Zhang, and Berg, see :ref:`CEGEGDEI` (Mosher *et -al.* and references therein). In such scenario, MNE approximates -the solution with three dipoles in a homogeneous sphere whose locations -and amplitudes are determined by minimizing the cost function: - -.. math:: S(r_1,\dotsc,r_m\ ,\ \mu_1,\dotsc,\mu_m) = \int_{scalp} {(V_{true} - V_{approx})}\,dS - -where :math:`r_1,\dotsc,r_m` and :math:`\mu_1,\dotsc,\mu_m` are -the locations and amplitudes of the approximating dipoles and -:math:`V_{true}` and :math:`V_{approx}` are -the potential distributions given by the true and approximative -formulas, respectively. It can be shown that this integral can be -expressed in closed form using an expansion of the potentials in -spherical harmonics. The formula is evaluated for the most superficial -dipoles, *i.e.*, those lying just inside the -inner skull surface. - -.. note:: See :ref:`Brainstorm CTF phantom dataset tutorial `, - :ref:`Brainstorm Elekta phantom dataset tutorial `, - and :ref:`plot_source_alignment_without_mri`. - -.. _CHDBBFCA: - -Averaging forward solutions -########################### - -Purpose -======= - -One possibility to make a grand average over several runs -of a experiment is to average the data across runs and average the -forward solutions accordingly. For this purpose, -:func:`mne.average_forward_solutions` computes a weighted average of several -forward solutions. The function averages both MEG and EEG forward solutions. -Usually the EEG forward solution is identical across runs because the electrode -locations do not change. diff -Nru python-mne-0.18.1+dfsg/doc/manual/source_localization/inverse.rst python-mne-0.19.1+dfsg/doc/manual/source_localization/inverse.rst --- python-mne-0.18.1+dfsg/doc/manual/source_localization/inverse.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/source_localization/inverse.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,439 +0,0 @@ -.. _ch_mne: - -================================== -The minimum-norm current estimates -================================== - -This page describes the mathematical concepts and the -computation of the minimum-norm estimates needed -in order to obtain the linear inverse operator using -:func:`mne.minimum_norm.make_inverse_operator`. -Its usage is presented in the tutorial :ref:`tut-inverse-methods`. - -.. contents:: Contents - :local: - :depth: 2 - -.. _CBBDJFBJ: - -Minimum-norm estimates -###################### - -This section describes the mathematical details of the calculation -of minimum-norm estimates. In Bayesian sense, the ensuing current -distribution is the maximum a posteriori (MAP) estimate under the -following assumptions: - -- The viable locations of the currents - are constrained to the cortex. Optionally, the current orientations - can be fixed to be normal to the cortical mantle. - -- The amplitudes of the currents have a Gaussian prior distribution - with a known source covariance matrix. - -- The measured data contain additive noise with a Gaussian distribution with - a known covariance matrix. The noise is not correlated over time. - -The linear inverse operator -=========================== - -The measured data in the source estimation procedure consists -of MEG and EEG data, recorded on a total of N channels. The task -is to estimate a total of M strengths of sources located on the -cortical mantle. If the number of source locations is P, M = P for -fixed-orientation sources and M = 3P if the source orientations -are unconstrained. The regularized linear inverse operator following -from the Bayesian approach is given by the :math:`M \times N` matrix - -.. math:: M = R' G^T (G R' G^T + C)^{-1}\ , - -where G is the gain matrix relating the source strengths -to the measured MEG/EEG data, :math:`C` is the data noise-covariance matrix -and :math:`R'` is the source covariance matrix. -The dimensions of these matrices are :math:`N \times M`, :math:`N \times N`, -and :math:`M \times M`, respectively. The :math:`M \times 1` source-strength -vector is obtained by multiplying the :math:`N \times 1` data -vector by :math:`M`. - -The expected value of the current amplitudes at time *t* is -then given by :math:`\hat{j}(t) = Mx(t)`, where :math:`x(t)` is -a vector containing the measured MEG and EEG data values at time *t*. - -.. note:: For computational convenience, in MNE-Python the linear inverse operator is not computed explicitly. See :ref:`mne_solution` for mathematical details, and :ref:`CIHCFJEI` for a detailed example. - -.. _mne_regularization: - -Regularization -============== - -The a priori variance of the currents is, in practise, unknown. -We can express this by writing :math:`R' = R/ \lambda^2`, -which yields the inverse operator - -.. math:: M = R G^T (G R G^T + \lambda^2 C)^{-1}\ , - -where the unknown current amplitude is now interpreted in -terms of the regularization parameter :math:`\lambda^2`. -Small :math:`\lambda^2` corresponds to large current amplitudes -and complex estimate current patterns while a large :math:`\lambda^2` means the -amplitude of the current is limited and a simpler, smooth, current -estimate is obtained. - -We can arrive in the regularized linear inverse operator -also by minimizing the cost function - -.. math:: S = \tilde{e}^T \tilde{e} + \lambda^2 j^T R^{-1} j\ , - -where the first term consists of the difference between the -whitened measured data (see :ref:`CHDDHAGE`) and those predicted -by the model while the second term is a weighted-norm of the current -estimate. It is seen that, with increasing :math:`\lambda^2`, -the source term receive more weight and larger discrepancy between -the measured and predicted data is tolerable. - -.. _CHDDHAGE: - -Whitening and scaling -===================== - -The MNE software employs data whitening so that a 'whitened' inverse operator -assumes the form - -.. math:: \tilde{M} = R \tilde{G}^T (\tilde{G} R \tilde{G}^T + I)^{-1}\ , - -where :math:`\tilde{G} = C^{-^1/_2}G` is the spatially -whitened gain matrix. The expected current values are :math:`\hat{j} = Mx(t)`, -where :math:`x(t) = C^{-^1/_2}x(t)` is a the whitened measurement -vector at *t*. The spatial whitening operator -is obtained with the help of the eigenvalue decomposition :math:`C = U_C \Lambda_C^2 U_C^T` as :math:`C^{-^1/_2} = \Lambda_C^{-1} U_C^T`. -In the MNE software the noise-covariance matrix is stored as the -one applying to raw data. To reflect the decrease of noise due to -averaging, this matrix, :math:`C_0`, is scaled -by the number of averages, :math:`L`, *i.e.*, :math:`C = C_0 / L`. - -As shown above, regularization of the inverse solution is -equivalent to a change in the variance of the current amplitudes -in the Bayesian *a priori* distribution. - -Convenient choice for the source-covariance matrix :math:`R` is -such that :math:`\text{trace}(\tilde{G} R \tilde{G}^T) / \text{trace}(I) = 1`. With this choice we -can approximate :math:`\lambda^2 \sim 1/SNR`, where SNR is -the (power) signal-to-noise ratio of the whitened data. - -.. note:: - The definition of the signal to noise-ratio/ :math:`\lambda^2` relationship - given above works nicely for the whitened forward solution. In the - un-whitened case scaling with the trace ratio - :math:`\text{trace}(GRG^T) / \text{trace}(C)` - does not make sense, since the diagonal elements summed have, in general, - different units of measure. For example, the MEG data are expressed - in T or T/m whereas the unit of EEG is Volts. - -See :ref:`tut_compute_covariance` for example of noise covariance -computation and whitening. - -.. _cov_regularization: - -Regularization of the noise-covariance matrix -============================================= - -Since finite amount of data is usually available to compute -an estimate of the noise-covariance matrix :math:`C`, -the smallest eigenvalues of its estimate are usually inaccurate -and smaller than the true eigenvalues. Depending on the seriousness -of this problem, the following quantities can be affected: - -- The model data predicted by the current estimate, - -- Estimates of signal-to-noise ratios, which lead to estimates - of the required regularization, see :ref:`mne_regularization`, - -- The estimated current values, and - -- The noise-normalized estimates, see :ref:`noise_normalization`. - -Fortunately, the latter two are least likely to be affected -due to regularization of the estimates. However, in some cases especially -the EEG part of the noise-covariance matrix estimate can be deficient, *i.e.*, -it may possess very small eigenvalues and thus regularization of -the noise-covariance matrix is advisable. - -Historically, the MNE software accomplishes the regularization by replacing -a noise-covariance matrix estimate :math:`C` with - -.. math:: C' = C + \sum_k {\varepsilon_k \bar{\sigma_k}^2 I^{(k)}}\ , - -where the index :math:`k` goes across -the different channel groups (MEG planar gradiometers, MEG axial -gradiometers and magnetometers, and EEG), :math:`\varepsilon_k` are -the corresponding regularization factors, :math:`\bar{\sigma_k}` are -the average variances across the channel groups, and :math:`I^{(k)}` are -diagonal matrices containing ones at the positions corresponding -to the channels contained in each channel group. - -See :ref:`plot_compute_covariance_howto` for details. - -.. _mne_solution: -.. _inverse_operator: - -Computation of the solution -=========================== - -The most straightforward approach to calculate the MNE is -to employ expression for the original or whitened inverse operator -directly. However, for computational convenience we prefer to take -another route, which employs the singular-value decomposition (SVD) -of the matrix - -.. math:: A = \tilde{G} R^{^1/_2} = U \Lambda V^T - -where the superscript :math:`^1/_2` indicates a -square root of :math:`R`. For a diagonal matrix, -one simply takes the square root of :math:`R` while -in the more general case one can use the Cholesky factorization :math:`R = R_C R_C^T` and -thus :math:`R^{^1/_2} = R_C`. - -With the above SVD it is easy to show that - -.. math:: \tilde{M} = R^{^1/_2} V \Gamma U^T - -where the elements of the diagonal matrix :math:`\Gamma` are - -.. math:: \gamma_k = \frac{1}{\lambda_k} \frac{\lambda_k^2}{\lambda_k^2 + \lambda^2}\ . - -With :math:`w(t) = U^T C^{-^1/_2} x(t)` the expression for -the expected current is - -.. math:: \hat{j}(t) = R^C V \Gamma w(t) = \sum_k {\bar{v_k} \gamma_k w_k(t)}\ , - -where :math:`\bar{v_k} = R^C v_k`, :math:`v_k` being -the :math:`k` th column of :math:`V`. It is thus seen that the current estimate is -a weighted sum of the 'modified' eigenleads :math:`v_k`. - -It is easy to see that :math:`w(t) \propto \sqrt{L}`. -To maintain the relation :math:`(\tilde{G} R \tilde{G}^T) / \text{trace}(I) = 1` when :math:`L` changes -we must have :math:`R \propto 1/L`. With this approach, :math:`\lambda_k` is -independent of :math:`L` and, for fixed :math:`\lambda`, -we see directly that :math:`j(t)` is independent -of :math:`L`. - -.. note:: This is computed using :func:`mne.minimum_norm.make_inverse_operator` and its usage is illustrated in :ref:`CIHCFJEI`. - -.. _noise_normalization: - -Noise normalization -=================== - -The noise-normalized linear estimates introduced by Dale -et al. require division of the expected current amplitude by its -variance. Noise normalization serves three purposes: - -- It converts the expected current value - into a dimensionless statistical test variable. Thus the resulting - time and location dependent values are often referred to as dynamic - statistical parameter maps (dSPM). - -- It reduces the location bias of the estimates. In particular, - the tendency of the MNE to prefer superficial currents is eliminated. - -- The width of the point-spread function becomes less dependent - on the source location on the cortical mantle. The point-spread - is defined as the MNE resulting from the signals coming from a point - current source (a current dipole) located at a certain point on - the cortex. - -In practice, noise normalization requires the computation -of the diagonal elements of the matrix - -.. math:: M C M^T = \tilde{M} \tilde{M}^T\ . - -With help of the singular-value decomposition approach we -see directly that - -.. math:: \tilde{M} \tilde{M}^T\ = \bar{V} \Gamma^2 \bar{V}^T\ . - -Under the conditions expressed at the end of :ref:`mne_solution`, it follows that the *t*-statistic values associated -with fixed-orientation sources) are thus proportional to :math:`\sqrt{L}` while -the *F*-statistic employed with free-orientation sources is proportional -to :math:`L`, correspondingly. - -.. note:: A section discussing statistical considerations related to the noise normalization procedure will be added to this manual in one of the subsequent releases. - -.. note:: The MNE software usually computes the square roots of the F-statistic to be displayed on the inflated cortical surfaces. These are also proportional to :math:`\sqrt{L}`. - -.. _CHDCACDC: - -Predicted data -============== - -Under noiseless conditions the SNR is infinite and thus leads -to :math:`\lambda^2 = 0` and the minimum-norm estimate -explains the measured data perfectly. Under realistic conditions, -however, :math:`\lambda^2 > 0` and there is a misfit -between measured data and those predicted by the MNE. Comparison -of the predicted data, here denoted by :math:`x(t)`, -and measured one can give valuable insight on the correctness of -the regularization applied. - -In the SVD approach we easily find - -.. math:: \hat{x}(t) = G \hat{j}(t) = C^{^1/_2} U \Pi w(t)\ , - -where the diagonal matrix :math:`\Pi` has -elements :math:`\pi_k = \lambda_k \gamma_k` The predicted data is -thus expressed as the weighted sum of the 'recolored eigenfields' in :math:`C^{^1/_2} U`. - -.. _patch_stats: - -Cortical patch statistics -========================= - -``use_cps`` parameter in -:func:`mne.convert_forward_solution`, and -:func:`mne.minimum_norm.make_inverse_operator` -controls whether to use cortical patch statistics (CPS) to define normal orientations -or not (see :ref:`CHDBBCEJ`). -The CPS contain for each vertex of the cortical surface the information -about the source space point closest to it as well as the distance -from the vertex to this source space point. The vertices for which -a given source space point is the nearest one define the cortical -patch associated with with the source space point. Once these data -are available, it is straightforward to compute the following -for each source location :math:`d`: - -- The average over the normals of at the - vertices in a patch, :math:`\bar{n_d}`, - -- The areas of the patches, :math:`A_d`, - and - -- The average deviation of the vertex normals in a patch from - their average, :math:`\sigma_d`, given in degrees. - -.. _inverse_orientation_constrains: - -The orientation constraints -=========================== - -The principal sources of MEG and EEG signals are generally -believed to be postsynaptic currents in the cortical pyramidal neurons. -Since the net primary current associated with these microscopic -events is oriented normal to the cortical mantle, it is reasonable -to use the cortical normal orientation as a constraint in source -estimation. In addition to allowing completely free source orientations, -the MNE software implements three orientation constraints based -of the surface normal data: - -- Source orientation can be rigidly fixed - by specifying ``fixed=True`` when calling - :func:`mne.minimum_norm.make_inverse_operator`. - In such case, the dipole orientations are - fixed to be orthogonal to the surface of the cortex, pointing outwards. - If cortical patch statistics are available the average normal over - each patch, :math:`\bar{n_d}`, are used to define - the source orientation. Otherwise, the vertex normal at the source - space location is employed. - See :ref:`plot_dipole_orientations_fixed_orientations` - -- A *location independent or fixed loose orientation - constraint* (fLOC) can be employed - by specifying ``fixed=False`` and ``loose=1.0`` when calling - :func:`mne.minimum_norm.make_inverse_operator`. - In this approach, a source coordinate system based on the local - surface orientation at the source location is employed. By default, - the three columns of the gain matrix G, associated with a given - source location, are the fields of unit dipoles pointing to the - directions of the x, y, and z axis of the coordinate system employed - in the forward calculation - (usually the :ref:`MEG head coordinate frame `). - For LOC the orientation is changed so that the first two source - components lie in the plane normal to the surface normal at the source - location and the third component is aligned with it. Thereafter, the - variance of the source components tangential to the cortical surface are - reduced by a factor defined by the ``loose`` parameter. - See :ref:`plot_dipole_orientations_fLOC_orientations` - -- A *variable loose orientation constraint* (vLOC) - can be employed - by specifying ``fixed=False`` and ``loose`` parameters when calling - :func:`mne.minimum_norm.make_inverse_operator`. - This is similar - to fLOC except that the value given with the ``loose`` parameter - will be multiplied by :math:`\sigma_d`, defined above. - See :ref:`plot_dipole_orientations_vLOC_orientations` - -.. _depth_weighting: - -Depth weighting -=============== - -The minimum-norm estimates have a bias towards superficial -currents. This tendency can be alleviated by adjusting the source -covariance matrix :math:`R` to favor deeper source locations. In the depth -weighting scheme employed in MNE analyze, the elements of :math:`R` corresponding -to the :math:`p` th source location are be -scaled by a factor - -.. math:: f_p = (g_{1p}^T g_{1p} + g_{2p}^T g_{2p} + g_{3p}^T g_{3p})^{-\gamma}\ , - -where :math:`g_{1p}`, :math:`g_{2p}`, and :math:`g_{3p}` are the three columns -of :math:`G` corresponding to source location :math:`p` and :math:`\gamma` is -the order of the depth weighting. -The maximal amount of depth weighting can be adjusted with ``depth`` parameter in -:func:`mne.minimum_norm.make_inverse_operator`. - -.. XXX: is there any example/tutorial showing the influence of this parameter? - -.. _CBBDGIAE: - -Effective number of averages -############################ - -It is often the case that the epoch to be analyzed is a linear -combination over conditions rather than one of the original averages -computed. As stated above, the noise-covariance matrix computed -is originally one corresponding to raw data. Therefore, it has to -be scaled correctly to correspond to the actual or effective number -of epochs in the condition to be analyzed. In general, we have - -.. math:: C = C_0 / L_{eff} - -where :math:`L_{eff}` is the effective -number of averages. To calculate :math:`L_{eff}` for -an arbitrary linear combination of conditions - -.. math:: y(t) = \sum_{i = 1}^n {w_i x_i(t)} - -we make use of the the fact that the noise-covariance matrix - -.. math:: C_y = \sum_{i = 1}^n {w_i^2 C_{x_i}} = C_0 \sum_{i = 1}^n {w_i^2 / L_i} - -which leads to - -.. math:: 1 / L_{eff} = \sum_{i = 1}^n {w_i^2 / L_i} - -An important special case of the above is a weighted average, -where - -.. math:: w_i = L_i / \sum_{i = 1}^n {L_i} - -and, therefore - -.. math:: L_{eff} = \sum_{i = 1}^n {L_i} - -Instead of a weighted average, one often computes a weighted -sum, a simplest case being a difference or sum of two categories. -For a difference :math:`w_1 = 1` and :math:`w_2 = -1` and -thus - -.. math:: 1 / L_{eff} = 1 / L_1 + 1 / L_2 - -or - -.. math:: L_{eff} = \frac{L_1 L_2}{L_1 + L_2} - -Interestingly, the same holds for a sum, where :math:`w_1 = w_2 = 1`. -Generalizing, for any combination of sums and differences, where :math:`w_i = 1` or :math:`w_i = -1`, :math:`i = 1 \dotso n`, -we have - -.. math:: 1 / L_{eff} = \sum_{i = 1}^n {1/{L_i}} diff -Nru python-mne-0.18.1+dfsg/doc/manual/source_localization/morph_stc.rst python-mne-0.19.1+dfsg/doc/manual/source_localization/morph_stc.rst --- python-mne-0.18.1+dfsg/doc/manual/source_localization/morph_stc.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/source_localization/morph_stc.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,248 +0,0 @@ -.. _ch_morph: - -================================================================ -Morphing source estimates: Moving data from one brain to another -================================================================ - -Morphing refers to the operation of transferring -:ref:`source estimates ` -from one anatomy to another. It is commonly referred as realignment in fMRI -literature. This operation is necessary for group studies as one needs -then data in a common space. - -In this tutorial we will morph different kinds of source estimation results -between individual subject spaces using :class:`mne.SourceMorph` object. - -We will use precomputed data and morph surface and volume source estimates to a -reference anatomy. The common space of choice will be FreeSurfer's 'fsaverage' -See :ref:`tut-freesurfer` for more -information. Method used for cortical surface data in based -on spherical registration [1]_ and Symmetric Diffeomorphic Registration (SDR) -for volumic data [2]_. - -Furthermore we will convert our volume source estimate into a NIfTI image using -:meth:`morph.apply(..., output='nifti1') `. - -In order to morph :class:`labels ` between subjects allowing the -definition of labels in a one brain and transforming them to anatomically -analogous labels in another use :func:`mne.Label.morph`. - -.. contents:: - :local: - -Why morphing? -============= - -Modern neuroimaging techniques, such as source reconstruction or fMRI analyses, -make use of advanced mathematical models and hardware to map brain activity -patterns into a subject specific anatomical brain space. - -This enables the study of spatio-temporal brain activity. The representation of -spatio-temporal brain data is often mapped onto the anatomical brain structure -to relate functional and anatomical maps. Thereby activity patterns are -overlaid with anatomical locations that supposedly produced the activity. -Anatomical MR images are often used as such or are transformed into an inflated -surface representations to serve as "canvas" for the visualization. - -In order to compute group level statistics, data representations across -subjects must be morphed to a common frame, such that anatomically and -functional similar structures are represented at the same spatial location for -*all subjects equally*. - -Since brains vary, morphing comes into play to tell us how the data -produced by subject A, would be represented on the brain of subject B. - -See also this :ref:`tutorial on surface source estimation ` -or this :ref:`example on volumetric source estimation `. - -Morphing **volume** source estimates -==================================== - -A volumetric source estimate represents functional data in a volumetric 3D -space. The difference between a volumetric representation and a "mesh" ( -commonly referred to as "3D-model"), is that the volume is "filled" while the -mesh is "empty". Thus it is not only necessary to morph the points of the -outer hull, but also the "content" of the volume. - -In MNE-Python, volumetric source estimates are represented as -:class:`mne.VolSourceEstimate`. The morph was successful if functional data of -Subject A overlaps with anatomical data of Subject B, in the same way it does -for Subject A. - -Setting up :class:`mne.SourceMorph` for :class:`mne.VolSourceEstimate` ----------------------------------------------------------------------- - -Morphing volumetric data from subject A to subject B requires a non-linear -registration step between the anatomical T1 image of subject A to -the anatomical T1 image of subject B. - -MNE-Python uses the Symmetric Diffeomorphic Registration [2]_ as implemented -in dipy_ [3]_ (See -`tutorial `_ -from dipy_ for more details). - -:class:`mne.SourceMorph` uses segmented anatomical MR images computed -using :ref:`FreeSurfer ` -to compute the transformations. In order tell SourceMorph which MRIs to use, -``subject_from`` and ``subject_to`` need to be defined as the name of the -respective folder in FreeSurfer's home directory. - -See :ref:`ex-morph-volume` usage and for more details on: - - - How to create a SourceMorph object for volumetric data - - - Apply it to VolSourceEstimate - - - Get the output is NIfTI format - - - Save a SourceMorph object to disk - -Morphing **surface** source estimates -===================================== - -A surface source estimate represents data relative to a 3-dimensional mesh of -the cortical surface computed using FreeSurfer. This mesh is defined by -its vertices. If we want to morph our data from one brain to another, then -this translates to finding the correct transformation to transform each -vertex from Subject A into a corresponding vertex of Subject B. Under the hood -:ref:`FreeSurfer ` -uses spherical representations to compute the morph, as relies on so -called *morphing maps*. - -The morphing maps ------------------ - -The MNE software accomplishes morphing with help of morphing -maps which can be either computed on demand or precomputed. -The morphing is performed with help -of the registered spherical surfaces (``lh.sphere.reg`` and ``rh.sphere.reg`` ) -which must be produced in FreeSurfer. -A morphing map is a linear mapping from cortical surface values -in subject A (:math:`x^{(A)}`) to those in another -subject B (:math:`x^{(B)}`) - -.. math:: x^{(B)} = M^{(AB)} x^{(A)}\ , - -where :math:`M^{(AB)}` is a sparse matrix -with at most three nonzero elements on each row. These elements -are determined as follows. First, using the aligned spherical surfaces, -for each vertex :math:`x_j^{(B)}`, find the triangle :math:`T_j^{(A)}` on the -spherical surface of subject A which contains the location :math:`x_j^{(B)}`. -Next, find the numbers of the vertices of this triangle and set -the corresponding elements on the *j* th row of :math:`M^{(AB)}` so that -:math:`x_j^{(B)}` will be a linear interpolation between the triangle vertex -values reflecting the location :math:`x_j^{(B)}` within the triangle -:math:`T_j^{(A)}`. - -It follows from the above definition that in general - -.. math:: M^{(AB)} \neq (M^{(BA)})^{-1}\ , - -*i.e.*, - -.. math:: x_{(A)} \neq M^{(BA)} M^{(AB)} x^{(A)}\ , - -even if - -.. math:: x^{(A)} \approx M^{(BA)} M^{(AB)} x^{(A)}\ , - -*i.e.*, the mapping is *almost* a bijection. - -Morphing maps can be computed on the fly or read with -:func:`mne.read_morph_map`. Precomputed maps are -located in ``$SUBJECTS_DIR/morph-maps``. - -The names of the files in ``$SUBJECTS_DIR/morph-maps`` are -of the form: - - <*A*> - <*B*> -``morph.fif`` , - -where <*A*> and <*B*> are names of subjects. These files contain the maps -for both hemispheres, and in both directions, *i.e.*, both :math:`M^{(AB)}` -and :math:`M^{(BA)}`, as defined above. Thus the files -<*A*> - <*B*> -``morph.fif`` or <*B*> - <*A*> -``morph.fif`` are -functionally equivalent. The name of the file produced depends on the role -of <*A*> and <*B*> in the analysis. - -About smoothing ---------------- - -The current estimates are normally defined only in a decimated -grid which is a sparse subset of the vertices in the triangular -tessellation of the cortical surface. Therefore, any sparse set -of values is distributed to neighboring vertices to make the visualized -results easily understandable. This procedure has been traditionally -called smoothing but a more appropriate name -might be smudging or blurring in -accordance with similar operations in image processing programs. - -In MNE software terms, smoothing of the vertex data is an -iterative procedure, which produces a blurred image :math:`x^{(N)}` from -the original sparse image :math:`x^{(0)}` by applying -in each iteration step a sparse blurring matrix: - -.. math:: x^{(p)} = S^{(p)} x^{(p - 1)}\ . - -On each row :math:`j` of the matrix :math:`S^{(p)}` there -are :math:`N_j^{(p - 1)}` nonzero entries whose values -equal :math:`1/N_j^{(p - 1)}`. Here :math:`N_j^{(p - 1)}` is -the number of immediate neighbors of vertex :math:`j` which -had non-zero values at iteration step :math:`p - 1`. -Matrix :math:`S^{(p)}` thus assigns the average -of the non-zero neighbors as the new value for vertex :math:`j`. -One important feature of this procedure is that it tends to preserve -the amplitudes while blurring the surface image. - -Once the indices non-zero vertices in :math:`x^{(0)}` and -the topology of the triangulation are fixed the matrices :math:`S^{(p)}` are -fixed and independent of the data. Therefore, it would be in principle -possible to construct a composite blurring matrix - -.. math:: S^{(N)} = \prod_{p = 1}^N {S^{(p)}}\ . - -However, it turns out to be computationally more effective -to do blurring with an iteration. The above formula for :math:`S^{(N)}` also -shows that the smudging (smoothing) operation is linear. - -From theory to practice ------------------------ - -In MNE-Python, surface source estimates are represented as -:class:`mne.SourceEstimate` or :class:`mne.VectorSourceEstimate`. Those can -be used together with :class:`mne.SourceSpaces` or without. - -The morph was successful if functional data of Subject A overlaps with -anatomical surface data of Subject B, in the same way it does for Subject A. - -See :ref:`ex-morph-surface` usage and for more details: - - - How to create a :class:`mne.SourceMorph` object using - :func:`mne.compute_source_morph` for surface data - - - Apply it to :class:`mne.SourceEstimate` or - :class:`mne.VectorSourceEstimate` - - - Save a :class:`mne.SourceMorph` object to disk - -Please see also Gramfort *et al.* (2013) [4]_. - -References -========== -.. [1] Greve D. N., Van der Haegen L., Cai Q., Stufflebeam S., Sabuncu M. - R., Fischl B., Brysbaert M. - A Surface-based Analysis of Language Lateralization and Cortical - Asymmetry. Journal of Cognitive Neuroscience 25(9), 1477-1492, 2013. -.. [2] Avants, B. B., Epstein, C. L., Grossman, M., & Gee, J. C. (2009). - Symmetric Diffeomorphic Image Registration with Cross- Correlation: - Evaluating Automated Labeling of Elderly and Neurodegenerative - Brain, 12(1), 26-41. -.. [3] Garyfallidis E, Brett M, Amirbekian B, Rokem A, van der Walt S, - Descoteaux M, Nimmo-Smith I and Dipy Contributors (2014). DIPY, a - library for the analysis of diffusion MRI data. Frontiers in - Neuroinformatics, vol.8, no.8. -.. [4] Gramfort A., Luessi M., Larson E., Engemann D. A., Strohmeier D., - Brodbeck C., Goj R., Jas. M., Brooks T., Parkkonen L. & Hämäläinen, M. - (2013). MEG and EEG data analysis with MNE-Python. Frontiers in - neuroscience, 7, 267. - -.. _dipy: http://nipy.org/dipy/ diff -Nru python-mne-0.18.1+dfsg/doc/manual/time_frequency.rst python-mne-0.19.1+dfsg/doc/manual/time_frequency.rst --- python-mne-0.18.1+dfsg/doc/manual/time_frequency.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/time_frequency.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,30 +0,0 @@ -==================================== -Spectral and Time-frequency Analysis -==================================== - - -Source Space -^^^^^^^^^^^^ - -Currently, MNE-Python provides a set of functions -allowing to compute spectral analyses in the source space. -Many these functions return :func:`mne.SourceEstimate` objects or collections thereof. - -.. note:: - The :func:`mne.SourceEstimate` object was initially designed for classical time-domain analyses. - In this context, the time axis can actually refer to frequencies. This might be improved - in the future. - - -The following functions are based on minimum norm estimates (MNE). - -- :func:`mne.minimum_norm.compute_source_psd_epochs` returns single-trial power spectral density (PSD) esitmates using multi-tapers. - Here, the time axis actually refers to frequencies, even if labeled as time. - -- :func:`mne.minimum_norm.compute_source_psd` returns power spectral density (PSD) esitmates from continuous data using FFT. - Here, the time axis actually refers to frequencies, even if labeled as time. - -- :func:`mne.minimum_norm.source_band_induced_power` returns a collection of time-domain :func:`mne.SourceEstimate` for each - frequency band, based on Morlet-Wavelets. - -- :func:`mne.minimum_norm.source_induced_power` returns power and inter-trial-coherence (ITC) as raw numpy arrays, based on Morlet-Wavelets. diff -Nru python-mne-0.18.1+dfsg/doc/manual/visualization.rst python-mne-0.19.1+dfsg/doc/manual/visualization.rst --- python-mne-0.18.1+dfsg/doc/manual/visualization.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/manual/visualization.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,5 +0,0 @@ -:orphan: - -============= -Visualization -============= diff -Nru python-mne-0.18.1+dfsg/doc/overview/cite.rst python-mne-0.19.1+dfsg/doc/overview/cite.rst --- python-mne-0.18.1+dfsg/doc/overview/cite.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/cite.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,31 @@ +.. _cite: + +How to cite MNE-Python +====================== + +To cite MNE-C or the inverse imaging implementations provided by the MNE +software, please use: + + A. Gramfort, M. Luessi, E. Larson, D. Engemann, D. Strohmeier, C. Brodbeck, + L. Parkkonen, M. Hämäläinen, `MNE software for processing MEG and EEG data + `_, *NeuroImage*, Volume 86, + 1 February 2014, Pages 446-460, ISSN 1053-8119, + `[DOI] `__ + + +To cite the MNE-Python package, please use: + + A. Gramfort, M. Luessi, E. Larson, D. Engemann, D. Strohmeier, C. Brodbeck, + R. Goj, M. Jas, T. Brooks, L. Parkkonen, M. Hämäläinen, `MEG and EEG data + analysis with MNE-Python + `_, + *Frontiers in Neuroscience*, Volume 7, 2013, ISSN 1662-453X, + `[DOI] `__ + + +To cite specific version numbers of the software, you can use the DOIs provided +by `Zenodo `_. + +Depending on your research topic, it may also be appropriate to cite related +method papers, some of which are listed in :ref:`ch_reading` and in the +documentation strings of the relevant functions or methods. diff -Nru python-mne-0.18.1+dfsg/doc/overview/cookbook.rst python-mne-0.19.1+dfsg/doc/overview/cookbook.rst --- python-mne-0.18.1+dfsg/doc/overview/cookbook.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/cookbook.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,429 @@ +.. _cookbook: + +========================== +The typical M/EEG workflow +========================== + +.. contents:: Contents + :local: + :depth: 2 + +Overview +======== + +This section describes a typical MEG/EEG workflow, eventually up to source +reconstruction. The workflow is summarized in :ref:`flow_diagram`. +References below refer to Python functions and objects. + +.. _flow_diagram: + +.. figure:: images/flow_diagram.svg + :alt: MNE Workflow Flowchart + :align: center + + **Workflow of the MNE software** + + +Preprocessing +============= +The following MEG and EEG data preprocessing steps are recommended: + +- Bad channels in the MEG and EEG data must be identified, see :ref:`marking_bad_channels`. + +- The data has to be filtered to the desired passband. + +- Artifacts should be suppressed (e.g., using ICA or SSP). + +.. _marking_bad_channels: + +Marking bad channels +-------------------- + +Sometimes some MEG or EEG channels are not functioning properly +for various reasons. These channels should be excluded from +analysis by marking them bad as:: + + >>> raw.info['bads'] = ['MEG2443'] # doctest: +SKIP + +Especially if a channel does not show +a signal at all (flat) it is important to exclude it from the +analysis, since its noise estimate will be unrealistically low and +thus the current estimate calculations will give a strong weight +to the zero signal on the flat channels and will essentially vanish. +It is also important to exclude noisy channels because they can +possibly affect others when signal-space projections or EEG average electrode +reference is employed. Noisy bad channels can also adversely affect +averaging and noise-covariance matrix estimation by causing +unnecessary rejections of epochs. + +Recommended ways to identify bad channels are: + +- Observe the quality of data during data + acquisition and make notes of observed malfunctioning channels to + your measurement protocol sheet. + +- View the on-line averages and check the condition of the channels. + +- Compute preliminary off-line averages with artifact rejection, + SSP/ICA, and EEG average electrode reference computation + off and check the condition of the channels. + +- View raw data with :func:`mne.io.Raw.plot` without SSP/ICA + enabled and identify bad channels. + +.. note:: It is strongly recommended that bad channels are identified and + marked in the original raw data files. If present in the raw data + files, the bad channel selections will be automatically transferred + to averaged files, noise-covariance matrices, forward solution + files, and inverse operator decompositions. + +Artifact suppression +-------------------- + +SSP +### + +The Signal-Space Projection (SSP) is one approach to rejection +of external disturbances in software. Unlike many other +noise-cancellation approaches, SSP does +not require additional reference sensors to record the disturbance +fields. Instead, SSP relies on the fact that the magnetic field +distributions generated by the sources in the brain have spatial +distributions sufficiently different from those generated by external +noise sources. Furthermore, it is implicitly assumed that the linear +space spanned by the significant external noise patters has a low +dimension. + +SSP-based rejection is often done using the +:func:`mne.preprocessing.compute_proj_ecg` and +:func:`mne.preprocessing.compute_proj_eog` methods, see +:ref:`tut-projectors-background` and :ref:`tut-artifact-ssp` for more +information. + +ICA +### + +Many M/EEG signals including biological artifacts reflect non-Gaussian +processes. Therefore PCA-based artifact rejection will likely perform worse at +separating the signal from noise sources. + +ICA-based artifact rejection is done using the :class:`mne.preprocessing.ICA` +class, see the :ref:`ica` section for more information. + + +Epoching and evoked data +======================== + +Epoching of raw data is done using events, which define a ``t=0`` for your +data chunks. Event times stamped to the acquisition software can be extracted +using :func:`mne.find_events`:: + + >>> events = mne.find_events(raw) # doctest: +SKIP + +The ``events`` array can then be modified, extended, or changed if necessary. +If the original trigger codes and trigger times are correct for the analysis +of interest, :class:`mne.Epochs` for the first event type (``1``) can be +constructed using:: + + >>> reject = dict(grad=4000e-13, mag=4e-12, eog=150e-6) # doctest: +SKIP + >>> epochs = mne.Epochs(raw, events, event_id=1, tmin=-0.2, tmax=0.5, # doctest: +SKIP + >>> proj=True, picks=picks, baseline=(None, 0), # doctest: +SKIP + >>> preload=True, reject=reject) # doctest: +SKIP + +.. note:: The rejection thresholds (set with argument ``reject``) are defined + in T / m for gradiometers, T for magnetometers and V for EEG and EOG + channels. + + +Rejection using annotations +--------------------------- + +The reject keyword of :class:`mne.Epochs` is used for rejecting bad epochs +based on peak-to-peak thresholds. Bad segments of data can also be rejected +by marking segments of raw data with annotations. See +:ref:`tut-reject-data-spans` and :class:`mne.Annotations` for more . + +Once the :class:`mne.Epochs` are constructed, they can be averaged to obtain +:class:`mne.Evoked` data as:: + + >>> evoked = epochs.average() # doctest: +SKIP + + +Source localization +=================== + +MNE makes extensive use of the FreeSurfer file structure for analysis. +Before starting data analysis, we recommend setting up the environment +variable ``SUBJECTS_DIR`` (or set it permanently using :func:`mne.set_config`) +to select the directory under which the anatomical MRI data are stored. +This makes it so that the ``subjects_dir`` argument does not need to +be passed to many functions. + +Anatomical information +---------------------- + +.. _CHDBBCEJ: + +Cortical surface reconstruction with FreeSurfer +############################################### + +The first processing stage is the creation of various surface +reconstructions with FreeSurfer. The recommended FreeSurfer workflow +is summarized on the `FreeSurfer wiki pages `_. See +also this information :ref:`tut-freesurfer`. + +.. _setting_up_source_space: + +Setting up the source space +########################### + +This stage consists of the following: + +- Creating a suitable decimated dipole grid on the white matter surface. + +- Creating the source space file in fif format. + +This is accomplished with using :func:`mne.setup_source_space` and +:func:`mne.write_source_spaces`. These assume that the anatomical MRI processing +has been completed as described in :ref:`CHDBBCEJ`. + +.. _BABGCDHA: + +.. table:: Recommended subdivisions of an icosahedron and an octahedron for + the creation of source spaces. The approximate source spacing and + corresponding surface area have been calculated assuming a + 1000-cm2 surface area per hemisphere. + + =========== ====================== =================== ============================= + ``spacing`` Sources per hemisphere Source spacing / mm Surface area per source / mm2 + =========== ====================== =================== ============================= + ``'oct5'`` 1026 9.9 97 + ``'ico4'`` 2562 6.2 39 + ``'oct6'`` 4098 4.9 24 + ``'ico5'`` 10242 3.1 9.8 + =========== ====================== =================== ============================= + +For example, to create the reconstruction geometry for ``subject='sample'`` +with a ~5-mm spacing between the grid points, say:: + + >>> src = setup_source_space('sample', spacing='oct6') # doctest: +SKIP + >>> write_source_spaces('sample-oct6-src.fif', src) # doctest: +SKIP + +This creates the source spaces and writes them to disk. + +:ref:`plot_forward_source_space` illustrates how the source space is used to +compute the forward model. + +.. _CHDBJCIA: + +Creating the BEM model meshes +############################# + +Calculation of the forward solution using the boundary-element +model (BEM) requires that the surfaces separating regions of different +electrical conductivities are tessellated with suitable surface +elements. Our BEM software employs triangular tessellations. Therefore, +prerequisites for BEM calculations are the segmentation of the MRI +data and the triangulation of the relevant surfaces. + +For MEG computations, a reasonably accurate solution can +be obtained by using a single-compartment BEM assuming the shape +of the intracranial volume. For EEG, the standard model contains +the intracranial space, the skull, and the scalp. + +At present, no bulletproof method exists for creating the +triangulations. Feasible approaches are described in :ref:`bem-model`. + +.. _BABDBBFC: + +Setting up the head surface triangulation files +############################################### + +The segmentation algorithms described in :ref:`bem-model` produce +either FreeSurfer surfaces or triangulation +data in text. Before proceeding to the creation of the boundary +element model, standard files for FreeSurfer surfaces must be present: + +1. **inner_skull.surf** contains the inner skull triangulation. + +2. **outer_skull.surf** contains the outer skull triangulation. + +3. **outer_skin.surf** contains the head surface triangulation. + +.. _CIHDBFEG: + +Setting up the boundary-element model +##################################### + +This stage sets up the subject-dependent data for computing +the forward solutions:" + + >>> model = make_bem_model('sample') # doctest: +SKIP + >>> write_bem_surfaces('sample-5120-5120-5120-bem.fif', model) # doctest: +SKIP + +Where ``surfaces`` is a list of BEM surfaces that have each been read using +:func:`mne.read_surface`. This step also checks that the input surfaces +are complete and that they are topologically correct, *i.e.*, +that the surfaces do not intersect and that the surfaces are correctly +ordered (outer skull surface inside the scalp and inner skull surface +inside the outer skull). + +This step assigns the conductivity values to the BEM compartments. +For the scalp and the brain compartments, the default is 0.3 S/m. +The default skull conductivity is 50 times smaller, *i.e.*, +0.006 S/m. Recent publications, see :ref:`CEGEGDEI`, report +a range of skull conductivity ratios ranging from 1:15 (Oostendorp *et +al.*, 2000) to 1:25 - 1:50 (Slew *et al.*, +2009, Conçalves *et al.*, 2003). The +MNE default ratio 1:50 is based on the typical values reported in +(Conçalves *et al.*, 2003), since their +approach is based comparison of SEF/SEP measurements in a BEM model. +The variability across publications may depend on individual variations +but, more importantly, on the precision of the skull compartment +segmentation. + +.. note:: To produce single layer BEM models (--homog flag in the C command + line tools) pass a list with one single conductivity value, + e.g. ``conductivities=[0.3]``. + +Using this model, the BEM solution can be computed using +:func:`mne.make_bem_solution` as:: + + >>> bem_sol = make_bem_solution(model) # doctest: +SKIP + >>> write_bem_solution('sample-5120-5120-5120-bem-sol.fif', bem_sol) # doctest: +SKIP + +After the BEM is set up it is advisable to check that the +BEM model meshes are correctly positioned using *e.g.* +:func:`mne.viz.plot_alignment` or :class:`mne.Report`. + +.. note:: Up to this point all processing stages depend on the + anatomical (geometrical) information only and thus remain + identical across different MEG studies. + +.. note:: If you use custom head models you might need to set the ``ico=None`` + parameter to ``None`` and skip subsampling of the surface. + + +.. _CHDBEHDC: + +Aligning coordinate frames +-------------------------- + +The calculation of the forward solution requires knowledge +of the relative location and orientation of the MEG/EEG and MRI +coordinate systems (see :ref:`head_device_coords`). The head coordinate +frame is defined by identifying the fiducial landmark locations, +making the origin and orientation of the head coordinate system +slightly user dependent. As a result, it is safest to reestablish +the definition of the coordinate transformation computation +for each experimental session, *i.e.*, each time when new head +digitization data are employed. + +The corregistration is stored in ``-trans.fif`` file. If is present, +you can follow :ref:`plot_source_alignment` to validate its correctness. +If the ``-trans.fif`` is not present or the alignment is not correct +you need to use :func:`mne.gui.coregistration` (or its convenient command line +equivalent :ref:`gen_mne_coreg`) to generate it. + +.. XXX: It would be good to link to the ``-trans.fif`` file description + +.. warning:: This step is important. If the alignment of the + coordinate frames is inaccurate all subsequent processing + steps suffer from the error. Therefore, this step should be + performed by the person in charge of the study or by a trained + technician. Written or photographic documentation of the alignment + points employed during the MEG/EEG acquisition can also be + helpful. + +.. _computing_the_forward_solution: + +Computing the forward solution +------------------------------ + +After the MRI-MEG/EEG alignment has been set, the forward +solution, *i.e.*, the magnetic fields and electric +potentials at the measurement sensors and electrodes due to dipole +sources located on the cortex, can be calculated with help of +:func:`mne.make_forward_solution` as:: + + >>> fwd = make_forward_solution(raw.info, fname_trans, src, bem_sol) # doctest: +SKIP + +Computing the noise-covariance matrix +------------------------------------- + +The MNE software employs an estimate of the noise-covariance +matrix to weight the channels correctly in the calculations. The +noise-covariance matrix provides information about field and potential +patterns representing uninteresting noise sources of either human +or environmental origin. + +The noise covariance matrix can be calculated in several +ways: + +- Employ the individual epochs during + off-line averaging to calculate the full noise covariance matrix. + This is the recommended approach for evoked responses, *e.g.* using + :func:`mne.compute_covariance`:: + + >>> cov = mne.compute_covariance(epochs, method='auto') # doctest: +SKIP + +- Employ empty room data (collected without the subject) to + calculate the full noise covariance matrix. This is recommended + for analyzing ongoing spontaneous activity. This can be done using + :func:`mne.compute_raw_covariance` as:: + + >>> cov = mne.compute_raw_covariance(raw_erm) # doctest: +SKIP + +- Employ a section of continuous raw data collected in the presence + of the subject to calculate the full noise covariance matrix. This + is the recommended approach for analyzing epileptic activity. The + data used for this purpose should be free of technical artifacts + and epileptic activity of interest. The length of the data segment + employed should be at least 20 seconds. One can also use a long + (``*> 200 s``) segment of data with epileptic spikes present provided + that the spikes occur infrequently and that the segment is apparently + stationary with respect to background brain activity. This can also + use :func:`mne.compute_raw_covariance`. + +.. _CIHCFJEI: + +Calculating the inverse operator +-------------------------------- + +The MNE software doesn't calculate the inverse operator +explicitly but rather computes an SVD of a matrix composed of the +noise-covariance matrix, the result of the forward calculation, +and the source covariance matrix. This approach has the benefit +that the regularization parameter ('SNR') can +be adjusted easily when the final source estimates or dSPMs are +computed. For mathematical details of this approach, +please consult :ref:`minimum_norm_estimates`. + +This computation stage can be done by using +:func:`mne.minimum_norm.make_inverse_operator` as:: + + >>> inv = mne.minimum_norm.make_inverse_operator(raw.info, fwd, cov, loose=0.2) # doctest: +SKIP + +Creating source estimates +------------------------- + +Once all the preprocessing steps described above have been +completed, the inverse operator computed can be applied to the MEG +and EEG data as:: + + >>> stc = mne.minimum_norm.apply_inverse(evoked, inv, lambda2=1. / 9.) # doctest: +SKIP + +And the results can be viewed as:: + + >>> stc.plot() # doctest: +SKIP + +Group analyses +-------------- + +Group analysis is facilitated by morphing source estimates, which can be +done *e.g.*, to ``subject='fsaverage'`` as:: + + >>> morph = mne.compute_source_morph(stc, subject_from='sample', subject_to='fsaverage') # doctest: +SKIP + >>> stc_fsaverage = morph.apply(stc) # doctest: +SKIP + +See :ref:`ch_morph` for more information. diff -Nru python-mne-0.18.1+dfsg/doc/overview/datasets_index.rst python-mne-0.19.1+dfsg/doc/overview/datasets_index.rst --- python-mne-0.18.1+dfsg/doc/overview/datasets_index.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/datasets_index.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,369 @@ +.. _datasets: + +Datasets Overview +################# + +.. sidebar:: Contributing datasets to MNE-Python + + Do not hesitate to contact MNE-Python developers on the + `MNE mailing list `_ + to discuss the possibility of adding more publicly available datasets. + +All the dataset fetchers are available in :mod:`mne.datasets`. To download any of the datasets, +use the ``data_path`` (fetches full dataset) or the ``load_data`` (fetches dataset partially) functions. + +All fetchers will check the default download location first to see if the dataset +is already on your computer, and only download it if necessary. The default +download location is also configurable; see the documentation of any of the +``data_path`` functions for more information. + +.. contents:: Available datasets + :local: + :depth: 2 + + +.. _sample-dataset: + +Sample +====== +:func:`mne.datasets.sample.data_path` + +These data were acquired with the Neuromag +Vectorview system at MGH/HMS/MIT Athinoula A. Martinos Center Biomedical +Imaging. EEG data from a 60-channel electrode cap was acquired simultaneously with +the MEG. The original MRI data set was acquired with a Siemens 1.5 T +Sonata scanner using an MPRAGE sequence. + +.. note:: These data are provided solely for the purpose of getting familiar + with the MNE software. The data should not be used to evaluate the + performance of the MEG or MRI system employed. + +In this experiment, checkerboard patterns were presented to the subject +into the left and right visual field, interspersed by tones to the +left or right ear. The interval between the stimuli was 750 ms. Occasionally +a smiley face was presented at the center of the visual field. +The subject was asked to press a key with the right index finger +as soon as possible after the appearance of the face. + +.. table:: Trigger codes for the sample data set. + + ========= ===== ========================================== + Name Contents + ========= ===== ========================================== + LA 1 Response to left-ear auditory stimulus + RA 2 Response to right-ear auditory stimulus + LV 3 Response to left visual field stimulus + RV 4 Response to right visual field stimulus + smiley 5 Response to the smiley face + button 32 Response triggered by the button press + ========= ===== ========================================== + +Contents of the data set +^^^^^^^^^^^^^^^^^^^^^^^^ + +The sample data set contains two main directories: ``MEG/sample`` (the MEG/EEG +data) and ``subjects/sample`` (the MRI reconstructions). +In addition to subject ``sample``, the MRI surface reconstructions from another +subject, morph, are provided to demonstrate morphing capabilities. + +.. table:: Contents of the MEG/sample directory. + + ======================== ===================================================================== + File Contents + ======================== ===================================================================== + sample/audvis_raw.fif The raw MEG/EEG data + audvis.ave A template script for off-line averaging + auvis.cov A template script for the computation of a noise-covariance matrix + ======================== ===================================================================== + +.. table:: Overview of the contents of the subjects/sample directory. + + ======================= ====================================================================== + File / directory Contents + ======================= ====================================================================== + bem Directory for the forward modelling data + bem/watershed BEM surface segmentation data computed with the watershed algorithm + bem/inner_skull.surf Inner skull surface for BEM + bem/outer_skull.surf Outer skull surface for BEM + bem/outer_skin.surf Skin surface for BEM + sample-head.fif Skin surface in fif format for mne_analyze visualizations + surf Surface reconstructions + mri/T1 The T1-weighted MRI data employed in visualizations + ======================= ====================================================================== + +The following preprocessing steps have been already accomplished +in the sample data set: + +- The MRI surface reconstructions have + been computed using the FreeSurfer software. + +- The BEM surfaces have been created with the watershed algorithm, + see :ref:`bem_watershed_algorithm`. + +The **sample** dataset is distributed with :ref:`fsaverage` for convenience. + +Brainstorm +========== +Dataset fetchers for three Brainstorm tutorials are available. Users must agree to the +license terms of these datasets before downloading them. These files are recorded in a CTF 275 system +and are provided in native CTF format (.ds files). + +Auditory +^^^^^^^^ +:func:`mne.datasets.brainstorm.bst_raw.data_path`. + +Details about the data can be found at the Brainstorm `auditory dataset tutorial`_. + +.. topic:: Examples + + * :ref:`tut-brainstorm-auditory`: Partially replicates the original Brainstorm tutorial. + +Resting state +^^^^^^^^^^^^^ +:func:`mne.datasets.brainstorm.bst_resting.data_path` + +Details can be found at the Brainstorm `resting state dataset tutorial`_. + +.. topic:: Examples + + * :ref:`ex-envelope-correlation` + +Median nerve +^^^^^^^^^^^^ +:func:`mne.datasets.brainstorm.bst_raw.data_path` + +Details can be found at the Brainstorm `median nerve dataset tutorial`_. + +.. topic:: Examples + + * :ref:`ex-brainstorm-raw` + +SPM faces +========= +:func:`mne.datasets.spm_face.data_path` + +The `SPM faces dataset`_ contains EEG, MEG and fMRI recordings on face perception. + +.. topic:: Examples + + * :ref:`ex-spm-faces` Full pipeline including artifact removal, epochs averaging, forward model computation and source reconstruction using dSPM on the contrast: "faces - scrambled". + +EEGBCI motor imagery +==================== +:func:`mne.datasets.eegbci.load_data` + +The EEGBCI dataset is documented in [2]_. The data set is available at PhysioNet [3]_. +The dataset contains 64-channel EEG recordings from 109 subjects and 14 runs on each subject in EDF+ format. +The recordings were made using the BCI2000 system. To load a subject, do:: + + from mne.io import concatenate_raws, read_raw_edf + from mne.datasets import eegbci + raw_fnames = eegbci.load_data(subject, runs) + raws = [read_raw_edf(f, preload=True) for f in raw_fnames] + raw = concatenate_raws(raws) + +.. topic:: Examples + + * :ref:`ex-decoding-csp-eeg` + +.. _somato-dataset: + +Somatosensory +============= +:func:`mne.datasets.somato.data_path` + +This dataset contains somatosensory data with event-related synchronizations +(ERS) and desynchronizations (ERD). + +.. topic:: Examples + + * :ref:`tut-sensors-time-freq` + * :ref:`ex-inverse-source-power` + * :ref:`ex-time-freq-global-field-power` + +Multimodal +========== +:func:`mne.datasets.multimodal.data_path` + +This dataset contains a single subject recorded at Otaniemi (Aalto University) +with auditory, visual, and somatosensory stimuli. + +.. topic:: Examples + + * :ref:`ex-io-ave-fiff` + + +High frequency SEF +================== +:func:`mne.datasets.hf_sef.data_path()` + +This dataset contains somatosensory evoked fields (median nerve stimulation) +with thousands of epochs. It was recorded with an Elekta TRIUX MEG device at +a sampling frequency of 3 kHz. The dataset is suitable for investigating +high-frequency somatosensory responses. Data from two subjects are included +with MRI images in DICOM format and FreeSurfer reconstructions. + +.. topic:: Examples + + * :ref:`high-frequency SEF responses `. + +Visual 92 object categories +=========================== +:func:`mne.datasets.visual_92_categories.data_path`. + +This dataset is recorded using a 306-channel Neuromag vectorview system. + +Experiment consisted in the visual presentation of 92 images of human, animal +and inanimate objects either natural or artificial [4]_. Given the high number +of conditions this dataset is well adapted to an approach based on +Representational Similarity Analysis (RSA). + +.. topic:: Examples + + * :ref:`Representational Similarity Analysis (RSA) `: Partially replicates the results from Cichy et al. (2014). + + +mTRF Dataset +============ +:func:`mne.datasets.mtrf.data_path`. + +This dataset contains 128 channel EEG as well as natural speech stimulus features, +which is also available `here `_. + +The experiment consisted of subjects listening to natural speech. +The dataset contains several feature representations of the speech stimulus, +suitable for using to fit continuous regression models of neural activity. +More details and a description of the package can be found in [5]_. + +.. topic:: Examples + + * :ref:`Receptive Field Estimation and Prediction `: Partially replicates the results from Crosse et al. (2016). + + + +Kiloword dataset +================ +:func:`mne.datasets.kiloword.data_path`. + +This dataset consists of averaged EEG data from 75 subjects performing a lexical decision +task on 960 English words [6]_. The words are richly annotated, and can be used for e.g. +multiple regression estimation of EEG correlates of printed word processing. + + +4D Neuroimaging / BTi dataset +============================= +:func:`mne.datasets.phantom_4dbti.data_path`. + +This dataset was obtained with a phantom on a 4D Neuroimaging / BTi system at the MEG +center in La Timone hospital in Marseille. + +.. topic:: Examples + + * :ref:`tut_phantom_4Dbti` + +OPM +=== +:func:`mne.datasets.opm.data_path` + +OPM data acquired using an Elekta DACQ, simply piping the data into Elekta +magnetometer channels. The FIF files thus appear to come from a TRIUX system +that is only acquiring a small number of magnetometer channels instead of the +whole array. + +The OPM ``coil_type`` is custom, requiring a custom ``coil_def.dat``. +The new ``coil_type`` is 9999. + +OPM co-registration differs a bit from the typical SQUID-MEG workflow. +No ``-trans.fif`` file is needed for the OPMs, the FIF files include proper +sensor locations in MRI coordinates and no digitization of RPA/LPA/Nasion. +Thus the MEG<->Head coordinate transform is taken to be an identity matrix +(i.e., everything is in MRI coordinates), even though this mis-identifies +the head coordinate frame (which is defined by the relationship of the +LPA, RPA, and Nasion). + +Triggers include: + +* Median nerve stimulation: trigger value 257. +* Magnetic trigger (in OPM measurement only): trigger value 260. + 1 second before the median nerve stimulation, a magnetic trigger is piped into the MSR. + This was to be able to check the synchronization between OPMs retrospectively, as each + sensor runs on an independent clock. Synchronization turned out to be satisfactory. + +.. topic:: Examples + + * :ref:`ex-opm-somatosensory` + * :ref:`ex-opm-resting-state` + +The Sleep PolySomnoGraphic Database +=================================== +:func:`mne.datasets.sleep_physionet.age.fetch_data` +:func:`mne.datasets.sleep_physionet.temazepam.fetch_data` + +The sleep PhysioNet database contains 197 whole-night PolySomnoGraphic sleep +recordings, containing EEG, EOG, chin EMG, and event markers. Some records also +contain respiration and body temperature. Corresponding hypnograms (sleep +patterns) were manually scored by well-trained technicians according to the +Rechtschaffen and Kales manual, and are also available. If you use these +data please cite [7]_ and [8]_. + +.. topic:: Examples + + * :ref:`tut-sleep-stage-classif` + +Miscellaneous Datasets +====================== +These datasets are used for specific purposes in the documentation and in +general are not useful for separate analyses. + +.. _fsaverage: + +fsaverage +^^^^^^^^^ +:func:`mne.datasets.fetch_fsaverage` + +For convenience, we provide a function to separately download and extract the +(or update an existing) fsaverage subject. + +.. topic:: Examples + + :ref:`tut-eeg-fsaverage-source-modeling` + + +ECoG Dataset +^^^^^^^^^^^^ +:func:`mne.datasets.misc.data_path`. Data exists at ``/ecog/sample_ecog.mat``. + +This dataset contains a sample Electrocorticography (ECoG) dataset. It includes +a single grid of electrodes placed over the temporal lobe during an auditory +listening task. This dataset is primarily used to demonstrate visualization +functions in MNE and does not contain useful metadata for analysis. + +.. topic:: Examples + + * :ref:`How to convert 3D electrode positions to a 2D image. + `: Demonstrates + how to project a 3D electrode location onto a 2D image, a common procedure + in electrocorticography. + +References +========== + +.. [2] Schalk, G., McFarland, D.J., Hinterberger, T., Birbaumer, N., Wolpaw, J.R. (2004) BCI2000: A General-Purpose Brain-Computer Interface (BCI) System. IEEE TBME 51(6):1034-1043 + +.. [3] Goldberger AL, Amaral LAN, Glass L, Hausdorff JM, Ivanov PCh, Mark RG, Mietus JE, Moody GB, Peng C-K, Stanley HE. (2000) PhysioBank, PhysioToolkit, and PhysioNet: Components of a New Research Resource for Complex Physiologic Signals. Circulation 101(23):e215-e220 + +.. [4] Cichy, R. M., Pantazis, D., & Oliva, A. Resolving human object recognition in space and time. Nature Neuroscience (2014): 17(3), 455-462 + +.. [5] Crosse, M. J., Di Liberto, G. M., Bednar, A., & Lalor, E. C. The Multivariate Temporal Response Function (mTRF) Toolbox: A MATLAB Toolbox for Relating Neural Signals to Continuous Stimuli. Frontiers in Human Neuroscience (2016): 10. + +.. [6] Dufau, S., Grainger, J., Midgley, KJ., Holcomb, PJ. A thousand words are worth a picture: Snapshots of printed-word processing in an event-related potential megastudy. Psychological science, 2015 + +.. [7] B Kemp, AH Zwinderman, B Tuk, HAC Kamphuisen, JJL Oberyé. Analysis of a sleep-dependent neuronal feedback loop: the slow-wave microcontinuity of the EEG. IEEE-BME 47(9):1185-1194 (2000). https://ieeexplore.ieee.org/document/867928 + +.. [8] Goldberger AL, Amaral LAN, Glass L, Hausdorff JM, Ivanov PCh, Mark RG, Mietus JE, Moody GB, Peng C-K, Stanley HE. PhysioBank, PhysioToolkit, and PhysioNet: Components of a New Research Resource for Complex Physiologic Signals. Circulation 101(23):e215-e220 [Circulation Electronic Pages; http://circ.ahajournals.org/cgi/content/full/101/23/e215]; 2000 (June 13). + + +.. _auditory dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetAuditory +.. _resting state dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetResting +.. _median nerve dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetMedianNerveCtf +.. _SPM faces dataset: https://www.fil.ion.ucl.ac.uk/spm/data/mmfaces/ diff -Nru python-mne-0.18.1+dfsg/doc/overview/design_philosophy.rst python-mne-0.19.1+dfsg/doc/overview/design_philosophy.rst --- python-mne-0.18.1+dfsg/doc/overview/design_philosophy.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/design_philosophy.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,94 @@ +.. include:: ../links.inc + +.. _design_philosophy: + +MNE-Python design philosophy +============================ + +Interactive versus scripted analysis +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +MNE-Python has some great interactive plotting abilities that can help you +explore your data, and there are a few GUI-like interactive plotting commands +(like browsing through the raw data and clicking to mark bad channels, or +click-and-dragging to annotate bad temporal spans). But in general it is not +possible to use MNE-Python to mouse-click your way to a finished, publishable +analysis. MNE-Python works best when you assemble your analysis pipeline into +one or more Python scripts. On the plus side, your scripts act as a record of +everything you did in your analysis, making it easy to tweak your analysis +later and/or share it with others (including your future self). + + +Integration with the scientific python stack +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +MNE-Python also integrates well with other standard scientific python +libraries. For example, MNE-Python objects underlyingly store their data in +NumPy arrays, making it easy to apply custom algorithms or pass your data into +one of `scikit-learn's `_ machine learning pipelines. +MNE-Python's 2-D plotting functions also return `matplotlib`_ +:class:`~matplotlib.figure.Figure` objects, and the 3D plotting functions +return `mayavi`_ scenes, so you can customize your MNE-Python plots using any +of matplotlib or mayavi's plotting commands. The intent is that MNE-Python will +get most neuroscientists 90% of the way to their desired analysis goal, and +other packages can get them over the finish line. + + +Submodule-based organization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A useful-to-know organizing principle is that MNE-Python objects and functions +are separated into submodules. This can help you discover related functions if +you're using an editor that supports tab-completion. For example, you can type +:samp:`mne.preprocessing.{}` to see all the functions in the preprocessing +submodule; similarly for visualization functions (:mod:`mne.viz`), functions +for reading and writing data (:mod:`mne.io`), statistics (:mod:`mne.stats`), +etc. This also helps save keystrokes — instead of:: + + import mne + mne.preprocessing.eog.peak_finder(...) + mne.preprocessing.eog.find_eog_events(...) + mne.preprocessing.eog.create_eog_epochs(...) + +you can import submodules directly, and use just the submodule name to access +its functions:: + + from mne.preprocessing import eog + eog.peak_finder(...) + eog.find_eog_events(...) + eog.create_eog_epochs(...) + + +(Mostly) unified API +^^^^^^^^^^^^^^^^^^^^ + +Whenever possible, we've tried to provide a unified API for the different data +classes. For example, the :class:`~mne.io.Raw`, :class:`~mne.Epochs`, +:class:`~mne.Evoked`, and :class:`~mne.SourceEstimate` classes all have a +``plot()`` method that can typically be called with no parameters specified and +still yield an informative plot of the data. Similarly, they all have the +methods ``copy()``, ``crop()``, ``resample()`` and ``save()`` with similar or +identical method signatures. The sensor-level classes also all have an ``info`` +attribute containing an :class:`~mne.Info` object, which keeps track of channel +names and types, applied filters, projectors, etc. See :ref:`tut-info-class` +for more info. + + +In-place operation +^^^^^^^^^^^^^^^^^^ + +Because neuroimaging datasets can be quite large, MNE-Python tries very hard to +avoid making unnecessary copies of your data behind-the-scenes. To further +improve memory efficiency, many object methods operate in-place (and silently +return their object to allow `method chaining`_). In-place operation may lead +you to frequent use of the ``copy()`` method during interactive, exploratory +analysis — so you can try out different preprocessing approaches or parameter +settings without having to re-load the data each time — but it can also be a +big memory-saver when applying a finished script to dozens of subjects' worth +of data. + + + +.. LINKS + +.. _`method chaining`: https://en.wikipedia.org/wiki/Method_chaining diff -Nru python-mne-0.18.1+dfsg/doc/overview/faq.rst python-mne-0.19.1+dfsg/doc/overview/faq.rst --- python-mne-0.18.1+dfsg/doc/overview/faq.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/faq.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,313 @@ +.. include:: ../links.inc + +.. _faq: + +================================ +Frequently Asked Questions (FAQ) +================================ + +.. contents:: Page contents + :local: + + +General MNE-Python issues +========================= + + +Help! I can't get Python and MNE-Python working! +------------------------------------------------ + +Check out our section on how to get Anaconda up and running over at the +:ref:`getting started page `. + + +I still can't get it to work! +----------------------------- + +See :ref:`help`. + + +I can't get Mayavi/3D plotting to work under Windows +---------------------------------------------------- + +If Mayavi plotting in Jupyter Notebooks doesn't work well, using the IPython +magic ``%gui qt`` after importing MNE/Mayavi/PySurfer should `help +`_. + +.. code:: ipython + + from mayavi import mlab + %gui qt + + +How do I cite MNE? +------------------ + +See :ref:`cite`. + + +I'm not sure how to do *X* analysis step with my *Y* data... +------------------------------------------------------------ + +Knowing "the right thing" to do with EEG and MEG data is challenging. We use +the `MNE mailing list`_ to discuss analysis strategies for different kinds of +data. It's worth searching the archives to see if there have been relevant +discussions in the past, but don't hesitate to ask a new question if the answer +isn't out there already. + + +I think I found a bug, what do I do? +------------------------------------ + +If you're *confident* that you've found a bug, head over to the `GitHub issues +page`_ and do a quick search to see if it's already been reported, and if not, +`open a new issue +`__. +If you're *not sure* whether it's a bug, user error, bad data file, etc., try +asking on the `MNE mailing list`_ or the `MNE gitter channel`_ first. In either +case, you should: + +- Try :ref:`using the latest master version ` to see if the + problem persists before reporting the bug, as it may have been fixed since + the latest release. + +- Try to replicate the problem with one of the :ref:`MNE sample datasets + `. If you can't, provide a link to the data file that does yield + the error. + +- Provide the *smallest possible* code sample that replicates the error you're + seeing. Using a `GitHub Public Gist `_ for the code + sample is recommended when using the mailing list; on Gitter use three + backticks (`\`\`\``) at the beginning and end of the code block to separate + it from your question or explanation. + + +Why is it dangerous to "pickle" my MNE-Python objects and data for later use? +----------------------------------------------------------------------------- + +`Pickling `_ data and MNE-Python +objects for later use can be tempting due to its simplicity and generality, but +it is usually not the best option. Pickling is not designed for stable +persistence, and it is likely that you will not be able to read your data in +the not-too-distant future. For details, see: + +- http://www.benfrederickson.com/dont-pickle-your-data/ +- https://stackoverflow.com/questions/21752259/python-why-pickle + +MNE-Python is designed to provide its own file saving formats (often based on +the FIF standard) for its objects usually via a ``save`` method or ``write_*`` +method, e.g. :func:`mne.io.Raw.save`, :func:`mne.Epochs.save`, +:func:`mne.write_evokeds`, :func:`mne.SourceEstimate.save`. If you have some +data that you want to save but can't figure out how, shoot an email to the `MNE +mailing list`_ or post it to the `GitHub issues page`_. + +If you want to write your own data to disk (e.g., subject behavioral scores), +we strongly recommend using `h5io `_, which is +based on the `HDF5 format +`_ and h5py_, to save +data in a fast, future-compatible, standard format. + + +I downloaded a dataset once, but MNE-Python is asking to download it again. Why? +-------------------------------------------------------------------------------- + +The default location for the MNE-sample data is ``~/mne_data``. If you +downloaded data and an example asks you whether to download it again, make sure +the data reside in the examples directory and that you run the script from its +current directory: + +.. code-block:: console + + $ cd examples/preprocessing + +Then in Python you can do:: + + In [1]: %run plot_find_ecg_artifacts.py + +See :ref:`datasets` for a list of all available datasets and some advanced +configuration options, e.g. to specify a custom location for storing the +datasets. + + +.. _faq_cpu: + +A function uses multiple CPU cores even though I didn't tell it to. Why? +------------------------------------------------------------------------ + +Ordinarily in MNE-python the ``parallel`` module is used to deploy multiple +cores via the ``n_jobs`` variable. However, functions like +:func:`mne.preprocessing.maxwell_filter` that use :mod:`scipy.linalg` do not +have an ``n_jobs`` flag but may still use multiple cores. This is because +:mod:`scipy.linalg` is built with linear algebra libraries that natively +support multithreading: + +- `OpenBLAS `_ +- `Intel Math Kernel Library (MKL) `_, + which uses `OpenMP `_ + +To control how many cores are used for linear-algebra-heavy functions like +:func:`mne.preprocessing.maxwell_filter`, you can set the ``OMP_NUM_THREADS`` +or ``OPENBLAS_NUM_THREADS`` environment variable to the desired number of cores +for MKL or OpenBLAS, respectively. This can be done before running Python, or +inside Python you can achieve the same effect by, e.g.:: + + >>> import os + >>> num_cpu = '4' # Set as a string + >>> os.environ['OMP_NUM_THREADS'] = num_cpu + +This must be done *before* running linear algebra functions; subsequent +changes in the same Python session will have no effect. + + +I have a mystery FIF file, how do I read it? +-------------------------------------------- + +The :func:`mne.what` function can be called on any :file:`.fif` file to +identify the kind of data contained in the file. This will help you determine +whether to use :func:`mne.read_cov`, :func:`mne.read_epochs`, +:func:`mne.read_evokeds`, etc. There is also a corresponding command line tool +:ref:`mne what `: + +.. code-block:: console + + $ mne what sample_audvis_eog-eve.fif + events + + +Resampling and decimating data +============================== + +What are all these options for resampling, decimating, and binning data? +------------------------------------------------------------------------ + +There are many functions in MNE-Python for changing the effective sampling rate +of data. We'll discuss some major ones here, with some of their implications: + +- :func:`mne.io.Raw.resample` is used to resample (typically downsample) raw + data. Resampling is the two-step process of applying a low-pass FIR filter + and subselecting samples from the data. + + Using this function to resample data before forming :class:`mne.Epochs` + for final analysis is generally discouraged because doing so effectively + loses precision of (and jitters) the event timings, see + `this gist `_ as + a demonstration. However, resampling raw data can be useful for + (at least): + + - Computing projectors in low- or band-passed data + - Exploring data + +- :func:`mne.preprocessing.ICA.fit` decimates data without low-passing, + but is only used for fitting a statistical model to the data. + +- :func:`mne.Epochs.decimate`, which does the same thing as the + ``decim`` parameter in the :class:`mne.Epochs` constructor, sub-selects every + :math:`N^{th}` sample before and after each event. This should only be + used when the raw data have been sufficiently low-passed e.g. by + :func:`mne.io.Raw.filter` to avoid aliasing artifacts. + +- :func:`mne.Epochs.resample`, :func:`mne.Evoked.resample`, and + :func:`mne.SourceEstimate.resample` all resample data. + This process avoids potential aliasing artifacts because the + resampling process applies a low-pass filter. However, this filtering + introduces edge artifacts. Edge artifacts also exist when using + :func:`mne.io.Raw.resample`, but there the edge artifacts are constrained + to two times: the start and end of the recording. With these three methods, + edge artifacts are introduced to the start and end of every epoch + of data (or the start and end of the :class:`mne.Evoked` or + :class:`mne.SourceEstimate` data), which often has a more pronounced + effect on the data. + +- :func:`mne.SourceEstimate.bin` can be used to decimate, with or without + "binning" (averaging across data points). This is equivalent to applying + a moving-average (boxcar) filter to the data and decimating. A boxcar in + time is a `sinc `_ in + frequency, so this acts as a simplistic, non-ideal low-pass filter; + this will reduce but not eliminate aliasing if data were not sufficiently + low-passed. In the case where the "filter" or bin-width is a single sample + (i.e., an impulse) this operation simplifies to decimation without filtering. + + +Resampling raw data is taking forever! What do I do? +---------------------------------------------------- + +:func:`mne.io.Raw.resample` has a parameter ``npad=='auto'``. This is the +default, but if you've changed it you could try changing it back to ``'auto'``, +it might help. + +If you have an NVIDIA GPU you could also try using :ref:`CUDA`, which can +sometimes speed up filtering and resampling operations by an order of +magnitude. + + +Inverse Solution +================ + + +How should I regularize the covariance matrix? +---------------------------------------------- + +The estimated covariance can be numerically unstable and tends to induce +correlations between estimated source amplitudes and the number of samples +available. It is thus suggested to regularize the noise covariance +matrix (see :ref:`cov_regularization_math`), especially if only few samples +are available. Unfortunately it is not easy to tell the effective number of +samples, hence, to choose the appropriate regularization. In MNE-Python, +regularization is done using advanced regularization methods described in [1]_. +For this the 'auto' option can be used. With this option cross-validation will +be used to learn the optimal regularization:: + + >>> import mne + >>> epochs = mne.read_epochs(epochs_path) # doctest: +SKIP + >>> cov = mne.compute_covariance(epochs, tmax=0., method='auto') # doctest: +SKIP + +This procedure evaluates the noise covariance quantitatively by how well it +whitens the data using the negative log-likelihood of unseen data. The final +result can also be visually inspected. Under the assumption that the baseline +does not contain a systematic signal (time-locked to the event of interest), +the whitened baseline signal should be follow a multivariate Gaussian +distribution, i.e., whitened baseline signals should be between -1.96 and 1.96 +at a given time sample. Based on the same reasoning, the expected value for the +:term:`Global Field Power (GFP) ` is 1 (calculation of the :term:`GFP` +should take into account the true degrees of freedom, e.g. ``ddof=3`` with 2 +active SSP vectors):: + + >>> evoked = epochs.average() # doctest: +SKIP + >>> evoked.plot_white(cov) # doctest: +SKIP + +This plot displays both, the whitened evoked signals for each channels and the +whitened :term:`GFP`. The numbers in the :term:`GFP` panel represent the +estimated rank of the data, which amounts to the effective degrees of freedom +by which the squared sum across sensors is divided when computing the whitened +:term:`GFP`. The whitened :term:`GFP` also helps detecting spurious late evoked +components which can be the consequence of over- or under-regularization. + +Note that if data have been processed using signal space separation (SSS) [2]_, +gradiometers and magnetometers will be displayed jointly because both are +reconstructed from the same SSS basis vectors with the same numerical rank. +This also implies that both sensor types are not any longer linearly +independent. + +These methods for evaluation can be used to assess model violations. Additional +introductory materials can be found `here +`_. + +For expert use cases or debugging the alternative estimators can also be +compared:: + + >>> covs = mne.compute_covariance(epochs, tmax=0., method='auto', return_estimators=True) # doctest: +SKIP + >>> evoked = epochs.average() # doctest: +SKIP + >>> evoked.plot_white(covs) # doctest: +SKIP + +This will plot the whitened evoked for the optimal estimator and display the +:term:`GFPs ` for all estimators as separate lines in the related panel. + +References +---------- + +.. [1] Engemann D. and Gramfort A. (2015) Automated model selection in + covariance estimation and spatial whitening of MEG and EEG signals, + vol. 108, 328-342, NeuroImage. + +.. [2] Taulu, S., Simola, J., Kajola, M., 2005. Applications of the signal + space separation method. IEEE Trans. Signal Proc. 53, 3359–3372. diff -Nru python-mne-0.18.1+dfsg/doc/overview/get_help.rst python-mne-0.19.1+dfsg/doc/overview/get_help.rst --- python-mne-0.18.1+dfsg/doc/overview/get_help.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/get_help.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,16 @@ +.. include:: ../links.inc + +.. _help: + +Getting help +^^^^^^^^^^^^ + +There are three main channels for obtaining help with MNE software tools. + +The `MNE mailing list`_ and `MNE gitter channel`_ are a good place to start for +both troubleshooting and general questions. If you want to request new +features or if you're confident that you have found a bug, please create a new +issue on the `GitHub issues page`_. When reporting bugs, please try to +replicate the bug with the MNE-Python :ref:`sample data `, and +make every effort to simplify your example script to only the elements +necessary to replicate the bug. Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/overview/images/Digitizer-example.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/overview/images/Digitizer-example.png differ diff -Nru python-mne-0.18.1+dfsg/doc/overview/images/flow_diagram.svg python-mne-0.19.1+dfsg/doc/overview/images/flow_diagram.svg --- python-mne-0.18.1+dfsg/doc/overview/images/flow_diagram.svg 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/images/flow_diagram.svg 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,204 @@ + + + + + + +%3 + +cluster0 + +Structural information + + +src + +Source space +mne.SourceSpaces + + +fwd + + + + + + + +Forward solution +mne.forward.Forward + + +src->fwd + + + + +bem + +BEM + + +bem->fwd + + + + +recon + +Freesurfer surfaces + + +recon->src + + +setup_source_space + + +recon->bem + + + + +T1 + +T1 + + +T1->recon + + + + +flashes + +Flash5/30 + + +flashes->bem + + + + +inv + + + + + + + +Inverse operator +mne.minimum_norm.Inverse + + +fwd->inv + + + + +stc + +Source estimate +mne.SourceEstimate + + +inv->stc + + + + +pre + +Preprocessed data +mne.io.Raw + + +epo + +Epoched data +mne.Epochs + + +pre->epo + + +Epochs + + +epo->stc + + +apply_inverse_epochs + + +evo + +Averaged data +mne.Evoked + + +epo->evo + + +epochs.average + + +cov + +Noise covariance +mne.Covariance + + +epo->cov + + +compute_covariance + + +evo->stc + + +apply_inverse + + +cov->inv + + +make_inverse_operator + + +raw + +Raw data +mne.io.Raw + + +raw->pre + + +raw.filter +etc. + + +trans + + + + + + + +Head-MRI trans + + +trans->fwd + + +make_forward_solution + + + diff -Nru python-mne-0.18.1+dfsg/doc/overview/implementation.rst python-mne-0.19.1+dfsg/doc/overview/implementation.rst --- python-mne-0.18.1+dfsg/doc/overview/implementation.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/implementation.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,142 @@ +.. _implementation: + +Algorithms and other implementation details +=========================================== + +This page describes some of the technical details of MNE-Python implementation. + +.. contents:: Page contents + :local: + :depth: 1 + + +.. _units: + +Internal representation (units) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/units.rst + :start-after: units-begin-content + + +.. _precision: + +Floating-point precision +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/precision.rst + :start-after: precision-begin-content + + +.. _channel-types: + +Supported channel types +^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/channel_types.rst + :start-after: channel-types-begin-content + + +.. _data-formats: + +Supported data formats +^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/data_formats.rst + :start-after: data-formats-begin-content + + +.. _dig-formats: + +Supported formats for digitized 3D locations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/dig_formats.rst + :start-after: dig-formats-begin-content + + +.. _memory: + +Memory-efficient I/O +^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/memory.rst + :start-after: memory-begin-content + + +.. _channel-interpolation: + +Bad channel repair via interpolation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/channel_interpolation.rst + :start-after: channel-interpolation-begin-content + :end-before: channel-interpolation-end-content + + +.. _maxwell: + +Maxwell filtering +^^^^^^^^^^^^^^^^^ + +MNE-Python's implementation of Maxwell filtering is described in the +:ref:`tut-artifact-sss` tutorial. + + +.. _ssp-method: + +Signal-Space Projection (SSP) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/ssp.rst + :start-after: ssp-begin-content + + +.. _bem-model: + +The Boundary Element Model (BEM) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/bem_model.rst + :start-after: bem-begin-content + + +.. _ch_forward: + +The forward solution +^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/forward.rst + :start-after: forward-begin-content + + +.. _ch_mne: + +The minimum-norm current estimates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/inverse.rst + :start-after: inverse-begin-content + :end-before: inverse-end-content + + +.. _ch_morph: + +Morphing and averaging source estimates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_includes/morph.rst + :start-after: morph-begin-content + + +References +^^^^^^^^^^ + +.. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989). + Spherical splines for scalp potential and current density mapping. + *Electroencephalography Clinical Neurophysiology* 72(2), 184-187. + doi: 10.1016/0013-4694(89)90180-6 + +.. [2] Dale AM, Fischl B, Sereno MI (1999). "Cortical surface-based analysis. + I. Segmentation and surface reconstruction." *Neuroimage* 9, 179-94. + doi: 10.1006/nimg.1998.0395 diff -Nru python-mne-0.18.1+dfsg/doc/overview/index.rst python-mne-0.19.1+dfsg/doc/overview/index.rst --- python-mne-0.18.1+dfsg/doc/overview/index.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/index.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,60 @@ +:orphan: + +.. include:: ../links.inc + +Documentation overview +====================== + +.. note:: + + If you haven't already installed Python and MNE-Python, here are the + :doc:`installation instructions `, and some resources for + :doc:`learn_python`. + + +The documentation for MNE-Python is divided into four main sections: + +1. The :doc:`../auto_tutorials/index` provide narrative explanations, sample + code, and expected output for the most common MNE-Python analysis tasks. The + emphasis is on thorough explanations that get new users up to speed quickly, + at the expense of covering only a limited number of topics. + +2. The :doc:`Examples Gallery <../auto_examples/index>` provides working code + samples demonstrating various analysis and visualization techniques. These + examples often lack the narrative explanations seen in the tutorials, but + can be a useful way to discover new analysis or plotting ideas, or to see + how a particular technique you've read about can be applied using + MNE-Python. + +3. The :doc:`../glossary` provides short definitions of MNE-Python-specific + vocabulary and general neuroimaging concepts. The glossary is often a good + place to look if you don't understand a term or acronym used somewhere else + in the documentation. + +4. The :doc:`API reference <../python_reference>` provides documentation for + the classes, functions and methods in the MNE-Python codebase. This is the + same information that is rendered when running + :samp:`help(mne.{})` in an interactive Python session, or + when typing :samp:`mne.{}?` in an IPython session or Jupyter + notebook. + +The rest of the MNE-Python documentation pages (parts outside of the four +categories above) are linked here: + +.. toctree:: + :maxdepth: 1 + + faq + design_philosophy + implementation + datasets_index + cookbook + ../generated/commands + migrating + cite + get_help + +Documentation for the related C and MATLAB tools are available here: + +- :ref:`MNE-MATLAB ` (HTML) +- `MNE-C `_ (PDF) diff -Nru python-mne-0.18.1+dfsg/doc/overview/learn_python.rst python-mne-0.19.1+dfsg/doc/overview/learn_python.rst --- python-mne-0.18.1+dfsg/doc/overview/learn_python.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/learn_python.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,29 @@ +:orphan: + +.. include:: ../links.inc + +.. _learn-python: + +Getting started with Python +=========================== + +`Python`_ is a modern general-purpose object-oriented high-level programming +language. There are many general introductions to Python online; here are a +few: + +- The official `Python tutorial `__ +- W3Schools `Python tutorial `__ +- Software Carpentry's `Python lesson `_ + +Additionally, here are a couple tutorials focused on scientific programming in +Python: + +- the `SciPy Lecture Notes `_ +- `NumPy for MATLAB users `_ + +There are also many video tutorials online, including `videos from the annual +SciPy conferences +`_. +One of those is a `Python introduction for complete beginners +`_, but there are many more +lectures on advanced topics available as well. diff -Nru python-mne-0.18.1+dfsg/doc/overview/matlab.rst python-mne-0.19.1+dfsg/doc/overview/matlab.rst --- python-mne-0.18.1+dfsg/doc/overview/matlab.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/matlab.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,1223 @@ +:orphan: + +.. include:: ../links.inc + +.. _mne_matlab: + +======================== +MNE-MATLAB documentation +======================== + +.. contents:: Page contents + :local: + :depth: 2 + +.. note:: The MNE MATLAB Toolbox is compatible with Matlab versions 7.0 or later. + +Overview +######## + +The MNE software contains a collection Matlab ``.m``-files to +facilitate interfacing with binary file formats of the MNE software. +The toolbox is located at ``$MNE_ROOT/share/matlab`` . The +names of the MNE Matlab toolbox functions begin either with `mne_` or +with `fiff_` . When you source the ``mne_setup`` script +as described in :ref:`user_environment`, one of the following actions +takes place: + +- If you do not have the Matlab startup.m + file, it will be created and lines allowing access to the MNE Matlab + toolbox are added. + +- If you have startup.m and it does not have the standard MNE + Matlab toolbox setup lines, you will be instructed to add them manually. + +- If you have startup.m and the standard MNE Matlab toolbox + setup lines are there, nothing happens. + +A summary of the available routines is provided in the `MNE-C manual`_. The +toolbox also contains a set of examples which may be useful starting points +for your own development. The names of these functions start with ``mne_ex``. + +.. note:: + + The MATLAB function ``fiff_setup_read_raw`` has a significant change. The + sample numbers now take into account possible initial skip in the file, + *i.e.*, the time between the start of the data acquisition and the start of + saving the data to disk. The ``first_samp`` member of the returned structure + indicates the initial skip in samples. If you want your own routines, which + assume that initial skip has been removed, perform identically with the + previous version, subtract ``first_samp`` from the sample numbers you + specify to ``fiff_read_raw_segment``. Furthermore, ``fiff_setup_read_raw`` + has an optional argument to allow reading of unprocessed MaxShield data + acquired with the Elekta MEG systems. + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. _BGBCGHAG: +.. table:: High-level reading routines. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | fiff_find_evoked | Find all evoked data sets from a file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_bad_channels | Read the bad channel list. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_ctf_comp | Read CTF software gradient compensation data. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_evoked | Read evoked-response data. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_evoked_all | Read all evoked-response data from a file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_meas_info | Read measurement information. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_mri | Read an MRI description file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_proj | Read signal-space projection data. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_raw_segment | Read a segment of raw data with time limits are specified | + | | in samples. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_raw_segment_times | Read a segment of raw data with time limits specified | + | | in seconds. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_setup_read_raw | Set up data structures before using fiff_read_raw_segment | + | | or fiff_read_raw_segment_times. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: Channel selection utilities. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | fiff_pick_channels | Create a selector to pick desired channels from data | + | | according to include and exclude lists. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_pick_channels_evoked | Pick desired channels from evoked-response data according | + | | to include and exclude lists. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_pick_info | Modify measurement info to include only selected channels. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_pick_types | Create a selector to pick desired channels from data | + | | according to channel types (MEG, EEG, STIM) in combination | + | | with include and exclude lists. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_pick_types_evoked | Pick desired channels from evoked-response data according | + | | to channel types (MEG, EEG, STIM) in combination with | + | | include and exclude lists. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: Coordinate transformation utilities. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | fiff_invert_transform | Invert a coordinate transformation structure. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_reset_ch_pos | Reset channel position transformation to the default values | + | | present in the file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_transform_eeg_chs | Transform electrode positions to another coordinate frame. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_transform_meg_chs | Apply a coordinate transformation to the sensor location | + | | data to bring the integration points to another coordinate | + | | frame. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: Basic reading routines. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | fiff_define_constants | Define a structure which contains the constant relevant | + | | to fif files. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_dir_tree_find | Find nodes of a given type in a directory tree structure. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_list_dir_tree | List a directory tree structure. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_make_dir_tree | Create a directory tree structure. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_open | Open a fif file and create the directory tree structure. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_named_matrix | Read a named matrix from a fif file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_tag | Read one tag from a fif file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_read_tag_info | Read the info of one tag from a fif file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_split_name_list | Split a colon-separated list of names into a cell array | + | | of strings. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: Writing routines. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | fiff_end_block | Write a FIFF_END_BLOCK tag. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_end_file | Write the standard closing. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_start_block | Write a FIFF_START_BLOCK tag. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_start_file | Write the appropriate beginning of a file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_ch_info | Write a channel information structure. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_coord_trans | Write a coordinate transformation structure. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_ctf_comp | Write CTF compensation data. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_dig_point | Write one digitizer data point. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_complex | Write single-precision complex numbers. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_complex_matrix | Write a single-precision complex matrix. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_double | Write double-precision floats. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_double_complex | Write double-precision complex numbers. | + +--------------------------------+--------------------------------------------------------------+ + |fiff_write_double_complex_matrix| Write a double-precision complex matrix. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_double_matrix | Write a double-precision matrix. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_evoked | Write an evoked-reponse data file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_float | Write single-precision floats. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_float_matrix | Write a single-precision matrix. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_id | Write an id tag. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_int | Write 32-bit integers. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_int_matrix | Write a matrix of 32-bit integers. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_name_list | Write a name list. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_named_matrix | Write a named matrix. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_proj | Write SSP data. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_short | Write 16-bit integers. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_string | Write a string. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: High-level data writing routines. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | fiff_write_evoked | Write an evoked-response data file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_finish_writing_raw | Write the closing tags to a raw data file. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_start_writing_raw | Start writing raw data file, *i.e.*, write the measurement | + | | information. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_dig_file | Write a fif file containing digitization data. | + +--------------------------------+--------------------------------------------------------------+ + | fiff_write_raw_buffer | Write one raw data buffer. This is used after a call to | + | | fiff_start_writing_raw. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: Coil definition utilities. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | mne_add_coil_defs | Add coil definitions to an array of channel information | + | | structures. | + +--------------------------------+--------------------------------------------------------------+ + | mne_load_coil_def | Load a coil definition file. | + +--------------------------------+--------------------------------------------------------------+ + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: Routines for software gradient compensation and signal-space projection. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | mne_compensate_to | Apply or remove CTF software gradient compensation from | + | | evoked-response data. | + +--------------------------------+--------------------------------------------------------------+ + | mne_get_current_comp | Get the state of software gradient compensation from | + | | measurement info. | + +--------------------------------+--------------------------------------------------------------+ + | mne_make_compensator | Make a compensation matrix which switches the status of | + | | CTF software gradient compensation from one state to another.| + +--------------------------------+--------------------------------------------------------------+ + | mne_make_projector_info | Create a signal-space projection operator with the | + | | projection item definitions and cell arrays of channel names | + | | and bad channel names as input. | + +--------------------------------+--------------------------------------------------------------+ + | mne_make_projector_info | Like mne_make_projector but uses the measurement info | + | | structure as input. | + +--------------------------------+--------------------------------------------------------------+ + | mne_set_current_comp | Change the information about the compensation status in | + | | measurement info. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: High-level routines for reading MNE data files. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | mne_pick_channels_cov | Pick desired channels from a sensor covariance matrix. | + +--------------------------------+--------------------------------------------------------------+ + | mne_pick_channels_forward | Pick desired channels (rows) from a forward solution. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_bem_surfaces | Read triangular tessellations of surfaces for | + | | boundary-element models. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_cov | Read a covariance matrix. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_epoch | Read an epoch of data from the output file of mne_epochs2mat.| + +--------------------------------+--------------------------------------------------------------+ + | mne_read_events | Read an event list from a fif file produced by | + | | mne_browse_raw or mne_process_raw. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_forward_solution | Read a forward solution from a fif file. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_inverse_operator | Read an inverse operator from a fif file. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_morph_map | Read an morphing map produced with mne_make_morph_maps. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_noise_cov | Read a noise-covariance matrix from a fif file. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_source_spaces | Read source space information from a fif file. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: High-level routines for writing MNE data files. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | mne_write_cov | Write a covariance matrix to an open file. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_cov_file | Write a complete file containing just a covariance matrix. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_events | Write a fif format event file compatible with mne_browse_raw | + | | and mne_process_raw. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_inverse_sol_stc | Write stc files containing an inverse solution or other | + | | dynamic data on the cortical surface. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_inverse_sol_w | Write w files containing an inverse solution or other static | + | | data on the cortical surface. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. _BABBDDAI: +.. table:: Routines related to stc, w, and label files. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | mne_read_stc_file | Read data from one stc file. The vertex numbering in the | + | | returned structure will start from 0. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_stc_file1 | Read data from one stc file. The vertex numbering in the | + | | returned structure will start from 1. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_w_file | Read data from one w file. The vertex numbering in the | + | | returned structure will start from 0. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_w_file1 | Read data from one w file. The vertex numbering in the | + | | returned structure will start from 1. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_stc_file | Write a new stc file. It is assumed the the vertex numbering | + | | in the input data structure containing the stc information | + | | starts from 0. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_stc_file1 | Write a new stc file. It is assumed the the vertex numbering | + | | in the input data structure containing the stc information | + | | starts from 1. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_w_file | Write a new w file. It is assumed the the vertex numbering | + | | in the input data structure containing the w file | + | | information starts from 0. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_w_file1 | Write a new w file. It is assumed the the vertex numbering | + | | in the input data structure containing the w file | + | | information starts from 1. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_label_file | Read a label file (ROI). | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_label_file | Write a label file (ROI). | + +--------------------------------+--------------------------------------------------------------+ + | mne_label_time_courses | Extract time courses corresponding to a label from an | + | | stc file. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. table:: Routines for reading FreeSurfer surfaces. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | mne_read_curvature | Read a curvature file. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_surface | Read one surface, return the vertex locations and | + | | triangulation info. | + +--------------------------------+--------------------------------------------------------------+ + | mne_read_surfaces | Read surfaces corresponding to one or both hemispheres. | + | | Optionally read curvature information and add derived | + | | surface data. | + +--------------------------------+--------------------------------------------------------------+ + | mne_reduce_surface | Reduce the number of triangles on a surface using the | + | | reducepatch Matlab function. | + +--------------------------------+--------------------------------------------------------------+ + | mne_write_surface | Write a FreeSurfer surface file. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. _BGBEGFBD: +.. table:: Utility functions. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | mne_block_diag | Create a sparse block-diagonal matrix out of a vector. | + +--------------------------------+--------------------------------------------------------------+ + | mne_combine_xyz | Calculate the square sum of the three Cartesian components | + | | of several vectors listed in one row or column vector. | + +--------------------------------+--------------------------------------------------------------+ + | mne_file_name | Compose a file name relative to $MNE_ROOT. | + +--------------------------------+--------------------------------------------------------------+ + | mne_find_channel | Find a channel by name from measurement info. | + +--------------------------------+--------------------------------------------------------------+ + | mne_find_source_space_hemi | Determine whether a given source space belongs to the left | + | | or right hemisphere. | + +--------------------------------+--------------------------------------------------------------+ + | mne_fread3 | Read a three-byte integer. | + +--------------------------------+--------------------------------------------------------------+ + | mne_fwrite3 | Write a three-byte integer. | + +--------------------------------+--------------------------------------------------------------+ + | mne_make_combined_event_file | Combine data from several trigger channels into one event | + | | file. | + +--------------------------------+--------------------------------------------------------------+ + | mne_omit_first_line | Omit first line from a multi-line message. This routine is | + | | useful for formatting error messages. | + +--------------------------------+--------------------------------------------------------------+ + | mne_prepare_inverse_operator | Prepare inverse operator data for calculating L2 | + | | minimum-norm solutions and dSPM. | + +--------------------------------+--------------------------------------------------------------+ + | mne_setup_toolbox | Set up the MNE Matlab toolbox. | + +--------------------------------+--------------------------------------------------------------+ + | mne_transform_coordinates | Transform locations between different coordinate systems. | + | | This function uses the output file from | + | | ``mne_collect_transforms``. | + +--------------------------------+--------------------------------------------------------------+ + | mne_transpose_named_matrix | Create a transpose of a named matrix. | + +--------------------------------+--------------------------------------------------------------+ + | mne_transform_source_space_to | Transform source space data to another coordinate frame. | + +--------------------------------+--------------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.3\linewidth}|p{0.6\linewidth}| +.. _BGBEFADJ: +.. table:: Examples demonstrating the use of the toolbox. + + +--------------------------------+--------------------------------------------------------------+ + | Function | Purpose | + +================================+==============================================================+ + | mne_ex_average_epochs | Example of averaging epoch data produced by mne_epochs2mat. | + +--------------------------------+--------------------------------------------------------------+ + | mne_ex_cancel_noise | Example of noise cancellation procedures. | + +--------------------------------+--------------------------------------------------------------+ + | mne_ex_compute_inverse | Example of computing a L2 minimum-norm estimate or a dSPM | + | | solution. | + +--------------------------------+--------------------------------------------------------------+ + | mne_ex_data_sets | Example of listing evoked-response data sets. | + +--------------------------------+--------------------------------------------------------------+ + | mne_ex_evoked_grad_amp | Compute tangential gradient amplitudes from planar | + | | gradiometer data. | + +--------------------------------+--------------------------------------------------------------+ + | mne_ex_read_epochs | Read epoch data from a raw data file. | + +--------------------------------+--------------------------------------------------------------+ + | mne_ex_read_evoked | Example of reading evoked-response data. | + +--------------------------------+--------------------------------------------------------------+ + | mne_ex_read_raw | Example of reading raw data. | + +--------------------------------+--------------------------------------------------------------+ + | mne_ex_read_write_raw | Example of processing raw data (read and write). | + +--------------------------------+--------------------------------------------------------------+ + +.. note:: In order for the inverse operator calculation to work correctly with data processed with the Elekta-Neuromag Maxfilter (TM) software, the so-called *processing history* block must be included in data files. Previous versions of the MNE Matlab functions did not copy processing history to files saved. As of March 30, 2009, the Matlab toolbox routines fiff_start_writing_raw and fiff_write_evoked have been enhanced to include these data to the output file as appropriate. If you have older raw data files created in Matlab from input which has been processed Maxfilter, it is necessary to copy the *processing history* block from the original to modified raw data file using the ``mne_copy_processing_history`` utility. The raw data processing programs mne_browse_raw and mne_process_raw have handled copying of the processing history since revision 2.5 of the MNE software. + +Some data structures +#################### + +The MNE Matlab toolbox relies heavily on structures to organize +the data. This section gives detailed information about fields in +the essential data structures employed in the MNE Matlab toolbox. +In the structure definitions, data types referring to other MNE +Matlab toolbox structures are shown in italics. In addition, :ref:`matlab_fif_constants` +lists the values of various FIFF constants defined by fiff_define_constants.m . +The documented structures are: + +**tag** + + Contains one tag from the fif file, see :ref:`BGBGIIGD`. + +**taginfo** + + Contains the information about one tag, see :ref:`BGBBJBJJ`. + +**directory** + + Contains the tag directory as a tree structure, see :ref:`BGBEDHBG`. + +**id** + + A fif ID, see :ref:`BGBDAHHJ`. + +**named matrix** + + Contains a matrix with names for rows and/or columns, see :ref:`BGBBEDID`. + A named matrix is used to store, *e.g.*, SSP vectors and forward solutions. + +**trans** + + A 4 x 4 coordinate-transformation matrix operating on augmented column + vectors. Indication of the coordinate frames to which this transformation + relates is included, see :ref:`BGBDHBIF`. + +**dig** + + A Polhemus digitizer data point, see :ref:`BGBHDEDG`. + +**coildef** + + The coil definition structure useful for forward calculations and array + visualization, see :ref:`BGBGBEBH`. For more detailed information on + coil definitions, see :ref:`coil_geometry_information`. + +**ch** + + Channel information structure, see :ref:`BGBIABGD`. + +**proj** + + Signal-space projection data, see :ref:`BGBCJHJB`. + +**comp** + + Software gradiometer compensation data, see :ref:`BGBJDIFD`. + +**measurement info** + + Translation of the FIFFB_MEAS_INFO entity, see :ref:`BGBFHDIJ`. This + data structure is returned by fiff_read_meas_info . + +**surf** + + Used to represent triangulated surfaces and cortical source spaces, see :ref:`BGBEFJCB`. + +**cov** + + Used for storing covariance matrices, see :ref:`BGBJJIED`. + +**fwd** + + Forward solution data returned by mne_read_forward_solution , + see :ref:`BGBFJIBJ`. + +**inv** + + Inverse operator decomposition data returned by mne_read_inverse_operator. + For more information on inverse operator + decomposition, see :ref:`minimum_norm_estimates`. For an example on how to + compute inverse solution using this data, see the sample routine mne_ex_compute_inverse . + +.. note:: The MNE Matlab toolbox tries it best to employ vertex numbering starting from 1 as opposed to 0 as recorded in the data files. There are, however, two exceptions where explicit attention to the vertex numbering convention is needed. First, the standard stc and w file reading and writing routines return and assume zero-based vertex numbering. There are now versions with names ending with '1', which return and assume one-based vertex numbering, see :ref:`BABBDDAI`. Second, the logno field of the channel information in the data files produced by mne_compute_raw_inverse is the zero-based number of the vertex whose source space signal is contained on this channel. + + +.. tabularcolumns:: |p{0.38\linewidth}|p{0.06\linewidth}|p{0.46\linewidth}| +.. _matlab_fif_constants: +.. table:: FIFF constants. + + +-------------------------------+-------+----------------------------------------------------------+ + | Name | Value | Purpose | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MEG_CH | 1 | This is a MEG channel. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_REF_MEG_CH | 301 | This a reference MEG channel, located far away from the | + | | | head. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_EEF_CH | 2 | This is an EEG channel. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MCG_CH | 201 | This a MCG channel. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_STIM_CH | 3 | This is a digital trigger channel. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_EOG_CH | 202 | This is an EOG channel. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_EMG_CH | 302 | This is an EMG channel. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ECG_CH | 402 | This is an ECG channel. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MISC_CH | 502 | This is a miscellaneous analog channel. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_RESP_CH | 602 | This channel contains respiration monitor output. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_UNKNOWN | 0 | Unknown coordinate frame. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_DEVICE | 1 | The MEG device coordinate frame. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_ISOTRAK | 2 | The Polhemus digitizer coordinate frame (does not appear | + | | | in data files). | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_HPI | 3 | HPI coil coordinate frame (does not appear in data | + | | | files). | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_HEAD | 4 | The MEG head coordinate frame (Neuromag convention). | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_MRI | 5 | The MRI coordinate frame. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_MRI_SLICE | 6 | The coordinate frame of a single MRI slice. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_MRI_DISPLAY | 7 | The preferred coordinate frame for displaying the MRIs | + | | | (used by MRIlab). | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_DICOM_DEVICE | 8 | The DICOM coordinate frame (does not appear in files). | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_COORD_IMAGING_DEVICE | 9 | A generic imaging device coordinate frame (does not | + | | | appear in files). | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_COORD_TUFTS_EEG | 300 | The Tufts EEG data coordinate frame. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_COORD_CTF_DEVICE | 1001 | The CTF device coordinate frame (does not appear in | + | | | files). | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_COORD_CTF_HEAD | 1004 | The CTF/4D head coordinate frame. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ASPECT_AVERAGE | 100 | Data aspect: average. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ASPECT_STD_ERR | 101 | Data aspect: standard error of mean. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ASPECT_SINGLE | 102 | Single epoch. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ASPECT_SUBAVERAGE | 103 | One subaverage. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ASPECT_ALTAVERAGE | 104 | One alternating (plus-minus) subaverage. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ASPECT_SAMPLE | 105 | A sample cut from raw data. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ASPECT_POWER_DENSITY | 106 | Power density spectrum. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_ASPECT_DIPOLE_WAVE | 200 | The time course of an equivalent current dipole. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_BEM_SURF_ID_UNKNOWN | -1 | Unknown BEM surface. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_BEM_SURF_ID_BRAIN | 1 | The inner skull surface | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_BEM_SURF_ID_SKULL | 3 | The outer skull surface | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_BEM_SURF_ID_HEAD | 4 | The scalp surface | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_SURF_LEFT_HEMI | 101 | Left hemisphere cortical surface | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_SURF_RIGHT_HEMI | 102 | Right hemisphere cortical surface | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_POINT_CARDINAL | 1 | Digitization point which is a cardinal landmark aka. | + | | | fiducial point | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_POINT_HPI | 2 | Digitized HPI coil location | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_POINT_EEG | 3 | Digitized EEG electrode location | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_POINT_ECG | 3 | Digitized ECG electrode location | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_POINT_EXTRA | 4 | Additional head surface point | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_POINT_LPA | 1 | Identifier for left auricular landmark | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_POINT_NASION | 2 | Identifier for nasion | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_POINT_RPA | 3 | Identifier for right auricular landmark | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_FIXED_ORI | 1 | Fixed orientation constraint used in the computation of | + | | | a forward solution. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_FREE_ORI | 2 | No orientation constraint used in the computation of | + | | | a forward solution | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_MEG | 1 | Indicates an inverse operator based on MEG only | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_EEG | 2 | Indicates an inverse operator based on EEG only. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_MEG_EEG | 3 | Indicates an inverse operator based on both MEG and EEG. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_UNKNOWN_COV | 0 | An unknown covariance matrix | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_NOISE_COV | 1 | Indicates a noise covariance matrix. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_SENSOR_COV | 1 | Synonym for FIFFV_MNE_NOISE_COV | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_SOURCE_COV | 2 | Indicates a source covariance matrix | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_FMRI_PRIOR_COV | 3 | Indicates a covariance matrix associated with fMRI priors| + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_SIGNAL_COV | 4 | Indicates the data (signal + noise) covariance matrix | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_DEPTH_PRIOR_COV | 5 | Indicates the depth prior (depth weighting) covariance | + | | | matrix | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_MNE_ORIENT_PRIOR_COV | 6 | Indicates the orientation (loose orientation constrain) | + | | | prior covariance matrix | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_PROJ_ITEM_NONE | 0 | The nature of this projection item is unknown | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_PROJ_ITEM_FIELD | 1 | This is projection item is a generic field pattern or | + | | | field patters. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_PROJ_ITEM_DIP_FIX | 2 | This projection item is the field of one dipole | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_PROJ_ITEM_DIP_ROT | 3 | This projection item corresponds to the fields of three | + | | | or two orthogonal dipoles at some location. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_PROJ_ITEM_HOMOG_GRAD | 4 | This projection item contains the homogeneous gradient | + | | | fields as seen by the sensor array. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_PROJ_ITEM_HOMOG_FIELD | 5 | This projection item contains the three homogeneous field| + | | | components as seen by the sensor array. | + +-------------------------------+-------+----------------------------------------------------------+ + | FIFFV_PROJ_ITEM_EEG_AVREF | 10 | This projection item corresponds to the average EEG | + | | | reference. | + +-------------------------------+-------+----------------------------------------------------------+ + +.. _BGBGIIGD: + +.. table:: The tag structure. + + ======= =========== ============================================ + Field Data type Description + ======= =========== ============================================ + kind int32 The kind of the data item. + type uint32 The data type used to represent the data. + size int32 Size of the data in bytes. + next int32 Byte offset of the next tag in the file. + data various The data itself. + ======= =========== ============================================ + +.. _BGBBJBJJ: + +.. table:: The taginfo structure. + + ======= =========== ============================================ + Field Data type Description + ======= =========== ============================================ + kind double The kind of the data item. + type double The data type used to represent the data. + size double Size of the data in bytes. + pos double Byte offset to this tag in the file. + ======= =========== ============================================ + +.. _BGBEDHBG: + +.. table:: The directory structure. + + ============ ============ ================================================================ + Field Data type Description + ============ ============ ================================================================ + block double The block id of this directory node. + id id The unique identifier of this node. + parent_id id The unique identifier of the node this node was derived from. + nent double Number of entries in this node. + nchild double Number of children to this node. + dir taginfo Information about tags in this node. + children directory The children of this node. + ============ ============ ================================================================ + +.. _BGBDAHHJ: + +.. table:: The id structure. + + ========== =========== ============================================================ + Field Data type Description + ========== =========== ============================================================ + version int32 The fif file version (major < < 16 | minor). + machid int32(2) Unique identifier of the computer this id was created on. + secs int32 Time since January 1, 1970 (seconds). + usecs int32 Time since January 1, 1970 (microseconds past secs ). + ========== =========== ============================================================ + +.. _BGBBEDID: + +.. table:: The named matrix structure. + + ============ =========== ====================================================================== + Field Data type Description + ============ =========== ====================================================================== + nrow int32 Number of rows. + ncol int32 Number of columns. + row_names cell(*) The names of associated with the rows. This member may be empty. + col_names cell(*) The names of associated with the columns. This member may be empty. + data various The matrix data, usually of type single or double. + ============ =========== ====================================================================== + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBDHBIF: +.. table:: The trans structure. + + +---------------------------+-----------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===========================+===========+==========================================================+ + | from | int32 | The source coordinate frame, see | + | | | :ref:`matlab_fif_constants`. Look | + | | | for entries starting with FIFFV_COORD or FIFFV_MNE_COORD.| + +---------------------------+-----------+----------------------------------------------------------+ + | to | int32 | The destination coordinate frame. | + +---------------------------+-----------+----------------------------------------------------------+ + | trans |double(4,4)| The 4-by-4 coordinate transformation matrix. This | + | | | operates from augmented position column vectors given in | + | | | *from* coordinates to give results in *to* coordinates. | + +---------------------------+-----------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBHDEDG: +.. table:: The dig structure. + + +---------------------------+-----------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===========================+===========+==========================================================+ + | kind | int32 | The type of digitizing point. Possible values are listed | + | | | in :ref:`matlab_fif_constants`. Look for entries | + | | | starting with FIFF_POINT. | + +---------------------------+-----------+----------------------------------------------------------+ + | ident | int32 | Identifier for this point. | + +---------------------------+-----------+----------------------------------------------------------+ + | r | single(3) | The location of this point. | + +---------------------------+-----------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBGBEBH: +.. table:: The coildef structure. For more detailed information, see :ref:`coil_geometry_information`. + + +-------------------+-------------------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===================+===================+==========================================================+ + | class | double | The coil (or electrode) class. | + +-------------------+-------------------+----------------------------------------------------------+ + | id | double | The coil (or electrode) id. | + +-------------------+-------------------+----------------------------------------------------------+ + | accuracy | double | Representation accuracy. | + +-------------------+-------------------+----------------------------------------------------------+ + | num_points | double | Number of integration points. | + +-------------------+-------------------+----------------------------------------------------------+ + | size | double | Coil size. | + +-------------------+-------------------+----------------------------------------------------------+ + | baseline | double | Coil baseline. | + +-------------------+-------------------+----------------------------------------------------------+ + | description | char(*) | Coil description. | + +-------------------+-------------------+----------------------------------------------------------+ + | coildefs | double | Each row contains the integration point weight, followed | + | | (num_points,7) | by location [m] and normal. | + +-------------------+-------------------+----------------------------------------------------------+ + | FV | struct | Contains the faces and vertices which can be used to | + | | | draw the coil for visualization. | + +-------------------+-------------------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBIABGD: +.. table:: The ch structure. + + +---------------------------+-----------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===========================+===========+==========================================================+ + | scanno | int32 | Scanning order number, starting from 1. | + +---------------------------+-----------+----------------------------------------------------------+ + | logno | int32 | Logical channel number, conventions in the usage of this | + | | | number vary. | + +---------------------------+-----------+----------------------------------------------------------+ + | kind | int32 | The channel type (FIFFV_MEG_CH, FIFF_EEG_CH, etc., see | + | | | :ref:`matlab_fif_constants` ). | + +---------------------------+-----------+----------------------------------------------------------+ + | range | double | The hardware-oriented part of the calibration factor. | + | | | This should be only applied to the continuous raw data. | + +---------------------------+-----------+----------------------------------------------------------+ + | cal | double | The calibration factor to bring the channels to physical | + | | | units. | + +---------------------------+-----------+----------------------------------------------------------+ + | loc | double(12)| The channel location. The first three numbers indicate | + | | | the location [m], followed by the three unit vectors of | + | | | the channel-specific coordinate frame. These data contain| + | | | the values saved in the fif file and should not be | + | | | changed. The values are specified in device coordinates | + | | | for MEG and in head coordinates for EEG channels, | + | | | respectively. | + +---------------------------+-----------+----------------------------------------------------------+ + | coil_trans |double(4,4)| Initially, transformation from the channel coordinates | + | | | to device coordinates. This transformation is updated by | + | | | calls to fiff_transform_meg_chs and | + | | | fiff_transform_eeg_chs. | + +---------------------------+-----------+----------------------------------------------------------+ + | eeg_loc | double(6) | The location of the EEG electrode in coord_frame | + | | | coordinates. The first three values contain the location | + | | | of the electrode [m]. If six values are present, the | + | | | remaining ones indicate the location of the reference | + | | | electrode for this channel. | + +---------------------------+-----------+----------------------------------------------------------+ + | coord_frame | int32 | Initially, the coordinate frame is FIFFV_COORD_DEVICE | + | | | for MEG channels and FIFFV_COORD_HEAD for EEG channels. | + +---------------------------+-----------+----------------------------------------------------------+ + | unit | int32 | Unit of measurement. Relevant values are: 201 = T/m, | + | | | 112 = T, 107 = V, and 202 = Am. | + +---------------------------+-----------+----------------------------------------------------------+ + | unit_mul | int32 | The data are given in unit s multiplied by 10unit_mul. | + | | | Presently, unit_mul is always zero. | + +---------------------------+-----------+----------------------------------------------------------+ + | ch_name | char(*) | Name of the channel. | + +---------------------------+-----------+----------------------------------------------------------+ + | coil_def | coildef | The coil definition structure. This is present only if | + | | | mne_add_coil_defs has been successfully called. | + +---------------------------+-----------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBCJHJB: +.. table:: The proj structure. + + +---------------------------+-----------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===========================+===========+==========================================================+ + | kind | int32 | The type of the projection item. Possible values are | + | | | listed in :ref:`matlab_fif_constants`. Look for entries | + | | | starting with FIFFV_PROJ_ITEM or FIFFV_MNE_PROJ_ITEM. | + +---------------------------+-----------+----------------------------------------------------------+ + | active | int32 | Is this item active, i.e., applied or about to be | + | | | applied to the data. | + +---------------------------+-----------+----------------------------------------------------------+ + | data | named | The projection vectors. The column names indicate the | + | | matrix | names of the channels associated to the elements of the | + | | | vectors. | + +---------------------------+-----------+----------------------------------------------------------+ + + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBJDIFD: +.. table:: The comp structure. + + +---------------------------+-----------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===========================+===========+==========================================================+ + | ctfkind | int32 | The kind of the compensation as stored in file. | + +---------------------------+-----------+----------------------------------------------------------+ + | kind | int32 | ctfkind mapped into small integer numbers. | + +---------------------------+-----------+----------------------------------------------------------+ + | save_calibrated | logical | Were the compensation data saved in calibrated form. If | + | | | this field is false, the matrix will be decalibrated | + | | | using the fields row_cals and col_cals when the | + | | | compensation data are saved by the toolbox. | + +---------------------------+-----------+----------------------------------------------------------+ + | row_cals | double(*) | Calibration factors applied to the rows of the | + | | | compensation data matrix when the data were read. | + +---------------------------+-----------+----------------------------------------------------------+ + | col_cals | double(*) | Calibration factors applied to the columns of the | + | | | compensation data matrix when the data were read. | + +---------------------------+-----------+----------------------------------------------------------+ + | data | named | The compensation data matrix. The row_names list the | + | | matrix | names of the channels to which this compensation applies | + | | | and the col_names the compensation channels. | + +---------------------------+-----------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBFHDIJ: +.. table:: The meas info structure. + + +---------------------------+-----------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===========================+===========+==========================================================+ + | file_id | id | The fif ID of the measurement file. | + +---------------------------+-----------+----------------------------------------------------------+ + | meas_id | id | The ID assigned to this measurement by the acquisition | + | | | system or during file conversion. | + +---------------------------+-----------+----------------------------------------------------------+ + | nchan | int32 | Number of channels. | + +---------------------------+-----------+----------------------------------------------------------+ + | sfreq | double | Sampling frequency. | + +---------------------------+-----------+----------------------------------------------------------+ + | highpass | double | Highpass corner frequency [Hz]. Zero indicates a DC | + | | | recording. | + +---------------------------+-----------+----------------------------------------------------------+ + | lowpass | double | Lowpass corner frequency [Hz]. | + +---------------------------+-----------+----------------------------------------------------------+ + | chs | ch(nchan) | An array of channel information structures. | + +---------------------------+-----------+----------------------------------------------------------+ + | ch_names |cell(nchan)| Cell array of channel names. | + +---------------------------+-----------+----------------------------------------------------------+ + | dev_head_t | trans | The device to head transformation. | + +---------------------------+-----------+----------------------------------------------------------+ + | ctf_head_t | trans | The transformation from 4D/CTF head coordinates to | + | | | Neuromag head coordinates. This is only present in | + | | | 4D/CTF data. | + +---------------------------+-----------+----------------------------------------------------------+ + | dev_ctf_t | trans | The transformation from device coordinates to 4D/CTF | + | | | head coordinates. This is only present in 4D/CTF data. | + +---------------------------+-----------+----------------------------------------------------------+ + | dig | dig(*) | The Polhemus digitization data in head coordinates. | + +---------------------------+-----------+----------------------------------------------------------+ + | bads | cell(*) | Bad channel list. | + +---------------------------+-----------+----------------------------------------------------------+ + | projs | proj(*) | SSP operator data. | + +---------------------------+-----------+----------------------------------------------------------+ + | comps | comp(*) | Software gradient compensation data. | + +---------------------------+-----------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBEFJCB: + +.. table:: The surf structure. + + +---------------------------+-----------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===========================+===========+==========================================================+ + | id | int32 | The surface ID. | + +---------------------------+-----------+----------------------------------------------------------+ + | sigma | double | The electrical conductivity of the compartment bounded by| + | | | this surface. This field is present in BEM surfaces only.| + +---------------------------+-----------+----------------------------------------------------------+ + | np | int32 | Number of vertices on the surface. | + +---------------------------+-----------+----------------------------------------------------------+ + | ntri | int32 | Number of triangles on the surface. | + +---------------------------+-----------+----------------------------------------------------------+ + | coord_frame | int32 | Coordinate frame in which the locations and orientations | + | | | are expressed. | + +---------------------------+-----------+----------------------------------------------------------+ + | rr | double | The vertex locations. | + | | (np,3) | | + +---------------------------+-----------+----------------------------------------------------------+ + | nn | double | The vertex normals. If derived surface data was not | + | | (np,3) | requested, this is empty. | + +---------------------------+-----------+----------------------------------------------------------+ + | tris | int32 | Vertex numbers of the triangles in counterclockwise | + | | (ntri,3) | order as seen from the outside. | + +---------------------------+-----------+----------------------------------------------------------+ + | nuse | int32 | Number of active vertices, *i.e.*, vertices included in | + | | | a decimated source space. | + +---------------------------+-----------+----------------------------------------------------------+ + | inuse | int32(np) | Which vertices are in use. | + +---------------------------+-----------+----------------------------------------------------------+ + | vertno |int32(nuse)| Indices of the vertices in use. | + +---------------------------+-----------+----------------------------------------------------------+ + | curv | double(np)| Curvature values at the vertices. If curvature | + | | | information was not requested, this field is empty or | + | | | absent. | + +---------------------------+-----------+----------------------------------------------------------+ + | tri_area | double | The triangle areas in m2.If derived surface data was not | + | | (ntri) | requested, this field will be missing. | + +---------------------------+-----------+----------------------------------------------------------+ + | tri_cent | double | The triangle centroids. If derived surface data was not | + | | (ntri,3) | requested, this field will be missing. | + +---------------------------+-----------+----------------------------------------------------------+ + | tri_nn | double | The triangle normals. If derived surface data was not | + | | (ntri,3) | requested, this field will be missing. | + +---------------------------+-----------+----------------------------------------------------------+ + | nuse_tri | int32 | Number of triangles in use. This is present only if the | + | | | surface corresponds to a source space created with the | + | | | ``--ico`` option. | + +---------------------------+-----------+----------------------------------------------------------+ + | use_tris | int32 | The vertices of the triangles in use in the complete | + | | (nuse_tri)| triangulation. This is present only if the surface | + | | | corresponds to a source space created with the | + | | | ``--ico`` option. | + +---------------------------+-----------+----------------------------------------------------------+ + | nearest | int32(np) | This field is present only if patch information has been | + | | | computed for a source space. For each vertex in the | + | | | triangulation, these values indicate the nearest active | + | | | source space vertex. | + +---------------------------+-----------+----------------------------------------------------------+ + | nearest_dist | double(np)| This field is present only if patch information has been | + | | | computed for a source space. For each vertex in the | + | | | triangulation, these values indicate the distance to the | + | | | nearest active source space vertex. | + +---------------------------+-----------+----------------------------------------------------------+ + | dist | double | Distances between vertices on this surface given as a | + | | (np,np) | sparse matrix. A zero off-diagonal entry in this matrix | + | | | indicates that the corresponding distance has not been | + | | | calculated. | + +---------------------------+-----------+----------------------------------------------------------+ + | dist_limit | double | The value given to mne_add_patch_info with the ``--dist``| + | | | option. This value is presently | + | | | always negative, indicating that only distances between | + | | | active source space vertices, as indicated by the vertno | + | | | field of this structure, have been calculated. | + +---------------------------+-----------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBJJIED: + +.. table:: The cov structure. + + +---------------------------+-----------+----------------------------------------------------------+ + | Field | Data Type | Description | + +===========================+===========+==========================================================+ + | kind | double | What kind of a covariance matrix (1 = noise covariance, | + | | | 2 = source covariance). | + +---------------------------+-----------+----------------------------------------------------------+ + | diag | double | Is this a diagonal matrix. | + +---------------------------+-----------+----------------------------------------------------------+ + | dim | int32 | Dimension of the covariance matrix. | + +---------------------------+-----------+----------------------------------------------------------+ + | names | cell(*) | Names of the channels associated with the entries | + | | | (may be empty). | + +---------------------------+-----------+----------------------------------------------------------+ + | data | double | The covariance matrix. This a double(dim) vector for a | + | | (dim,dim) | diagonal covariance matrix. | + +---------------------------+-----------+----------------------------------------------------------+ + | projs | proj(*) | The SSP vectors applied to these data. | + +---------------------------+-----------+----------------------------------------------------------+ + | bads | cell(*) | Bad channel names. | + +---------------------------+-----------+----------------------------------------------------------+ + | nfree | int32 | Number of data points used to compute this matrix. | + +---------------------------+-----------+----------------------------------------------------------+ + | eig |double(dim)| The eigenvalues of the covariance matrix. This field may | + | | | be empty for a diagonal covariance matrix. | + +---------------------------+-----------+----------------------------------------------------------+ + | eigvec | double | The eigenvectors of the covariance matrix. | + | | (dim,dim) | | + +---------------------------+-----------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBFJIBJ: + +.. table:: The fwd structure. + + +-------------------------+-------------+----------------------------------------------------------+ + | Field | Data Type | Description | + +=========================+=============+==========================================================+ + | source_ori | int32 | Has the solution been computed for the current component | + | | | normal to the cortex only (1) or all three source | + | | | orientations (2). | + +-------------------------+-------------+----------------------------------------------------------+ + | coord_frame | int32 | Coordinate frame in which the locations and orientations | + | | | are expressed. | + +-------------------------+-------------+----------------------------------------------------------+ + | nsource | int32 | Total number of source space points. | + +-------------------------+-------------+----------------------------------------------------------+ + | nchan | int32 | Number of channels. | + +-------------------------+-------------+----------------------------------------------------------+ + | sol | named | The forward solution matrix. | + | | matrix | | + +-------------------------+-------------+----------------------------------------------------------+ + | sol_grad | named | The derivatives of the forward solution with respect to | + | | matrix | the dipole location coordinates. | + | | | This field is present only if the forward solution was | + | | | computed with the ``--grad`` option in MNE-C. | + +-------------------------+-------------+----------------------------------------------------------+ + | mri_head_t | trans | Transformation from the MRI coordinate frame to the | + | | | (Neuromag) head coordinate frame. | + +-------------------------+-------------+----------------------------------------------------------+ + | src | surf(:) | The description of the source spaces. | + +-------------------------+-------------+----------------------------------------------------------+ + | source_rr | double | The source locations. | + | | (nsource,3) | | + +-------------------------+-------------+----------------------------------------------------------+ + | source_nn | double(:,3) | The source orientations. Number of rows is either | + | | | nsource (fixed source orientations) or 3*nsource | + | | | (all source orientations). | + +-------------------------+-------------+----------------------------------------------------------+ + + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.2\linewidth}|p{0.55\linewidth}| +.. _BGBIEIJE: + +.. table:: The inv structure. Note: The fields proj, whitener, reginv, and noisenorm are filled in by the routine mne_prepare_inverse_operator. + + +---------------------+-------------+----------------------------------------------------------+ + | Field | Data Type | Description | + +=====================+=============+==========================================================+ + | methods | int32 | Has the solution been computed using MEG data (1), EEG | + | | | data (2), or both (3). | + +---------------------+-------------+----------------------------------------------------------+ + | source_ori | int32 | Has the solution been computed for the current component | + | | | normal to the cortex only (1) or all three source | + | | | orientations (2). | + +---------------------+-------------+----------------------------------------------------------+ + | nsource | int32 | Total number of source space points. | + +---------------------+-------------+----------------------------------------------------------+ + | nchan | int32 | Number of channels. | + +---------------------+-------------+----------------------------------------------------------+ + | coord_frame | int32 | Coordinate frame in which the locations and orientations | + | | | are expressed. | + +---------------------+-------------+----------------------------------------------------------+ + | source_nn | double(:,3) | The source orientations. Number of rows is either | + | | | nsource (fixed source orientations) or 3*nsource (all | + | | | source orientations). | + +---------------------+-------------+----------------------------------------------------------+ + | sing | double | The singular values, *i.e.*, the diagonal values of | + | | (nchan) | :math:`\Lambda`, see :ref:`mne_solution`. | + +---------------------+-------------+----------------------------------------------------------+ + | eigen_leads | double | The matrix :math:`V`, see :ref:`mne_solution`. | + | | (:,nchan) | | + +---------------------+-------------+----------------------------------------------------------+ + | eigen_fields | double | The matrix :math:`U^T`, see | + | | (nchan, | :ref:`mne_solution`. | + | | nchan) | | + +---------------------+-------------+----------------------------------------------------------+ + | noise_cov | cov | The noise covariance matrix :math:`C`. | + +---------------------+-------------+----------------------------------------------------------+ + | source_cov | cov | The source covariance matrix :math:`R`. | + +---------------------+-------------+----------------------------------------------------------+ + | src | surf(:) | The description of the source spaces. | + +---------------------+-------------+----------------------------------------------------------+ + | mri_head_t | trans | Transformation from the MRI coordinate frame to the | + | | | (Neuromag) head coordinate frame. | + +---------------------+-------------+----------------------------------------------------------+ + | nave | double | The number of averages. | + +---------------------+-------------+----------------------------------------------------------+ + | projs | proj(:) | The SSP vectors which were active when the decomposition | + | | | was computed. | + +---------------------+-------------+----------------------------------------------------------+ + | proj | double | The projection operator computed using projs. | + | | (nchan) | | + +---------------------+-------------+----------------------------------------------------------+ + | whitener | | A sparse matrix containing the noise normalization | + | | | factors. Dimension is either nsource (fixed source | + | | | orientations) or 3*nsource (all source orientations). | + +---------------------+-------------+----------------------------------------------------------+ + | reginv | double | The diagonal matrix :math:`\Gamma`, see | + | | (nchan) | :ref:`mne_solution`. | + +---------------------+-------------+----------------------------------------------------------+ + | noisenorm | double(:) | A sparse matrix containing the noise normalization | + | | | factors. Dimension is either nsource (fixed source | + | | | orientations) or 3*nsource (all source orientations). | + +---------------------+-------------+----------------------------------------------------------+ + + +On-line documentation for individual routines +############################################# + +Each of the routines listed in Tables :ref:`BGBCGHAG` - :ref:`BGBEFADJ` has on-line documentation accessible by saying ``help`` <*routine name*> in Matlab. diff -Nru python-mne-0.18.1+dfsg/doc/overview/migrating.rst python-mne-0.19.1+dfsg/doc/overview/migrating.rst --- python-mne-0.18.1+dfsg/doc/overview/migrating.rst 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/overview/migrating.rst 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,76 @@ +.. _migrating: + +Migrating from other analysis software +====================================== + +Here we offer some tips on how to migrate from other analysis software. + +EEGLAB +^^^^^^ + +To read in data exported from EEGLAB, MNE-Python includes an :file:`.edf` +reader :func:`mne.io.read_raw_edf` and a ``set`` file reader. To read in +``set`` files containing ``raw`` data, use :func:`mne.io.read_raw_eeglab` and +to read in ``set`` files containing ``epochs`` data, use +:func:`mne.read_epochs_eeglab`. + +This table summarizes equivalent EEGLAB and MNE-Python code for some of the +most common analysis tasks. For the sake of clarity, the table below assumes +the following variables exist: the file name ``fname``, time interval of the +epochs ``tmin`` and ``tmax``, and the experimental conditions ``cond1`` and +``cond2``. The variables ``l_freq`` and ``h_freq`` are the frequencies (in Hz) +below which and above which to filter out data. + +.. cssclass:: table-bordered +.. rst-class:: midvalign + ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Processing step | EEGLAB function | MNE-Python | ++=====================+==========================================================+==================================================================================================+ +| Get started | | ``addpath(...);`` | | :mod:`import mne ` | +| | | ``eeglab;`` | | :mod:`from mne import io, ` :class:`~mne.Epochs` | +| | | | :mod:`from mne.preprocessing ` :class:`import ICA ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Import data | ``EEG = pop_fileio(fname);`` | | :func:`raw = io.read_raw_fif(fname) ` | +| | | | :func:`raw = io.read_raw_edf(fname) ` | +| | | | :func:`raw = io.read_raw_eeglab(fname) ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Filter data | ``EEG = pop_eegfiltnew(EEG, l_freq, h_freq);`` | :func:`raw.filter(l_freq, h_freq) ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Run ICA | ``EEG = pop_runica(EEG);`` | :func:`ica.fit(raw) ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Epoch data | | ``event_id = {'cond1', 'cond2'};`` | | :func:`events = mne.find_events(raw) ` | +| | | ``Epochs = pop_epochs(EEG, event_id, [tmin, tmax]);`` | | :py:class:`event_id = dict(cond1=32, cond2=64) ` | +| | | | :class:`epochs = Epochs(raw, events, event_id, tmin, tmax) ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Selecting epochs | ``Epochs = pop_epochs(EEG_epochs, {cond2});`` | :class:`epochs[cond2] ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| ERP butterfly plot | ``pop_timtopo(EEG_epochs, ...);`` | | :meth:`evoked = epochs[cond2].average() ` | +| | | | :func:`evoked.plot() ` | +| | | | :func:`evoked.plot_joint() ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Contrast ERPs | ``pop_compareerps(EEG_epochs1, EEG_epochs2);`` | | :func:`mne.combine_evoked([evoked1, -evoked2], weights='equal').plot() ` | +| | | | :func:`mne.viz.plot_compare_evokeds([evoked1, evoked2]) ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Save data | ``EEG = pop_saveset(EEG, fname);`` | | :func:`raw.save(fname) ` | +| | | | :func:`epochs.save(fname) ` | +| | | | :func:`evoked.save(fname) ` | ++---------------------+----------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + +Potential pitfalls +~~~~~~~~~~~~~~~~~~ + +- Many of the MNE-Python objects have methods that operate in-place to save + memory (i.e., the data in the :class:`~mne.io.Raw` object is changed when you + call :meth:`raw.filter(lfreq, hfreq) `). If you do not + want this, it is always possible to first call the object's + :meth:`~mne.io.Raw.copy` method (e.g., ``filtered_raw = + raw.copy().filter(lfreq, hfreq)``). In addition, some MNE-Python functions + have a boolean ``copy`` parameter that achieves the same purpose. + +- The concept of channel types is critical in MNE because it supports analysis + of multimodal data (e.g., EEG, MEG, EOG, Stim channel, etc) whereas most + EEGLAB functions assume all channels are of the same type (EEG). To restrict + channels to a single type, see :func:`mne.pick_types`, :meth:`raw.pick_types + `, :meth:`epochs.pick_types `, + :meth:`evoked.pick_types `, etc. diff -Nru python-mne-0.18.1+dfsg/doc/pre_install.rst python-mne-0.19.1+dfsg/doc/pre_install.rst --- python-mne-0.18.1+dfsg/doc/pre_install.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/pre_install.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,72 +0,0 @@ -.. include:: links.inc - -.. _preinstall: - -Before you install -================== - -.. contents:: - :local: - :depth: 1 - -Overview of the MNE tools suite -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- :doc:`MNE-C ` was the initial stage of this project, - providing a set of interrelated command-line and GUI programs focused on - computing cortically constrained Minimum Norm Estimates from MEG and EEG - data. These tools were written in C by Matti Hämäläinen. - -- :doc:`MNE-Python ` reimplements the functionality of MNE-C, - and extends considerably the analysis and visualization capabilities. - MNE-Python is collaboratively developed and has more than 150 contributors. - -- The :doc:`manual/matlab` provides a MATLAB interface to the .fif file format - and other MNE data structures, and provides example MATLAB implementations of - some of the core analysis functionality of MNE-C. It is distributed alongside - MNE-C, and can also be downloaded from the `MNE-MATLAB git repository`_. - -- :doc:`MNE-CPP ` provides core MNE functionality implemented in C++ - and is primarily intended for embedded and real-time applications. - -There are also Python tools for easily importing MEG data from the Human -Connectome Project for use with MNE-Python (`MNE-HCP`_), and tools for -managing MNE projects so that they comply with the Brain Imaging Data Structure -specification (`MNE-BIDS`_). - -What should I install? -^^^^^^^^^^^^^^^^^^^^^^ - -If you intend only to perform ERP, ERF, or other sensor-level analyses, -:doc:`MNE-Python ` is all you need. If you prefer MATLAB -over Python, probably all you need is :doc:`MNE-C ` — the MNE -MATLAB toolbox is distributed with it — although note that the MATLAB toolbox -is less actively developed than the MNE-Python module, and hence the MATLAB -code is considerably less feature-complete. - -If you want to transform sensor recordings into estimates of localized brain -activity, you will most likely need: - -- :doc:`FreeSurfer ` to convert structural MRI scans into - models of the scalp, inner/outer skull, and cortical surfaces - -- :doc:`MNE-C ` for constructing and solving a boundary-element - model of tissue conductance, and for aligning coordinate frames between the - structural MRI and the digitizations of M/EEG sensor locations - -- :doc:`MNE-Python ` can be used for everything else - -Getting help -^^^^^^^^^^^^ - -There are three main channels for obtaining help with MNE software tools. - -The `MNE mailing list`_ and `MNE gitter channel`_ are a good place to start for -both troubleshooting and general questions. If you want to request new -features or if you're confident that you have found a bug, please create a new -issue on the `GitHub issues page`_. When reporting bugs, please try to -replicate the bug with the MNE-Python sample data, and make every effort to -simplify your example script to only the elements necessary to replicate the -bug. - -**Next:** :doc:`install_mne_python` diff -Nru python-mne-0.18.1+dfsg/doc/python_reference.rst python-mne-0.19.1+dfsg/doc/python_reference.rst --- python-mne-0.18.1+dfsg/doc/python_reference.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/python_reference.rst 2019-10-25 14:42:45.000000000 +0000 @@ -53,11 +53,11 @@ :toctree: generated/ anonymize_info - find_edf_events read_raw_artemis123 read_raw_bti read_raw_cnt read_raw_ctf + read_raw_curry read_raw_edf read_raw_bdf read_raw_gdf @@ -99,6 +99,8 @@ :toctree: generated decimate_surface + channel_type + channel_indices_by_type get_head_surf get_meg_helmet_surf get_volume_labels_from_aseg @@ -139,9 +141,9 @@ write_source_spaces write_surface write_trans + what io.read_info io.show_fiff - io.DigPoint Base class: @@ -187,8 +189,7 @@ fetch_hcp_mmp_parcellation hf_sef.data_path kiloword.data_path - megsim.data_path - megsim.load_data + limo.load_data misc.data_path mtrf.data_path multimodal.data_path @@ -222,6 +223,7 @@ circular_layout mne_analyze_colormap plot_bem + plot_brain_colorbar plot_connectivity_circle plot_cov plot_csd @@ -253,6 +255,7 @@ plot_raw plot_raw_psd plot_sensors + plot_sensors_connectivity plot_snr_estimate plot_source_estimates plot_volume_source_estimates @@ -267,6 +270,9 @@ set_3d_backend get_3d_backend use_3d_backend + set_3d_view + set_3d_title + create_3d_figure Preprocessing @@ -298,12 +304,19 @@ :toctree: generated/ Layout - Montage DigMontage fix_mag_coil_types - read_montage + read_polhemus_fastscan get_builtin_montages - read_dig_montage + make_dig_montage + read_dig_polhemus_isotrak + read_dig_captrack + read_dig_egi + read_dig_fif + read_dig_hpts + make_standard_montage + read_custom_montage + compute_dev_head_t read_layout find_layout make_eeg_layout @@ -520,6 +533,7 @@ .. autosummary:: :toctree: generated/ + coreg.get_mni_fiducials gui.coregistration gui.fiducials create_default_subject @@ -544,6 +558,7 @@ apply_forward_raw average_forward_solutions convert_forward_solution + dig_mri_distances forward.compute_depth_prior forward.compute_orient_prior forward.restrict_forward_to_label @@ -862,6 +877,7 @@ spatio_temporal_cluster_test spatio_temporal_cluster_1samp_test summarize_clusters_stc + bootstrap_confidence_interval Compute ``connectivity`` matrices for cluster-level statistics: @@ -994,6 +1010,7 @@ :toctree: generated/ deprecated + warn :py:mod:`mne.cuda`: @@ -1008,3 +1025,4 @@ get_cuda_memory init_cuda + set_cuda_device diff -Nru python-mne-0.18.1+dfsg/doc/sphinxext/gen_commands.py python-mne-0.19.1+dfsg/doc/sphinxext/gen_commands.py --- python-mne-0.18.1+dfsg/doc/sphinxext/gen_commands.py 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/sphinxext/gen_commands.py 2019-10-25 14:42:45.000000000 +0000 @@ -1,12 +1,11 @@ # -*- coding: utf-8 -*- -import os import glob +from importlib import import_module +import os from os import path as op -import subprocess -import sys -from mne.utils import run_subprocess, _replace_md5 +from mne.utils import _replace_md5, ArgvSetter def setup(app): @@ -25,13 +24,15 @@ # 4. - : Command sections (Examples, Notes) header = """\ +:orphan: + .. _python_commands: =============================== Command line tools using Python =============================== -.. contents:: Contents +.. contents:: Page contents :local: :depth: 1 @@ -69,11 +70,13 @@ f.write(header) for fname in iterator: cmd_name = fname[:-3] - run_name = op.join(command_path, fname) - output, _ = run_subprocess([sys.executable, run_name, '--help'], - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, verbose=False) - output = output.splitlines() + module = import_module('.' + cmd_name, 'mne.commands') + with ArgvSetter(('mne', cmd_name, '--help')) as out: + try: + module.run() + except SystemExit: # this is how these terminate + pass + output = out.stdout.getvalue().splitlines() # Swap usage and title lines output[0], output[2] = output[2], output[0] @@ -102,7 +105,6 @@ '=' * len(cmd_name), output)) _replace_md5(out_fname) - print('[Done]') # This is useful for testing/iterating to see what the result looks like diff -Nru python-mne-0.18.1+dfsg/doc/sphinxext/ipython_console_highlighting.py python-mne-0.19.1+dfsg/doc/sphinxext/ipython_console_highlighting.py --- python-mne-0.18.1+dfsg/doc/sphinxext/ipython_console_highlighting.py 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/sphinxext/ipython_console_highlighting.py 1970-01-01 00:00:00.000000000 +0000 @@ -1,100 +0,0 @@ -# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*- -# vi: set ft=python sts=4 ts=4 sw=4 et: -"""reST directive for syntax-highlighting ipython interactive sessions. -""" - -#----------------------------------------------------------------------------- -# Needed modules - -# Standard library -import re - -# Third party -from pygments.lexer import Lexer, do_insertions -from pygments.lexers.agile import (PythonConsoleLexer, PythonLexer, - PythonTracebackLexer) -from pygments.token import Comment, Generic - -from sphinx import highlighting - - -#----------------------------------------------------------------------------- -# Global constants -line_re = re.compile('.*?\n') - -#----------------------------------------------------------------------------- -# Code begins - classes and functions - -class IPythonConsoleLexer(Lexer): - """ - For IPython console output or doctests, such as: - - .. sourcecode:: ipython - - In [1]: a = 'foo' - - In [2]: a - Out[2]: 'foo' - - In [3]: print a - foo - - In [4]: 1 / 0 - - Notes: - - - Tracebacks are not currently supported. - - - It assumes the default IPython prompts, not customized ones. - """ - - name = 'IPython console session' - aliases = ['ipython'] - mimetypes = ['text/x-ipython-console'] - input_prompt = re.compile(r"(In \[[0-9]+\]: )|( \.\.\.+:)") - output_prompt = re.compile(r"(Out\[[0-9]+\]: )|( \.\.\.+:)") - continue_prompt = re.compile(r" \.\.\.+:") - tb_start = re.compile(r"\-+") - - def get_tokens_unprocessed(self, text): - pylexer = PythonLexer(**self.options) - tblexer = PythonTracebackLexer(**self.options) - - curcode = '' - insertions = [] - for match in line_re.finditer(text): - line = match.group() - input_prompt = self.input_prompt.match(line) - continue_prompt = self.continue_prompt.match(line.rstrip()) - output_prompt = self.output_prompt.match(line) - if line.startswith("#"): - insertions.append((len(curcode), - [(0, Comment, line)])) - elif input_prompt is not None: - insertions.append((len(curcode), - [(0, Generic.Prompt, input_prompt.group())])) - curcode += line[input_prompt.end():] - elif continue_prompt is not None: - insertions.append((len(curcode), - [(0, Generic.Prompt, continue_prompt.group())])) - curcode += line[continue_prompt.end():] - elif output_prompt is not None: - insertions.append((len(curcode), - [(0, Generic.Output, output_prompt.group())])) - curcode += line[output_prompt.end():] - else: - if curcode: - for item in do_insertions(insertions, - pylexer.get_tokens_unprocessed(curcode)): - yield item - curcode = '' - insertions = [] - yield match.start(), Generic.Output, line - if curcode: - for item in do_insertions(insertions, - pylexer.get_tokens_unprocessed(curcode)): - yield item - -#----------------------------------------------------------------------------- -# Register the extension as a valid pygments lexer -highlighting.lexers['ipython'] = IPythonConsoleLexer() diff -Nru python-mne-0.18.1+dfsg/doc/sphinxext/only_directives.py python-mne-0.19.1+dfsg/doc/sphinxext/only_directives.py --- python-mne-0.18.1+dfsg/doc/sphinxext/only_directives.py 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/sphinxext/only_directives.py 1970-01-01 00:00:00.000000000 +0000 @@ -1,65 +0,0 @@ -# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*- -# vi: set ft=python sts=4 ts=4 sw=4 et: -# -# A pair of directives for inserting content that will only appear in -# either html or latex. -# - -from docutils.nodes import Body, Element -from docutils.parsers.rst import directives - -class only_base(Body, Element): - def dont_traverse(self, *args, **kwargs): - return [] - -class html_only(only_base): - pass - -class latex_only(only_base): - pass - -def run(content, node_class, state, content_offset): - text = '\n'.join(content) - node = node_class(text) - state.nested_parse(content, content_offset, node) - return [node] - -def html_only_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return run(content, html_only, state, content_offset) - -def latex_only_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return run(content, latex_only, state, content_offset) - -def builder_inited(app): - if app.builder.name == 'html': - latex_only.traverse = only_base.dont_traverse - else: - html_only.traverse = only_base.dont_traverse - -def setup(app): - app.add_directive('htmlonly', html_only_directive, True, (0, 0, 0)) - app.add_directive('latexonly', latex_only_directive, True, (0, 0, 0)) - app.add_node(html_only) - app.add_node(latex_only) - - # This will *really* never see the light of day As it turns out, - # this results in "broken" image nodes since they never get - # processed, so best not to do this. - # app.connect('builder-inited', builder_inited) - - # Add visit/depart methods to HTML-Translator: - def visit_perform(self, node): - pass - def depart_perform(self, node): - pass - def visit_ignore(self, node): - node.children = [] - def depart_ignore(self, node): - node.children = [] - - app.add_node(html_only, html=(visit_perform, depart_perform)) - app.add_node(html_only, latex=(visit_ignore, depart_ignore)) - app.add_node(latex_only, latex=(visit_perform, depart_perform)) - app.add_node(latex_only, html=(visit_ignore, depart_ignore)) diff -Nru python-mne-0.18.1+dfsg/doc/sphinxext/README.txt python-mne-0.19.1+dfsg/doc/sphinxext/README.txt --- python-mne-0.18.1+dfsg/doc/sphinxext/README.txt 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/sphinxext/README.txt 1970-01-01 00:00:00.000000000 +0000 @@ -1,25 +0,0 @@ -=================== - Sphinx Extensions -=================== - -We've copied these sphinx extensions over from nipy-core. Any edits -should be done upstream in nipy-core, not here in nipype! - -These are a few sphinx extensions we are using to build the nipy -documentation. In this file we list where they each come from, since we intend -to always push back upstream any modifications or improvements we make to them. - -It's worth noting that some of these are being carried (as copies) by more -than one project. Hopefully once they mature a little more, they will be -incorproated back into sphinx itself, so that all projects can use a common -base. - -* From numpy: - * docscrape.py - * docscrape_sphinx.py - * numpydoc.py - -* From matplotlib: - * inheritance_diagram.py - * ipython_console_highlighting.py - * only_directives.py diff -Nru python-mne-0.18.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/bootstrap_divs.css python-mne-0.19.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/bootstrap_divs.css --- python-mne-0.18.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/bootstrap_divs.css 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/bootstrap_divs.css 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,9 @@ +.panel-title a { + display: block !important; + text-decoration: none; +} +@media (max-width: 991px) { + .collapse.in{ + display:block !important; + } + } diff -Nru python-mne-0.18.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/bootstrap_divs.js python-mne-0.19.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/bootstrap_divs.js --- python-mne-0.18.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/bootstrap_divs.js 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/bootstrap_divs.js 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,6 @@ +$(document).ready(function () { + if(location.hash != null && location.hash != ""){ + $('.collapse').removeClass('in'); + $(location.hash + '.collapse').addClass('in'); + } +}); diff -Nru python-mne-0.18.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/__init__.py python-mne-0.19.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/__init__.py --- python-mne-0.18.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/__init__.py 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/sphinxext/sphinx_bootstrap_divs/__init__.py 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,196 @@ +"""A .. collapse:: directive for sphinx-bootstrap-theme.""" + +import os.path as op +from docutils import nodes +from docutils.parsers.rst.directives import flag, class_option +from docutils.parsers.rst.roles import set_classes +from docutils.statemachine import StringList + +from sphinx.locale import _ +from sphinx.util.docutils import SphinxDirective +from sphinx.util.fileutil import copy_asset + +this_dir = op.dirname(__file__) + +__version__ = '0.1.0.dev0' + + +############################################################################### +# Super classes + +class DivNode(nodes.Body, nodes.Element): + """Generic DivNode class.""" + + def __init__(self, **options): + diff = set(options.keys()).symmetric_difference(set(self.OPTION_KEYS)) + assert len(diff) == 0, (diff, self.__class__.__name__) + self.options = options + super().__init__() + + def visit_node(self, node): + """Visit the node.""" + atts = {} + if node.BASECLASS: + atts['class'] = node.BASECLASS + if node.options.get('class'): + atts['class'] += \ + ' {}-{}'.format(node.BASECLASS, node.options['class']) + self.body.append(self.starttag(node, node.ELEMENT, **atts)) + + def depart_node(self, node): + """Depart the node.""" + self.body.append(''.format(node.ELEMENT)) + + +def _assemble(node, directive): + title_text = directive.arguments[0] + directive.add_name(node) + header = node.HEADER_PRETITLE.format(**node.options).split('\n') + directive.state.nested_parse( + StringList(header), directive.content_offset, node) + + textnodes, messages = directive.state.inline_text( + title_text, directive.lineno) + node += textnodes + node += messages + + header = node.HEADER_POSTTITLE.format(**node.options).split('\n') + directive.state.nested_parse( + StringList(header), directive.content_offset, node) + + directive.state.nested_parse( + directive.content, directive.content_offset, node) + + footer = node.FOOTER.format(**node.options).split('\n') + directive.state.nested_parse( + StringList(footer), directive.content_offset, node) + + +############################################################################### +# .. collapse:: + +class CollapseNode(DivNode): + """Class for .. collapse:: directive.""" + + OPTION_KEYS = ('title', 'id_', 'extra', 'class') + ELEMENT = 'div' + BASECLASS = 'panel' + HEADER_PRETITLE = """.. raw:: html + +

+ """ + HEADER_POSTTITLE = """.. raw:: html + +

+
+
""" + FOOTER = """.. raw:: html + +
""" + KNOWN_CLASSES = ( + 'default', 'primary', 'success', 'info', 'warning', 'danger') + + @staticmethod + def _check_class(class_): + if class_ not in CollapseNode.KNOWN_CLASSES: + raise ValueError(':class: option %r must be one of %s' + % (class_, CollapseNode.KNOWN_CLASSES)) + return class_ + + +class CollapseDirective(SphinxDirective): + """Collapse directive.""" + + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {'open': flag, + 'class': CollapseNode._check_class} + has_content = True + + def run(self): + """Parse.""" + self.assert_has_content() + title_text = _(self.arguments[0]) + extra = _(' in' if 'open' in self.options else '') + class_ = {'class': self.options.get('class', 'default')} + id_ = nodes.make_id(title_text) + node = CollapseNode(title=title_text, id_=id_, extra=extra, **class_) + _assemble(node, self) + return [node] + + +############################################################################### +# .. details:: + +class DetailsNode(DivNode): + """Class for .. details:: directive.""" + + ELEMENT = 'details' + BASECLASS = '' + OPTION_KEYS = ('title', 'class') + HEADER_PRETITLE = """.. raw:: html + + """ + HEADER_POSTTITLE = """.. raw:: html + + """ + FOOTER = """""" + + +class DetailsDirective(SphinxDirective): + """Details directive.""" + + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {'class': class_option} + has_content = True + + def run(self): + """Parse.""" + set_classes(self.options) + self.assert_has_content() + title_text = _(self.arguments[0]) + class_ = {'class': self.options.get('class', '')} + node = DetailsNode(title=title_text, **class_) + _assemble(node, self) + return [node] + + +############################################################################### +# Generic setup + +def setup(app): + """Set up for Sphinx app.""" + directives = dict( + collapse=CollapseDirective, + details=DetailsDirective, + ) + for key, value in directives.items(): + app.add_directive(key, value) + try: + app.add_css_file('bootstrap_divs.css') + except AttributeError: + app.add_stylesheet('bootstrap_divs.css') + try: + app.add_js_file('bootstrap_divs.js') + except AttributeError: + app.add_javascript('bootstrap_divs.js') + app.connect('build-finished', copy_asset_files) + for node in (CollapseNode, DetailsNode): + app.add_node(node, + html=(node.visit_node, node.depart_node), + latex=(node.visit_node, node.depart_node), + text=(node.visit_node, node.depart_node)) + return dict(version='0.1', parallel_read_safe=True, + parallel_write_safe=True) + + +def copy_asset_files(app, exc): + """Copy static assets.""" + asset_files = ['bootstrap_divs.css', 'bootstrap_divs.js'] + if exc is None: # build succeeded + for path in asset_files: + copy_asset(op.join(this_dir, path), + op.join(app.outdir, '_static')) diff -Nru python-mne-0.18.1+dfsg/doc/_static/diagrams/ica.dot python-mne-0.19.1+dfsg/doc/_static/diagrams/ica.dot --- python-mne-0.18.1+dfsg/doc/_static/diagrams/ica.dot 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/diagrams/ica.dot 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,72 @@ +digraph ICAdiagram { + /* LAYOUT CONTROL */ + rankdir=LR + newrank=true + ranksep=0.75 + clusterrank=local + + /* GLOBAL STYLES */ + splines=true + fontsize=20 + fontname="Source Code Pro" + + node [style="filled" + fontsize=18 + fontname="Source Sans Pro"] + + edge [arrowsize=1.2 + penwidth=2.5 + color="gray50" + fontsize=12 + fontname="Source Code Pro"] + + /* starting node */ + sensor [label="Sensor data" shape="box" fillcolor="#bbbbbb"] + + /* ICA.FIT() */ + subgraph cluster_0 { + label="ICA.fit()" + color="#009988" + fontcolor="#009988" + penwidth=1.5 + + /* PRE-WHITENING */ + subgraph cluster_1 { + label="Pre-whitening" + style="dashed" + fontname="Source Sans Pro" + color="gray50" + fontcolor="gray50" + /* nodes & edges */ + pca [label="PCA" shape="circle" fillcolor="#ee7733"] + pcs [label="Principal\ncomponents" shape="box" fillcolor="#33bbee"] + pca -> pcs [label="max_pca_components\r"] + } + + /* nodes & edges */ + ica [label="ICA" shape="circle" fillcolor="#ee7733"] + ics [label="Independent\ncomponents" shape="box" fillcolor="#33bbee"] + ica -> ics [label="n_components\r"] + } + + /* ICA.APPLY() */ + subgraph cluster_2 { + label="ICA.apply()" + color="#ee3377" + fontcolor="#ee3377" + penwidth=1.5 + /* ending node */ + recon [label="Reconstructed\nsensor data" shape="box" fillcolor="#bbbbbb"] + } + + /* subgraph-crossing edges */ + sensor -> pca [label="all sensor channels\r" fontsize=14 fontname="Source Sans Pro"] + pcs -> ica [label="n_components\l"] + ics -> recon [constraint=false color="#ee3377" + xlabel="Retained ICs:\ln_components -\llen(ICA.exclude)\l"] + pcs -> recon [constraint=false color="#ee3377" + xlabel="PCA residual:\ln_pca_components\l- n_components\l"] + + /* position recon box where we want it */ + { rank="same" recon ica } +} diff -Nru python-mne-0.18.1+dfsg/doc/_static/flow_diagram.svg python-mne-0.19.1+dfsg/doc/_static/flow_diagram.svg --- python-mne-0.18.1+dfsg/doc/_static/flow_diagram.svg 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/flow_diagram.svg 1970-01-01 00:00:00.000000000 +0000 @@ -1,204 +0,0 @@ - - - - - - -%3 - -cluster0 - -Structural information - - -src - -Source space -mne.SourceSpaces - - -fwd - - - - - - - -Forward solution -mne.forward.Forward - - -src->fwd - - - - -bem - -BEM - - -bem->fwd - - - - -recon - -Freesurfer surfaces - - -recon->src - - -setup_source_space - - -recon->bem - - - - -T1 - -T1 - - -T1->recon - - - - -flashes - -Flash5/30 - - -flashes->bem - - - - -inv - - - - - - - -Inverse operator -mne.minimum_norm.Inverse - - -fwd->inv - - - - -stc - -Source estimate -mne.SourceEstimate - - -inv->stc - - - - -pre - -Preprocessed data -mne.io.Raw - - -epo - -Epoched data -mne.Epochs - - -pre->epo - - -Epochs - - -epo->stc - - -apply_inverse_epochs - - -evo - -Averaged data -mne.Evoked - - -epo->evo - - -epochs.average - - -cov - -Noise covariance -mne.Covariance - - -epo->cov - - -compute_covariance - - -evo->stc - - -apply_inverse - - -cov->inv - - -make_inverse_operator - - -raw - -Raw data -mne.io.Raw - - -raw->pre - - -raw.filter -etc. - - -trans - - - - - - - -Head-MRI trans - - -trans->fwd - - -make_forward_solution - - - diff -Nru python-mne-0.18.1+dfsg/doc/_static/font-awesome.css python-mne-0.19.1+dfsg/doc/_static/font-awesome.css --- python-mne-0.18.1+dfsg/doc/_static/font-awesome.css 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/font-awesome.css 2019-10-25 14:42:45.000000000 +0000 @@ -6,8 +6,8 @@ * -------------------------- */ @font-face { font-family: 'FontAwesome'; - src: url('./fontawesome-webfont.eot?v=4.7.0'); - src: url('./fontawesome-webfont.eot?#iefix&v=4.7.0') format('embedded-opentype'), url('./fontawesome-webfont.woff2?v=4.7.0') format('woff2'), url('./fontawesome-webfont.woff?v=4.7.0') format('woff'), url('./fontawesome-webfont.ttf?v=4.7.0') format('truetype'); + src: url('./fonts/fontawesome/fontawesome-webfont.eot?v=4.7.0'); + src: url('./fonts/fontawesome/fontawesome-webfont.eot?#iefix&v=4.7.0') format('embedded-opentype'), url('./fonts/fontawesome/fontawesome-webfont.woff2?v=4.7.0') format('woff2'), url('./fonts/fontawesome/fontawesome-webfont.woff?v=4.7.0') format('woff'), url('./fonts/fontawesome/fontawesome-webfont.ttf?v=4.7.0') format('truetype'); font-weight: normal; font-style: normal; } Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fontawesome-webfont.eot and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fontawesome-webfont.eot differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fontawesome-webfont.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fontawesome-webfont.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fontawesome-webfont.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fontawesome-webfont.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fontawesome-webfont.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fontawesome-webfont.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/fontawesome/fontawesome-webfont.eot and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/fontawesome/fontawesome-webfont.eot differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/fontawesome/fontawesome-webfont.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/fontawesome/fontawesome-webfont.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/fontawesome/fontawesome-webfont.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/fontawesome/fontawesome-webfont.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/fontawesome/fontawesome-webfont.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/fontawesome/fontawesome-webfont.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-Bold.eot and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-Bold.eot differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-BoldIt.eot and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-BoldIt.eot differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-It.eot and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-It.eot differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-Regular.eot and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-Regular.eot differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-Semibold.eot and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-Semibold.eot differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-SemiboldIt.eot and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/EOT/SourceCodePro-SemiboldIt.eot differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-BoldIt.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-BoldIt.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-Bold.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-Bold.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-It.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-It.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-Regular.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-Regular.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-SemiboldIt.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-SemiboldIt.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-Semibold.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/OTF/SourceCodePro-Semibold.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-BoldIt.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-BoldIt.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-Bold.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-Bold.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-It.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-It.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-Regular.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-Regular.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-SemiboldIt.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-SemiboldIt.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-Semibold.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/TTF/SourceCodePro-Semibold.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-BoldIt.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-BoldIt.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-Bold.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-Bold.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-It.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-It.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-Regular.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-Regular.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-SemiboldIt.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-SemiboldIt.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-Semibold.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF/SourceCodePro-Semibold.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-BoldIt.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-BoldIt.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-Bold.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-Bold.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-It.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-It.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-Regular.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-Regular.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-SemiboldIt.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-SemiboldIt.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-Semibold.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_code_pro/WOFF2/SourceCodePro-Semibold.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-BoldIt.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-BoldIt.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-Bold.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-Bold.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-It.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-It.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-Regular.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-Regular.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-SemiboldIt.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-SemiboldIt.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-Semibold.otf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/OTF/SourceSansPro-Semibold.otf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-BoldIt.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-BoldIt.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-Bold.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-Bold.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-It.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-It.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-Regular.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-Regular.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-SemiboldIt.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-SemiboldIt.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-Semibold.ttf and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/TTF/SourceSansPro-Semibold.ttf differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-BoldIt.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-BoldIt.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-Bold.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-Bold.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-It.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-It.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-Regular.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-Regular.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-SemiboldIt.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-SemiboldIt.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-Semibold.otf.woff and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF/SourceSansPro-Semibold.otf.woff differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-BoldIt.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-BoldIt.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-Bold.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-Bold.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-It.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-It.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-Regular.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-Regular.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-SemiboldIt.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-SemiboldIt.ttf.woff2 differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-Semibold.ttf.woff2 and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/fonts/source_sans_pro/WOFF2/SourceSansPro-Semibold.ttf.woff2 differ diff -Nru python-mne-0.18.1+dfsg/doc/_static/font-source-code-pro.css python-mne-0.19.1+dfsg/doc/_static/font-source-code-pro.css --- python-mne-0.18.1+dfsg/doc/_static/font-source-code-pro.css 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/font-source-code-pro.css 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,167 @@ +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 200; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-ExtraLight.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-ExtraLight.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-ExtraLight.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-ExtraLight.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-ExtraLight.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 200; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-ExtraLightIt.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-ExtraLightIt.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-ExtraLightIt.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-ExtraLightIt.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-ExtraLightIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 300; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-Light.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-Light.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-Light.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-Light.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-Light.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 300; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-LightIt.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-LightIt.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-LightIt.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-LightIt.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-LightIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 400; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-Regular.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-Regular.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-Regular.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-Regular.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-Regular.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 400; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-It.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-It.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-It.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-It.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-It.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 500; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-Medium.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-Medium.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-Medium.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-Medium.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-Medium.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 500; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-MediumIt.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-MediumIt.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-MediumIt.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-MediumIt.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-MediumIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 600; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-Semibold.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-Semibold.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-Semibold.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-Semibold.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-Semibold.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 600; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-SemiboldIt.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-SemiboldIt.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-SemiboldIt.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-SemiboldIt.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-SemiboldIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 700; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-Bold.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-Bold.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-Bold.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-Bold.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-Bold.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 700; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-BoldIt.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-BoldIt.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-BoldIt.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-BoldIt.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-BoldIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 900; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-Black.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-Black.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-Black.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-Black.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-Black.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Code Pro'; + font-weight: 900; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_code_pro/EOT/SourceCodePro-BlackIt.eot') format('embedded-opentype'), + url('./fonts/source_code_pro/WOFF2/SourceCodePro-BlackIt.ttf.woff2') format('woff2'), + url('./fonts/source_code_pro/WOFF/SourceCodePro-BlackIt.otf.woff') format('woff'), + url('./fonts/source_code_pro/OTF/SourceCodePro-BlackIt.otf') format('opentype'), + url('./fonts/source_code_pro/TTF/SourceCodePro-BlackIt.ttf') format('truetype'); +} diff -Nru python-mne-0.18.1+dfsg/doc/_static/font-source-sans-pro.css python-mne-0.19.1+dfsg/doc/_static/font-source-sans-pro.css --- python-mne-0.18.1+dfsg/doc/_static/font-source-sans-pro.css 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/font-source-sans-pro.css 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,131 @@ +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 200; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-ExtraLight.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-ExtraLight.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-ExtraLight.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-ExtraLight.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 200; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-ExtraLightIt.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-ExtraLightIt.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-ExtraLightIt.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-ExtraLightIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 300; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-Light.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-Light.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-Light.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-Light.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 300; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-LightIt.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-LightIt.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-LightIt.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-LightIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 400; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-Regular.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-Regular.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-Regular.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-Regular.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 400; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-It.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-It.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-It.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-It.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 600; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-Semibold.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-Semibold.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-Semibold.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-Semibold.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 600; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-SemiboldIt.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-SemiboldIt.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-SemiboldIt.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-SemiboldIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 700; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-Bold.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-Bold.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-Bold.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-Bold.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 700; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-BoldIt.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-BoldIt.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-BoldIt.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-BoldIt.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 900; + font-style: normal; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-Black.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-Black.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-Black.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-Black.ttf') format('truetype'); +} + +@font-face{ + font-family: 'Source Sans Pro'; + font-weight: 900; + font-style: italic; + font-stretch: normal; + src: url('./fonts/source_sans_pro/WOFF2/SourceSansPro-BlackIt.ttf.woff2') format('woff2'), + url('./fonts/source_sans_pro/WOFF/SourceSansPro-BlackIt.otf.woff') format('woff'), + url('./fonts/source_sans_pro/OTF/SourceSansPro-BlackIt.otf') format('opentype'), + url('./fonts/source_sans_pro/TTF/SourceSansPro-BlackIt.ttf') format('truetype'); +} diff -Nru python-mne-0.18.1+dfsg/doc/_static/institution_logos/Aalto.svg python-mne-0.19.1+dfsg/doc/_static/institution_logos/Aalto.svg --- python-mne-0.18.1+dfsg/doc/_static/institution_logos/Aalto.svg 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/institution_logos/Aalto.svg 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,2466 @@ + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + eJzsvWtvHbmVKPrdgP+D7ocBOrhjpfgmcwcDSFvSmZxRHshjZg4GB4Hjdnp8Y9kNtzu5Ob/+rjdZ +VdxbcludZBKpErf2EjeLXFxcXG/+w//181++uPjy/W9fvwjny9nzZ//wD4cPr19+fP/hR2cEPvvx +27fffvPxA4K++MUPztxyvmCrix/X30jLf3v94Zs379/9yP52g9/+4ttvXn/4wdkXr97fff3y3Z9+ +gH/41ZuPb1/Dn3797iP+9uWL/AN7I/Rw9fIj/LX+0OUf+sW5s/Aj+OfnP8Eml++/ffflm3dfXb7/ +/3505sNyFrKH/9ezWBL+/V/e/OL1N9tG5y4VbOX1l3KewhLgO/G8hlbxi1fvX3179/rdx59/eP/q +9TffHN6/ff/hmx+dHf708t3ZT15+BX95efa/Xr99+/6PZ5dvX776PXzn4sfpNzdv3r6Gad69/HiW +adIXPw6/oS//+hv4FnSAvxO8/ObHdwD65euPH2Fs0Dfh6PCT//Wv4zsBe/J88Z+/eP3VG0I54OR/ +/4Cxnbn3X77++iX/Afrj73wBfzy7ev27l9++/civPeut4NePP6Bl/b/PfvY1Qr6hb+WzBf7D/+dH +Xl8NoM8Lh//rzfa/4e+A3rPI7/n5z6/wHZ4b5OUsJvizly+43Qvw+YIGiUj81eu7r98CIfAitnqe +zqJfzkNtefNRvwBLQY3bWYxnqaazGvRvfXVf/+HN6z/+6Oyn79+9liW8+PDxl2/+DyxVauk8xlTO +anTntRJdYINffPv29Ydfv3vzEVFGsMaL8JP3X75+C4PrHd28ffkVIbbPkP6VFr96+eGr1x+BQt+/ +/fYjbZW66N9++u3d7cs/vf4wvORnX79+96v3/0YDfpFcPKvF48AyrVz0Z80DPnkJXTsrbVhA7Rb7 +wB6074Jr83Ogw599ePPVm3c/QmQxZYXf/Pzl168//OL1q48/etEAeRWQmM9e2J9/AqOnb7yAV0OL +KGT9Pz68+bJTNWywyv/QzM/r8P+m/5cJAro+fnz9TrbC9bsvD+/vcJm+oa0O1P8Otsbb91/JX/sH ++hu889uvZZoE+A2s6s8/vHmHI3n+7KfwN8DZ5buxyf/48PLLN/AGYD60jf/x7N//683H12e/APDL +t7DHpmCi68svnz/7z+fP/un5s5ubm+ubq5vDzeXNxU27qTflJt+km3gTbvyNu1mub66vr6+uD9eX +1xfX7bpel+t8na7jdbj21+56ubq5ur66ujpcXV5dXLUroLOrcpWv0lW8Clf+yl0th5vD9eHqcDhc +Hi4O7VAP5ZAP6RAP4eAP7rBc3lxeX15dHi4vLy8u22W9LJf5Ml3Gy3DpL90loPPi5uL64uricHF5 +cXHRLupFucgX6SJehAt/4S6WdtOu21U7tMt20VqrrbTcUostNN9cW+pNva5X9VAv6wVsBRhjLTXX +VCMQhq+uLuWmXJerciiX5aK0UkspuaQSSyi+uLLkm3ydr/IhX+aL3HLNJeeccszAiLPLMMZ0k67T +VTqky3QBm6+mknJKKaaQfHJpiTfxOl7FQ7yMF7HFCvw6xxRjDNFHF5dwE67DVTiEy3ARWoAxhhJy +SCGGEHxwYfE3/tpf+YO/9Be++eqLzz756IP33sHhcuOu3ZU7uEt34ZqrrrjsYKe54LxzDsa4wHIu +sCDL5QJIW2DaS15gaAt0vjjcvf8Mjc7+4TeXH4g8OidM+B+A/xLo7zcb8OU32tIxCHratB3+gK0v +r4SMYR8oER8h7MP7r2EfIy3Lb9BbGcgXkI5oZ8Qj6hH5iH5cAFwCXARcBlwIXApaDFoOXBBcElwU +XBZcmIvnz2BxcHlwgXCJeJFwmXChcKlgsWi5cMFwyXDRcNl44WDp4Cm0eLh8cJLjV0OgZcSFhKWk +xeTlxAXFJcVFxWXFhcWlxcXF5cUF5iXGRYZl9rBMsNS42LjcuOC45LjouOy48Lz0uPi4/EgASAJI +BI6WGPAmG2W9VdabxbYLbZZxu6w3DG2Z589s06y3zXrjrLeObB7ZOuvNA7x9tYHWW2i9idbbaNxI +tJV0I9FKjJtpvZ3WG2q9pQ6KN2RIj8mOgBUphh+JHT1/NuD0UdgR4G3A4qexI8Ub0V9/tj/L+gFG +tX6uNw/0C4xsfA6753LzXGyetn6gx7p5yubJmydtnrh+oEdkrevHb57d1PmH8OaEFQP+Svikx+8e +NzwwFeiRp3Rjz7U8V/Ic6Lmk54KeJjsY6a0QzSHVId3BA3THOxr3tCP03CAV2s45PODZ/lzY0+Sp +8gB/QNbDw7sk5o9s4ZIYMbJTZIm07De0X3HH4p7lXYv7lneu7l3YvSBo+GEH2x7WGYB4M3/q7inD +owhN8tCRg8cG9IgikicxyRER39BzTQITi0woNKHYxIITi04qPKn4ZAIU4ORiJkTpDIjL9WdCJrsn +b540PLDmdDrxCaWPt7NKziviBXpi8ZnFp1Y/t+zkAqIvs9Nrux+AuwF10TbExji0QHSI9Ig/SJ9I +qY0oF4kEqRkXAmn8hqgfX4WThB0znIuXgOwrWH2QhoFNOKCIANSRaAsUoJkG1HMJi4L0dH1xAzTm +AMeBqC/Biwpgv8Eq4M94bnCbdYsDrNv15Q2wKwerGWBdEwyzwGpfwMofgAauDzdAGQ5oJADVJJhA +AfpqA19F/CCeEmENJ4VHNOIT8XpJeEaMI+5hFWhFHK0RrhauHa4lorD4usUzsCLkSvgl5F7I15DT +IeIRhZV4J3JT3GrIdZGMkUMD1yaG5ogMbIzQ+XacPMpj43TTcRaiXxRZYHeS9ITbAbcSnuogWxGz +xdfilwNJYCgAIovC5UYZDWU1lBAuSX7DDYnyHMgPIAPiRHHA+Fr8ciQpAwkMpUKUDlFKRLaBy36g +LY3SJEiVdBQg8eJw8aUxwazh7EXSRPEIZVOUUVFWRbaFG/oK5VhdU8K54jsRpqth+UD4vSHMOsIs +r3zH5iXhkbDIKw0YCoa9Qni7MIxdE64cYSkQljLhh7FzSZgBrAhGPOMCMKSYaISDg86f5u5p1pHm +XGi2OlOc5w3tWd2xifYq0B2dLRe0T3GP3tAedbQ7I6ANN3QBSagBy74ERois9brcwDHtgBQCLgkg +NoMkhdaOC5KsLkHGugJZ6waIFDeEh0lFQH0GiQxl39Z5u+F8jfE1vtfYHnEtmBY8A5aJ1yqe11ge +cbzGsOGXsLvGLVDlgNs1Ztd4HbC6xugGn4Vk9o7PNTZHXK7xuMZiGzkmnKBrjrnml8ItB5zrz1YK +Up6zfbbSVNjJW9F41PbZSm/Kw9bPSgI0mbBNnq08ebGTOJUnDg/0qFxy/WwlXOGh22ePJuCos5+1 +vL07P7c6pZzPa32ya5Nlqk2qpA5jJXlcpe4LMS9Uk5qTmBmCybyLUoEaPERnPqVh3G/ygLHCNFdm +j53RY272+Cfk+lsjzKfpPNvRkCxzeixHRjLdD/PnQT+rvfbAb2zkLbWqsF2FLStsW2HrCttXgoiG +jjV2s7SwrYWtLWRvAWyzHk9WF9JB1e7Clhe2vbB2zxYYtsEEETidWmJE5wfeQ+c3W2TYJqNWmQux +zLBtpoqSlNVCQyusNpogYiwsGfToRGm7EXvNtdhs2GrDdhu23LDtpq0k61FipkHr+m40ka6HqBWB +tBCzJLAecrmy2ahFgWwKILeqXUEtC2y7WVtv1vYbtTGwlUHtDGLDgbMhih7pRE+8Fq3w0qwO1XTA +bs1R2wNbH9T+ALQDNKT2uLix6qgt4iDU0Mz61m073uxuanO7NL1sY4L+XAM0aZYrE/TnWnxAFtmY +oD/X4gPy0sYE/bkWH+M9x60uYnuZPnv7i5wG0OPsXNyfnhObjDz1yKm8P73ndpq5tWaw2QySgz57 +SWNuv5lbcdyKf6Ip/XyBxTpbzh2IWPgfF9CJBJw2TIzmD2lMZvfzkCs6ofISsX1u0WNDOHa4YU1D +p/e35T5jQj/cOUio+J8KOMIxpIRW/BLOmwv5rIwdP/ALDxpxDg8fMbTtzgfxR4Q491MAnN/vQivQ +C4rq+J/kCLO+CWaHr9/fVGYE2wmHVxo2qCUFbJeqLJYfJ3Rf0090j/zi5Zt3v33/R/SP6K/onh79 +e4/g0xsZKrDbR/DpjQwVjsNH8OmNDBXY7SP49EaGSgLQZ/v0RnGShYvP9emNAiWQ4kakZH/eOWDH +M2ufs8Dv/EiPc3b7nR7o8RF72/R47Lj4xAd6fKSejvS4dUN8h2fvzGBaWMn013X1tBPPxYnnUh/o +8XLzHE48Vyce+YEe9z83x5+JwmyKMz/AEN3k8SeecPQh0RV6jNMnnXjy0Qe4FvRYjjz1xNPGx+zD +D7RXPdRaBWzrgfaqh1qrQJJ9oL3qodYqYP8PtFc9xFqFdns4kx9qua/32+7hUIUxwvF6BaR+AyK1 +g2M3wPGb4BgutBMvaO/gPrgh2vVEbYnoA1cahnZjvoUjUvPDngcxj8dnR38RJvyXOno+64jds+1T +TPX0s2XPx9j2Zz67Hk8dHw96oMdP/c6p4wwe6PGeFp/6SI/1uz7GssPjPn/lPZIdjw6qR33++nrU +9f0c7Wumez1/9jna10z3ev7sc7Svme71/NnnaF8z3ev5s8/Rvma61/Nnn6N9LW3Cqj/Xi7iVykD6 ++kwv4lYqA8X2M72IW6kMpK/P9CJupbLnz47JZd9VKgPp64hcdr9UZlLXwzyM43O/RHO/LHWfPDdY +U6HHmY11Zo094bGceC9n/sv7vZlTz+bK3nyPp3PzHPkZ/KH+nmdysAmLfuih/7jiy+eIWJ+ieU+f +k4LlKV396AM9ntTuP/3nU+0B4zNjz8eM/MeerZNgFvD5ec/cwva4Nrvvz8L2SJa2Byh330EB1c39 +WJZwlcVA/nokS7jKYnDgPZIlXGUxkL8eyRKushiFtD2KJVxlMZC/HskSrnZw3D1qA3ehrLY/++SW +QqlctZJjCeQydRdt3HEn27EXqJWchjauZW1Tx65ONpOelkbuvlIjvQ2dROLwWvV0qpn05FOiJpHe +CVjXJnHV06lm3BPPWcZL2NQmfoWoU82kJ+cIl3mpmyarjk60+kQf2a8+vP/6zauXb89++e27b15/ +RF/ZFgSdJvWZLRyve2rb3qdETTauZdyUdeTGJmpjjNlI04wb3cbQ4zpi4954jSZx+xqxEcdofTRK +WzbVYZVNdTqXap9N1fOpQErZxPYci+zR2B6N7vErzXk4Hzk216Kqb/Q5IbTq4+5/gJX7Bz7hYQ/0 +iFrIpz3p1AM9Hv9r/i4P9DiDl+/+kEmizBXi+fMdTbkPlmY+1af5aVLbSalxImfOg0iOP7vgku8W +FDioro8Q4tyNE3RyP0KIczdOSMD8Z4c4d+MESUCPEOLcjRMkpZ1wGh0zTmyUTLX/Fns0EyvZI9GT +1xLheO3tkZwa1KmhR47PupGna1z6c7DnUp4Le7bJTIAuyuWepTBpElO8Cvb4IZXJaQ== + + + QtOQ1HQjsvK1pTdxipP+aA7YhT1NnmqPMpjOpDo77OxTma+y6s7gNSrt5nKmDtpum7mIryfP1e5Z +HSfQec9y2j4Xk6ftnrp+oEeNx94+efKkyTMzas/M8jN7yexnEo8+tec8NJJwEkM4jSB8aPTgOgDi +nyjPpA6SUM9gDNv8Rc1glOzktVxkeeYU17qVj9YS0lpGWuecX+4lJMquyRb9OsY9mzS0yj+/msQ6 +r+Kcnz/bRDlrJvqYi369yUdfZ6Svc9KTZP6t8/3WmX4nsvwGmjWaFKdSp7Mhu0BopWf16mp34UEO ++ad8nj9/Ps+nWOKBXT8wQuKUJX7CvB/XAnMBhPS4FpgCCuvjWmAorfBRLTAexnjcArPaWpoS2hNC +y7JOB+3JoLNU0GRpoHyojWmgV0P64j4FVBJVNf1zSP601E+KrdynfpYhsXGd9nkzJDiuEz4l3ZPK +gkzSPUllcLKNe9JjXqV5rpI8JW3ZUZmGMW25Jy0beW/MVRSDjHHWdWqlmv9ZAqTPS5J/4E8hnQMe +w1kq58DFVgHTJ9vdZwpK6Ty7+iBzkDSVkGwad3Q9WjvG8xbD2NXxNtxHHYO9XTtHehu+Pv3zJxqS +fv3u3cu711+efSUgtCTtYE/h10/h10/h17MeP9Mp9AnOoc/r8XuJd/wOmZ0Pev5b9fhoP5+ez/rX +0OM2p/Yp/v4p/v4p/v4p/v4B0fKPfh79RU7hv5Ts8Vky1j9zoEBoT0H4T0H4fx0h84/f419pyPzj +9/gUhP93EIT/XUI773ke3OODnfrQ46eGAfx19fgX0S539QmfMiyeMiz6c7/Mer+0/JRhoc9ThsVT +hsWnZlj80yNb0r5fi+TnPX/Np/nnyDDT7/7zU+rMU+rMU+rMU+rMnyd1hkxuD8yfWbc9nkQztLs3 +k2bd9ng6DWeqPCynZt32v31izTb24czNIiIACv2PMRFPZ8fT2fF0dvx9nh1PJpsnk82TyebJZPNk +snky2TyZbP6sJpunkIUHPU8hC99HgMHj9/hXGmDwFLLwFLLwFLLwV9rjX0TyeAr7fgr7fgr7fgr7 +fgr7fqAZ+7EM459lrp+HfT+lcz6lcz6lc9LzmZzkszjKp/T4vfDRp3TO5Smdc3/F36N44B8zJuD7 +iFj4XiIrvocIkMeLUPmsmAg/D4rwq6Kj/0QxDL1S0TEH6VytmCoWJyoWzR2lx9QLUzCeP1upGHMl +45jDdFAzjHk+gvN3VJhACLjf+ftJ6hIIKp/t+kV1yW6qZT37pj8rD2AvLeeHJwxPHB5AMyjqXCAw +D08ZnrmZYe5eWzu8jrmm5kr/Tqnf1OHqlbh6La5O4Z0OOiV0WljROVXpc1RxLKzKATWqVnbZCwER +ZXRlutP7huKpoqwbaKSr1Z1SOq10aun0QhSzNfOsROFjwvDcTDkVh2Gcx0TiuVB87y3qgMtRMJ6L +xsciPQbhWNf6L6QmfILxFkNFHkNJsJgmNlWN1D+WPOwmsvFn3FkbJ5uZ8o45pPp+LpOCoZOiodDj +unTounyoH3jOWJhx4FA8UJ1xv89b1qWvTF+bvjpdjetrtKJbWJFLq1hY5D52NbUr9fb16ivW12xD +wbAJL6XWYLUag7x6nY47JVvUUlf0yFC8q9bxdD4/nc9P5/PT+fx0Pj+dz0/n81/Z+UzmF3gdGgaA +DTTU5yP+G1JuM6X//raaVJEKWgUStagwDjUOlHq+1NZWhp372nKfp9+dwnkLPj94rNr+vvH6Txiv +/4TxPhyrn29MmdtSyJTi1/e3LNv6z/dVgL5HtgFefFq+uS/4fOeyhfNiLeWcdNveK+eApPP82QlZ +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 +eH1x7zmu+9ms7ZI94r3c4HG8g5Kt6tU8v1/6XdVbeb5F+n1+v/i7rj389IBX/u2ri/M3m7PbZyCi +tX38Noz6rzeX13fP9hFuf0N6c/+VPm6StzFruhMPUuqO48p2sUWv+5/7d+HWdhj/80uZGj4tTvi6 +kay/vNk1blVs8PXdz5v7HTUbpr3H5zebm9t//fHlbkPsbyRI4i4Wm3tz++Ls/OLb87M99riqWLXp +yhf7Ypb4bz+9urm+uN7H3rKqzS2Wv2uDpzfXr+/O9tngGvfXV//eQs9H4u5YISH8NMj6Pq6b1Vps +Pk0PzsdJAT4oh+eedGBzeffXs8udXOmDIwQrpGuPIwJnt5d3L68u7tZ14ybEYLKxf+6y0gxuzDXt +BNa72MMuEWyte7Bb9uA/LEET1rvYw/3vfV17cA9gjn+6uP3h12KM2z4N//vD5svrNNZfPsQN9JGc +yBqliv3O4wm+tP8s72vwduuKNHmYuXtlm3h4FFNY10YeGcW0st08Lorpq4u3F5tvX549v/lxlXkp +H3CUz59ubl+9vNnc/HAvvfoNWdTt2fPLN/dHhtmTVWU/y6qXeu+Ha/96sGFiVfvYZQ== + + + kdhbi39+uTlbl5tptwa/B4ld1eHsQVO3CNoHMrZCMraue/WIcMs17eNAvFZ8OA8iXh9FsOiqTuER +T31V+sVO18kez2JVG9mW9LFHmOvxumJEf37A4z6kxP/Sx7I9JX4fmrWuJ/IIorUugfGJsvpXtamn +y+pfVTDfp5TV/94cdFUX8EGS5deXr19tzs4vri6u7/509mrFHOiTIte7fPmrItf7hOes7Ilsi8zZ +56Gv6jy2ico/n748u76+2Hx7sbk430fH/3JNO1qufr6/n953f39b0/6Wq1+w0r3C/Fd1DV9rfP/7 +sZxTSMP401kbd6/zeO0Kz9W7dvGBqTqruluP4Z2rsgg8xj6zqo1sYzq4kPtFf3Mk/z1a/Kud/Oua +Niybe2/69huUxZis4Oz68mq3+X4NtPXF5WazhzHp4uJ/VmVGomXPD1zH/RmXfl+4+v31Ln6Tvc12 +sbjVtzdXH1ZoLq14vo+7mw/L+gLrne/h+f1k5fO4iyr/NmbxN1sk3iY9nv/p5v7A1883l9cXZ6uK +9O1LXxCD8/M3V2/e4T0dDWLXq6Ju49IX23r+/PLu8u39m7q9QGvSqvala98iUN6d3e4RmbT58ezn +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 +C0js2Fs= + + + \ No newline at end of file Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/Aarhus.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/Aarhus.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/BIDS.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/BIDS.png differ diff -Nru python-mne-0.18.1+dfsg/doc/_static/institution_logos/BU.svg python-mne-0.19.1+dfsg/doc/_static/institution_logos/BU.svg --- python-mne-0.18.1+dfsg/doc/_static/institution_logos/BU.svg 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/institution_logos/BU.svg 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1 @@ + \ No newline at end of file Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/CEA.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/CEA.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/Graz.jpg and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/Graz.jpg differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/Harvard.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/Harvard.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/ICM.jpg and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/ICM.jpg differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/Ilmenau.gif and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/Ilmenau.gif differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/inria.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/inria.png differ diff -Nru python-mne-0.18.1+dfsg/doc/_static/institution_logos/Inserm.svg python-mne-0.19.1+dfsg/doc/_static/institution_logos/Inserm.svg --- python-mne-0.18.1+dfsg/doc/_static/institution_logos/Inserm.svg 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/institution_logos/Inserm.svg 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,46 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff -Nru python-mne-0.18.1+dfsg/doc/_static/institution_logos/Julich.svg python-mne-0.19.1+dfsg/doc/_static/institution_logos/Julich.svg --- python-mne-0.18.1+dfsg/doc/_static/institution_logos/Julich.svg 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/institution_logos/Julich.svg 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,41 @@ + + + + + + image/svg+xml + + Logo_FZ_Juellich_RGB_schutzzone_weiss + + + + + Logo_FZ_Juellich_RGB_schutzzone_weiss + + + Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/Martinos.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/Martinos.png differ diff -Nru python-mne-0.18.1+dfsg/doc/_static/institution_logos/MGH.svg python-mne-0.19.1+dfsg/doc/_static/institution_logos/MGH.svg --- python-mne-0.18.1+dfsg/doc/_static/institution_logos/MGH.svg 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/institution_logos/MGH.svg 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff -Nru python-mne-0.18.1+dfsg/doc/_static/institution_logos/MIT.svg python-mne-0.19.1+dfsg/doc/_static/institution_logos/MIT.svg --- python-mne-0.18.1+dfsg/doc/_static/institution_logos/MIT.svg 1970-01-01 00:00:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/institution_logos/MIT.svg 2019-10-25 14:42:45.000000000 +0000 @@ -0,0 +1,9 @@ + + + + + + + + + \ No newline at end of file Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/NYU.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/NYU.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/Telecom_Paris_Tech.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/Telecom_Paris_Tech.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institution_logos/Washington.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institution_logos/Washington.png differ Binary files /tmp/tmpmItHjQ/LIHbrWDTSj/python-mne-0.18.1+dfsg/doc/_static/institutions.png and /tmp/tmpmItHjQ/2KQvhfTJHE/python-mne-0.19.1+dfsg/doc/_static/institutions.png differ diff -Nru python-mne-0.18.1+dfsg/doc/_static/reset-syntax.css python-mne-0.19.1+dfsg/doc/_static/reset-syntax.css --- python-mne-0.18.1+dfsg/doc/_static/reset-syntax.css 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/reset-syntax.css 2019-10-25 14:42:45.000000000 +0000 @@ -1,12 +1,9 @@ .highlight a { color: rgb(41, 122, 204); } -div.highlight { - background-color: #fafafa; -} .highlight * { color: inherit; font-weight: inherit; font-style: inherit; - background-color: transparent; + background-color: #fafafa; } diff -Nru python-mne-0.18.1+dfsg/doc/_static/style.css python-mne-0.19.1+dfsg/doc/_static/style.css --- python-mne-0.18.1+dfsg/doc/_static/style.css 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_static/style.css 2019-10-25 14:42:45.000000000 +0000 @@ -1,15 +1,52 @@ :root { --a-color-dark: rgb(31, 92, 153); --a-color: rgb(41, 122, 204); - --a-hover-color: rgb(102, 179, 255); + --a-color-light: rgb(102, 179, 255); + --a-color-lighter: rgb(204, 230, 255); } html { position: relative; min-height: 100%; } - +/* overrides of bootstrap fonts */ body { - margin-bottom: 150px; + font-family:"Source Sans Pro", sans-serif; +} +h1,h2,h3,h4,h5,h6,.h1,.h2,.h3,.h4,.h5,.h6 { + font-family:"Source Sans Pro", sans-serif; +} +code,kbd,pre,samp { + font-family:"Source Code Pro", monospace; + font-size: 100%; +} +/* reduce horizontal padding for inline code (bootstrap defaults to 4px) */ +p code { + padding: 0 2px 0; +} +/* use semibold instead of bold for API links */ +code.xref, a code { + font-weight: 600; +} +/* .. unless in a param list */ +span.classifier a.reference code.literal { + font-weight: bold; +} +/* use semibold weight for version dropdown */ +.btn { + font-weight: 600; +} +/* Modify our definition lists to be more like sklearn */ +dl.field-list dt.field-odd, dt.field-even { + border-right-style: solid; + border-width: 1px; + border-color: var(--a-color-lighter); +} +dl.field-list dd dl dd { + padding-left: 30px; +} +dl.field-list dt, dd { + margin-top: 10px; + margin-bottom: 10px; } .navbar-version { @@ -22,7 +59,7 @@ } a:hover { - color: var(--a-hover-color); + color: var(--a-color-light); } blockquote { @@ -70,21 +107,23 @@ color: var(--a-color); } a:hover code { - color: var(--a-hover-color); + color: var(--a-color-light); } -.note a, .note a code { + +/* Background is light */ +.alert-info a, .alert-info a code { color: var(--a-color-dark); } -.note a:hover, .note a:hover code { +.alert-info a:hover, .alert-info a:hover code { color: var(--a-color); } -.note { - background-color: rgb(204, 230, 255); +.alert-info { + background-color: var(--a-color-lighter); color: rgb(0, 0, 0); border: none; } -.note pre { - background-color: rgb(242, 249, 255); +.alert-info pre { + background-color: var(--a-color-lighter); } .warning { background-color: rgb(230, 57, 57); @@ -177,6 +216,14 @@ margin: 10px; float: left; } +.table.midvalign td { + vertical-align: middle; + border-width: 2px; +} +.table.midvalign th { + border-width: 2px; + border-top-width: 2px; +} /* our carousel */ .chopper { overflow: hidden; @@ -207,9 +254,8 @@ width: 100%; } .footer { - position: absolute; - bottom: 0; width: 100%; + margin-top: 20px; } .footer a { font-weight: 700; @@ -296,6 +342,12 @@ display:block !important; } } +details.example_details summary { + font-weight: bold; +} +.panel { + margin-bottom: 3px; +} .skinnytable { width: auto; @@ -308,7 +360,7 @@ color: var(--a-color); } span.classifier a:hover span.xref, span.classifier a:hover code.docutils.literal.notranslate, span.classifier a.reference.external:hover { - color: var(--a-hover-color); + color: var(--a-color-light); } /* Allow easier copy-paste in code blocks */ @@ -359,3 +411,36 @@ dd table.align-center { width: 100%; } +/* Sphinx-gallery Report embedding */ +iframe.sg_report { + width: 95%; + height: 70vh; + margin: 20px auto; + display: block; + border-style: solid; +} +/* institutions logos in footer */ +div.institutions { + text-align: center; + line-height: 52px; + margin-bottom: 6px; + } +div.institutions a { + border: 0px; + margin-right: 6px; +} +.institution_xs .institution_sm .institution_md .institution_lg { + vertical-align: middle; + } + .institution_xs { + max-height: 24px; + } + .institution_sm { + max-height: 36px; + } + .institution_md { + max-height: 48px; + } + .institution_lg { + max-height: 60px; + } diff -Nru python-mne-0.18.1+dfsg/doc/_templates/autosummary/class.rst python-mne-0.19.1+dfsg/doc/_templates/autosummary/class.rst --- python-mne-0.18.1+dfsg/doc/_templates/autosummary/class.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_templates/autosummary/class.rst 2019-10-25 14:42:45.000000000 +0000 @@ -7,4 +7,8 @@ :special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__,__hash__ :members: -.. include:: {{module}}.{{objname}}.examples +.. include:: {{fullname}}.examples + +.. raw:: html + +
diff -Nru python-mne-0.18.1+dfsg/doc/_templates/autosummary/function.rst python-mne-0.19.1+dfsg/doc/_templates/autosummary/function.rst --- python-mne-0.18.1+dfsg/doc/_templates/autosummary/function.rst 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_templates/autosummary/function.rst 2019-10-25 14:42:45.000000000 +0000 @@ -5,7 +5,7 @@ .. autofunction:: {{ objname }} -.. include:: {{module}}.{{objname}}.examples +.. include:: {{ fullname }}.examples .. raw:: html diff -Nru python-mne-0.18.1+dfsg/doc/_templates/layout.html python-mne-0.19.1+dfsg/doc/_templates/layout.html --- python-mne-0.18.1+dfsg/doc/_templates/layout.html 2019-05-21 11:45:00.000000000 +0000 +++ python-mne-0.19.1+dfsg/doc/_templates/layout.html 2019-10-25 14:42:45.000000000 +0000 @@ -22,6 +22,8 @@ + + @@ -65,7 +67,26 @@ {%- block footer %}