= Using MNE-Python from Brainstorm =
''Authors: Francois Tadel''

{{attachment:mne_logo.png||align="right",width="195px"}} [[https://mne.tools/|MNE-Python]] is an open-source software for processing neurophysiological signals written with the [[https://en.wikipedia.org/wiki/Python_(programming_language)|Python programming language]]. It provides a rich library of methods that are not available in Brainstorm, especially for MEG signal pre-processing, statistics and machine learning. Since MATLAB now offers a very efficient [[https://www.mathworks.com/help/matlab/call-python-libraries.html|interface with Python environments]], it makes more sense to use directly the MNE-Python code rather than trying to recode its original features in MATLAB scripts. This tutorial will teach you how to set up MNE-Python for using it within MATLAB/Brainstorm.

For GUI users who are not familiar with terminals and command-line operations, setting-up a Python environment with MNE-Python might be challenging. The programs involved here are subject to frequent changes, we will most likely need to update this page regularly. If the documentation below is incomplete or incorrect, please share your comments on the user forum.

<<TableOfContents(2,2)>>

== Requirements ==
The Python integration in MATLAB is recent has been changing a lot over the years. Only a limited number of Python distributions are supported in MATLAB, you need to make sure you are using versions of MATLAB, Python and MNE-Python that are compatible.

The reference version used to write this documentation is '''MNE-Python 0.21''', which requires '''Python >= 3.6'''. The oldest version of MATLAB supporting Python 3.6 is '''Matlab 2017b'''. If you are using versions of Matlab older than this, consider using the compiled version of Brainstorm, based on Matlab 2020a, which supports recent Python integrations.

 * Python 3.6 is supported by MATLAB 2017b-2020b ([[https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/python-support.pdf|Mathworks website]])
 * Python 3.7 is supported by MATLAB 2019a-2020b
 * Python 3.8 is supported by MATLAB 2020b

== Installing Python and MNE-Python ==
In order to call MNE-Python functions from MATLAB or Brainstorm, you need to install a Python environment on your computer  (version 3.6). The MNE-Python [[https://mne.tools/stable/install/mne_python.html|installation page]] recommends using the Anaconda distribution, which is unfortunately not officially supported by MATLAB.

The MATLAB-Python integration is only supported for [[https://en.wikipedia.org/wiki/CPython|CPython]], the reference implementation of the Python programming language. Using other Python distributions is possible, but may take a lot of extra manual configuration work, and would break often with new software updates. Therefore we strongly recommend you use CPython instead of Anaconda.

=== Windows 10 ===
Install Python:

 * Download the latest '''Python 3.8''' on [[https://www.python.org/downloads/windows/|python.org]] (Windows x86-64 executable installer)
 * Execute the installer: select the option "'''Add Python to PATH'''", this will make it much easier to access Python from the Windows command prompt and from MATLAB.

Install MNE-Python:

 * Open the Windows command prompt (press the keys Windows+R and execute "cmd").
 * Install MNE-Python and all its dependencies with the following command:
 * {{{
C:\> pip install numpy scipy matplotlib numba pandas xlrd scikit-learn h5py pillow statsmodels jupyter joblib psutil numexpr traits pyface traitsui imageio tqdm spyder-kernels mne imageio-ffmpeg vtk pyvista pyvistaqt mayavi PySurfer dipy nibabel nilearn neo python-picard PyQt5
}}}

Troubleshooting: Error mentioning Microsoft Visual Studio:

 * You might need to install some pre-compiled packages instead of the standard ones. For example, if the error occurs during the setup of the package `traits`, download its latest version from this website (cp38 for CPython 3.8): https://www.lfd.uci.edu/~gohlke/pythonlibs/#traits
 * {{{
C:\> cd C:\Users\username\Downloads\
C:\> pip install traits‑6.1.1‑cp38‑cp38‑win_amd64.whl
}}}

Troubleshooting: Error mentioning a bug in numpy:

 * You may need to install an version of numpy older than the current one, for instance:
 * {{{
C:\> pip install numpy==1.19.3
}}}

Test the MNE-Python installation with the following command:

 * {{{
C:\> 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-5.0.0-1031-gcp-x86_64-with-glibc2.2.5
Python:        3.8.1 (default, Dec 20 2019, 10:06:11)  [GCC 7.4.0]
Executable:    /home/travis/virtualenv/python3.8.1/bin/python
CPU:           x86_64: 2 cores
Memory:        7.8 GB

mne:           0.21.dev0
numpy:         1.19.0.dev0+8dfaa4a {blas=openblas, lapack=openblas}
scipy:         1.5.0.dev0+f614064
matplotlib:    3.2.1 {backend=Qt5Agg}

sklearn:       0.22.2.post1
numba:         0.49.0
nibabel:       3.1.0
cupy:          Not found
pandas:        1.0.3
dipy:          1.1.1
mayavi:        4.7.2.dev0
pyvista:       0.25.2 {pyvistaqt=0.1.0}
vtk:           9.0.0
PyQt5:         5.14.1
}}}

== Configure MATLAB ==
 * Start MATLAB (>= 2017b).
 * Start Brainstorm. Select menu: File > Edit preferences.
 * If the option `Python executable` is empty or not pointing at the correct Python version, click on the button [...], and select the appropriate `python.exe`. <<BR>>Windows example: `C:\Users\username\AppData\Local\Programs\Python\Python38\python.exe`<<BR>><<BR>> {{attachment:editpref.gif}}
 * Click Save. It should update the configuration of MATLAB and may ask you to restart MATLAB.
 * If you are having trouble with this step, or if you get errors in the MATLAB command window, you may try to set manually the python configuration:
  * Matlab 2017b-2019a: `pyversion('/path/to/python')`
  * Matlab 2019b-2020b: `pyenv('Version', '/path/to/python')`

== Anaconda environments ==
If you installed MNE-Python in a dedicated environment using conda, the most reliable way to get everything to work is to start MATLAB from the Anaconda prompt, with the correct environment activated.

{{attachment:anaconda_prompt.gif||width="498",height="166"}}

However, this is not the most convenient solution for Windows computers,  where you would just like to click on the Matlab icon. Try with the  other solutions first and get back to this one if you can't get it to  work in other ways.

 . panel_options('SystemPathAdd', PythonPath); setenv('QT_PLUGIN_PATH', bst_fileparts(PythonConfig.QtDir)); setenv('QT_QPA_PLATFORM_PLUGIN_PATH', PythonConfig.QtDir);

==== Locate the Python executable ====
asks you where is your Python executable located on your hard drive, and

pyversion('C:\Users\franc\Anaconda3\envs\mne\python.exe');

==== Windows ====
 * Open a terminal:
  *
  * Install compiled packages:
   * https://www.lfd.uci.edu/~gohlke/pythonlibs/#traits > traits‑6.1.1‑cp38‑cp38‑win_amd64.whl
   *
  *

== API description ==