mnextend 0.1.0__tar.gz

mnextend-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+© MNEXTEND developers
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mnextend-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: mnextend
+Version: 0.1.0
+Summary: Additional functionality for MNE-Python
+Keywords: EEG,MEG,MNE-Python,XDF,electrophysiology
+Author: Clemens Brunner
+Author-email: Clemens Brunner <clemens.brunner@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: edfio>=0.4.13
+Requires-Dist: mne>=1.12.1
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: pybv>=0.8.1
+Requires-Dist: pybvrf>=0.1.3
+Requires-Dist: pyxdf>=1.17.5
+Requires-Dist: scipy>=1.15.3
+Requires-Python: >=3.12
+Project-URL: homepage, https://github.com/cbrnr/mnextend
+Project-URL: documentation, https://github.com/cbrnr/mnextend/blob/main/README.md
+Project-URL: repository, https://github.com/cbrnr/mnextend
+Project-URL: changelog, https://github.com/cbrnr/mnextend/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# MNExtend
+
+This package provides additional functionality for working with [MNE-Python](https://mne.tools/), the most popular Python package for processing electrophysiological data (EEG, MEG, ...).
+
+## Features
+
+### Reading additional file formats
+
+MNExtend provides readers for the following file formats that are not natively supported by MNE-Python:
+
+- [XDF](https://github.com/sccn/xdf/wiki/Specifications) (Extensible Data Format)
+- [MAT](https://www.mathworks.com/help/matlab/import_export/mat-file-versions.html) (MATLAB)
+- [NPY](https://numpy.org/doc/stable/reference/generated/numpy.lib.format.html) (NumPy)
+
+In addition, MNExtend adds the following readers from third-party packages:
+
+- [BVRF](https://www.brainproducts.com/support-resources/brainvision-recording-format/) (via [PyBVRF](https://github.com/cbrnr/pybvrf))
+
+Together with the native MNE-Python readers, `read_raw()` and `read_epochs()` provide a unified interface for reading electrophysiological data from a wide range of file formats, so all you have to do is:
+
+```python
+from mnextend import read_raw, read_epochs
+
+raw = read_raw("my_data-raw.xdf", stream_ids=[1, 2, 3])
+epochs = read_epochs("my_data-epochs.fif.gz")
+```
+
+### Writing raw data
+
+Writing raw data is supported via `write_raw()`, which does not implement any new file formats, but provides a unified interface for writing raw data to the file formats that are natively supported by MNE-Python:
+
+```python
+from mnextend import write_raw
+
+write_raw("my_data-raw.fif.gz", raw)
+```

mnextend-0.1.0/README.md

@@ -0,0 +1,36 @@
+# MNExtend
+
+This package provides additional functionality for working with [MNE-Python](https://mne.tools/), the most popular Python package for processing electrophysiological data (EEG, MEG, ...).
+
+## Features
+
+### Reading additional file formats
+
+MNExtend provides readers for the following file formats that are not natively supported by MNE-Python:
+
+- [XDF](https://github.com/sccn/xdf/wiki/Specifications) (Extensible Data Format)
+- [MAT](https://www.mathworks.com/help/matlab/import_export/mat-file-versions.html) (MATLAB)
+- [NPY](https://numpy.org/doc/stable/reference/generated/numpy.lib.format.html) (NumPy)
+
+In addition, MNExtend adds the following readers from third-party packages:
+
+- [BVRF](https://www.brainproducts.com/support-resources/brainvision-recording-format/) (via [PyBVRF](https://github.com/cbrnr/pybvrf))
+
+Together with the native MNE-Python readers, `read_raw()` and `read_epochs()` provide a unified interface for reading electrophysiological data from a wide range of file formats, so all you have to do is:
+
+```python
+from mnextend import read_raw, read_epochs
+
+raw = read_raw("my_data-raw.xdf", stream_ids=[1, 2, 3])
+epochs = read_epochs("my_data-epochs.fif.gz")
+```
+
+### Writing raw data
+
+Writing raw data is supported via `write_raw()`, which does not implement any new file formats, but provides a unified interface for writing raw data to the file formats that are natively supported by MNE-Python:
+
+```python
+from mnextend import write_raw
+
+write_raw("my_data-raw.fif.gz", raw)
+```

mnextend-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["uv_build >= 0.11.24, < 0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "mnextend"
+version = "0.1.0"
+description = "Additional functionality for MNE-Python"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Clemens Brunner", email = "clemens.brunner@gmail.com"},
+]
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+keywords = ["EEG", "MEG", "MNE-Python", "XDF", "electrophysiology"]
+dependencies = [
+    "edfio>=0.4.13",
+    "mne>=1.12.1",
+    "numpy>=2.2.6",
+    "pybv>=0.8.1",
+    "pybvrf>=0.1.3",
+    "pyxdf>=1.17.5",
+    "scipy>=1.15.3",
+]
+
+[dependency-groups]
+dev = [
+    "pytest >= 9.1.1",
+    "ruff >= 0.15.19",
+]
+
+[project.urls]
+homepage = "https://github.com/cbrnr/mnextend"
+documentation = "https://github.com/cbrnr/mnextend/blob/main/README.md"
+repository = "https://github.com/cbrnr/mnextend"
+changelog = "https://github.com/cbrnr/mnextend/blob/main/CHANGELOG.md"
+
+[tool.ruff.lint]
+select = ["C4", "E", "F", "I", "PERF", "UP", "W"]

mnextend-0.1.0/src/mnextend/__init__.py

@@ -0,0 +1,9 @@
+# © MNEXTEND developers
+#
+# License: BSD (3-clause)
+
+from mnextend.io.readers import read_epochs, read_raw
+from mnextend.io.utils import split_name_ext
+from mnextend.io.writers import write_epochs, write_raw
+
+__all__ = ["read_epochs", "read_raw", "split_name_ext", "write_epochs", "write_raw"]

mnextend-0.1.0/src/mnextend/io/__init__.py

@@ -0,0 +1,9 @@
+# © MNEXTEND developers
+#
+# License: BSD (3-clause)
+
+from mnextend.io.readers import read_epochs, read_raw
+from mnextend.io.utils import split_name_ext
+from mnextend.io.writers import write_epochs, write_raw
+
+__all__ = ["read_epochs", "read_raw", "split_name_ext", "write_epochs", "write_raw"]

mnextend-0.1.0/src/mnextend/io/mat.py

@@ -0,0 +1,93 @@
+# © MNEXTEND developers
+#
+# License: BSD (3-clause)
+
+import re
+
+import numpy as np
+from mne import create_info
+from mne.io import BaseRaw
+from numpy import atleast_2d
+from scipy.io import loadmat
+
+
+class RawMAT(BaseRaw):
+    """Raw data from .mat file."""
+
+    def __init__(self, fname, variable, fs, transpose=False):
+        """Read raw data from .mat file.
+
+        Parameters
+        ----------
+        fname : str
+            File name to load.
+        variable : str
+            Name of the variable to use. If nested within a struct, separate all names
+            with dots. For example, `y.X` corresponds to a variable `X` contained in a
+            struct `y`. If the cell array has multiple items, use `y.[0].X` to access
+            the first item named `X`, `y.[1].X` to access the second item named `X`, and
+            so on.
+        fs : float
+            Sampling frequency (in Hz).
+        transpose : bool
+            Whether to transpose the data; set to `True` if the original shape is *not*
+            (channels, samples).
+        """
+        mat = loadmat(fname, simplify_cells=True)
+        data = atleast_2d(_get_dict_value(mat, variable.split(".")))
+        if transpose:
+            data = data.T
+        info = create_info(data.shape[0], fs, "eeg")
+        super().__init__(preload=data, info=info, filenames=[fname])
+
+
+def read_raw_mat(fname, variable, fs, transpose=False, *args, **kwargs):
+    """Read raw data from .mat file.
+
+    Parameters
+    ----------
+    fname : str
+        File name to load.
+    variable : str
+        Name of the variable to use. If nested within a struct, separate all names with
+        dots. For example, `y.X` corresponds to a variable `X` contained in a struct
+        `y`. If the cell array has multiple items, use `y.[0].X` to access the first
+        item named `X`, `y.[1].X` to access the second item named `X`, and so on.
+    fs : float
+        Sampling frequency (in Hz).
+    transpose : bool
+        Whether to transpose the data, the data should be of shape (channels, samples).
+
+    Returns
+    -------
+    RawMAT
+        The raw data.
+    """
+    return RawMAT(fname, variable, fs, transpose)
+
+
+def parse_mat(fname):
+    """Remove dunder variables from dict returned by scipy.io.loadmat()."""
+    mat = loadmat(fname, simplify_cells=True)
+    return {
+        k: v for k, v in mat.items() if not k.startswith("__") and not k.endswith("__")
+    }
+
+
+def _get_dict_value(d, keys):
+    """Get dictionary value from nested dictionary keys."""
+    if isinstance(keys, str):  # no nesting
+        return d[keys]
+    value = d
+    for key in keys:
+        if match := re.search(r"\[(\d+)\]", key):  # list element
+            idx = int(match.group(1))
+            if not isinstance(value, (list, np.ndarray)):
+                raise ValueError(
+                    f"Expected a list or array at '{key}', got {type(value).__name__}."
+                    " Use a plain name (without brackets) to access a struct field."
+                )
+            value = value[idx]
+        else:  # dict element
+            value = value[key]
+    return value

mnextend-0.1.0/src/mnextend/io/npy.py

@@ -0,0 +1,76 @@
+# © MNEXTEND developers
+#
+# License: BSD (3-clause)
+
+import mne
+import numpy as np
+from mne.io import BaseRaw
+
+
+class RawNPY(BaseRaw):
+    """Raw data from .npy file."""
+
+    def __init__(self, fname, fs, transpose=False):
+        """Read raw data from .npy file.
+
+        Parameters
+        ----------
+        fname : str
+            File name to load.
+        fs : float
+            Sampling frequency (in Hz).
+        transpose : bool
+            Whether to transpose the data; set to `True` if the original shape is *not*
+            (channels, samples).
+        """
+        data = np.load(fname)
+        if transpose:
+            data = data.T
+        if data.ndim != 2:
+            raise ValueError(f"Array must have two dimensions (got {data.ndim}).")
+        info = mne.create_info(data.shape[0], fs)
+        super().__init__(preload=data, info=info, filenames=[fname])
+
+
+def read_raw_npy(fname, fs, transpose=False, *args, **kwargs):
+    """Read raw data from .npy file.
+
+    Parameters
+    ----------
+    fname : str
+        File name to load.
+    fs : float
+        Sampling frequency (in Hz).
+    transpose : bool
+        Whether to transpose the data, the data should be of shape (channels, samples).
+
+    Returns
+    -------
+    RawNPY
+        The raw data.
+    """
+    return RawNPY(fname, fs, transpose)
+
+
+def parse_npy(fname):
+    """Return shape of array contained in .npy file.
+
+    Parameters
+    ----------
+    fname : str
+        File name to load.
+
+    Returns
+    -------
+    shape : tuple[int, int]
+        The shape of the array.
+    """
+    with open(fname, "rb") as f:
+        major, _ = np.lib.format.read_magic(f)
+        read_header = (
+            np.lib.format.read_array_header_2_0
+            if major == 2
+            else np.lib.format.read_array_header_1_0
+        )
+        shape, _, _ = read_header(f)
+    return shape

mnextend-0.1.0/src/mnextend/io/readers.py

@@ -0,0 +1,107 @@
+# © MNEXTEND developers
+#
+# License: BSD (3-clause)
+
+from functools import partial
+from pathlib import Path
+
+import mne
+from pybvrf import read_raw_bvrf
+
+from mnextend.io.mat import read_raw_mat
+from mnextend.io.npy import read_raw_npy
+from mnextend.io.utils import split_name_ext
+from mnextend.io.xdf import read_raw_xdf
+
+
+def _read_unsupported(fname, *, suggest=None, **kwargs):
+    ext = "".join(Path(fname).suffixes)
+    msg = f"Unsupported file type ({ext})."
+    if suggest is not None:
+        msg += f" Try reading a {suggest} file instead."
+    raise ValueError(msg)
+
+
+# known file formats for raw (continuous) data
+raw_readers = {
+    ".edf": mne.io.read_raw_edf,
+    ".bdf": mne.io.read_raw_bdf,
+    ".gdf": mne.io.read_raw_gdf,
+    ".vhdr": mne.io.read_raw_brainvision,
+    ".fif": mne.io.read_raw_fif,
+    ".set": mne.io.read_raw_eeglab,
+    ".cnt": mne.io.read_raw_cnt,
+    ".mff": mne.io.read_raw_egi,
+    ".nxe": mne.io.read_raw_eximia,
+    ".hdr": mne.io.read_raw_nirx,
+    ".snirf": mne.io.read_raw_snirf,
+    ".mat": read_raw_mat,
+    ".npy": read_raw_npy,
+    **dict.fromkeys([".fif.gz"], mne.io.read_raw_fif),
+    **dict.fromkeys([".xdf", ".xdfz", ".xdf.gz"], read_raw_xdf),
+    **dict.fromkeys([".bvrh", ".bvrd", ".bvrm", ".bvri"], read_raw_bvrf),
+    **dict.fromkeys([".vmrk", ".eeg"], partial(_read_unsupported, suggest=".vhdr")),
+}
+
+# known file formats for epochs (segmented) data
+epochs_readers = {
+    ".fif": mne.read_epochs,
+    ".fif.gz": mne.read_epochs,
+    ".set": mne.read_epochs_eeglab,
+}
+
+
+def _read(fname, readers, *args, **kwargs):
+    """Read file using appropriate reader based on file extension."""
+    fname = Path(fname).expanduser()
+    _, ext = split_name_ext(fname, readers)
+    if ext is not None:
+        return readers[ext](fname, *args, **kwargs)
+    ext = "".join(Path(fname).suffixes).lower()
+    raise ValueError(
+        f"Unsupported file type ({ext})." if ext else "Unsupported file type."
+    )
+
+
+def read_raw(fname, *args, **kwargs):
+    """Read raw (continuous) data file.
+
+    Parameters
+    ----------
+    fname : str | Path
+        File name to load.
+
+    Returns
+    -------
+    raw : mne.io.Raw
+        Raw object.
+
+    Notes
+    -----
+    This function supports reading raw data from different file formats. It uses the
+    `raw_readers` dict to dispatch the appropriate read function for a supported file
+    type.
+    """
+    return _read(fname, raw_readers, *args, **kwargs)
+
+
+def read_epochs(fname, *args, **kwargs):
+    """Read epochs (segmented) data file.
+
+    Parameters
+    ----------
+    fname : str | Path
+        File name to load.
+
+    Returns
+    -------
+    epochs : mne.Epochs
+        Epochs object.
+
+    Notes
+    -----
+    This function supports reading epochs data from different file formats. It uses the
+    `epochs_readers` dict to dispatch the appropriate read function for a supported file
+    type.
+    """
+    return _read(fname, epochs_readers, *args, **kwargs)

mnextend-0.1.0/src/mnextend/io/utils.py

@@ -0,0 +1,16 @@
+# © MNEXTEND developers
+#
+# License: BSD (3-clause)
+
+from pathlib import Path
+
+
+def split_name_ext(fname, readers):
+    """Return name and supported file extension."""
+    maxsuffixes = max(ext.count(".") for ext in readers)
+    suffixes = Path(fname).suffixes
+    for n in range(maxsuffixes, 0, -1):
+        ext = "".join(suffixes[-n:]).lower()
+        if ext in readers:
+            return Path(fname).name[: -len(ext)], ext
+    return Path(fname).name, None

mnextend-0.1.0/src/mnextend/io/writers.py

@@ -0,0 +1,156 @@
+# © MNEXTEND developers
+#
+# License: BSD (3-clause)
+
+from pathlib import Path
+
+import numpy as np
+from numpy.rec import fromarrays
+from scipy.io import savemat
+
+from mnextend.io.utils import split_name_ext
+
+
+def write_fif(fname, raw):
+    raw.save(fname, overwrite=True)
+
+
+def write_set(fname, raw):
+    """Export raw to EEGLAB .set file."""
+    data = raw.get_data() * 1e6  # convert to microvolts
+    fs = raw.info["sfreq"]
+    times = raw.times
+    ch_names = raw.info["ch_names"]
+    chanlocs = fromarrays([ch_names], names=["labels"])
+    events = fromarrays(
+        [
+            raw.annotations.description,
+            raw.annotations.onset * fs + 1,
+            raw.annotations.duration * fs,
+        ],
+        names=["type", "latency", "duration"],
+    )
+    savemat(
+        fname,
+        {
+            "EEG": {
+                "data": data,
+                "setname": str(fname),
+                "nbchan": data.shape[0],
+                "pnts": data.shape[1],
+                "trials": 1,
+                "srate": fs,
+                "xmin": times[0],
+                "xmax": times[-1],
+                "chanlocs": chanlocs,
+                "event": events,
+                "icawinv": [],
+                "icasphere": [],
+                "icaweights": [],
+            }
+        },
+        appendmat=False,
+    )
+
+
+def write_bdf_edf(fname, raw):
+    """Export raw to EDF file."""
+    raw.export(fname, overwrite=True)
+
+
+def write_bv(fname, raw):
+    """Export data to BrainVision EEG/VHDR/VMRK file (requires pybv)."""
+    raw.export(fname=Path(fname).with_suffix(".vhdr"), overwrite=True)
+
+
+# These dicts contain each supported file extension as a key; the corresponding value is
+# a list with two elements: (1) the writer function and (2) the full file format name.
+raw_writers = {
+    ".bdf": [write_bdf_edf, "Biosemi Data Format"],
+    ".edf": [write_bdf_edf, "European Data Format"],
+    ".eeg": [write_bv, "BrainVision"],
+    ".fif": [write_fif, "Elekta Neuromag"],
+    ".fif.gz": [write_fif, "Elekta Neuromag"],
+    ".set": [write_set, "EEGLAB"],
+}
+
+
+def write_epochs_set(fname, epochs):
+    """Export epochs to EEGLAB .set file."""
+    data = epochs.get_data() * 1e6  # (n_epochs, n_channels, n_times), convert to µV
+    data = data.transpose(1, 2, 0)  # EEGLAB expects (n_channels, n_times, n_epochs)
+
+    n_epochs = len(epochs)
+    n_times = len(epochs.times)
+    fs = epochs.info["sfreq"]
+
+    chanlocs = fromarrays([epochs.ch_names], names=["labels"])
+
+    id_to_name = {v: k for k, v in epochs.event_id.items()}
+    event_types = np.array(
+        [id_to_name.get(eid, str(eid)) for eid in epochs.events[:, 2]]
+    )
+    # latency in samples (1-based) within the concatenated epoch data
+    offset = round(abs(epochs.tmin) * fs)
+    latencies = (np.arange(n_epochs) * n_times + offset + 1).astype(float)
+    epoch_indices = np.arange(1, n_epochs + 1, dtype=float)
+
+    events = fromarrays(
+        [event_types, latencies, np.zeros(n_epochs), epoch_indices],
+        names=["type", "latency", "duration", "epoch"],
+    )
+    # per-epoch struct: eventlatency in ms (0 = time-locking event)
+    epoch_struct = fromarrays(
+        [epoch_indices, event_types, np.zeros(n_epochs), np.zeros(n_epochs)],
+        names=["event", "eventtype", "eventlatency", "eventduration"],
+    )
+
+    savemat(
+        fname,
+        {
+            "EEG": {
+                "data": data,
+                "setname": str(fname),
+                "nbchan": data.shape[0],
+                "pnts": n_times,
+                "trials": n_epochs,
+                "srate": fs,
+                "xmin": epochs.tmin,
+                "xmax": epochs.tmax,
+                "chanlocs": chanlocs,
+                "event": events,
+                "epoch": epoch_struct,
+                "icawinv": [],
+                "icasphere": [],
+                "icaweights": [],
+            }
+        },
+        appendmat=False,
+    )
+
+
+epochs_writers = {
+    ".fif": [write_fif, "Elekta Neuromag"],
+    ".fif.gz": [write_fif, "Elekta Neuromag"],
+    ".set": [write_epochs_set, "EEGLAB"],
+}
+
+
+def _write(fname, data, writer_dict):
+    """Write data using appropriate writer based on file extension."""
+    fname = Path(fname).expanduser()
+    _, ext = split_name_ext(fname, writer_dict)
+    if ext is not None:
+        return writer_dict[ext][0](fname, data)
+    ext = "".join(Path(fname).suffixes).lower()
+    raise ValueError(
+        f"Unsupported file type ({ext})." if ext else "Unsupported file type."
+    )
+
+
+def write_raw(fname, raw):
+    return _write(fname, raw, raw_writers)
+
+
+def write_epochs(fname, epochs):
+    return _write(fname, epochs, epochs_writers)

mnextend-0.1.0/src/mnextend/io/xdf.py

@@ -0,0 +1,480 @@
+# © MNEXTEND developers
+#
+# License: BSD (3-clause)
+
+import struct
+import xml.etree.ElementTree as ETree
+from collections import defaultdict
+from datetime import UTC, datetime
+
+import mne
+import numpy as np
+import scipy.signal
+from mne.io import BaseRaw, get_channel_type_constants
+from pyxdf import load_xdf, resolve_streams
+from pyxdf.pyxdf import _read_varlen_int, open_xdf
+
+
+class RawXDF(BaseRaw):
+    """Raw data from .xdf file."""
+
+    def __init__(
+        self,
+        fname,
+        stream_ids,
+        marker_ids=None,
+        prefix_markers=False,
+        fs_new=None,
+        gap_threshold=0.0,
+        *args,
+        **kwargs,
+    ):
+        """Read raw data from .xdf file.
+
+        Parameters
+        ----------
+        fname : str | Path
+            File name to load.
+        stream_ids : int | list[int]
+            ID(s) of streams to load. Use `pyxdf.resolve_streams(fname)` to list
+            available streams.
+        marker_ids : list[int] | None
+            IDs of marker streams to load. If `None`, load all marker streams. A marker
+            stream is a stream with a nominal sampling frequency of 0 Hz.
+        prefix_markers : bool
+            Whether to prefix marker streams with their corresponding stream ID.
+        fs_new : float | None
+            Target sampling frequency in Hz (required when reading multiple streams). If
+            only one stream is provided, this can be `None`, in which case the stream's
+            original sampling rate is used.
+        gap_threshold : float
+            Detect gaps in timestamps larger than this value (in seconds) and mark those
+            samples as NaN. Set to 0.0 to disable gap detection. If `gap_threshold > 0`,
+            linear interpolation is used instead of resampling, and `fs_new` must be
+            specified.
+
+        Notes
+        -----
+        Resampling depends on whether gap detection is requested or not:
+        - If `gap_threshold > 0`, uses linear interpolation to resample to the new
+          sampling frequency `fs_new`. This method will detect gaps in the original
+          timestamps and mark those samples as NaN.
+        - If `gap_threshold == 0`, uses Fourier-based resampling if `fs_new` is provided
+          or does not resample at all if `fs_new` is `None`. This method assumes that
+          the original timestamps are regular and does not account for any gaps.
+        By default, gap detection is disabled.
+        """
+        if len(stream_ids) == 0:
+            raise ValueError("Argument `stream_ids` must not be empty.")
+
+        if len(stream_ids) > 1 and fs_new is None:
+            raise ValueError(
+                "Argument `fs_new` is required when reading multiple streams."
+            )
+
+        if gap_threshold < 0:
+            raise ValueError(
+                f"Argument `gap_threshold` must be non-negative, got {gap_threshold}."
+            )
+
+        if gap_threshold > 0 and fs_new is None:
+            raise ValueError(
+                "Argument `fs_new` is required when `gap_threshold > 0`. "
+                "Gap detection requires resampling to a regular time grid."
+            )
+
+        streams, header = load_xdf(fname)
+        streams = {stream["info"]["stream_id"]: stream for stream in streams}
+
+        if all(_is_stringstream(streams[stream_id]) for stream_id in stream_ids):
+            raise RuntimeError(
+                "Loading only marker streams is not supported, at least one stream must"
+                " be a regular stream."
+            )
+
+        labels_all, types_all, units_all = [], [], []
+        channel_types = get_channel_type_constants(True)
+        for stream_id in stream_ids:
+            stream = streams[stream_id]
+
+            n_chans = int(stream["info"]["channel_count"][0])
+            labels, types, units = [], [], []
+            try:
+                for ch in stream["info"]["desc"][0]["channels"][0]["channel"]:
+                    labels.append(str(ch["label"][0]))
+                    if ch["type"] and ch["type"][0].lower() in channel_types:
+                        types.append(ch["type"][0].lower())
+                    else:
+                        types.append("misc")
+                    units.append(ch["unit"][0] if ch["unit"] else "NA")
+            except (TypeError, IndexError):  # no channel labels found
+                pass
+            if not labels:
+                labels = [f"{stream['info']['name'][0]}_{n}" for n in range(n_chans)]
+            if not units:
+                units = ["NA" for _ in range(n_chans)]
+            if not types:
+                types = ["misc" for _ in range(n_chans)]
+            labels_all.extend(labels)
+            types_all.extend(types)
+            units_all.extend(units)
+
+        # interpolate if gap detection is requested, otherwise resample
+        use_interpolation = gap_threshold > 0
+
+        if fs_new is not None:
+            data, first_time = _resample_streams(
+                streams, stream_ids, fs_new, use_interpolation
+            )
+            fs = fs_new
+
+            if gap_threshold > 0:  # mark gaps if requested
+                timestamps = first_time + np.arange(len(data)) / fs
+                col_start = 0
+                for stream_id in stream_ids:
+                    n_chans = int(streams[stream_id]["info"]["channel_count"][0])
+                    _mark_gaps(
+                        data,
+                        timestamps,
+                        streams[stream_id]["time_stamps"],
+                        gap_threshold,
+                        slice(col_start, col_start + n_chans),
+                    )
+                    col_start += n_chans
+        else:  # only possible if a single stream was selected
+            if len(streams[stream_ids[0]]["time_stamps"]) == 0:
+                raise ValueError(f"Stream {stream_ids[0]} contains no samples.")
+            data = streams[stream_ids[0]]["time_series"]
+            first_time = streams[stream_ids[0]]["time_stamps"][0]
+            fs = float(
+                np.array(streams[stream_ids[0]]["info"]["effective_srate"]).item()
+            )
+            if fs == 0:  # fall back to nominal rate (e.g. when only one sample exists)
+                fs = float(streams[stream_ids[0]]["info"]["nominal_srate"][0])
+
+        info = mne.create_info(ch_names=labels_all, sfreq=fs, ch_types=types_all)
+
+        microvolts = ("microvolt", "microvolts", "µV", "μV", "uV")
+        scale = np.array([1e-6 if u in microvolts else 1 for u in units_all])
+        data = (data * scale).T
+        super().__init__(preload=data, info=info, filenames=[fname], *args, **kwargs)
+
+        # convert string streams to annotations
+        for stream_id, stream in streams.items():
+            if not _is_stringstream(stream):
+                continue
+            srate = float(stream["info"]["nominal_srate"][0])
+            # classic marker streams (srate=0) respect the user's marker selection;
+            # regular-rate string streams are always converted automatically
+            if srate == 0 and marker_ids is not None and stream_id not in marker_ids:
+                continue
+            prefix = f"{stream_id}-" if prefix_markers else ""
+            onsets_list, descriptions_list = [], []
+            for ts, sub in zip(stream["time_stamps"], stream["time_series"]):
+                for item in sub:
+                    if item:  # skip empty strings
+                        onsets_list.append(ts - first_time)
+                        descriptions_list.append(f"{prefix}{item}")
+            if onsets_list:
+                self.annotations.append(
+                    onsets_list, [0] * len(onsets_list), descriptions_list
+                )
+
+        recording_datetime = header["info"].get("datetime", [None])[0]
+        if recording_datetime is not None:
+            try:
+                meas_date = datetime.fromisoformat(recording_datetime)
+            except ValueError:
+                # LabRecorder emits timezone offsets as +HHMM without the colon
+                recording_datetime = (
+                    recording_datetime[:-2] + ":" + recording_datetime[-2:]
+                )
+                meas_date = datetime.fromisoformat(recording_datetime)
+            self.set_meas_date(meas_date.astimezone(UTC))
+
+
+def _mark_gaps(data, timestamps, original_timestamps, gap_threshold, cols):
+    """Mark gaps in data with NaN based on gaps in original timestamps.
+
+    This function modifies the data array in-place.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Data array of shape (n_samples, n_channels). Modified in-place.
+    timestamps : np.ndarray
+        Timestamps corresponding to data (interpolated/resampled uniform grid).
+    original_timestamps : np.ndarray
+        Original timestamps from the stream.
+    gap_threshold : float
+        Gap threshold in seconds.
+    cols : slice
+        Column slice indicating which columns belong to this stream.
+    """
+    # find gaps in original timestamps
+    gaps = np.diff(original_timestamps) > gap_threshold
+    gap_indices = np.where(gaps)[0]
+
+    if len(gap_indices) == 0:
+        return
+
+    # for each gap, find the time range and mark it in the data
+    for idx in gap_indices:
+        gap_start_time = original_timestamps[idx]
+        gap_end_time = original_timestamps[idx + 1]
+
+        # find corresponding indices in the uniform time grid
+        start_idx = np.searchsorted(timestamps, gap_start_time, side="right")
+        end_idx = np.searchsorted(timestamps, gap_end_time, side="left")
+
+        # mark the gap region as NaN (only for this stream's columns)
+        if start_idx < len(data) and end_idx <= len(data):
+            data[start_idx:end_idx, cols] = np.nan
+
+
+def _resample_streams(streams, stream_ids, fs_new, use_interpolation=False):
+    """Resample XDF stream(s) to a common sampling rate.
+
+    Parameters
+    ----------
+    streams : dict
+        A dictionary mapping stream IDs to XDF streams.
+    stream_ids : list[int]
+        The IDs of the desired streams.
+    fs_new : float
+        Target sampling frequency in Hz.
+    use_interpolation : bool
+        If True, use linear interpolation. If False, use Fourier-based resampling.
+
+    Returns
+    -------
+    all_time_series : np.ndarray
+        Array of shape (n_samples, n_channels) containing raw data. Time intervals where
+        a stream has no data contain `np.nan`.
+    first_time : float
+        Time of the very first sample in seconds.
+    """
+    from scipy.interpolate import interp1d
+    from scipy.signal import butter, sosfiltfilt
+
+    start_times = []
+    end_times = []
+    n_total_chans = 0
+    for stream_id in stream_ids:
+        if len(streams[stream_id]["time_stamps"]) == 0:
+            raise ValueError(f"Stream {stream_id} contains no samples.")
+        start_times.append(streams[stream_id]["time_stamps"][0])
+        end_times.append(streams[stream_id]["time_stamps"][-1])
+        n_total_chans += int(streams[stream_id]["info"]["channel_count"][0])
+    first_time = min(start_times)
+    last_time = max(end_times)
+
+    n_samples = int(np.ceil((last_time - first_time) * fs_new))
+    all_time_series = np.full((n_samples, n_total_chans), np.nan)
+    time_grid = first_time + np.arange(n_samples) / fs_new
+
+    col_start = 0
+    for stream_id in stream_ids:
+        timestamps = streams[stream_id]["time_stamps"]
+        sort_indices = np.argsort(timestamps)
+        timestamps = timestamps[sort_indices]
+        timestamps, unique_idx = np.unique(timestamps, return_index=True)
+
+        if not sort_indices.shape == unique_idx.shape:
+            from warnings import warn
+
+            warn(
+                f"Non-unique timestamps found in stream {stream_id}: "
+                f"{sort_indices.shape[0]} timestamps, {unique_idx.shape[0]} unique.",
+                RuntimeWarning,
+            )
+
+        start_time = timestamps[0]
+        end_time = timestamps[-1]
+        x_old = streams[stream_id]["time_series"][sort_indices[unique_idx], :]
+
+        # apply anti-aliasing filter if downsampling
+        fs_original = float(
+            np.array(streams[stream_id]["info"]["effective_srate"]).item()
+        )
+        if fs_new < fs_original:
+            nyquist = fs_new / 2
+            sos = butter(8, 0.95 * nyquist, btype="low", fs=fs_original, output="sos")
+            x_old = sosfiltfilt(sos, x_old, axis=0)
+
+        # find valid time range in output grid
+        row_start = int(np.floor((start_time - first_time) * fs_new))
+        row_end = int(np.ceil((end_time - first_time) * fs_new))
+        time_new = time_grid[row_start:row_end]
+
+        if use_interpolation:  # linear interpolation
+            interpolator = interp1d(
+                timestamps,
+                x_old,
+                axis=0,
+                kind="linear",
+                bounds_error=False,
+                fill_value=np.nan,
+            )
+            x_new = interpolator(time_new)
+        else:  # Fourier-based resampling
+            len_new = len(time_new)
+            x_new = scipy.signal.resample(x_old, len_new, axis=0)
+
+        col_end = col_start + x_new.shape[1]
+        all_time_series[row_start:row_end, col_start:col_end] = x_new
+
+        col_start += x_new.shape[1]
+
+    return all_time_series, first_time
+
+
+def read_raw_xdf(
+    fname,
+    stream_ids=None,
+    marker_ids=None,
+    prefix_markers=False,
+    fs_new=None,
+    gap_threshold=0.0,
+    **kwargs,
+):
+    """Read XDF file.
+
+    Parameters
+    ----------
+    fname : str
+        File name to load.
+    stream_ids : int | list[int] | None
+        ID(s) of streams to load. If `None`, raises a `ValueError` listing the available
+        regular stream IDs. Use `pyxdf.resolve_streams(fname)` to list available
+        streams.
+    marker_ids : list[int] | None
+        IDs of marker streams to load. If `None`, load all marker streams. A marker
+        stream is a stream with a nominal sampling frequency of 0 Hz.
+    prefix_markers : bool
+        Whether to prefix marker streams with their corresponding stream ID.
+    fs_new : float | None
+        Target sampling frequency in Hz (required when reading multiple streams). If
+        only one stream is provided, this can be `None`, in which case the stream's
+        original sampling rate is used.
+    gap_threshold : float
+        Detect gaps in timestamps larger than this value (in seconds) and mark those
+        samples as NaN. Set to 0.0 to disable gap detection. If `gap_threshold > 0`,
+        linear interpolation is used instead of resampling, and `fs_new` must be
+        specified.
+
+    Returns
+    -------
+    RawXDF
+        The raw data.
+    """
+    if isinstance(stream_ids, int):
+        stream_ids = [stream_ids]
+    if stream_ids is None:
+        streams = resolve_streams(fname)
+        ids = [s["stream_id"] for s in streams if s["channel_format"] != "string"]
+        msg = (
+            "Argument `stream_ids` is required (available regular stream IDs: "
+            f"{', '.join(map(str, ids))})."
+        )
+        raise ValueError(msg)
+    return RawXDF(
+        fname,
+        stream_ids,
+        marker_ids,
+        prefix_markers,
+        fs_new,
+        gap_threshold,
+    )
+
+
+def _is_stringstream(stream):
+    return stream["info"]["channel_format"][0] == "string"
+
+
+def get_xml(fname):
+    """Get XML stream headers and footers from all streams.
+
+    Parameters
+    ----------
+    fname : str
+        Name of the XDF file.
+
+    Returns
+    -------
+    xml : dict
+        XML stream headers and footers.
+    """
+    with open_xdf(fname) as f:
+        xml = defaultdict(dict)
+        while True:
+            try:
+                nbytes = _read_varlen_int(f)
+            except EOFError:
+                return xml
+            tag = struct.unpack("<H", f.read(2))[0]
+            if tag in [2, 3, 4, 6]:
+                stream_id = struct.unpack("<I", f.read(4))[0]
+                if tag in [2, 6]:  # parse StreamHeader/StreamFooter chunk
+                    string = f.read(nbytes - 6).decode()
+                    xml[stream_id][tag] = ETree.fromstring(string)
+                else:  # skip remaining chunk contents
+                    f.seek(nbytes - 6, 1)
+            else:
+                f.seek(nbytes - 2, 1)  # skip remaining chunk contents
+
+
+def list_chunks(fname):
+    """List all chunks contained in an XDF file.
+
+    Listing chunks summarizes the content of the XDF file. Because this function does
+    not attempt to parse the data, this also works for corrupted files.
+
+    Parameters
+    ----------
+    fname : str
+        Name of the XDF file.
+
+    Returns
+    -------
+    chunks : list
+        List of dicts containing a short summary for each chunk.
+    """
+    with open_xdf(fname) as f:
+        chunks = []
+        while True:
+            try:
+                nbytes = _read_varlen_int(f)
+            except EOFError:
+                return chunks
+            chunk = {"nbytes": nbytes}
+            tag = struct.unpack("<H", f.read(2))[0]
+            chunk["tag"] = tag
+            if tag == 1:
+                chunk["content"] = f.read(nbytes - 2).decode()
+            elif tag == 5:
+                chunk["content"] = (
+                    "0x43 0xA5 0x46 0xDC 0xCB 0xF5 0x41 0x0F "
+                    "0xB3 0x0E 0xD5 0x46 0x73 0x83 0xCB 0xE4"
+                )
+                f.seek(chunk["nbytes"] - 2, 1)  # skip remaining chunk contents
+            elif tag in [2, 6]:  # XML
+                chunk["stream_id"] = struct.unpack("<I", f.read(4))[0]
+                chunk["content"] = (
+                    f.read(chunk["nbytes"] - 6).decode().replace("\t", "  ")
+                )
+            elif tag == 4:
+                chunk["stream_id"] = struct.unpack("<I", f.read(4))[0]
+                collection_time = struct.unpack("<d", f.read(8))[0]
+                offset_value = struct.unpack("<d", f.read(8))[0]
+                chunk["content"] = (
+                    f"Collection time: {collection_time}\nOffset value: {offset_value}"
+                )
+            elif tag == 3:
+                chunk["stream_id"] = struct.unpack("<I", f.read(4))[0]
+                remainder = chunk["nbytes"] - 6
+                chunk["content"] = f"<BINARY DATA ({remainder} Bytes)>"
+                f.seek(remainder, 1)  # skip remaining chunk contents
+            else:
+                f.seek(chunk["nbytes"] - 2, 1)  # skip remaining chunk contents
+            chunks.append(chunk)