|
Size: 2791
Comment:
|
Size: 7935
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 4: | Line 4: |
| {{attachment:mne_logo.png||align="right",width="195px"}} [[https://www.nmr.mgh.harvard.edu/mne/stable/index.html|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 an interesting 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. | {{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. |
| Line 6: | Line 6: |
| In order to use MNE-Python functions from Brainstorm you will need to: install a Python environment on your computer (version 3.5 or higher), install MNE-Python in your Python environment, and configure Matlab and Brainstorm to connect to this Python environment. For GUI users who are not very familiar with terminals and command-line operations, setting-up a Python environment with MNE-Python working might be a bit of challenge. 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 so that we can improve it. |
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. |
| Line 12: | Line 10: |
| == 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.24.1''', which requires '''Python >= 3.7'''. The oldest version of MATLAB supporting Python 3.7 is '''Matlab 2019a'''. If you are using an older version of Matlab, consider using either the compiled version of Brainstorm (based on Matlab 2020a, which supports recent Python integrations), or an older version of MNE-Python (which works with an older version of Python). See the complete list of compatible versions: [[https://pypi.org/project/mne/|MNE-Python/Python]] and [[http://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/python-support.pdf|Matlab/Python]]. Other combinations might work as well, with no guarantee. |
|
| Line 13: | Line 16: |
| First you need to install Python and MNE-Python package on your computer. This is done independently from MATLAB. Follow the installation instructions from the MNE-Python website: | In order to call MNE-Python functions from MATLAB or Brainstorm, you need to install a Python environment on your computer. 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. |
| Line 15: | Line 18: |
| https://www.nmr.mgh.harvard.edu/mne/stable/install_mne_python.html | 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. |
| Line 17: | Line 20: |
| == Configuration in Brainstorm == In an ideal configuration, your Python environment is automatically detected and configured by Matlab, and you can use any process based on MNE-Python without any additional configuration. This might be the case on Linux or MacOS, but Windows computers always require some manual setup. |
=== Windows 10 === Install Python: |
| Line 20: | Line 23: |
| Try to run a process using MNE-Python in Brainstorm. If it works, you can skip the rest of this section. Otherwise, follow the instructions below to locate the Python installation. | * Download the latest '''Python 3.8''' from [[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. |
| Line 22: | Line 26: |
| ==== Anaconda environments ==== If you installed MNE-Python in a dedicated environment using conda, the easiest way to get everything to work is to start MATLAB from the Anaconda prompt, with the correct environment activated. |
Install MNE-Python: |
| Line 25: | Line 28: |
| {{attachment:anaconda_prompt.gif}} | * 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 dipy nibabel nilearn neo python-picard PyQt5 mayavi PySurfer }}} |
| Line 27: | Line 34: |
| ==== Locate the Python executable ==== asks you where is your Python executable located on your hard drive, and |
Troubleshooting: Error mentioning Microsoft Visual Studio: |
| Line 30: | Line 36: |
| pyversion('C:\Users\franc\Anaconda3\envs\mne\python.exe'); | * You may 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 }}} Final check: * 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: Windows-10-10.0.19041-SP0 Python: 3.8.6 (tags/v3.8.6:db45529, Sep 23 2020, 15:52:53) [MSC v.1927 64 bit (AMD64)] Executable: C:\Users\franc\AppData\Local\Programs\Python\Python38\python.exe CPU: Intel64 Family 6 Model 94 Stepping 3, GenuineIntel: 8 cores Memory: 15.9 GB mne: 0.24.1 numpy: 1.19.3 {blas=D:\\a\\1\\s\\numpy\\build\\openblas_info, lapack=D:\\a\\1\\s\\numpy\\build\\openblas_lapack_info} scipy: 1.5.4 matplotlib: 3.3.2 {backend=Qt5Agg} sklearn: 0.23.2 numba: 0.51.2 nibabel: 3.2.0 nilearn: 0.6.2 dipy: 1.3.0 cupy: Not found pandas: 1.1.4 mayavi: 4.7.2 pyvista: 0.26.1 {OpenGL 4.5.0 - Build 26.20.100.8142 via Intel(R) HD Graphics 530} pyvistaqt: 0.2.0 ipyvtklink: Not found vtk: 9.0.1 PyQt5: 5.15.1 ipympl: Not found mne_qt_browser: Not found pooch: Not found }}} == 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 this doesn't work as expected, you may try to configure manually Python manually: * Matlab 2017b-2019a: `pyversion('/path/to/python')` * Matlab 2019b-2020b: `pyenv('Version', '/path/to/python')` * See Mathworks documentation: [[https://fr.mathworks.com/help/matlab/matlab_external/install-supported-python-implementation.html|Configure Your System to Use Python]] <<TAG(Advanced)>> == Anaconda environments == If you already have MNE-Python working in a dedicated conda environment, you may try to use it - with moderate chances of success. 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"}} Another solution is to configure the system environment variables from MATLAB: * The system path can be edited with `panel_options('SystemPathAdd', PythonPath);`, and may need to include the following subfolders: * .../env/mingw-w64/bin * .../env/Library/mingw-w64/bin * .../env/Library/usr/bin * .../env/Library/bin * .../env/Library/Scripts * .../env/bin * .../env/condabin * .../env/Scripts * You might need to set some additional environment variables for Qt to work: * `setenv('QT_PLUGIN_PATH', '.../env/Library/plugins/'));` * `setenv('QT_QPA_PLATFORM_PLUGIN_PATH', '.../env/Library/plugins/platforms');` |
| Line 33: | Line 120: |
| * [[https://github.com/brainstorm-tools/brainstorm3/blob/master/toolbox/io/out_mne_channel.m|out_mne_channel.m]] * [[https://github.com/brainstorm-tools/brainstorm3/blob/master/toolbox/io/out_mne_data.m|out_mne_data.m]] |
Using MNE-Python from Brainstorm
Authors: Francois Tadel
MNE-Python is an open-source software for processing neurophysiological signals written with the 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 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.
Contents
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.24.1, which requires Python >= 3.7. The oldest version of MATLAB supporting Python 3.7 is Matlab 2019a. If you are using an older version of Matlab, consider using either the compiled version of Brainstorm (based on Matlab 2020a, which supports recent Python integrations), or an older version of MNE-Python (which works with an older version of Python). See the complete list of compatible versions: MNE-Python/Python and Matlab/Python. Other combinations might work as well, with no guarantee.
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. The MNE-Python installation page recommends using the Anaconda distribution, which is unfortunately not officially supported by MATLAB.
The MATLAB-Python integration is only supported for 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 from 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 dipy nibabel nilearn neo python-picard PyQt5 mayavi PySurfer
Troubleshooting: Error mentioning Microsoft Visual Studio:
You may 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
Final check:
- 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: Windows-10-10.0.19041-SP0 Python: 3.8.6 (tags/v3.8.6:db45529, Sep 23 2020, 15:52:53) [MSC v.1927 64 bit (AMD64)] Executable: C:\Users\franc\AppData\Local\Programs\Python\Python38\python.exe CPU: Intel64 Family 6 Model 94 Stepping 3, GenuineIntel: 8 cores Memory: 15.9 GB mne: 0.24.1 numpy: 1.19.3 {blas=D:\\a\\1\\s\\numpy\\build\\openblas_info, lapack=D:\\a\\1\\s\\numpy\\build\\openblas_lapack_info} scipy: 1.5.4 matplotlib: 3.3.2 {backend=Qt5Agg} sklearn: 0.23.2 numba: 0.51.2 nibabel: 3.2.0 nilearn: 0.6.2 dipy: 1.3.0 cupy: Not found pandas: 1.1.4 mayavi: 4.7.2 pyvista: 0.26.1 {OpenGL 4.5.0 - Build 26.20.100.8142 via Intel(R) HD Graphics 530} pyvistaqt: 0.2.0 ipyvtklink: Not found vtk: 9.0.1 PyQt5: 5.15.1 ipympl: Not found mne_qt_browser: Not found pooch: Not found
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.
Windows example: C:\Users\username\AppData\Local\Programs\Python\Python38\python.exe
- Click Save. It should update the configuration of MATLAB and may ask you to restart MATLAB.
- If this doesn't work as expected, you may try to configure manually Python manually:
Matlab 2017b-2019a: pyversion('/path/to/python')
Matlab 2019b-2020b: pyenv('Version', '/path/to/python')
See Mathworks documentation: Configure Your System to Use Python
Anaconda environments
If you already have MNE-Python working in a dedicated conda environment, you may try to use it - with moderate chances of success. The most reliable way to get everything to work is to start MATLAB from the Anaconda prompt, with the correct environment activated.
Another solution is to configure the system environment variables from MATLAB:
The system path can be edited with panel_options('SystemPathAdd', PythonPath);, and may need to include the following subfolders:
- .../env/mingw-w64/bin
- .../env/Library/mingw-w64/bin
- .../env/Library/usr/bin
- .../env/Library/bin
- .../env/Library/Scripts
- .../env/bin
- .../env/condabin
- .../env/Scripts
- You might need to set some additional environment variables for Qt to work:
setenv('QT_PLUGIN_PATH', '.../env/Library/plugins/'));
setenv('QT_QPA_PLATFORM_PLUGIN_PATH', '.../env/Library/plugins/platforms');