Merge branch 'main' into fix-show-channel-names-rendering

Author: aman-coder03

doc/api/reading_raw_data.rst

@@ -16,6 +16,7 @@ Reading raw data
    read_raw
    read_raw_ant
    read_raw_artemis123
+   read_raw_bci2k
    read_raw_bdf
    read_raw_boxy
    read_raw_brainvision

doc/changes/dev/13619.bugfix.rst

@@ -0,0 +1 @@
+Fix bug with :func:`mne.make_forward_solution` when no MEG channels are present where ``dev_head_t`` was errantly set, by `Eric Larson`_.

doc/changes/dev/13699.newfeature.rst

@@ -0,0 +1 @@
+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`.

doc/changes/dev/13753.other.rst

@@ -0,0 +1 @@
+Improved internal functions for inspecting MATLAB v7.3 (HDF5) files in :func:`mne.io.read_raw_eeglab`, by `Bruno Aristimunha`_.

doc/changes/dev/13756.newfeature.rst

@@ -0,0 +1 @@
+Added ``cmap`` parameter to ``Evoked.animate_topomap`` to allow user-specified colormaps., by :newcontrib:`Hansuja Budhiraja`.

doc/changes/dev/13778.newfeature.rst

@@ -0,0 +1 @@
+Added a ``font_file`` parameter to :meth:`mne.viz.Brain.add_text` to support rendering glyphs not available in the default font, by `Pragnya Khandelwal`_.

doc/conf.py

@@ -291,6 +291,7 @@
     "EpochsEEGLAB": "mne.Epochs",
     "EpochsKIT": "mne.Epochs",
     "RawANT": "mne.io.Raw",
+    "RawBCI2k": "mne.io.Raw",
     "RawBOXY": "mne.io.Raw",
     "RawBrainVision": "mne.io.Raw",
     "RawBTi": "mne.io.Raw",

doc/sphinxext/related_software_nodeps.txt

@@ -3,3 +3,4 @@ cross-domain-saliency-maps
 fsleyes
 mne-kit-gui
 mne-videobrowser
+hedtools  # because it limits our Pandas version currently

examples/inverse/multi_dipole_model.py

@@ -45,6 +45,7 @@
 cov_fname = meg_path / "sample_audvis-shrunk-cov.fif"
 bem_dir = data_path / "subjects" / "sample" / "bem"
 bem_fname = bem_dir / "sample-5120-5120-5120-bem-sol.fif"
+trans_fname = meg_path / "sample_audvis_raw-trans.fif"
 
 ###############################################################################
 # Read the MEG data from the audvis experiment. Make epochs and evokeds for the
@@ -102,8 +103,9 @@
 cov_fit_right["projs"] = evoked_fit_right.info["projs"]
 
 # Fit the dipoles with the subset of sensors.
-dip_left, _ = mne.fit_dipole(evoked_fit_left, cov_fit_left, bem)
-dip_right, _ = mne.fit_dipole(evoked_fit_right, cov_fit_right, bem)
+kwargs = dict(bem=bem, trans=trans_fname)
+dip_left, _ = mne.fit_dipole(evoked_fit_left, cov_fit_left, **kwargs)
+dip_right, _ = mne.fit_dipole(evoked_fit_right, cov_fit_right, **kwargs)
 
 ###############################################################################
 # Now that we have the location and orientations of the dipoles, compute the

examples/io/read_bci2k.py

@@ -0,0 +1,66 @@
+"""
+======================
+Reading BCI2000 files
+======================
+
+In this example, we use MNE-Python to read a BCI2000 ``.dat`` file.
+BCI2000 is a general-purpose brain-computer interface (BCI) system widely
+used in EEG research. The file is downloaded from the MNE testing data
+repository using ``pooch``.
+"""  # noqa: D205 D400
+
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+import pooch
+
+import mne
+
+# %%
+# First, we download the sample BCI2000 ``.dat`` file using ``pooch``.
+
+data_dir = mne.datasets.default_path() / "bci2k_data"
+data_dir.mkdir(exist_ok=True)
+
+fname = pooch.retrieve(
+    url="https://raw.githubusercontent.com/mne-tools/mne-testing-data/master/BCI2k/bci2k_test.dat",
+    known_hash="sha256:8efc7b5f700660a044086cb1449806ca408c2e6d32d9338c32e1bf31ce3ca9cb",
+    path=data_dir,
+)
+
+# %%
+# Now we can read the file using :func:`mne.io.read_raw_bci2k`.
+# Note that ``preload=True`` is required for BCI2000 files.
+
+raw = mne.io.read_raw_bci2k(fname, preload=True)
+print(raw.info)
+
+# %%
+# We can inspect the object representation, channel names, types, sampling
+# frequency, and recording duration.
+
+print(raw)
+print(f"Channel names : {raw.ch_names}")
+print(f"Channel types : {raw.get_channel_types()}")
+print(f"Sampling freq : {raw.info['sfreq']} Hz")
+print(f"Duration      : {raw.times[-1]:.2f} s")
+print(f"n_channels    : {raw.info['nchan']}")
+print(f"Data shape    : {raw.get_data().shape}  (n_channels, n_samples)")
+
+# %%
+# If the BCI2000 file contains a ``StimulusCode`` state, it is automatically
+# mapped to a ``STI 014`` stim channel. We can extract events from it using
+# :func:`mne.find_events`.
+
+if "STI 014" in raw.ch_names:
+    events = mne.find_events(raw, shortest_event=1)
+    print(f"Found {len(events)} events")
+    print(mne.count_events(events))
+else:
+    print("No stim channel found in this file.")
+
+# %%
+# Finally, we can visualize the raw data.
+
+raw.plot(duration=5, n_channels=len(raw.ch_names), scalings="auto")