Merge branch 'main' into enh-concatenate-epochsspectrum

Author: drammock

.github/workflows/spec_zero.yml

@@ -46,8 +46,12 @@ jobs:
           version: ">=0.9"
           activate-environment: true
           python-version: 3.12
-      - run: uv pip install packaging requests tomlkit
-      - run: python ./tools/dev/spec_zero_update_versions.py
+      - name: Install dependencies
+        run: uv pip install -e . packaging requests tomlkit
+      - name: Update tracked dependencies
+        run: python ./tools/dev/spec_zero_update_versions.py
+      - name: Sync updated dependencies to README
+        run: python tools/sync_dependencies.py
       - name: Create lockfile for old CI
         # uv pip compile requires setting the python version explicitly in the command :(
         run: |
@@ -72,7 +76,9 @@ jobs:
           git config --global user.email "50266005+mne-bot@users.noreply.github.com"
           git config --global user.name "mne[bot]"
           git checkout -b spec_zero
-          git add doc/changes/dev/dependency.rst  # one new file, others changed
+          if [ -f doc/changes/dev/dependency.rst ]; then
+            git add doc/changes/dev/dependency.rst  # one new file, others changed
+          fi
           git commit -am "mne[bot]: Update dependency specifiers"
           git push origin spec_zero
           PR_NUM=$(gh pr create --base main --head spec_zero --title "MAINT: Update dependency specifiers" --body "Created by spec_zero [GitHub action](https://github.com/mne-tools/mne-python/actions/runs/${{ github.run_id }}). <br> <br> *Adjustments may need to be made to shims in \`mne/fixes.py\` and elswhere in this or another PR. \`make -C tools/dev dep\` is a good starting point for finding potential updates.*")

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
   # Ruff mne
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.9
+    rev: v0.15.10
     hooks:
       - id: ruff-check
         name: ruff lint mne
@@ -71,28 +71,16 @@ repos:
         language: python
         entry: ./tools/hooks/update_environment_file.py
         files: '^(pyproject.toml|tools/hooks/update_environment_file.py)$'
-  - repo: local
-    hooks:
-      - id: dependency-sync
-        name: Copy core dependencies from pyproject.toml to README.rst
-        language: python
-        entry: ./tools/hooks/sync_dependencies.py
-        files: '^(pyproject.toml|tools/hooks/sync_dependencies.py)$'
-        additional_dependencies: ["mne==1.12.0"]
 
   # zizmor
   - repo: https://github.com/woodruffw/zizmor-pre-commit
-    rev: v1.23.1
+    rev: v1.24.1
     hooks:
       - id: zizmor
         args: [--fix]
         # We correctly use pull_request_trigger, and need Zizmor 2.0+ to configure the ignore
         exclude: ^.github/workflows/automerge.yml
 
-# 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

doc/changes/dev/13673.other.rst

@@ -0,0 +1 @@
+Reorganized EDF submodule structure by moving private functionality into the public ``mne.io`` namespace to improve module consistency and avoid exposing private modules in the Credits page, by `Aniket Singh Yadav`_.

doc/changes/dev/13825.bugfix.rst

@@ -0,0 +1 @@
+Improved colocated OPM topomap handling by recognizing additional OPM coil types (FieldLine and Kernel), by `Pragnya Khandelwal`_.

doc/changes/dev/13843.bugfix.rst

@@ -0,0 +1 @@
+Fix bug where logging messages were sometimes errantly printed, by `Eric Larson`_.

doc/changes/v1.12.rst

@@ -23,12 +23,12 @@ Bugfixes
 - Fix bug where :func:`mne.viz.plot_raw` would access incorrect matplotlib attributes, by :newcontrib:`Thomas Caswell`. (`#13606 <https://github.com/mne-tools/mne-python/pull/13606>`__)
 - Allow reading alternative nasion label ("Nz") in SNIRF files when parsing landmarkPos3D, by :newcontrib:`Aniket Singh Yadav`. (`#13672 <https://github.com/mne-tools/mne-python/pull/13672>`__)
 - Change default-pick 'data' for "eyegaze" to false, following existing documentation. by :newcontrib:`Benedikt Ehinger`. (`#13723 <https://github.com/mne-tools/mne-python/pull/13723>`__)
-  by :newcontrib:`Christoph Huber-Huber`. (`#13759 <https://github.com/mne-tools/mne-python/pull/13759>`__)
 - Fix bug in when reading EDF/GDF files where non-positive lowpass values were not handled correctly, now mapping them to the Nyquist frequency to prevent errors during plotting, by :newcontrib:`Hansuja Budhiraja`. (`#13769 <https://github.com/mne-tools/mne-python/pull/13769>`__)
 - Clearer error message when no ECG events are found in :func:`~mne.preprocessing.find_ecg_events`, by :newcontrib:`Hansuja Budhiraja`. (`#13771 <https://github.com/mne-tools/mne-python/pull/13771>`__)
 - Fix bug in 3D overlay compositing that could produce NaN RGBA values when the resulting alpha is zero, by `Pragnya Khandelwal`_. (`#13714 <https://github.com/mne-tools/mne-python/pull/13714>`__)
 - Make :meth:`~mne.io.Raw.interpolate_bads` method flexible (ignore, warn, raise) about how to handle interpolation of channels with invalid positions, by :newcontrib:`Himanshu Mahor`. (`#13518 <https://github.com/mne-tools/mne-python/pull/13518>`__)
 - Fix bug where outdated ``seghead.mgz`` files were reused in :func:`mne.bem.make_scalp_surfaces`. Add a new parameter ``reuse_seghead`` to control whether to reuse existing ``seghead.mgz`` files, by `Victor Ferat`_. (`#13024 <https://github.com/mne-tools/mne-python/pull/13024>`__)
+- When interpolating from axial to planar gradiometers, set info fields "chs", "ch_names", and "nchan", according to the interpolated data, reset info fields "device_info", "helium_info", "gantry_angle", "ctf_head_t", "dev_ctf_t", "bads", "projs", and "comps" to [] or None, and preserve all remaining info fields.   by :newcontrib:`Christoph Huber-Huber`. (`#13759 <https://github.com/mne-tools/mne-python/pull/13759>`__)
 - Clarified an internal forward-model invariant in ``mne.forward._lead_dots`` by asserting that ``rref`` is ``None`` on the current code path, by :newcontrib:`Pragnya Khandelwal`. (`#13764 <https://github.com/mne-tools/mne-python/pull/13764>`__)
 - Fix bug preventing :func:`mne.time_frequency.read_spectrum` from reading saved :class:`mne.time_frequency.Spectrum` objects created from :meth:`mne.time_frequency.EpochsSpectrum.average`, by `Thomas Binns`_. (`#13521 <https://github.com/mne-tools/mne-python/pull/13521>`__)
 - Fix bug where :func:`mne.chpi.refit_hpi` did not take ``gof_limit`` into account when fitting HPI order, by `Eric Larson`_ (`#13525 <https://github.com/mne-tools/mne-python/pull/13525>`__)
@@ -50,9 +50,6 @@ Bugfixes
 - Fix annotation removal logic in matplotlib based figures to correctly handle non-contiguous visible annotations, by `Johannes Herforth`_. (`#13703 <https://github.com/mne-tools/mne-python/pull/13703>`__)
 - Support mixed-type concatenation of :class:`mne.Annotations` and :class:`mne.HEDAnnotations`, preserving HED strings in ``extras["HED"]``, by `Bruno Aristimunha`_. (`#13736 <https://github.com/mne-tools/mne-python/pull/13736>`__)
 - Improved handling of dropped epochs in :func:`mne.viz.plot_ica_properties` and :meth:`mne.preprocessing.ICA.plot_properties`, allowing plots to be generated even with many bad annotations, by `Clemens Brunner`_. (`#13746 <https://github.com/mne-tools/mne-python/pull/13746>`__)
-- When interpolating from axial to planar gradiometers, set info fields "chs", "ch_names", and "nchan", according to the interpolated data,
-  reset info fields "device_info", "helium_info", "gantry_angle", "ctf_head_t", "dev_ctf_t", "bads", "projs", and "comps" to [] or None, and
-  preserve all remaining info fields.
 - Avoid some unnecessary computations when ``n_jobs=None`` is equivalent to ``n_jobs=1``, by `Simon Kern`_. (`#13777 <https://github.com/mne-tools/mne-python/pull/13777>`__)
 - Fix clipped annotations and x-axis label in :meth:`mne.io.Raw.plot`, by `Clemens Brunner`_. (`#13787 <https://github.com/mne-tools/mne-python/pull/13787>`__)
 - Fix bug with reading large CNT files by adding ``recompute_n_samples`` to :func:`mne.io.read_raw_cnt` with stricter ``data_format`` handling by `Teon Brooks`_ and `Eric Larson`_. (`#13548 <https://github.com/mne-tools/mne-python/pull/13548>`__)
@@ -67,7 +64,7 @@ New features
 - Add support for multi-wavelength NIRS processing to :func:`mne.preprocessing.nirs.beer_lambert_law`, :func:`mne.preprocessing.nirs.scalp_coupling_index`, and SNIRF reader :func:`mne.io.read_raw_snirf`, by :newcontrib:`Tamas Fehervari`. (`#13408 <https://github.com/mne-tools/mne-python/pull/13408>`__)
 - Add an optional ``show_channel_names`` parameter to :meth:`mne.viz.plot_alignment` to overlay channel labels at sensor locations in the 3D alignment view, by :newcontrib:`Aman Srivastava`. (`#13570 <https://github.com/mne-tools/mne-python/pull/13570>`__)
 - Add support for reading BCI2000 ``.dat`` files via :func:`mne.io.read_raw_bci2k`, and an example :file:`examples/io/read_bci2k.py` for downloading and visualizing BCI2000 data, by :newcontrib:`Hansuja Budhiraja`. (`#13699 <https://github.com/mne-tools/mne-python/pull/13699>`__)
-- Add support for scalar or per-vertex ``alpha`` (shape ``(n_vertices,)``) in distributed overlays, including validation/errors for invalid shapes, tests, and a visualization example in ``examples/visualization/brain.py`` using :meth:`mne.viz.Brain.add_data`, by :newcontrib:`Pragnya Khandelwal`. (:gh:`13706`) (`#13706 <https://github.com/mne-tools/mne-python/pull/13706>`__)
+- Add support for scalar or per-vertex ``alpha`` (shape ``(n_vertices,)``) in distributed overlays, including validation/errors for invalid shapes, tests, and a visualization example in ``examples/visualization/brain.py`` using :meth:`mne.viz.Brain.add_data`, by :newcontrib:`Pragnya Khandelwal`. (`#13706 <https://github.com/mne-tools/mne-python/pull/13706>`__)
 - Added ``cmap`` parameter to ``Evoked.animate_topomap`` to allow user-specified colormaps., by :newcontrib:`Hansuja Budhiraja`. (`#13756 <https://github.com/mne-tools/mne-python/pull/13756>`__)
 - Allow per-channel color overrides in :func:`mne.viz.plot_raw` via channel name keys in the ``color`` dict, by :newcontrib:`Hansuja Budhiraja`. (`#13765 <https://github.com/mne-tools/mne-python/pull/13765>`__)
 - Add example showing how to interoperate with R using ``rpy2``, by  :newcontrib:`Aman Srivastava`. (`#13729 <https://github.com/mne-tools/mne-python/pull/13729>`__)
@@ -83,7 +80,7 @@ Other changes
 - Created a quality control report tutorial :ref:`tut-qc-report`, by :newcontrib:`varshaa-1616`. (`#13532 <https://github.com/mne-tools/mne-python/pull/13532>`__)
 - Improved docs for :func:`mne.io.read_raw_nirx`, by :newcontrib:`Natneal B`. (`#13541 <https://github.com/mne-tools/mne-python/pull/13541>`__)
 - Refactor f-strings in ``mne/tests/test_import_nesting.py``, by :newcontrib:`Shruti Bhale`. (`#13551 <https://github.com/mne-tools/mne-python/pull/13551>`__)
-- Remove legacy Python-version compatibility checks in ``mne.utils.misc._empty_hash`` now that ``usedforsecurity=False`` is always supported, by :newcontrib:`Varun Kasyap Pentamaraju` (:gh:`13566`). (`#13566 <https://github.com/mne-tools/mne-python/pull/13566>`__)
+- Remove legacy Python-version compatibility checks in ``mne.utils.misc._empty_hash`` now that ``usedforsecurity=False`` is always supported, by :newcontrib:`Varun Kasyap Pentamaraju`. (`#13566 <https://github.com/mne-tools/mne-python/pull/13566>`__)
 - Add optional low-variance ("hat") regularization to :func:`mne.stats.f_oneway` via new ``sigma`` and ``method`` parameters, by :newcontrib:`Aniket Singh Yadav`. (`#13698 <https://github.com/mne-tools/mne-python/pull/13698>`__)
 - Improve documentation of return values to clarify that methods typically return the original instance type for chaining purposes, by :newcontrib:`Aniket Singh Yadav`. (`#13674 <https://github.com/mne-tools/mne-python/pull/13674>`__)
 - Examples Using <some-method> section quirk fix in documentation, by :newcontrib:`Himanshu Mahor`. (`#13596 <https://github.com/mne-tools/mne-python/pull/13596>`__)

doc/conf.py

@@ -180,15 +180,13 @@
     "picard": ("https://mind-inria.github.io/picard/", None),
     "eeglabio": ("https://eeglabio.readthedocs.io/en/latest", None),
     "pybv": ("https://pybv.readthedocs.io/en/latest", None),
-    # should go back below after https://github.com/dipy/dipy/issues/3870 is fixed
-    "dipy": ("https://docs.dipy.org/1.12.0", None),
 }
 intersphinx_mapping.update(
     get_intersphinx_mapping(
         packages=set(
             """
 imageio matplotlib numpy pandas python scipy statsmodels sklearn numba joblib nibabel
-seaborn patsy pyvista nilearn pyqtgraph
+seaborn patsy pyvista dipy nilearn pyqtgraph
 """.strip().split()
         ),
     )

doc/install/installers.rst

@@ -17,28 +17,28 @@ Platform-specific installers
         :class-content: text-center
         :name: install-linux
 
-        .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.12.0/MNE-Python-1.12.0_0-Linux.sh
+        .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.12.0-post1/MNE-Python-1.12.0_1-Linux.sh
             :ref-type: ref
             :color: primary
             :shadow:
             :class: font-weight-bold mt-3 install-download-button
 
             |cloud-arrow-down| |ensp| Download for Linux
 
-        **Supported platforms:** Ubuntu 18.04 (Bionic Beaver) and newer
+        **Supported platforms:** Ubuntu 20.04 (Focal Fossa) and newer
 
         Run the installer in a terminal via:
 
         .. code-block:: console
 
-            $ sh ./MNE-Python-1.12.0_0-Linux.sh
+            $ sh ./MNE-Python-1.12.0_1-Linux.sh
 
 
     .. tab-item:: macOS (Intel)
         :class-content: text-center
         :name: install-macos-intel
 
-        .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.12.0/MNE-Python-1.12.0_0-macOS_Intel.pkg
+        .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.12.0-post1/MNE-Python-1.12.0_1-macOS_Intel.pkg
             :ref-type: ref
             :color: primary
             :shadow:
@@ -54,7 +54,7 @@ Platform-specific installers
         :class-content: text-center
         :name: install-macos-apple
 
-        .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.12.0/MNE-Python-1.12.0_0-macOS_M1.pkg
+        .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.12.0-post1/MNE-Python-1.12.0_1-macOS_M1.pkg
             :ref-type: ref
             :color: primary
             :shadow:
@@ -70,7 +70,7 @@ Platform-specific installers
         :class-content: text-center
         :name: install-windows
 
-        .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.12.0/MNE-Python-1.12.0_0-Windows.exe
+        .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.12.0-post1/MNE-Python-1.12.0_1-Windows.exe
             :ref-type: ref
             :color: primary
             :shadow:
@@ -128,6 +128,14 @@ bundles to the ``Applications`` folder on macOS.
    particularly long on Apple Silicon-based computers. Subsequent runs should
    usually be much faster.
 
+The installer sets up a standard ``conda`` environment. If you want to activate the
+environment manually (e.g., in headless setups) you can do as you would for any other
+conda environment:
+
+.. code-block:: bash
+
+    $ source /path-to-installation-dir/bin/activate
+
 Uninstallation
 ^^^^^^^^^^^^^^
 
@@ -156,7 +164,7 @@ To remove the MNE-Python distribution provided by our installers above:
            .. code-block:: bash
 
                $ which python
-               /home/username/mne-python/1.12.0_0/bin/python
+               /home/username/mne-python/1.12.0_1/bin/python
                $ rm -Rf /home/$USER/mne-python
                $ rm /home/$USER/.local/share/applications/mne-python-*.desktop
 
@@ -170,7 +178,7 @@ To remove the MNE-Python distribution provided by our installers above:
            .. code-block:: bash
 
                $ which python
-               /Users/username/Applications/MNE-Python/1.12.0_0/.mne-python/bin/python
+               /Users/username/Applications/MNE-Python/1.12.0_1/.mne-python/bin/python
                $ rm -Rf /Users/$USER/Applications/MNE-Python  # if user-specific
                $ rm -Rf /Applications/MNE-Python              # if system-wide
 

doc/sphinxext/credit_tools.py

@@ -315,6 +315,9 @@ def generate_credit_rst(app=None, *, verbose=False):
         logo/LICENSE doc/credit.rst
     """.strip().split():
         globs[key] = "null"
+    # A few remaps
+    globs["mne/io/edf/_open.py"] = "mne.io"
+    globs["mne/_edf/open.py"] = "mne.io"
     # Now onto the actual module organization
     root_path = pathlib.Path(mne.__file__).parent
     mod_file_map = dict()
@@ -392,15 +395,30 @@ def generate_credit_rst(app=None, *, verbose=False):
             other_files.add(fname)
             mod = "other"
         for e, pm in counts.items():
-            if mod == "mne._fiff":
-                raise RuntimeError
+            # Assert no private (_-prefixed) submodules appear without a redirect
+            if mod.startswith("mne.") and mod.split(".")[-1].startswith("_"):
+                raise RuntimeError(
+                    f"Private submodule {mod!r} found in credit page for {fname!r}. "
+                    "Add an override in credit_tools.py to remap it to a public module."
+                )
             # sanity check a bit
             if mod != "null" and (".png" in fname or "/manual/" in fname):
                 raise RuntimeError(f"Unexpected {mod} {fname}")
             mod_stats[mod][e] += pm
             mod_stats["mne"][e] += pm
             total_lines += pm
     mod_stats.pop("null")  # stuff we shouldn't give credit for
+    # Assert no private (_-prefixed) submodule names remain after null-removal
+    private_mods = [
+        m
+        for m in mod_stats
+        if m.startswith("mne.") and m.split(".")[-1].startswith("_")
+    ]
+    if private_mods:
+        raise RuntimeError(
+            f"Private submodule(s) {private_mods} found in credit page. "
+            "Update credit_tools.py to remap them to a public module."
+        )
     mod_stats = dict(
         (k, mod_stats[k])
         for k in sorted(

doc/sphinxext/related_software.txt

@@ -1,5 +1,5 @@
-# cross-domain-saliency-maps requirements are onerous (torch and tensorflow)
-# so we don't add it here, and install it separately in circleci_dependencies.sh
+# related software with onerous dependencies (e.g., torch and tensorflow)
+# should be added to related_software_nodeps.txt
 alphaCSC
 autoreject
 bycycle
@@ -34,6 +34,7 @@ pycrostates
 pyprep
 pyriemann
 python-picard
+rsatoolbox
 sesameeg
 sleepecg
 tensorpac