Advanced setup#
Working with Jupyter Notebooks and JupyterLab#
If you like using Jupyter notebooks, you should also update the “base”
conda environment to include the nb_conda_kernels package; this will
make it easier to use MNE-Python in Jupyter Notebooks launched from the
Anaconda GUI:
$ conda install --name=base nb_conda_kernels
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:
$ ipython --matplotlib=qt
or in a Jupyter Notebook, you can use the “magic” command:
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:
In [1]: %matplotlib inline
but some functionality will be lost. For example, PyVista 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.
Windows
If you are using MNE-Python on Windows through IPython or Jupyter, you might
also have to use the IPython magic command %gui qt (see here). For example:
In [2]: %gui qt
If you installed the nb_conda_kernels package into your base
environment (as recommended), you should be able to launch mne-capable
notebooks from within the Anaconda Navigator GUI without having to explicitly
switch to the mne environment first; look for Python [conda env:mne]
when choosing which notebook kernel to use. Otherwise, be sure to activate the
mne environment before launching the notebook.
If you use another Python setup and you encounter some difficulties please report them on the MNE Forum or on the GitHub issues page to get assistance.
It is also possible to interact with the 3D plots without installing Qt by using the notebook 3d backend:
In [1]: import mne
In [2]: mne.viz.set_3d_backend("notebook")
The notebook 3d backend requires PyVista to be installed along with other packages, please follow Install via pip or conda.
Installing to a headless server#
With pyvista: Download the server environment file and use it to create the conda environment
$ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/main/server_environment.yml
$ conda env create -f server_environment.yml
Using the development version#
See Upgrading to the development version for how to do a one-time update to the latest
development version of MNE-Python. If you plan to contribute to MNE-Python, or
just prefer to use git rather than pip to make frequent updates, there are
instructions for installing from a git clone in the Contributing guide.
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.
A similar alternative is MiniForge, which uses the conda-forge channel
as the default source for package installation (saving you the trouble of
typing --channel=conda-forge with each conda install command).
Warning
If you have the PYTHONPATH or PYTHONHOME environment variables set,
you may run into difficulty using Anaconda. See the
Anaconda troubleshooting guide for more information. Note that it is
easy to switch between conda-managed Python installations and the
system Python installation using the conda activate and conda
deactivate commands, so you may find that after adopting Anaconda it is
possible (indeed, preferable) to leave PYTHONPATH and PYTHONHOME
permanently unset.
It is also possible to use a system-level installation of Python (version
3.7 or higher) and use pip to install MNE-Python and its
dependencies, using the provided requirements file:
$ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/main/requirements.txt
$ pip install --user -r 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.
GPU acceleration with CUDA#
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:
$ 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')
You can then test MNE CUDA support by running the associated test:
$ 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
mne.io.Raw.filter() and mne.io.Raw.resample(),
and they should run faster than the CPU-based multithreading such as
n_jobs=8.
Off-screen rendering with MESA#
On remote Linux 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:
$ 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.
MESA also can have trouble with full-screen antialiasing, which you can disable with:
$ export MNE_3D_OPTION_ANTIALIAS=false
or by doing
mne.viz.set_3d_options(antialias=False) within
a given Python session.
Another issue that may come up is that the MESA software itself may be out of date in certain operating systems, for example CentOS. This may lead to incomplete rendering of some 3D plots. A solution is described in this Github comment. It boils down to building a newer version (e.g., 18.3.6) locally following a variant of these instructions. If you have CentOS 7 or newer, you can also try some prebuilt binaries we made. After downloading the files, untar them and add them to the appropriate library paths using the following commands:
$ tar xzvf mesa_18.3.6_centos_lib.tgz
$ export LIBGL_DRIVERS_PATH="${PWD}/lib"
$ export LD_LIBRARY_PATH="${PWD}/lib"
To check that everything went well, type the following:
$ glxinfo | grep "OpenGL core profile version"
which should give:
OpenGL core profile version string: 3.3 (Core Profile) Mesa 18.3.6
Another way to check is to type:
$ mne sys_info
and it should show the right version of MESA:
...
pyvista: 0.27.4 {pyvistaqt=0.2.0, OpenGL 3.3 (Core Profile) Mesa 18.3.6 via llvmpipe (LLVM 3.4, 256 bits)}
...
Troubleshooting 3D plots#
3D plotting trouble after upgrade on macOS#
When upgrading MNE-Python from version 0.19 or lower, some macOS users may end up with conflicting versions of some of the 3D plotting dependencies. If you plot using the pyvista 3D backend and find that you can click-drag to rotate the brain, but cannot adjust any of the settings sliders, it is likely that your versions of VTK and/or QT are incompatible. This series of commands should fix it:
$ conda uninstall vtk
$ pip uninstall -y pyvista
$ conda install vtk
$ pip install --no-cache pyvista
If you installed VTK using pip rather than conda, substitute the first
line for pip uninstall -y vtk.