ENH: Use official reader for curry files (curry-python-reader) (mne-tools#13176)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Larson <[email protected]>

Author: 4 people

azure-pipelines.yml

@@ -114,7 +114,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" pyvista scikit-learn python-picard qtpy nibabel sphinx-gallery "PySide6!=6.8.0,!=6.8.0.1,!=6.8.1.1,!=6.9.1" pandas neo pymatreader antio defusedxml
+              python -m pip install --progress-bar off "mne-qt-browser[opengl] @ git+https://github.com/mne-tools/mne-qt-browser.git" pyvista scikit-learn python-picard qtpy nibabel sphinx-gallery "PySide6!=6.8.0,!=6.8.0.1,!=6.8.1.1,!=6.9.1" pandas neo pymatreader antio defusedxml curryreader
               python -m pip uninstall -yq mne
               python -m pip install --progress-bar off --upgrade -e . --group=test
             displayName: 'Install dependencies with pip'

doc/_includes/dig_formats.rst

@@ -22,21 +22,23 @@ function for more info on reading specific file types.
 .. cssclass:: table-bordered
 .. rst-class:: midvalign
 
-=================  ================  ==============================================
-Vendor             Extension(s)      MNE-Python function
-=================  ================  ==============================================
-Neuromag           .fif              :func:`mne.channels.read_dig_fif`
+=====================  ================  ==============================================
+Vendor                 Extension(s)      MNE-Python function
+=====================  ================  ==============================================
+Neuromag               .fif              :func:`mne.channels.read_dig_fif`
 
-Polhemus ISOTRAK   .hsp, .elp, .eeg  :func:`mne.channels.read_dig_polhemus_isotrak`
+Polhemus ISOTRAK       .hsp, .elp, .eeg  :func:`mne.channels.read_dig_polhemus_isotrak`
 
-EGI                .xml              :func:`mne.channels.read_dig_egi`
+EGI                    .xml              :func:`mne.channels.read_dig_egi`
 
-MNE-C              .hpts             :func:`mne.channels.read_dig_hpts`
+MNE-C                  .hpts             :func:`mne.channels.read_dig_hpts`
 
-Brain Products     .bvct             :func:`mne.channels.read_dig_captrak`
+Brain Products         .bvct             :func:`mne.channels.read_dig_captrak`
 
-Compumedics        .dat              :func:`mne.channels.read_dig_dat`
-=================  ================  ==============================================
+Compumedics            .dat, .cdt        :func:`mne.channels.read_dig_curry`
+
+Compumedics (legacy)   .dat              :func:`mne.channels.read_dig_dat`
+=====================  ================  ==============================================
 
 To load Polhemus FastSCAN files you can use
 :func:`montage <mne.channels.read_polhemus_fastscan>`.

doc/api/preprocessing.rst

@@ -42,6 +42,7 @@ Projections:
    read_dig_polhemus_isotrak
    read_dig_captrak
    read_dig_dat
+   read_dig_curry
    read_dig_egi
    read_dig_fif
    read_dig_hpts

doc/changes/dev/13176.dependency.rst

@@ -0,0 +1 @@
+New reader for Neuroscan Curry files, using the curry-python-reader module, by `Dominik Welke`_.

doc/changes/dev/13176.newfeature.rst

@@ -0,0 +1 @@
+Read impedances and montage from Neuroscan Curry files, by `Dominik Welke`_.

environment.yml

@@ -5,6 +5,7 @@ channels:
 dependencies:
   - python >=3.10
   - antio >=0.5.0
+  - curryreader >=0.1.2
   - darkdetect
   - decorator
   - defusedxml

mne/annotations.py

@@ -1415,6 +1415,8 @@ def read_annotations(
         ".csv": _read_annotations_csv,
         ".cnt": _read_annotations_cnt,
         ".ds": _read_annotations_ctf,
+        ".dat": _read_annotations_curry,
+        ".cdt": _read_annotations_curry,
         ".cef": _read_annotations_curry,
         ".set": _read_annotations_eeglab,
         ".edf": _read_annotations_edf,
@@ -1427,6 +1429,8 @@ def read_annotations(
     kwargs = {
         ".vmrk": {"sfreq": sfreq, "ignore_marker_types": ignore_marker_types},
         ".amrk": {"sfreq": sfreq, "ignore_marker_types": ignore_marker_types},
+        ".dat": {"sfreq": sfreq},
+        ".cdt": {"sfreq": sfreq},
         ".cef": {"sfreq": sfreq},
         ".set": {"uint16_codec": uint16_codec},
         ".edf": {"encoding": encoding},

mne/channels/__init__.pyi

@@ -22,6 +22,7 @@ __all__ = [
     "read_ch_adjacency",
     "read_custom_montage",
     "read_dig_captrak",
+    "read_dig_curry",
     "read_dig_dat",
     "read_dig_egi",
     "read_dig_fif",
@@ -67,6 +68,7 @@ from .montage import (
     make_standard_montage,
     read_custom_montage,
     read_dig_captrak,
+    read_dig_curry,
     read_dig_dat,
     read_dig_egi,
     read_dig_fif,

mne/channels/_dig_montage_utils.py

@@ -2,6 +2,8 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
+import re
+
 import numpy as np
 
 from ..utils import Bunch, _check_fname, _soft_import, warn
@@ -94,3 +96,46 @@ def _parse_brainvision_dig_montage(fname, scale):
         ch_pos=dig_ch_pos,
         coord_frame="unknown",
     )
+
+
+def _read_dig_montage_curry(ch_names, ch_types, ch_pos, landmarks, landmarkslabels):
+    # scale ch_pos to m?!
+    ch_pos /= 1000.0
+    landmarks /= 1000.0
+    # channel locations
+    # what about misc without pos? can they mess things up if unordered?
+    assert len(ch_pos) >= (ch_types.count("mag") + ch_types.count("eeg"))
+    assert len(ch_pos) == (ch_types.count("mag") + ch_types.count("eeg"))
+    ch_pos_eeg = {
+        ch_names[i]: ch_pos[i, :3] for i, t in enumerate(ch_types) if t == "eeg"
+    }
+    # landmarks and headshape
+    landmark_dict = dict(zip(landmarkslabels, landmarks))
+    for k in ["Nas", "RPA", "LPA"]:
+        if k not in landmark_dict.keys():
+            landmark_dict[k] = None
+    if len(landmarkslabels) > 0:
+        hpi_pos = landmarks[
+            [i for i, n in enumerate(landmarkslabels) if re.match("HPI[1-99]", n)], :
+        ]
+    else:
+        hpi_pos = None
+    if len(landmarkslabels) > 0:
+        hsp_pos = landmarks[
+            [i for i, n in enumerate(landmarkslabels) if re.match("H[1-99]", n)], :
+        ]
+    else:
+        hsp_pos = None
+    # compile dig montage positions for eeg
+    if len(ch_pos_eeg) > 0:
+        return dict(
+            ch_pos=ch_pos_eeg,
+            nasion=landmark_dict["Nas"],
+            lpa=landmark_dict["LPA"],
+            rpa=landmark_dict["RPA"],
+            hsp=hsp_pos,
+            hpi=hpi_pos,
+            coord_frame="unknown",
+        )
+    else:  # not recorded?
+        raise ValueError("No eeg sensor locations found in header file.")

mne/channels/montage.py

@@ -49,12 +49,17 @@
     check_fname,
     copy_function_doc_to_method_doc,
     fill_doc,
+    legacy,
     verbose,
     warn,
 )
 from ..utils.docs import docdict
 from ..viz import plot_montage
-from ._dig_montage_utils import _parse_brainvision_dig_montage, _read_dig_montage_egi
+from ._dig_montage_utils import (
+    _parse_brainvision_dig_montage,
+    _read_dig_montage_curry,
+    _read_dig_montage_egi,
+)
 
 
 @dataclass
@@ -322,7 +327,6 @@ class DigMontage:
     See Also
     --------
     read_dig_captrak
-    read_dig_dat
     read_dig_egi
     read_dig_fif
     read_dig_hpts
@@ -757,6 +761,7 @@ def transform_to_head(montage):
     return montage
 
 
+@legacy(alt="read_dig_curry()")
 def read_dig_dat(fname):
     r"""Read electrode positions from a ``*.dat`` file.
 
@@ -779,7 +784,7 @@ def read_dig_dat(fname):
     See Also
     --------
     read_dig_captrak
-    read_dig_dat
+    read_dig_curry
     read_dig_egi
     read_dig_fif
     read_dig_hpts
@@ -845,9 +850,9 @@ def read_dig_fif(fname, *, verbose=None):
     See Also
     --------
     DigMontage
-    read_dig_dat
     read_dig_egi
     read_dig_captrak
+    read_dig_curry
     read_dig_polhemus_isotrak
     read_dig_hpts
     read_dig_localite
@@ -898,7 +903,7 @@ def read_dig_hpts(fname, unit="mm"):
     --------
     DigMontage
     read_dig_captrak
-    read_dig_dat
+    read_dig_curry
     read_dig_egi
     read_dig_fif
     read_dig_localite
@@ -991,7 +996,7 @@ def read_dig_egi(fname):
     --------
     DigMontage
     read_dig_captrak
-    read_dig_dat
+    read_dig_curry
     read_dig_fif
     read_dig_hpts
     read_dig_localite
@@ -1023,7 +1028,7 @@ def read_dig_captrak(fname):
     See Also
     --------
     DigMontage
-    read_dig_dat
+    read_dig_curry
     read_dig_egi
     read_dig_fif
     read_dig_hpts
@@ -1037,6 +1042,51 @@ def read_dig_captrak(fname):
     return make_dig_montage(**data)
 
 
+def read_dig_curry(fname):
+    """Read electrode locations from Neuroscan Curry files.
+
+    Parameters
+    ----------
+    fname : path-like
+        A valid Curry file.
+
+    Returns
+    -------
+    montage : instance of DigMontage | None
+        The montage.
+
+    See Also
+    --------
+    DigMontage
+    read_dig_captrak
+    read_dig_egi
+    read_dig_fif
+    read_dig_hpts
+    read_dig_localite
+    read_dig_polhemus_isotrak
+    make_dig_montage
+
+    Notes
+    -----
+    .. versionadded:: 1.11
+    """
+    from ..io.curry.curry import (
+        _check_curry_filename,
+        _extract_curry_info,
+    )
+
+    # TODO - REVIEW NEEDED
+    fname = _check_curry_filename(fname)
+    (_, _, ch_names, ch_types, ch_pos, landmarks, landmarkslabels, _, _, _, _, _, _) = (
+        _extract_curry_info(fname)
+    )
+    data = _read_dig_montage_curry(
+        ch_names, ch_types, ch_pos, landmarks, landmarkslabels
+    )
+    mont = make_dig_montage(**data) if data else None
+    return mont
+
+
 def read_dig_localite(fname, nasion=None, lpa=None, rpa=None):
     """Read Localite .csv file.
 
@@ -1060,7 +1110,7 @@ def read_dig_localite(fname, nasion=None, lpa=None, rpa=None):
     --------
     DigMontage
     read_dig_captrak
-    read_dig_dat
+    read_dig_curry
     read_dig_egi
     read_dig_fif
     read_dig_hpts
@@ -1461,7 +1511,7 @@ def read_dig_polhemus_isotrak(fname, ch_names=None, unit="m"):
     make_dig_montage
     read_polhemus_fastscan
     read_dig_captrak
-    read_dig_dat
+    read_dig_curry
     read_dig_egi
     read_dig_fif
     read_dig_localite
@@ -1821,8 +1871,8 @@ def make_standard_montage(kind, head_size="auto"):
     Notes
     -----
     Individualized (digitized) electrode positions should be read in using
-    :func:`read_dig_captrak`, :func:`read_dig_dat`, :func:`read_dig_egi`,
-    :func:`read_dig_fif`, :func:`read_dig_polhemus_isotrak`,
+    :func:`read_dig_captrak`, :func:`read_dig_curry`,
+    :func:`read_dig_egi`, :func:`read_dig_fif`, :func:`read_dig_polhemus_isotrak`,
     :func:`read_dig_hpts`, or manually made with :func:`make_dig_montage`.
 
     .. versionadded:: 0.19.0