Merge branch 'master' into resize

doc/changes/latest.inc

@@ -67,6 +67,8 @@ 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`_
@@ -77,6 +79,8 @@ Changelog
 
 - 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`_
@@ -104,6 +108,10 @@ Bug
 
 - Fix bug with :func:`mne.minimum_norm.apply_inverse` where the explained variance did not work for complex data by `Eric Larson`_
 
+- 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`_
@@ -176,6 +184,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/install/advanced.rst

@@ -160,6 +160,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/python_reference.rst

@@ -278,6 +278,7 @@ Visualization
    set_3d_backend
    get_3d_backend
    use_3d_backend
+   set_3d_options
    set_3d_view
    set_3d_title
    create_3d_figure

doc/references.bib

@@ -187,6 +187,14 @@ @article{CichyEtAl2014
   year = {2014}
 }
 
+@book{Cohen2014,
+  place={Cambridge, MA},
+  title={Analyzing Neural Time Series Data: Theory and Practice},
+  publisher={MIT Press},
+  author={Cohen, Mike X.},
+  year={2014}
+}
+
 @article{CohenHosaka1976,
   author = {Cohen, David and Hosaka, Hidehiro},
   doi = {10.1016/S0022-0736(76)80041-6},
@@ -382,7 +390,17 @@ @article{GlasserEtAl2016
   journal = {Nature},
   number = {7615},
   pages = {171-178},
-  title = {A Multi-Modal Parcellation of Human Cerebral Cortex},
+  title = {A multi-modal parcellation of human cerebral cortex},
+  volume = {536},
+  year = {2016}
+}
+
+@article{GlasserEtAl2016supp,
+  author = {Glasser, Matthew F. and Coalson, Timothy S. and Robinson, Emma C. and Hacker, Carl D. and Harwell, John and Yacoub, Essa and Ugurbil, Kamil and Andersson, Jesper and Beckmann, Christian F. and Jenkinson, Mark and Smith, Stephen M. and Van Essen, David C.},
+  url = {https://static-content.springer.com/esm/art%3A10.1038%2Fnature18933/MediaObjects/41586_2016_BFnature18933_MOESM330_ESM.pdf#page=2},
+  journal = {Nature},
+  number = {7615},
+  title = {Supplementary neuroanatomical results for “{A} multi-modal parcellation of human cerebral cortex”},
   volume = {536},
   year = {2016}
 }
@@ -1154,16 +1172,16 @@ @article{Pascual-Marqui2002
 }
 
 @article{Pascual-Marqui2011,
-	title = {Assessing interactions in the brain with exact low-resolution electromagnetic tomography},
-	volume = {369},
-	url = {https://royalsocietypublishing.org/doi/full/10.1098/rsta.2011.0081},
-	doi = {10.1098/rsta.2011.0081},
-	number = {1952},
-	journal = {Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences},
-	author = {Pascual-Marqui, Roberto D. and Lehmann, Dietrich and Koukkou, Martha and Kochi, Kieko and Anderer, Peter and Saletu, Bernd and Tanaka, Hideaki and Hirata, Koichi and John, E. Roy and Prichep, Leslie and Biscay-Lirio, Rolando and Kinoshita, Toshihiko},
-	month = oct,
-	year = {2011},
-	pages = {3768--3784}
+  title = {Assessing interactions in the brain with exact low-resolution electromagnetic tomography},
+  volume = {369},
+  url = {https://royalsocietypublishing.org/doi/full/10.1098/rsta.2011.0081},
+  doi = {10.1098/rsta.2011.0081},
+  number = {1952},
+  journal = {Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences},
+  author = {Pascual-Marqui, Roberto D. and Lehmann, Dietrich and Koukkou, Martha and Kochi, Kieko and Anderer, Peter and Saletu, Bernd and Tanaka, Hideaki and Hirata, Koichi and John, E. Roy and Prichep, Leslie and Biscay-Lirio, Rolando and Kinoshita, Toshihiko},
+  month = oct,
+  year = {2011},
+  pages = {3768--3784}
 }
 
 @book{PercivalWalden1993,
@@ -1177,6 +1195,20 @@ @book{PercivalWalden1993
   year = {1993}
 }
 
+@article{PerrinEtAl1987,
+  title = {Scalp {Current} {Density} {Mapping}: {Value} and {Estimation} from {Potential} {Data}},
+  volume = {BME-34},
+  issn = {1558-2531},
+  shorttitle = {Scalp {Current} {Density} {Mapping}},
+  doi = {10.1109/TBME.1987.326089},
+  number = {4},
+  journal = {IEEE Transactions on Biomedical Engineering},
+  author = {Perrin, F. and Bertrand, O. and Pernier, J.},
+  month = apr,
+  year = {1987},
+  pages = {283--288}
+}
+
 @article{PerrinEtAl1989,
   author = {Perrin, François M. and Pernier, Jacques and Bertrand, Olivier M. and Echallier, Jean Franćois},
   doi = {10.1016/0013-4694(89)90180-6},
@@ -1710,3 +1742,18 @@ @article{Zhang1995
   volume = {40},
   year = {1995}
 }
+
+@article{KayserTenke2015,
+  title = {On the benefits of using surface {Laplacian} ({Current} {Source} {Density}) methodology in electrophysiology},
+  volume = {97},
+  issn = {0167-8760},
+  doi = {10.1016/j.ijpsycho.2015.06.001},
+  number = {3},
+  journal = {International journal of psychophysiology : official journal of the International Organization of Psychophysiology},
+  author = {Kayser, Jürgen and Tenke, Craig E.},
+  month = sep,
+  year = {2015},
+  pmid = {26071227},
+  pmcid = {PMC4610715},
+  pages = {171--173}
+}

environment.yml

@@ -37,7 +37,7 @@ dependencies:
   - https://github.com/numpy/numpydoc/archive/master.zip
   - imageio-ffmpeg>=0.4.1
   - vtk
-  - pyvista>=0.24
+  - pyvista==0.24
   - https://github.com/enthought/mayavi/archive/master.zip
   - PySurfer[save_movie]
   - dipy --only-binary dipy

examples/datasets/plot_limo_data.py

@@ -161,8 +161,8 @@
 
 # Face A minus Face B
 difference_wave = combine_evoked([limo_epochs['Face/A'].average(),
-                                  -limo_epochs['Face/B'].average()],
-                                 weights='equal')
+                                  limo_epochs['Face/B'].average()],
+                                 weights=[1, -1])
 
 # plot difference wave
 difference_wave.plot_joint(times=[0.15], title='Difference Face A - Face B')

examples/preprocessing/plot_eeg_csd.py

@@ -3,13 +3,14 @@
 Transform EEG data using current source density (CSD)
 =====================================================
 
-This script shows an example of how to use CSD [1]_ [2]_ [3]_.
+This script shows an example of how to use CSD
+:footcite`PerrinEtAl1987,PerrinEtAl1989,Cohen2014,KayserTenke2015`.
 CSD takes the spatial Laplacian of the sensor signal (derivative in both
 x and y). It does what a planar gradiometer does in MEG. Computing these
 spatial derivatives reduces point spread. CSD transformed data have a sharper
 or more distinct topography, reducing the negative impact of volume conduction.
 """
-# Authors: Alex Rockhill <aprockhill206@gmail.com>
+# Authors: Alex Rockhill <aprockhill@mailbox.org>
 #
 # License: BSD (3-clause)
 
@@ -83,13 +84,4 @@
 ###############################################################################
 # References
 # ----------
-# .. [1] Perrin F, Bertrand O, Pernier J. "Scalp current density mapping:
-#        Value and estimation from potential data." IEEE Trans Biomed Eng.
-#        1987;34(4):283–288.
-# .. [2] Perrin F, Pernier J, Bertrand O, Echallier JF. "Spherical splines
-#        for scalp potential and current density mapping."
-#        [Corrigenda EEG 02274, EEG Clin. Neurophysiol., 1990, 76, 565]
-#        Electroenceph Clin Neurophysiol. 1989;72(2):184–187.
-# .. [3] Kayser J, Tenke CE. "On the benefits of using surface Laplacian
-#       (Current Source Density) methodology in electrophysiology.
-#       Int J Psychophysiol. 2015 Sep; 97(3): 171–173.
+# .. footbibliography::

examples/stats/plot_linear_regression_raw.py

@@ -57,8 +57,8 @@
               time_unit='s')
 epochs[cond].average().plot(axes=ax1, **params)
 evokeds[cond].plot(axes=ax2, **params)
-contrast = mne.combine_evoked([evokeds[cond], -epochs[cond].average()],
-                              weights='equal')
+contrast = mne.combine_evoked([evokeds[cond], epochs[cond].average()],
+                              weights=[1, -1])
 contrast.plot(axes=ax3, **params)
 ax1.set_title("Traditional averaging")
 ax2.set_title("rERF")

mne/beamformer/tests/test_external.py

@@ -12,6 +12,7 @@
 from mne.datasets import testing
 from mne.beamformer import make_lcmv, apply_lcmv, apply_lcmv_cov
 from mne.beamformer.tests.test_lcmv import _get_data
+from mne.externals.pymatreader import read_mat
 from mne.utils import run_tests_if_main
 
 
@@ -88,11 +89,15 @@ def test_lcmv_fieldtrip(_get_bf_data, bf_type, weight_norm, pick_ori, pwr):
         stc_mne.data[:, :] = np.abs(stc_mne.data)
 
     # load the FieldTrip output
-    ft_fname = op.join(ft_data_path, 'ft_source_' + bf_type + '-vol.stc')
-    stc_ft = mne.read_source_estimate(ft_fname)
+    ft_fname = op.join(ft_data_path, 'ft_source_' + bf_type + '-vol.mat')
+    stc_ft_data = read_mat(ft_fname)['stc']
+    if stc_ft_data.ndim == 3:
+        stc_ft_data = np.linalg.norm(stc_ft_data, axis=1)
+    else:
+        stc_ft_data = np.abs(stc_ft_data)
 
     # calculate the Pearson correlation between the source solutions:
-    pearson = np.corrcoef(stc_mne.data.ravel(), stc_ft.data.ravel())[0, 1]
+    pearson = np.corrcoef(stc_mne.data.ravel(), stc_ft_data.ravel())[0, 1]
     assert pearson >= 0.99
 
 

mne/conftest.py

@@ -85,7 +85,7 @@ def pytest_configure(config):
     ignore:scipy\.gradient is deprecated.*:DeprecationWarning
     ignore:sklearn\.externals\.joblib is deprecated.*:FutureWarning
     ignore:The sklearn.*module.*deprecated.*:FutureWarning
-    ignore:.*TraitTuple.*trait.*handler.*deprecated.*:DeprecationWarning
+    ignore:.*trait.*handler.*deprecated.*:DeprecationWarning
     ignore:.*rich_compare.*metadata.*deprecated.*:DeprecationWarning
     ignore:.*In future, it will be an error for 'np.bool_'.*:DeprecationWarning
     ignore:.*Converting `np\.character` to a dtype is deprecated.*:DeprecationWarning

mne/datasets/utils.py

@@ -239,7 +239,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
     path = _get_path(path, key, name)
     # To update the testing or misc dataset, push commits, then make a new
     # release on GitHub. Then update the "releases" variable:
-    releases = dict(testing='0.87', misc='0.6')
+    releases = dict(testing='0.92', misc='0.6')
     # And also update the "md5_hashes['testing']" variable below.
 
     # To update any other dataset, update the data archive itself (upload
@@ -271,7 +271,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         mtrf='https://osf.io/h85s2/download?version=1',
         kiloword='https://osf.io/qkvf9/download?version=1',
         fieldtrip_cmc='https://osf.io/j9b6s/download?version=1',
-        phantom_4dbti='https://osf.io/v2brw/download?version=1',
+        phantom_4dbti='https://osf.io/v2brw/download?version=2',
         refmeg_noise='https://osf.io/drt6v/download?version=1',
     )
     # filename of the resulting downloaded archive (only needed if the URL
@@ -326,7 +326,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         sample='12b75d1cb7df9dfb4ad73ed82f61094f',
         somato='ea825966c0a1e9b2f84e3826c5500161',
         spm='9f43f67150e3b694b523a21eb929ea75',
-        testing='a6e18de6405d84599c6d4dfb4c1d2b14',
+        testing='42daafd1b882da2ef041de860ca6e771',
         multimodal='26ec847ae9ab80f58f204d09e2c08367',
         fnirs_motor='c4935d19ddab35422a69f3326a01fef8',
         opm='370ad1dcfd5c47e029e692c85358a374',
@@ -335,7 +335,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         kiloword='3a124170795abbd2e48aae8727e719a8',
         mtrf='273a390ebbc48da2c3184b01a82e4636',
         fieldtrip_cmc='6f9fd6520f9a66e20994423808d2528c',
-        phantom_4dbti='f1d96f81d46480d0cc52a7ba4f125367',
+        phantom_4dbti='938a601440f3ffa780d20a17bae039ff',
         refmeg_noise='779fecd890d98b73a4832e717d7c7c45'
     )
     assert set(md5_hashes.keys()) == set(urls.keys())
@@ -651,8 +651,9 @@ def fetch_aparc_sub_parcellation(subjects_dir=None, verbose=None):
 def fetch_hcp_mmp_parcellation(subjects_dir=None, combine=True, verbose=None):
     """Fetch the HCP-MMP parcellation.
 
-    This will download and install the HCP-MMP parcellation [1]_ files for
-    FreeSurfer's fsaverage [2]_ to the specified directory.
+    This will download and install the HCP-MMP parcellation
+    :footcite:`GlasserEtAl2016` files for FreeSurfer's fsaverage
+    :footcite:`Mills2016` to the specified directory.
 
     Parameters
     ----------
@@ -661,7 +662,8 @@ def fetch_hcp_mmp_parcellation(subjects_dir=None, combine=True, verbose=None):
         ``subjects_dir + '/fsaverage/label'``.
     combine : bool
         If True, also produce the combined/reduced set of 23 labels per
-        hemisphere as ``HCPMMP1_combined.annot`` [3]_.
+        hemisphere as ``HCPMMP1_combined.annot``
+        :footcite:`GlasserEtAl2016supp`.
     %(verbose)s
 
     Notes
@@ -671,13 +673,8 @@ def fetch_hcp_mmp_parcellation(subjects_dir=None, combine=True, verbose=None):
 
     References
     ----------
-    .. [1] Glasser MF et al. (2016) A multi-modal parcellation of human
-           cerebral cortex. Nature 536:171-178.
-    .. [2] Mills K (2016) HCP-MMP1.0 projected on fsaverage.
-           https://figshare.com/articles/HCP-MMP1_0_projected_on_fsaverage/3498446/2
-    .. [3] Glasser MF et al. (2016) Supplemental information.
-           https://images.nature.com/full/nature-assets/nature/journal/v536/n7615/extref/nature18933-s3.pdf
-    """  # noqa: E501
+    .. footbibliography::
+    """
     subjects_dir = get_subjects_dir(subjects_dir, raise_error=True)
     destination = op.join(subjects_dir, 'fsaverage', 'label')
     fnames = [op.join(destination, '%s.HCPMMP1.annot' % hemi)

mne/defaults.py

@@ -15,19 +15,19 @@
     units=dict(mag='fT', grad='fT/cm', eeg='µV', eog='µV', ecg='µV', emg='µV',
                misc='AU', seeg='mV', dipole='nAm', gof='GOF', bio='µV',
                ecog='µV', hbo='µM', hbr='µM', ref_meg='fT', fnirs_raw='V',
-               fnirs_od='V', csd='V/m²'),
+               fnirs_od='V', csd='mV/m²'),
     # scalings for the units
     scalings=dict(mag=1e15, grad=1e13, eeg=1e6, eog=1e6, emg=1e6, ecg=1e6,
                   misc=1.0, seeg=1e3, dipole=1e9, gof=1.0, bio=1e6, ecog=1e6,
                   hbo=1e6, hbr=1e6, ref_meg=1e15, fnirs_raw=1.0, fnirs_od=1.0,
-                  csd=1e5),
+                  csd=1e3),
     # rough guess for a good plot
     scalings_plot_raw=dict(mag=1e-12, grad=4e-11, eeg=20e-6, eog=150e-6,
                            ecg=5e-4, emg=1e-3, ref_meg=1e-12, misc='auto',
                            stim=1, resp=1, chpi=1e-4, exci=1, ias=1, syst=1,
                            seeg=1e-4, bio=1e-6, ecog=1e-4, hbo=10e-6,
                            hbr=10e-6, whitened=10., fnirs_raw=2e-2,
-                           fnirs_od=2e-2, csd=20e-4),
+                           fnirs_od=2e-2, csd=200e-4),
     scalings_cov_rank=dict(mag=1e12, grad=1e11, eeg=1e5,  # ~100x scalings
                            seeg=1e1, ecog=1e4, hbo=1e4, hbr=1e4),
     ylim=dict(mag=(-600., 600.), grad=(-200., 200.), eeg=(-200., 200.),