Merge remote-tracking branch 'upstream/master' into refactor

* upstream/master: (24 commits)
  WIP: Fix Travis (mne-tools#7906)
  WIP: Prototype of notebook viz (screencast) (mne-tools#7758)
  MRG, FIX: Speed up I/O tests, mark some slow (mne-tools#7904)
  Proper attribution for Blender tutorial (mne-tools#7900)
  MAINT: Check usage [ci skip] (mne-tools#7902)
  Allow find_bad_channels_maxwell() to return scores (mne-tools#7845)
  Warn if NIRx directory structure has been modified from original format (mne-tools#7898)
  Pin pvyista to 0.24.3 (mne-tools#7899)
  MRG: Add support for reading and writing sufaces to .obj (mne-tools#7824)
  Fix _auto_topomap_coords docstring. (mne-tools#7895)
  MRG, FIX: Ensure Info H5-writeable (mne-tools#7887)
  Website contents (mne-tools#7889)
  MRG, ENH: Add mri_resolution="sparse" (mne-tools#7888)
  MRG, ENH: Allow disabling FXAA (mne-tools#7877)
  remove "and and" [ci skip] (mne-tools#7882)
  fix evoked nave → inverse guidance (mne-tools#7881)
  ENH: Better error messages (mne-tools#7879)
  FIX : EDF+ Annotation Timestamps missing sub-second accuracy (mne-tools#7875)
  FIX: Fix get_channel_types (mne-tools#7878)
  MRG, BUG: Fix combine evokeds (mne-tools#7869)
  ...

.circleci/config.yml

@@ -56,7 +56,7 @@ jobs:
             name: Install 3D rendering libraries \ PyQt5 dependencies \ graphviz \ optipng (for optimized images)
             command: |
               sudo apt-get install libosmesa6 libglx-mesa0 libopengl0 libglx0 libdbus-1-3 \
-                  libxkbcommon-x11-0 \
+                  libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xinerama0 \
                   graphviz \
                   optipng
 
@@ -81,7 +81,6 @@ jobs:
             command: |
               python -m pip install --user --upgrade --progress-bar off pip numpy setuptools
               python -m pip install --user --upgrade --progress-bar off -f "https://vtk.org/download" "vtk>=9"
-              python -m pip install --user --upgrade --progress-bar off https://github.com/enthought/mayavi/zipball/master
               python -m pip install --user --upgrade --progress-bar off -r requirements.txt
               python -m pip uninstall -yq pysurfer mayavi
               python -m pip install --user --upgrade --progress-bar off --pre sphinx
@@ -94,6 +93,10 @@ jobs:
             paths:
               - ~/.cache/pip
 
+        - run:
+            name: Check PyQt5
+            command: LD_DEBUG=libs python -c "from PyQt5.QtWidgets import QApplication, QWidget; app = QApplication([])"
+
         # Look at what we have and fail early if there is some library conflict
         - run:
             name: Check installation

.gitignore

@@ -46,6 +46,7 @@ coverage
 .pytest_cache/
 __pycache__/
 prof/
+mne/viz/_brain/tests/.ipynb_checkpoints
 
 dist/
 doc/_build/

.travis.yml

@@ -6,6 +6,7 @@ addons:
   apt:
     packages:
       - libxkbcommon-x11-0
+      - libxcb*
       - libosmesa6
       - libglx-mesa0
       - libopengl0
@@ -52,22 +53,21 @@ before_install:
     - if [ "${TRAVIS_OS_NAME}" == "linux" ]; then
         /sbin/start-stop-daemon --start --quiet --pidfile /tmp/custom_xvfb_99.pid --make-pidfile --background --exec /usr/bin/Xvfb -- :99 -screen 0 1400x900x24 -ac +extension GLX +render -noreset;
       fi;
-    - if [ -z "$CONDA_ENV" ] && [ -z "$CONDA_DEPENDENCIES" ]; then
-        pip uninstall -yq numpy;
-        pip install -i "https://pypi.anaconda.org/scipy-wheels-nightly/simple" --pre numpy;
-        pip install -f "https://7933911d6844c6c53a7d-47bd50c35cd79bd838daf386af554a83.ssl.cf2.rackcdn.com" scipy pandas scikit-learn matplotlib h5py Pillow;
-        pip install -f "https://vtk.org/download" "vtk>=9";
-        pip install https://github.com/enthought/mayavi/zipball/master;
-        pip install $PIP_DEPENDENCIES;
-        pip install --upgrade -r requirements.txt;
+    - |
+      if [ -z "$CONDA_ENV" ] && [ -z "$CONDA_DEPENDENCIES" ]; then
+        pip uninstall -yq numpy
+        pip install -i "https://pypi.anaconda.org/scipy-wheels-nightly/simple" --pre numpy
+        pip install -f "https://7933911d6844c6c53a7d-47bd50c35cd79bd838daf386af554a83.ssl.cf2.rackcdn.com" scipy pandas scikit-learn matplotlib h5py Pillow
+        pip install -f "https://vtk.org/download" "vtk>=9"
+        pip install --upgrade -r requirements.txt
       else
-        git clone https://github.com/astropy/ci-helpers.git;
-        source ci-helpers/travis/setup_conda.sh;
+        git clone https://github.com/astropy/ci-helpers.git
+        source ci-helpers/travis/setup_conda.sh
         if [ ! -z "$CONDA_ENV" ]; then
-          conda activate base;
-          conda env update --file $CONDA_ENV;
-          pip uninstall -yq mne;
-        fi;
+          conda activate base
+          conda env update --file $CONDA_ENV
+          pip uninstall -yq mne
+        fi
       fi
     # Always install these via pip so we get the latest possible versions (testing bugfixes)
     - pip install --upgrade "pytest<5.4" pytest-sugar pytest-cov pytest-mock pytest-timeout pytest-xdist codecov
@@ -141,7 +141,7 @@ script:
         pip install -e .;
         python mne/tests/test_evoked.py;
       fi;
-    - echo pytest -m "${CONDITION}" --cov=mne -n 1 ${USE_DIRS}
+    - echo 'pytest -m "${CONDITION}" --cov=mne -n 1 ${USE_DIRS}'
     - pytest -m "${CONDITION}" --tb=short --cov=mne -n 1 ${USE_DIRS}
     # run the minimal one with the testing data
     - if [ "${DEPS}" == "minimal" ]; then

MANIFEST.in

@@ -32,6 +32,7 @@ recursive-include mne mne/datasets *.csv
 include mne/io/edf/gdf_encodes.txt
 include mne/datasets/sleep_physionet/SHA1SUMS
 include mne/externals/tqdm/_tqdm/tqdm.1
+include mne/viz/_brain/tests/test.ipynb
 
 ### Exclude
 

Makefile

@@ -105,10 +105,10 @@ flake:
 	@echo "flake8 passed"
 
 codespell:  # running manually
-	@codespell --builtin clear,rare,informal,names -w -i 3 -q 3 -S $(CODESPELL_SKIPS) --ignore-words=ignore_words.txt $(CODESPELL_DIRS)
+	@codespell --builtin clear,rare,informal,names,usage -w -i 3 -q 3 -S $(CODESPELL_SKIPS) --ignore-words=ignore_words.txt $(CODESPELL_DIRS)
 
 codespell-error:  # running on travis
-	@codespell --builtin clear,rare,informal,names -i 0 -q 7 -S $(CODESPELL_SKIPS) --ignore-words=ignore_words.txt $(CODESPELL_DIRS)
+	@codespell --builtin clear,rare,informal,names,usage -i 0 -q 7 -S $(CODESPELL_SKIPS) --ignore-words=ignore_words.txt $(CODESPELL_DIRS)
 
 pydocstyle:
 	@echo "Running pydocstyle"

azure-pipelines.yml

@@ -15,11 +15,9 @@ jobs:
 - job: Style
   pool:
     vmImage: 'ubuntu-18.04'
-  strategy:
-    matrix:
-      Python37-64bit-fast:
-        PYTHON_VERSION: '3.7'
-        PYTHON_ARCH: 'x64'
+  variables:
+    PYTHON_VERSION: '3.8'
+    PYTHON_ARCH: 'x64'
   steps:
   - task: UsePythonVersion@0
     inputs:
@@ -28,6 +26,7 @@ jobs:
       addToPath: true
     displayName: 'Get Python'
   - bash: |
+      set -e
       python -m pip install --upgrade pip setuptools
       python -m pip install numpy scipy matplotlib sphinx pytest pytest-cov pytest-timeout pytest-sugar flake8
     displayName: Install dependencies
@@ -89,7 +88,7 @@ jobs:
     OPENBLAS_NUM_THREADS: '1'
   steps:
   - bash: |
-      sudo apt install libxkbcommon-x11-0 xvfb tcsh
+      sudo apt install libxkbcommon-x11-0 xvfb tcsh libxcb*
     displayName: 'Install Ubuntu dependencies'
   - bash: |
       source tools/get_minimal_commands.sh
@@ -124,16 +123,55 @@ jobs:
     displayName: 'Get test data'
   - script: pytest -m "ultraslowtest" --tb=short --cov=mne -n 1 mne
     displayName: 'Run ultraslow tests'
-  - script: codecov --root %BUILD_REPOSITORY_LOCALPATH% -t %CODECOV_TOKEN%
+  - script: codecov --root $BUILD_REPOSITORY_LOCALPATH -t $CODECOV_TOKEN
     displayName: 'Codecov'
     env:
       CODECOV_TOKEN: $(CODECOV_TOKEN)
-    condition: always()
+    condition: succeededOrFailed()
   - task: PublishTestResults@2
     inputs:
       testResultsFiles: 'junit-*.xml'
-      testRunTitle: 'Publish test results for Python $(python.version)'
-    condition: always()
+      testRunTitle: 'Publish test results for $(Agent.JobName)'
+      failTaskOnFailedTests: true
+    condition: succeededOrFailed()
+
+
+- job: Notebook
+  pool:
+    vmImage: 'ubuntu-18.04'
+  variables:
+    CONDA_ENV: 'server_environment.yml'
+  steps:
+  - bash: |
+      set -e
+      wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh --progress=dot:mega
+      bash miniconda.sh -b -p ~/miniconda
+      source ~/miniconda/etc/profile.d/conda.sh
+      conda activate base
+      conda env update --file $CONDA_ENV
+      pip uninstall -yq mne
+      pip install -ve .
+      pip install pytest pytest-cov pytest-timeout pytest-sugar pytest-xdist flake8 codecov
+      echo "##vso[task.setvariable variable=PATH]${PATH}"
+      echo "##vso[task.setvariable variable=LD_LIBRARY_PATH]${LD_LIBRARY_PATH}"
+    displayName: 'Install dependencies'
+  - script: mne sys_info
+    displayName: 'Print config and test access to commands'
+  - script: python -c "import mne; mne.datasets.testing.data_path(verbose=True)"
+    displayName: 'Get test data'
+  - script: pytest --tb=short --cov=mne mne/viz
+    displayName: 'Run viz tests'
+  - script: codecov --root $BUILD_REPOSITORY_LOCALPATH -t $CODECOV_TOKEN
+    displayName: 'Codecov'
+    env:
+      CODECOV_TOKEN: $(CODECOV_TOKEN)
+    condition: succeededOrFailed()
+  - task: PublishTestResults@2
+    inputs:
+      testResultsFiles: 'junit-*.xml'
+      testRunTitle: 'Publish test results for $(Agent.JobName)'
+      failTaskOnFailedTests: true
+    condition: succeededOrFailed()
 
 
 - job: Windows
@@ -220,15 +258,16 @@ jobs:
     displayName: Print NumPy config
   - script: python -c "import mne; mne.datasets.testing.data_path(verbose=True)"
     displayName: 'Get test data'
-  - script: pytest -m "not ultraslowtest" --tb=short --cov=mne -n 1 mne
+  - script: pytest -m "not slowtest" --tb=short --cov=mne -n 1 mne
     displayName: 'Run tests'
   - script: codecov --root %BUILD_REPOSITORY_LOCALPATH% -t %CODECOV_TOKEN%
     displayName: 'Codecov'
     env:
       CODECOV_TOKEN: $(CODECOV_TOKEN)
-    condition: always()
+    condition: succeededOrFailed()
   - task: PublishTestResults@2
     inputs:
       testResultsFiles: 'junit-*.xml'
-      testRunTitle: 'Publish test results for Python $(python.version)'
-    condition: always()
+      testRunTitle: 'Publish test results for $(Agent.JobName) $(TEST_MODE) $(PYTHON_VERSION)'
+      failTaskOnFailedTests: true
+    condition: succeededOrFailed()

doc/_templates/layout.html

@@ -64,7 +64,7 @@
 {% endblock %}
 
 {# put the sidebar before the body #}
-{% block sidebar1 %}{{ sidebar() }}{% endblock %}
+{% block sidebar1 %}{% endblock %}
 {% block sidebar2 %}{% endblock %}
 
 {%- block footer %}

doc/changes/latest.inc

@@ -67,16 +67,22 @@ Changelog
 
 - Add "on_missing='raise'" to :meth:`mne.io.Raw.set_montage` and related functions to allow ignoring of missing electrode coordinates by `Adam Li`_
 
+- Add better sanity checking of ``max_pca_components`` and ``n_components`` to provide more informative error messages for :class:`mne.preprocessing.ICA` by `Eric Larson`_
+
 - Add ``plot`` option to :meth:`mne.viz.plot_filter` allowing selection of which filter properties are plotted and added option for user to supply ``axes`` by `Robert Luke`_
 
 - Add estimation method legend to :func:`mne.viz.plot_snr_estimate` by `Eric Larson`_
 
+- Add support to `mne.SourceSpaces.export_volume` for ``mri_resolution='sparse'`` to color only the nearest-neighbor voxels instead of entire regions by `Eric Larson`_
+
 - Add ``axes`` argument to :func:`mne.viz.plot_evoked_white`, :meth:`mne.Evoked.plot_white`, and :func:`mne.viz.plot_snr_estimate` by `Eric Larson`_
 
 - Add ``sources`` and ``detectors`` options for fNIRS use of :meth:`mne.viz.plot_alignment` allowing plotting of optode locations in addition to channel midpoint ``channels`` and ``path`` between fNIRS optodes by `Kyle Mathewson`_
 
 - Add ECoG misc EDF dataset to the :ref:`tut_working_with_ecog` tutorial to show snapshots of time-frequency activity by `Adam Li`_
 
+- Add :func:`mne.viz.set_3d_options` and ``MNE_3D_OPTION_ANTIALIAS`` environment variable to control full-scene antialiasing (FXAA) in 3D functions like :ref:`mne coreg`, :func:`mne.viz.plot_alignment`, and :func:`mne.viz.plot_source_estimates`; this can be useful on systems where FXAA does not work well, such as some with MESA software rendering, by `Eric Larson`_
+
 - Add better support for reading corrupted FIF files in :func:`mne.io.read_raw_fif` by `Eric Larson`_
 
 - BIDS conformity: When saving FIF files to disk and the files are split into parts, the ``split_naming='bids'`` parameter now uses a "_split-%d" naming instead of the previous "_part-%d", by `Stefan Appelhoff`_
@@ -89,6 +95,12 @@ Changelog
 
 - Add ``'auto'`` option to :meth:`mne.preprocessing.ICA.find_bads_ecg` to automatically determine the threshold for CTPS method by `Yu-Han Luo`_
 
+- Add a ``notebook`` 3d backend for visualization in jupyter notebook with :func:`mne.viz.set_3d_backend` by`Guillaume Favelier`_
+
+- Add support for reading and writing surfaces in Wavefront .obj format to the :func:`mne.read_surface` and :func:`mne.write_surface` by `Marijn van Vliet`_
+
+- Add tutorial on how to manually fix BEM meshes in Blender by `Marijn van Vliet`_ and `Ezequiel Mikulan`_
+
 Bug
 ~~~
 
@@ -98,6 +110,8 @@ Bug
 
 - Fix bug with :func:`mne.setup_volume_source_space` when ``volume_label`` was supplied where voxels slightly (in a worst case, about 37% times ``pos`` in distance) outside the voxel-grid-based bounds of regions were errantly included, by `Eric Larson`_
 
+- Fix bug with `mne.SourceSpaces.export_volume` with ``use_lut=False`` where no values were written by `Eric Larson`_
+
 - Fix bug with :func:`mne.preprocessing.annotate_movement` where bad data segments, specified in ``raw.annotations``, would be handled incorrectly by `Luke Bloy`_
 
 - Fix bug with :func:`mne.compute_source_morph` when more than one volume source space was present (e.g., when using labels) where only the first label would be interpolated when ``mri_resolution=True`` by `Eric Larson`_
@@ -108,6 +122,8 @@ Bug
 
 - Fix bug with :func:`mne.preprocessing.compute_current_source_density` where values were not properly computed; maps should now be more focal, by `Alex Rockhill`_ and `Eric Larson`_
 
+- Fix bug with :func:`mne.combine_evoked` where equal-weighted averages were wrongly computed as equal-weighted sums, by `Daniel McCloy`_
+
 - Fix to enable interactive plotting with no colorbar with :func:`mne.viz.plot_evoked_topomap` by `Daniel McCloy`_
 
 - Fix plotting with :func:`mne.viz.plot_evoked_topomap` to pre-existing axes by `Daniel McCloy`_
@@ -128,6 +144,8 @@ Bug
 
 - Fix default to be ``foreground=None`` in :func:`mne.viz.plot_source_estimates` to use white or black text based on the background color by `Eric Larson`_
 
+- Fix bug with writing EGI and CTF `mne.Info` to H5 format, e.g., with `mne.time_frequency.AverageTFR.save` by `Eric Larson`_
+
 - Fix bug with :func:`mne.io.Raw.plot` where toggling all projectors did not actually take effect by `Eric Larson`_
 
 - Fix bug with :func:`mne.read_epochs` when loading data in complex format with ``preload=False`` by `Eric Larson`_
@@ -187,6 +205,10 @@ Bug
 
 - Fix bug with :func:`mne.bem.make_watershed_bem` where the RAS coordinates of watershed bem surfaces were not updated correctly from the volume file by `Yu-Han Luo`_
 
+- Fix bug with :meth:`mne.io.Raw.get_channel_types` and related methods where the ordering of ``picks`` was not preserved, by `Eric Larson`_
+
+- Fix bug with :meth:`mne.io.Raw.plot_psd` with ``average=False`` and multiple channel types where channel locations were not shown properly by `Eric Larson`_
+
 - Fix bug in FieldTrip reader functions when channels are missing in the ``info`` object by `Thomas Hartmann`_
 
 - Throw proper error when trying to import FieldTrip Epochs data with non-uniform time for trials by `Thomas Hartmann`_

doc/changes/names.inc

@@ -305,3 +305,5 @@
 .. _Lx37: https://github.com/Lx37
 
 .. _Kyle Mathewson: https://github.com/kylemath
+
+.. _Ezequiel Mikulan: https://github.com/ezemikulan

doc/conf.py

@@ -325,7 +325,7 @@
     # 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/'),
+             'https://dipy.org/documentation/1.1.1./objects.inv/'),
     'mne_realtime': ('https://mne.tools/mne-realtime', None),
     'picard': ('https://pierreablin.github.io/picard/', None),
 }

doc/index.rst

@@ -52,8 +52,8 @@
           <li style="background: url('_static/funding/anr.svg') no-repeat left top; background-size: 24px 10px;"><b>Agence Nationale de la Recherche:</b> 14-NEUC-0002-01<br><b>IDEX</b> Paris-Saclay, 11-IDEX-0003-02</li>
           <li style="background: url('_static/funding/cds.png') no-repeat left top; background-size: 24px 24px;"><b>Paris-Saclay Center for Data Science:</b> <a href="http://www.datascience-paris-saclay.fr"/>PARIS-SACLAY</a></li>
           <li style="background: url('_static/funding/google.svg') no-repeat left top; background-size: 24px 24px;"><b>Google:</b> Summer of code (×6)</li>
-          <li style="background: url('_static/funding/amazon.svg') no-repeat left top; background-size: 24px 24px;"><b>Amazon:</b> - AWS Research Grants</li>
-          <li style="background: url('_static/funding/czi.svg') no-repeat left top; background-size: 24px 24px;"><b>Chan Zuckerberg Initiative:</b> - <a href="https://chanzuckerberg.com/eoss/proposals/improving-usability-of-core-neuroscience-analysis-tools-with-mne-python/">Essential Open Source Software for Science</a></li>
+          <li style="background: url('_static/funding/amazon.svg') no-repeat left top; background-size: 24px 24px;"><b>Amazon:</b> AWS Research Grants</li>
+          <li style="background: url('_static/funding/czi.svg') no-repeat left top; background-size: 24px 24px;"><b>Chan Zuckerberg Initiative:</b> <a href="https://chanzuckerberg.com/eoss/proposals/improving-usability-of-core-neuroscience-analysis-tools-with-mne-python/">Essential Open Source Software for Science</a></li>
         </ul>
       </div>
     </div>

doc/install/advanced.rst

@@ -61,6 +61,19 @@ 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.
 
+It is also possible to interact with the 3D plots without installing Qt by using
+the notebook 3d backend:
+
+.. code-block:: ipython
+
+   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 :doc:`mne_python`
+
+
 .. _installing_master:
 
 Using the development version of MNE-Python (latest master)
@@ -160,6 +173,17 @@ to force MESA to use modern OpenGL by using this before executing
 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:
+
+.. code-block:: console
+
+    $ export MNE_3D_OPTION_ANTIALIAS=false
+
+or by doing
+:func:`mne.viz.set_3d_options(antialias=False) <mne.viz.set_3d_options>` within
+a given Python session.
+
 .. _troubleshoot_3d:
 
 Troubleshooting 3D plots in MNE-Python

doc/install/mne_python.rst

@@ -124,6 +124,7 @@ 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
+.. _server environment file: https://raw.githubusercontent.com/mne-tools/mne-python/master/server_environment.yml
 
 .. collapse:: |linux| Linux
 
@@ -179,6 +180,11 @@ you can create a new dedicated environment (here called "mne") with
 .. collapse:: |hand-stop-o| If you are installing on a headless server...
     :class: danger
 
+    With `pyvista`_:
+    Follow the steps described in :ref:`standard_instructions`
+    but use `server environment file`_ instead of `environment file`_.
+
+    With `mayavi`_:
     Installing `mayavi`_ requires a running `X server`_. If you are
     installing MNE-Python into a computer with no display connected to it, you
     can try removing `mayavi`_ from the :file:`environment.yml` file before
@@ -294,6 +300,7 @@ Python development are:
 .. LINKS
 
 .. _`mayavi`: https://docs.enthought.com/mayavi/mayavi/
+.. _`pyvista`: https://docs.pyvista.org/
 .. _`X server`: https://en.wikipedia.org/wiki/X_Window_System
 .. _`xvfb`: https://en.wikipedia.org/wiki/Xvfb
 .. _`off-screen rendering`: https://docs.enthought.com/mayavi/mayavi/tips.html#off-screen-rendering