Merge branch 'main' of https://github.com/mne-tools/mne-python into m…

…on_document

.pre-commit-config.yaml

@@ -41,3 +41,13 @@ repos:
     hooks:
       - id: yamllint
         args: [--strict, -c, .yamllint.yml]
+
+  # rstcheck
+  - repo: https://github.com/rstcheck/rstcheck.git
+    rev: v6.2.0
+    hooks:
+      - id: rstcheck
+        files: ^doc/.*\.(rst|inc)$
+        # https://github.com/rstcheck/rstcheck/issues/199
+        # https://github.com/rstcheck/rstcheck/issues/200
+        exclude: ^doc/(help/faq|install/manual_install|install/mne_c|install/advanced|install/updating|_includes/channel_interpolation|_includes/inverse|_includes/ssp)\.rst$

azure-pipelines.yml

@@ -108,7 +108,7 @@ stages:
           - bash: |
               set -e
               python -m pip install --progress-bar off --upgrade pip setuptools wheel
-              python -m pip install --progress-bar off "mne-qt-browser[opengl] @ git+https://github.com/mne-tools/mne-qt-browser.git@main" pyvista scikit-learn pytest-error-for-skips python-picard "PyQt6!=6.5.1" qtpy
+              python -m pip install --progress-bar off "mne-qt-browser[opengl] @ git+https://github.com/mne-tools/mne-qt-browser.git@main" pyvista scikit-learn pytest-error-for-skips python-picard "PyQt6!=6.5.1" qtpy nibabel
               python -m pip uninstall -yq mne
               python -m pip install --progress-bar off --upgrade -e .[test]
             displayName: 'Install dependencies with pip'

doc/_includes/dig_formats.rst

@@ -1,4 +1,5 @@
 :orphan:
+
 .. _dig-formats:
 
 Supported formats for digitized 3D locations

doc/changes/devel.rst

@@ -44,6 +44,7 @@ Enhancements
 - Enhance :func:`~mne.viz.plot_evoked_field` with a GUI that has controls for time, colormap, and contour lines (:gh:`11942` by `Marijn van Vliet`_)
 - Add :class:`mne.viz.ui_events.UIEvent` linking for interactive colorbars, allowing users to link figures and change the colormap and limits interactively. This supports :func:`~mne.viz.plot_evoked_topomap`, :func:`~mne.viz.plot_ica_components`, :func:`~mne.viz.plot_tfr_topomap`, :func:`~mne.viz.plot_projs_topomap`, :meth:`~mne.Evoked.plot_image`, and :meth:`~mne.Epochs.plot_image` (:gh:`12057` by `Santeri Ruuskanen`_)
 - :func:`~mne.epochs.make_metadata` now accepts ``tmin=None`` and ``tmax=None``, which will bound the time window used for metadata generation by event names (instead of a fixed time). That way, you can now for example generate metadata spanning from one cue or fixation cross to the next, even if trial durations vary throughout the recording (:gh:`12118` by `Richard Höchenberger`_)
+- Add support for passing multiple labels to :func:`mne.minimum_norm.source_induced_power` (:gh:`12026` by `Erica Peterson`_, `Eric Larson`_, and `Daniel McCloy`_ )
 - Added documentation to :func:`mne.io.Raw.set_montage`and :func:`mne.add_reference_channels` to specify that montages should be set after adding reference channels (:gh:`12160` by `Jacob Woessner`_)
 
 Bugs
@@ -63,6 +64,7 @@ Bugs
 - Fix bug with :meth:`mne.viz.Brain.get_view` where calling :meth:`~mne.viz.Brain.show_view` with returned parameters would change the view (:gh:`12000` by `Eric Larson`_)
 - Fix bug with :meth:`mne.viz.Brain.show_view` where ``distance=None`` would change the view distance (:gh:`12000` by `Eric Larson`_)
 - Fix bug with :meth:`~mne.viz.Brain.add_annotation` when reading an annotation from a file with both hemispheres shown (:gh:`11946` by `Marijn van Vliet`_)
+- Fix bug with reported component number and errant reporting of PCA explained variance as ICA explained variance in :meth:`mne.Report.add_ica` (:gh:`12155` by `Eric Larson`_)
 - Fix bug with axis clip box boundaries in :func:`mne.viz.plot_evoked_topo` and related functions (:gh:`11999` by `Eric Larson`_)
 - Fix bug with ``subject_info`` when loading data from and exporting to EDF file (:gh:`11952` by `Paul Roujansky`_)
 - Fix bug where :class:`mne.Info` HTML representations listed all channel counts instead of good channel counts under the heading "Good channels" (:gh:`12145` by `Eric Larson`_) 

doc/changes/names.inc

@@ -184,7 +184,7 @@
 
 .. _George O'Neill: https://georgeoneill.github.io
 
-.. _Gonzalo Reina: https://greina.me/
+.. _Gonzalo Reina: https://github.com/Gon-reina
 
 .. _Guillaume Dumas: https://mila.quebec/en/person/guillaume-dumas
 

doc/changes/v0.17.rst

@@ -201,7 +201,7 @@ Bug
 
 - Fix processing of data with bad segments and acquisition skips with new ``skip_by_annotation`` parameter in :func:`mne.preprocessing.maxwell_filter` by `Eric Larson`_
 
-- Fix symlinking to use relative paths in ``mne flash_bem` and ``mne watershed_bem`` by `Eric Larson`_
+- Fix symlinking to use relative paths in ``mne flash_bem`` and ``mne watershed_bem`` by `Eric Larson`_
 
 - Fix error in mne coreg when saving with scaled MRI if fiducials haven't been saved by `Ezequiel Mikulan`_
 

doc/changes/v0.18.rst

@@ -8,7 +8,7 @@ Changelog
 
 - Add ``event_id='auto'`` in :func:`mne.events_from_annotations` to accommodate Brainvision markers by `Jona Sassenhagen`_, `Joan Massich`_ and `Eric Larson`_
 
-- Add example on how to simulate raw data using subject anatomy, by `Ivana Kojcic`_,`Eric Larson`_,`Samuel Deslauriers-Gauthier`_ and`Kostiantyn Maksymenko`_
+- Add example on how to simulate raw data using subject anatomy, by `Ivana Kojcic`_, `Eric Larson`_, `Samuel Deslauriers-Gauthier`_ and `Kostiantyn Maksymenko`_
 
 - :func:`mne.beamformer.apply_lcmv_cov` returns static source power after supplying a data covariance matrix to the beamformer filter by `Britta Westner`_ and `Marijn van Vliet`_
 
@@ -159,7 +159,7 @@ Bug
 
 - Fix 32bits annotations in :func:`mne.io.read_raw_cnt` by `Joan Massich`_
 
-- Fix :func:`mne.events_from_annotations` to ignore ``'BAD_'` and ``'EDGE_'`` annotations by default using a new default ``regexp`` by `Eric Larson`_
+- Fix :func:`mne.events_from_annotations` to ignore ``'BAD_'`` and ``'EDGE_'`` annotations by default using a new default ``regexp`` by `Eric Larson`_
 
 - Fix bug in ``mne.preprocessing.mark_flat`` where ``raw.first_samp`` was not taken into account by `kalenkovich`_
 

doc/changes/v1.0.rst

@@ -132,7 +132,7 @@ Bugs
 
 - Fix use of arguments in :func:`numpy.loadtxt` (:gh:`10189` by :newcontrib:`Federico Zamberlan`)
 
-- Fix documentation of options in :func:`mne.stc_near_sensors` (:gh:`` by :newcontrib:`Nikolai Chapochnikov`)
+- Fix documentation of options in :func:`mne.stc_near_sensors` (:gh:`10007` by :newcontrib:`Nikolai Chapochnikov`)
 
 - :func:`mne.time_frequency.tfr_array_multitaper` now returns results per taper when ``output='complex'`` (:gh:`10281` by `Mikołaj Magnuski`_)
 

doc/changes/v1.1.rst

@@ -131,7 +131,7 @@ Bugs
 
 - Fix bug in :func:`mne.io.read_raw_ctf` where invalid measurement dates were not handled properly (:gh:`10957` by `Jean-Remi King`_ and `Eric Larson`_)
 
-- Rendering issues with recent MESA releases can be avoided by setting the new environment variable``MNE_3D_OPTION_MULTI_SAMPLES=1`` or using :func:`mne.viz.set_3d_options` (:gh:`10513` by `Eric Larson`_)
+- Rendering issues with recent MESA releases can be avoided by setting the new environment variable ``MNE_3D_OPTION_MULTI_SAMPLES=1`` or using :func:`mne.viz.set_3d_options` (:gh:`10513` by `Eric Larson`_)
 
 - Fix behavior for the ``pyvista`` 3D renderer's ``quiver3D`` function so that default arguments plot a glyph in ``arrow`` mode (:gh:`10493` by `Alex Rockhill`_)
 

doc/changes/v1.4.rst

@@ -8,7 +8,7 @@ Enhancements
 - Add functionality for reading CNT spans/annotations marked bad to :func:`mne.io.read_raw_cnt` (:gh:`11631` by :newcontrib:`Jacob Woessner`)
 - Add ``:unit:`` Sphinx directive to enable use of uniform non-breaking spaces throughout the documentation (:gh:`11469` by :newcontrib:`Sawradip Saha`)
 - Adjusted the algorithm used in :class:`mne.decoding.SSD` to support non-full rank data (:gh:`11458` by :newcontrib:`Thomas Binns`)
-- Changed suggested type for ``ch_groups``` in `mne.viz.plot_sensors` from array to list of list(s) (arrays are still supported). (:gh:`11465` by `Hyonyoung Shin`_)
+- Changed suggested type for ``ch_groups`` in `mne.viz.plot_sensors` from array to list of list(s) (arrays are still supported). (:gh:`11465` by `Hyonyoung Shin`_)
 - Add support for UCL/FIL OPM data using :func:`mne.io.read_raw_fil` (:gh:`11366` by :newcontrib:`George O'Neill` and `Robert Seymour`_)
 - Add harmonic field correction (HFC) for OPM sensors in :func:`mne.preprocessing.compute_proj_hfc` (:gh:`11536` by :newcontrib:`George O'Neill` and `Eric Larson`_)
 - Forward argument ``axes`` from `mne.viz.plot_sensors` to `mne.channels.DigMontage.plot` (:gh:`11470` by :newcontrib:`Jan Ebert` and `Mathieu Scheltienne`_)

doc/changes/v1.5.rst

@@ -76,7 +76,7 @@ Bugs
 API changes
 ~~~~~~~~~~~
 - The ``baseline`` argument can now be array-like (e.g. ``list``, ``tuple``, ``np.ndarray``, ...) instead of only a ``tuple`` (:gh:`11713` by `Clemens Brunner`_)
-- The ``events`` and ``event_id`` parameters of `:meth:`Epochs.plot() <mne.Epochs.plot>` now accept boolean values; see docstring for details (:gh:`11445` by `Daniel McCloy`_ and `Clemens Brunner`_)
+- The ``events`` and ``event_id`` parameters of :meth:`Epochs.plot() <mne.Epochs.plot>` now accept boolean values; see docstring for details (:gh:`11445` by `Daniel McCloy`_ and `Clemens Brunner`_)
 - Deprecated ``gap_description`` keyword argument of :func:`mne.io.read_raw_eyelink`, which will be removed in mne version 1.6, in favor of using :meth:`mne.Annotations.rename` (:gh:`11719` by `Scott Huberty`_)
 
 Authors

doc/conf.py

@@ -722,11 +722,17 @@ def append_attr_meth_examples(app, what, name, obj, options, lines):
     "https://doi.org/10.1088/",  # www.tandfonline.com
     "https://doi.org/10.3109/",  # www.tandfonline.com
     "https://www.researchgate.net/profile/",
+    "https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html",
+    "https://scholar.google.com/scholar?cites=12188330066413208874&as_ylo=2014",
+    "https://scholar.google.com/scholar?cites=1521584321377182930&as_ylo=2013",
+    # 500 server error
+    "https://openwetware.org/wiki/Beauchamp:FreeSurfer",
     # 503 Server error
     "https://hal.archives-ouvertes.fr/hal-01848442",
     # Read timed out
     "http://www.cs.ucl.ac.uk/staff/d.barber/brml",
     "https://www.cea.fr",
+    "http://www.humanconnectome.org/data",
     # Max retries exceeded
     "https://doi.org/10.7488/ds/1556",
     "https://datashare.is.ed.ac.uk/handle/10283",

doc/development/contributing.rst

@@ -215,8 +215,6 @@ Once you have git installed and configured, and before creating your local copy
 of the codebase, go to the `MNE-Python GitHub`_ page and create a `fork`_ into
 your GitHub user account.
 
-.. image:: https://docs.github.com/assets/cb-28613/images/help/repository/fork_button.png
-
 This will create a copy of the MNE-Python codebase inside your GitHub user
 account (this is called "your fork"). Changes you make to MNE-Python will
 eventually get "pushed" to your fork, and will be incorporated into the
@@ -1113,3 +1111,5 @@ it can serve as a useful example of what to expect from the PR review process.
 
 .. _optipng: http://optipng.sourceforge.net/
 .. _optipng for Windows: http://prdownloads.sourceforge.net/optipng/optipng-0.7.7-win32.zip?download
+
+.. include:: ../links.inc

doc/documentation/design_philosophy.rst

@@ -94,3 +94,5 @@ of data.
 .. LINKS
 
 .. _`method chaining`: https://en.wikipedia.org/wiki/Method_chaining
+
+.. include:: ../links.inc

doc/documentation/index.rst

@@ -59,3 +59,5 @@ Documentation for the related C and MATLAB tools are available here:
    cookbook
    cite
    cited
+
+.. include:: ../links.inc

doc/help/faq.rst

@@ -275,6 +275,7 @@ magnitude.
 Forward and Inverse Solution
 ============================
 
+.. _faq_how_should_i_regularize:
 
 How should I regularize the covariance matrix?
 ----------------------------------------------

doc/install/mne_tools_suite.rst

@@ -112,3 +112,5 @@ Help with installation is available through the `MNE Forum`_. See the
 .. _invertmeeg: https://github.com/LukeTheHecker/invert
 .. _MNE-ARI: https://github.com/john-veillette/mne_ari
 .. _niseq: https://github.com/john-veillette/niseq
+
+.. include:: ../links.inc

examples/time_frequency/source_label_time_frequency.py

@@ -35,8 +35,8 @@
 meg_path = data_path / "MEG" / "sample"
 raw_fname = meg_path / "sample_audvis_raw.fif"
 fname_inv = meg_path / "sample_audvis-meg-oct-6-meg-inv.fif"
-label_name = "Aud-rh"
-fname_label = meg_path / "labels" / f"{label_name}.label"
+label_names = ["Aud-lh", "Aud-rh"]
+fname_labels = [meg_path / "labels" / f"{ln}.label" for ln in label_names]
 
 tmin, tmax, event_id = -0.2, 0.5, 2
 
@@ -70,7 +70,8 @@
 # Compute a source estimate per frequency band including and excluding the
 # evoked response
 freqs = np.arange(7, 30, 2)  # define frequencies of interest
-label = mne.read_label(fname_label)
+labels = [mne.read_label(fl) for fl in fname_labels]
+label = labels[0]
 n_cycles = freqs / 3.0  # different number of cycle per frequency
 
 # subtract the evoked response in order to exclude evoked activity
@@ -122,3 +123,44 @@
     )
     ax.set(xlabel="Time (s)", ylabel="Frequency (Hz)", title=f"ITC ({title})")
     fig.colorbar(ax.images[0], ax=axes[ii])
+
+# %%
+
+##############################################################################
+# In the example above, we averaged power across vertices after calculating
+# power because we provided a single label for power calculation and therefore
+# power of all sources within the single label were returned separately. When
+# we provide a list of labels, power is averaged across sources within each
+# label automatically. With a list of labels, averaging is performed before
+# rescaling, so choose a baseline method appropriately.
+
+
+# Get power from multiple labels
+multi_label_power = source_induced_power(
+    epochs,
+    inverse_operator,
+    freqs,
+    labels,
+    baseline=(-0.1, 0),
+    baseline_mode="mean",
+    n_cycles=n_cycles,
+    n_jobs=None,
+    return_plv=False,
+)
+
+# visually compare evoked power in left and right auditory regions
+fig, axes = plt.subplots(ncols=2, layout="constrained")
+for l_idx, l_power in enumerate(multi_label_power):
+    ax = axes[l_idx]
+    ax.imshow(
+        l_power,
+        extent=[epochs.times[0], epochs.times[-1], freqs[0], freqs[-1]],
+        aspect="auto",
+        origin="lower",
+        vmin=multi_label_power.min(),
+        vmax=multi_label_power.max(),
+        cmap="RdBu_r",
+    )
+    title = f"{labels[l_idx].hemi.upper()} Evoked Power"
+    ax.set(xlabel="Time (s)", ylabel="Frequency (Hz)", title=title)
+    fig.colorbar(ax.images[0], ax=ax)

mne/commands/tests/test_commands.py

@@ -319,6 +319,7 @@ def test_watershed_bem(tmp_path):
 @testing.requires_testing_data
 def test_flash_bem(tmp_path):
     """Test mne flash_bem."""
+    pytest.importorskip("nibabel")
     check_usage(mne_flash_bem, force_help=True)
     # Copy necessary files to tempdir
     tempdir = Path(str(tmp_path))

mne/cov.py

@@ -1895,9 +1895,8 @@ def regularize(
     .. note:: This function is kept for reasons of backward-compatibility.
               Please consider explicitly using the ``method`` parameter in
               :func:`mne.compute_covariance` to directly combine estimation
-              with regularization in a data-driven fashion. See the `faq
-              <http://mne.tools/dev/overview/faq.html#how-should-i-regularize-the-covariance-matrix>`_
-              for more information.
+              with regularization in a data-driven fashion. See the
+              :ref:`FAQ <faq_how_should_i_regularize>` for more information.
 
     Parameters
     ----------

mne/decoding/tests/test_search_light.py

@@ -2,6 +2,7 @@
 #
 # License: BSD-3-Clause
 
+import platform
 from inspect import signature
 
 import numpy as np
@@ -10,7 +11,7 @@
 
 from mne.decoding.search_light import GeneralizingEstimator, SlidingEstimator
 from mne.decoding.transformer import Vectorizer
-from mne.utils import _record_warnings, use_log_level
+from mne.utils import _record_warnings, check_version, use_log_level
 
 pytest.importorskip("sklearn")
 
@@ -29,6 +30,9 @@ def make_data():
 
 def test_search_light():
     """Test SlidingEstimator."""
+    # https://github.com/scikit-learn/scikit-learn/issues/27711
+    if platform.system() == "Windows" and check_version("numpy", "2.0.0.dev0"):
+        pytest.skip("sklearn int_t / long long mismatch")
     from sklearn.linear_model import LogisticRegression, Ridge
     from sklearn.metrics import make_scorer, roc_auc_score
     from sklearn.pipeline import make_pipeline