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

.github/workflows/tests.yml

@@ -99,7 +99,7 @@ jobs:
           sed -i '/dipy/d' environment.yml
           sed -i 's/- mne$/- mne-base/' environment.yml
         if: matrix.os == 'ubuntu-latest' && startswith(matrix.kind, 'conda') && matrix.python == '3.12'
-      - uses: mamba-org/setup-micromamba@v1
+      - uses: mamba-org/setup-micromamba@v2
         with:
           environment-file: ${{ env.CONDA_ENV }}
           environment-name: mne

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
   # Ruff mne
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.5
+    rev: v0.6.9
     hooks:
       - id: ruff
         name: ruff lint mne
@@ -51,12 +51,33 @@ repos:
 
   # sorting
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: file-contents-sorter
         files: ^doc/changes/names.inc|^.mailmap
         args: ["--ignore-case"]
 
+  - repo: https://github.com/pappasam/toml-sort
+    rev: v0.23.1
+    hooks:
+      - id: toml-sort-fix
+        files: pyproject.toml
+
+  # dependencies
+  - repo: local
+    hooks:
+      - id: dependency-sync
+        name: Sync dependency list between pyproject.toml and README.rst
+        language: python
+        entry: ./tools/hooks/sync_dependencies.py
+        files: pyproject.toml
+        additional_dependencies: ["mne"]
+
+
+# these should *not* be run on CIs:
+ci:
+  skip: [dependency-sync]  # needs MNE to work, which exceeds the free tier space alloc.
+
 # The following are too slow to run on local commits, so let's only run on CIs:
 #
 #   - repo: https://github.com/pre-commit/mirrors-mypy

README.rst

@@ -43,9 +43,6 @@ only, use pip_ in a terminal:
 
     $ pip install --upgrade mne
 
-The current MNE-Python release requires Python 3.9 or higher. MNE-Python 0.17
-was the last release to support Python 2.7.
-
 For more complete instructions, including our standalone installers and more
 advanced installation methods, please refer to the `installation guide`_.
 
@@ -73,42 +70,20 @@ Dependencies
 
 The minimum required dependencies to run MNE-Python are:
 
+.. ↓↓↓ BEGIN CORE DEPS LIST. DO NOT EDIT! HANDLED BY PRE-COMMIT HOOK ↓↓↓
+
 - `Python <https://www.python.org>`__ ≥ 3.9
-- `NumPy <https://numpy.org>`__ ≥ 1.24
-- `SciPy <https://scipy.org>`__ ≥ 1.10
+- `NumPy <https://numpy.org>`__ ≥ 1.23
+- `SciPy <https://scipy.org>`__ ≥ 1.9
 - `Matplotlib <https://matplotlib.org>`__ ≥ 3.6
 - `Pooch <https://www.fatiando.org/pooch/latest/>`__ ≥ 1.5
 - `tqdm <https://tqdm.github.io>`__
 - `Jinja2 <https://palletsprojects.com/p/jinja/>`__
 - `decorator <https://github.com/micheles/decorator>`__
-- `lazy_loader <https://pypi.org/project/lazy_loader/>`__
-
-For full functionality, some functions require:
-
-- `scikit-learn <https://scikit-learn.org/stable/>`__ ≥ 1.2
-- `Joblib <https://joblib.readthedocs.io/en/latest/index.html>`__ ≥ 1.2 (for parallelization)
-- `mne-qt-browser <https://github.com/mne-tools/mne-qt-browser>`__ ≥ 0.5 (for fast raw data visualization)
-- `Qt <https://www.qt.io>`__ ≥ 5.15 via one of the following bindings (for fast raw data visualization and interactive 3D visualization):
-
-  - `PySide6 <https://doc.qt.io/qtforpython-6/>`__ ≥ 6.0
-  - `PyQt6 <https://www.riverbankcomputing.com/software/pyqt/>`__ ≥ 6.0
-  - `PyQt5 <https://www.riverbankcomputing.com/software/pyqt/>`__ ≥ 5.15
-
-- `Numba <https://numba.pydata.org>`__ ≥ 0.56.4
-- `NiBabel <https://nipy.org/nibabel/>`__ ≥ 3.2.1
-- `OpenMEEG <https://openmeeg.github.io>`__ ≥ 2.5.6
-- `pandas <https://pandas.pydata.org>`__ ≥ 1.5.2
-- `Picard <https://pierreablin.github.io/picard/>`__ ≥ 0.3
-- `CuPy <https://cupy.dev>`__ ≥ 9.0.0 (for NVIDIA CUDA acceleration)
-- `DIPY <https://dipy.org>`__ ≥ 1.4.0
-- `imageio <https://imageio.readthedocs.io/en/stable/>`__ ≥ 2.8.0
-- `PyVista <https://pyvista.org>`__ ≥ 0.37 (for 3D visualization)
-- `PyVistaQt <https://qtdocs.pyvista.org>`__ ≥ 0.9 (for 3D visualization)
-- `mffpy <https://github.com/BEL-Public/mffpy>`__ ≥ 0.5.7
-- `h5py <https://www.h5py.org>`__
-- `h5io <https://github.com/h5io/h5io>`__
-- `pymatreader <https://pymatreader.readthedocs.io/en/latest/>`__
+- `lazy-loader <https://pypi.org/project/lazy_loader>`__ ≥ 0.3
+- `packaging <https://packaging.pypa.io/en/stable/>`__
 
+.. ↑↑↑ END CORE DEPS LIST. DO NOT EDIT! HANDLED BY PRE-COMMIT HOOK ↑↑↑
 
 Contributing
 ^^^^^^^^^^^^

azure-pipelines.yml

@@ -111,7 +111,7 @@ stages:
           - bash: |
               set -e
               python -m pip install --progress-bar off --upgrade pip
-              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 qtpy nibabel sphinx-gallery PySide6
+              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 qtpy nibabel sphinx-gallery "PySide6!=6.8.0,!=6.8.0.1"
               python -m pip uninstall -yq mne
               python -m pip install --progress-bar off --upgrade -e .[test]
             displayName: 'Install dependencies with pip'
@@ -201,7 +201,7 @@ stages:
             displayName: 'PyQt6'
           - bash: |
               set -eo pipefail
-              python -m pip install PySide6
+              python -m pip install "PySide6!=6.8.0,!=6.8.0.1"
               mne sys_info -pd
               mne sys_info -pd | grep "qtpy .* (PySide6=.*)$"
               PYTEST_QT_API=PySide6 pytest ${TEST_OPTIONS}

doc/_static/style.css

@@ -13,6 +13,20 @@
 
 
 html[data-theme="light"] {
+    /* pydata-sphinx-theme overrides */
+    /* ↓↓↓ use default "info" colors for "primary" */
+    --pst-color-primary: #276be9;
+    --pst-color-primary-bg: #dce7fc;
+    /* ↓↓↓ use default "primary" colors for "info" */
+    --pst-color-info: var(--pst-teal-500);
+    --pst-color-info-bg: var(--pst-teal-200);
+    /* ↓↓↓ use "warning" colors for "secondary" */
+    --pst-color-secondary: var(--pst-color-warning);
+    --pst-color-secondary-bg: var(--pst-color-warning-bg);
+    /* ↓↓↓ make sure new primary (link) color propogates to links on code */
+    --pst-color-inline-code-links: var(--pst-color-link);
+    /* ↓↓↓ make sure new secondary (hover) color propogates to hovering on table rows */
+    --pst-color-table-row-hover-bg: var(--pst-color-secondary-bg);
     /* topbar logo links */
     --mne-color-github: #000;
     --mne-color-discourse: #d0232b;
@@ -21,8 +35,6 @@ html[data-theme="light"] {
     --copybtn-opacity: 0.75;
     /* card header bg color */
     --mne-color-card-header: rgba(0, 0, 0, 0.05);
-    /* section headings */
-    --mne-color-heading: #003e80;
     /* sphinx-gallery overrides */
     --sg-download-a-background-color: var(--pst-color-primary);
     --sg-download-a-background-image: unset;
@@ -33,6 +45,20 @@ html[data-theme="light"] {
     --sg-download-a-hover-box-shadow-2: none;
 }
 html[data-theme="dark"] {
+    /* pydata-sphinx-theme overrides */
+    /* ↓↓↓ use default "info" colors for "primary" */
+    --pst-color-primary: #79a3f2;
+    --pst-color-primary-bg: #06245d;
+    /* ↓↓↓ use default "primary" colors for "info" */
+    --pst-color-info: var(--pst-teal-400);
+    --pst-color-info-bg: var(--pst-teal-800);
+    /* ↓↓↓ use "warning" colors for "secondary" */
+    --pst-color-secondary: var(--pst-color-warning);
+    --pst-color-secondary-bg: var(--pst-color-warning-bg);
+    /* ↓↓↓ make sure new primary (link) color propogates to links on code */
+    --pst-color-inline-code-links: var(--pst-color-link);
+    /* ↓↓↓ make sure new secondary (hover) color propogates to hovering on table rows */
+    --pst-color-table-row-hover-bg: var(--pst-color-secondary-bg);
     /* topbar logo links */
     --mne-color-github: rgb(240, 246, 252);  /* from their logo SVG */
     --mne-color-discourse: #FFF9AE;  /* from their logo SVG */
@@ -41,8 +67,6 @@ html[data-theme="dark"] {
     --copybtn-opacity: 0.25;
     /* card header bg color */
     --mne-color-card-header: rgba(255, 255, 255, 0.2);
-    /* section headings */
-    --mne-color-heading: #b8cbe0;
     /* sphinx-gallery overrides */
     --sg-download-a-background-color: var(--pst-color-primary);
     --sg-download-a-background-image: unset;
@@ -52,9 +76,6 @@ html[data-theme="dark"] {
     --sg-download-a-hover-box-shadow-1: none;
     --sg-download-a-hover-box-shadow-2: none;
 }
-h1, h2, h3, h4, h5, h6 {
-    color: var(--mne-color-heading);
-}
 
 /* ************************************************************ Sphinx fixes */
 
@@ -161,20 +182,45 @@ iframe.sg_report {
     top: 0;
 }
 
-/* TODO: Either pydata-sphinx-theme (for using Bootstrap) or sphinx-gallery (for adding table formatting) should fix this */
-.table-striped-columns>:not(caption)>tr>:nth-child(2n),.table-striped>tbody>tr:nth-of-type(odd)>* {
-    --bs-table-accent-bg: var(--bs-table-striped-bg);
+/* ******************************************************** HTML repr tables */
+
+/* make table responsive to pydata-sphinx-theme's light/dark mode */
+.table > :not(caption) > * > * {
     color: var(--pst-color-text-base);
 }
-.table-hover>tbody>tr:hover>* {
-    --bs-table-accent-bg: var(--bs-table-hover-bg);
-    color: var(--pst-color-text-base);
+.mne-repr-table tbody tr:hover {
+    background-color: var(--pst-color-table-row-hover-bg);
 }
-.rendered_html table {
-    color: var(--pst-color-text-base);
+.mne-repr-section-toggle > button > svg > path {
+    fill: var(--pst-color-text-base);
 }
-
-
+/* make the expand/collapse button look nicer */
+.mne-repr-section-toggle > button {
+    padding: 20%;
+}
+/* make section header rows more distinct (and harmonize with pydata-sphinx-theme table
+style in the process). Color copied from pydata-sphinx-theme; 2px copied from bootstrap.
+*/
+.mne-repr-table th {
+    border-bottom: 2px solid var(--pst-color-primary);
+}
+/* harmonize the channel names buttons with the rest of the table */
+.mne-ch-names-btn {
+    font-size: inherit;
+    padding: 0.25rem;
+    min-width: 1.5rem;
+    font-weight: bold;
+}
+/*
+.mne-ch-names-btn:hover {
+    background-color: var(--pst-color-);
+    text-decoration: underline;
+}
+.mne-ch-names-btn:focus-visible {
+    outline: 0.1875rem solid var(--pst-color-accent);
+    outline-offset: 0.1875rem;
+}
+*/
 /* ***************************************************** sphinx-design fixes */
 p.btn a {
     color: unset;

doc/changes/devel/12366.newfeature.rst

@@ -0,0 +1 @@
+Add support for `dict` type argument ``ref_channels`` to :func:`mne.set_eeg_reference`, to allow flexible re-referencing (e.g. ``raw.set_eeg_reference(ref_channels={'A1': ['A2', 'A3']})`` will set the new A1 data to be ``A1 - mean(A2, A3)``), by `Alex Lepauvre`_ and `Qian Chu`_ and `Daniel McCloy`_.

doc/changes/devel/12843.bugfix.rst

@@ -0,0 +1,3 @@
+Fixed a bug where split FIF files that were read and then appended to other
+:class:`mne.io.Raw` instances had their ``BAD boundary`` annotations incorrectly offset
+in samples by the number of split files, by `Eric Larson`_.

doc/changes/devel/12843.other.rst

@@ -0,0 +1 @@
+Improve handling of filenames in ``raw.filenames`` by using :class:`~pathlib.Path` instead of :class:`str`, by `Mathieu Scheltienne`_.

doc/changes/devel/12844.other.rst

@@ -0,0 +1 @@
+Improve automatic figure scaling of :func:`mne.viz.plot_events`, and event_id and count overview legend when a high amount of unique events is supplied, by `Stefan Appelhoff`_.

doc/changes/devel/12846.bugfix.rst

@@ -1 +1,2 @@
-Enforce SI units for Eyetracking data (eyegaze data should be radians of visual angle, not pixels. Pupil size data should be meters). Updated tutorials so demonstrate how to convert data to SI units before analyses (:gh:`12846`` by `Scott Huberty`_)
+Enforce SI units for Eyetracking data (eyegaze data should be radians of visual angle, not pixels. Pupil size data should be meters).
+Updated tutorials so demonstrate how to convert data to SI units before analyses, by `Scott Huberty`_.

doc/changes/devel/12862.other.rst

@@ -0,0 +1 @@
+:meth:`mne.preprocessing.ICA.find_bads_muscle` can now be run when passing an ``inst`` without sensor positions. However, it will just use the first of three criteria (slope) to find muscle-related ICA components, by `Stefan Appelhoff`_.

doc/changes/devel/12871.newfeature.rst

@@ -0,0 +1,2 @@
+Added the ``title`` argument to :func:`mne.viz.create_3d_figure`, and
+``color`` and ``position`` arguments to :func:`mne.viz.set_3d_title`, by `Eric Larson`_.

doc/changes/devel/12875.bugfix.rst

@@ -0,0 +1,2 @@
+Fix bug where invalid data types (e.g., ``np.ndarray``s) could be used in some
+:class:`mne.io.Info` fields like ``info["subject_info"]["weight"]``, by `Eric Larson`_.

doc/changes/devel/12877.bugfix.rst

@@ -0,0 +1,4 @@
+When creating a :class:`~mne.time_frequency.SpectrumArray`, the array shape check now
+compares against the total of both 'good' and 'bad' channels in the provided
+:class:`~mne.Info` (previously only good channels were checked), by
+`Mathieu Scheltienne`_.

doc/changes/devel/12884.bugfix.rst

@@ -0,0 +1 @@
+Fix bug where :ref:`mne coreg` would always show MEG channels even if the "MEG Sensors" checkbox was disabled, by `Eric Larson`_.

doc/changes/devel/12901.bugfix.rst

@@ -0,0 +1 @@
+:class:`mne.Report` HDF5 files are now written in ``mode='a'`` (append) to allow users to store other data in the HDF5 files, by `Eric Larson`_.

doc/changes/devel/12901.newfeature.rst

@@ -0,0 +1,8 @@
+Improved reporting and plotting options:
+
+- :meth:`mne.Report.add_projs` can now plot with :func:`mne.viz.plot_projs_joint` rather than :func:`mne.viz.plot_projs_topomap`
+- :class:`mne.Report` now has attributes ``img_max_width`` and ``img_max_res`` that can be used to control image scaling.
+- :class:`mne.Report` now has an attribute ``collapse`` that allows collapsing sections and/or subsections by default.
+- :func:`mne.viz.plot_head_positions` now has a ``totals=True`` option to show the total distance and angle of the head.
+
+Changes by `Eric Larson`_.

doc/changes/names.inc

@@ -10,7 +10,7 @@
 .. _Alex Ciok: https://github.com/alexCiok
 .. _Alex Gramfort: https://alexandre.gramfort.net
 .. _Alex Kiefer: https://home.alexk101.dev
-.. _Alex Lepauvre:  https://github.com/AlexLepauvre
+.. _Alex Lepauvre: https://github.com/AlexLepauvre
 .. _Alex Rockhill: https://github.com/alexrockhill/
 .. _Alexander Rudiuk: https://github.com/ARudiuk
 .. _Alexandre Barachant: https://alexandre.barachant.org
@@ -22,7 +22,7 @@
 .. _Andrew Quinn: https://github.com/ajquinn
 .. _Aniket Pradhan: https://github.com/Aniket-Pradhan
 .. _Anna Padee: https://github.com/apadee/
-.. _Annalisa Pascarella: https://www.dima.unige.it/~pascarel/html/cv.html
+.. _Annalisa Pascarella: https://www.iac.cnr.it/personale/annalisa-pascarella
 .. _Anne-Sophie Dubarry: https://github.com/annesodub
 .. _Antoine Gauthier: https://github.com/Okamille
 .. _Antti Rantala: https://github.com/Odingod
@@ -206,7 +206,7 @@
 .. _Nathalie Gayraud: https://github.com/ngayraud
 .. _Naveen Srinivasan: https://github.com/naveensrinivasan
 .. _Nick Foti: https://nfoti.github.io
-.. _Nick Ward: https://www.ucl.ac.uk/ion/departments/sobell/Research/NWard
+.. _Nick Ward: https://profiles.ucl.ac.uk/10827-nick-ward
 .. _Nicolas Barascud: https://github.com/nbara
 .. _Nicolas Fourcaud-Trocmé: https://www.crnl.fr/fr/user/316
 .. _Niels Focke: https://neurologie.umg.eu/forschung/arbeitsgruppen/epilepsie-und-bildgebungsforschung
@@ -261,7 +261,7 @@
 .. _Samuel Louviot: https://github.com/Sam54000
 .. _Samuel Powell: https://github.com/samuelpowell
 .. _Santeri Ruuskanen: https://github.com/ruuskas
-.. _Sara Sommariva: https://www.dima.unige.it/~sommariva/
+.. _Sara Sommariva: https://github.com/sarasommariva
 .. _Sawradip Saha: https://sawradip.github.io/
 .. _Scott Huberty:  https://orcid.org/0000-0003-2637-031X
 .. _Sebastiaan Mathot: https://www.cogsci.nl/smathot

doc/conf.py

@@ -166,7 +166,7 @@
     "mne-gui-addons": ("https://mne.tools/mne-gui-addons", None),
     "picard": ("https://pierreablin.github.io/picard/", None),
     "eeglabio": ("https://eeglabio.readthedocs.io/en/latest", None),
-    "pybv": ("https://pybv.readthedocs.io/en/latest/", None),
+    "pybv": ("https://pybv.readthedocs.io/en/latest", None),
 }
 intersphinx_mapping.update(
     get_intersphinx_mapping(
@@ -648,6 +648,7 @@ def fix_sklearn_inherited_docstrings(app, what, name, obj, options, lines):
     "https://doi.org/10.1093/",  # academic.oup.com/sleep/
     "https://doi.org/10.1098/",  # royalsocietypublishing.org
     "https://doi.org/10.1101/",  # www.biorxiv.org
+    "https://doi.org/10.1103",  # journals.aps.org/rmp
     "https://doi.org/10.1111/",  # onlinelibrary.wiley.com/doi/10.1111/psyp
     "https://doi.org/10.1126/",  # www.science.org
     "https://doi.org/10.1137/",  # epubs.siam.org
@@ -681,6 +682,9 @@ def fix_sklearn_inherited_docstrings(app, what, name, obj, options, lines):
     # Too slow
     "https://speakerdeck.com/dengemann/",
     "https://www.dtu.dk/english/service/phonebook/person",
+    "https://www.gnu.org/software/make/",
+    "https://www.macports.org/",
+    "https://hastie.su.domains/CASI",
     # SSL problems sometimes
     "http://ilabs.washington.edu",
     "https://psychophysiology.cpmc.columbia.edu",