Merge remote-tracking branch 'upstream/main' into backend

* upstream/main:
  to_data_frame API change (mne-tools#10925)
  MAINT: Fix Qt issue (mne-tools#10923)
  Update inverse.rst DOC (mne-tools#10922)
  DOC: Clean up Forward and SourceSpaces (mne-tools#10911)
  [MAINT, MRG] Move sensor cluster permutation example to correct directory (mne-tools#10917)
  [MRG] Add data loader functions for BESA files (mne-tools#10892)

Author: larsoner

.github/workflows/linux_pip.yml

@@ -50,6 +50,9 @@ jobs:
       - shell: bash -el {0}
         run: ./tools/github_actions_infos.sh
         name: 'Show infos'
+      # Uncomment if "xcb not found" Qt errors/segfaults come up again
+      # - shell: bash -el {0}
+      #   run: LD_DEBUG=libs python -c "from PyQt6.QtWidgets import QApplication, QWidget; app = QApplication([]); import matplotlib; matplotlib.use('QtAgg'); import matplotlib.pyplot as plt; plt.figure()"
       - shell: bash -el {0}
         run: ./tools/get_testing_version.sh
         name: 'Get testing version'

MANIFEST.in

@@ -78,6 +78,7 @@ exclude .github/PULL_REQUEST_TEMPLATE.md
 # Test files
 
 recursive-exclude mne/io/tests/data *
+recursive-exclude mne/io/besa/tests/data *
 recursive-exclude mne/io/bti/tests/data *
 recursive-exclude mne/io/edf/tests/data *
 recursive-exclude mne/io/kit/tests/data *

azure-pipelines.yml

@@ -125,6 +125,10 @@ stages:
         mne sys_info -pd
         mne sys_info -pd | grep "qtpy: .*{PySide6=.*}$"
       displayName: Print config
+    # Uncomment if "xcb not found" Qt errors/segfaults come up again
+    # - bash: |
+    #     set -e
+    #     LD_DEBUG=libs python -c "from PySide6.QtWidgets import QApplication, QWidget; app = QApplication([]); import matplotlib; matplotlib.use('QtAgg'); import matplotlib.pyplot as plt; plt.figure()"
     - bash: source tools/get_testing_version.sh
       displayName: 'Get testing version'
     - task: Cache@2

doc/_includes/inverse.rst

@@ -150,6 +150,9 @@ to raw data. To reflect the decrease of noise due to averaging, this matrix,
 :math:`C_0`, is scaled by the number of averages, :math:`L`, *i.e.*, :math:`C =
 C_0 / L`.
 
+.. note::
+   When EEG data are included, the gain matrix :math:`G` needs to be average referenced when computing the linear inverse operator :math:`M`. This is incorporated during creating the spatial whitening operator :math:`C^{-^1/_2}`, which includes any projectors on the data. EEG data average reference (using a projector) is mandatory for source modeling and is checked when calculating the inverse operator. 
+
 As shown above, regularization of the inverse solution is equivalent to a
 change in the variance of the current amplitudes in the Bayesian *a priori*
 distribution.

doc/_templates/autosummary/class_no_inherited_members.rst

@@ -0,0 +1,13 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__
+   :members:
+   :no-inherited-members:
+
+.. _sphx_glr_backreferences_{{ fullname }}:
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/changes/latest.inc

@@ -23,6 +23,8 @@ Current (1.1.dev0)
 
 Enhancements
 ~~~~~~~~~~~~
+- Add a note to clarify the inclusion of average referencing gain matrix during whitening (:gh:`10922` by :newcontrib:`Mingjian He`)
+
 - Add time axis scale bar for :meth:`mne.Epochs.plot` using matplotlib backend (:gh:`10736` by :newcontrib:`Jordan Drew`)
 
 - Add :func:`mne.bem.distance_to_bem` to find depth of source positions (:gh:`10632` by :newcontrib:`Matt Courtemanche`)
@@ -105,6 +107,8 @@ Enhancements
 
 - :meth:`mne.Evoked.plot_field` gained a new parameter, ``interaction``, to control the rotation axes when interacting with the head (:gh:`10788` by `Richard Höchenberger`_)
 
+- Add :func:`mne.read_evoked_besa` for reading evokeds from BESA ``.avr`` and ``.mul`` files. (:gh:`10892` by `Marijn van Vliet`_)
+
 Bugs
 ~~~~
 - Fix bug in :func:`mne.io.read_raw_edf` to allow reading in all Hypnodyne ZMax EDFs to be read in without issues (:gh:`10754` by :newcontrib:`Frederik Weber`)
@@ -144,7 +148,7 @@ Bugs
 - Fix bug in coregistration GUI that prevented it from starting up if only a high-resolution head model was available (:gh:`10543` by `Richard Höchenberger`_)
 
 - Fix bug with :class:`mne.Epochs.add_reference_channels` where attributes were not updated properly so subsequent `~mne.Epochs.pick_types` calls were broken (:gh:`10912` by `Eric Larson`_)
-- 
+-
 - Fix bug in the :class:`mne.viz.Brain` tool bar that prevented the buttons to call the corresponding feature (:gh:`10560` by `Guillaume Favelier`_)
 
 - Fix issue with saving epochs once :func:`~mne.preprocessing.compute_current_source_density` has been used if a rejection threshold was used first (:gh:`10619` by `Alex Rockhill`_ and `Richard Höchenberger`_)
@@ -197,3 +201,5 @@ API and behavior changes
 - For :func:`mne.viz.plot_topomap`, :func:`mne.viz.plot_evoked_topomap`, :func:`mne.viz.plot_arrowmap`, :func:`mne.viz.plot_ica_components`, :meth:`mne.Covariance.plot_topomap`, :meth:`mne.Evoked.plot_topomap`, :meth:`mne.Evoked.animate_topomap`, :meth:`mne.decoding.CSP.plot_patterns`, :meth:`mne.Projection.plot_topomap` and :meth:`mne.preprocessing.ICA.plot_components` the topomap image interpolation was previously a cubic interpolation but now can be ``'linear'`` and ``'nearest'`` as well. Unless ``image_interp='nearest'`` is passed mne uses a subsequent matplotlib bilinear interpolation to make the interpolated image smoother. Previously, ``'image_interp'`` controlled this second interpolation step and, for the first interpolation, the only option was cubic. To simplify, ``image_interp`` is now responsible for the main interpolation and the subsequent matplotlib image interpolation is bilinear but can be changed afterward using ``im.set_interpolation`` (:gh:`10617` by `Alex Rockhill`_)
 
 - The FLASH BEM surface generation via :func:`mne.bem.make_flash_bem` or the :ref:`mne flash_bem` command has now been clarified in terms of expected inputs. In :func:`mne.bem.convert_flash_mris` the ``convert`` parameter is now deprecated and the ``flash5`` and ``flash30`` now accept list of file names or nibabel images. One breaking change is that now the flash files are looked for as mef05_*.mgz and mef30_*.mgz in mri/flash folder (:gh:`10715` by `Alex Gramfort`_)
+
+- The ``to_data_frame`` methods for :meth:`Raw <mne.io.Raw.to_data_frame>`, :meth:`Epochs <mne.Epochs.to_data_frame>`, :meth:`Evoked <mne.Evoked.to_data_frame>`, :meth:`SourceEstimate <mne.SourceEstimate.to_data_frame>`, :meth:`EpochsTFR <mne.time_frequency.EpochsTFR.to_data_frame>`, and :meth:`AverageTFR <mne.time_frequency.AverageTFR.to_data_frame>` all now have default ``time_format=None`` (keep time in seconds) instead of ``time_format='ms'`` (convert time to milliseconds) (:gh:`10925` by `Daniel McCloy`_)

doc/changes/names.inc

@@ -457,3 +457,5 @@
 .. _Lukas Gemein: https://github.com/gemeinl
 
 .. _Frederik Weber: https://github.com/Frederik-D-Weber
+
+.. _Mingjian He: https://github.com/mh105

doc/conf.py

@@ -171,6 +171,10 @@
 # Define what extra methods numpydoc will document
 docscrape.ClassDoc.extra_public_methods = mne.utils._doc_special_members
 numpydoc_class_members_toctree = False
+numpydoc_show_inherited_class_members = {
+    'mne.SourceSpaces': False,
+    'mne.Forward': False,
+}
 numpydoc_attributes_as_param_list = True
 numpydoc_xref_param_type = True
 numpydoc_xref_aliases = {
@@ -1039,7 +1043,7 @@ def reset_warnings(gallery_conf, fname):
     f'{tu}/{sr}/plot_stats_cluster_spatio_temporal.html': f'{tu}/{sr}/20_cluster_1samp_spatiotemporal.html',  # noqa E501
     f'{tu}/{sr}/plot_stats_cluster_spatio_temporal_2samp.html': f'{tu}/{sr}/30_cluster_ftest_spatiotemporal.html',  # noqa E501
     f'{tu}/{sr}/plot_stats_cluster_spatio_temporal_repeated_measures_anova.html': f'{tu}/{sr}/60_cluster_rmANOVA_spatiotemporal.html',  # noqa E501
-    f'{tu}/{sr}/plot_stats_cluster_time_frequency_repeated_measures_anova.html': f'{tu}/{sr}/70_cluster_rmANOVA_time_freq.html',  # noqa E501
+    f'{tu}/{sr}/plot_stats_cluster_time_frequency_repeated_measures_anova.html': f'{tu}/{sn}/70_cluster_rmANOVA_time_freq.html',  # noqa E501
     f'{tu}/{tf}/plot_sensors_time_frequency.html': f'{tu}/{tf}/20_sensors_time_frequency.html',  # noqa E501
     f'{tu}/{tf}/plot_ssvep.html': f'{tu}/{tf}/50_ssvep.html',
     f'{tu}/{si}/plot_creating_data_structures.html': f'{tu}/{si}/10_array_objs.html',  # noqa E501

doc/file_io.rst

@@ -24,6 +24,7 @@ File I/O
    read_epochs_fieldtrip
    read_events
    read_evokeds
+   read_evoked_besa
    read_evoked_fieldtrip
    read_evokeds_mff
    read_freesurfer_lut

doc/forward.rst

@@ -6,9 +6,14 @@ Forward Modeling
 
 .. autosummary::
    :toctree: generated/
+   :template: autosummary/class_no_inherited_members.rst
 
    Forward
    SourceSpaces
+
+.. autosummary::
+   :toctree: generated/
+
    add_source_space_distances
    apply_forward
    apply_forward_raw