mne-tools · larsoner · Apr 15, 2024 · Jan 30, 2024 · Jan 30, 2024 · Jan 31, 2024
@@ -0,0 +1 @@
+Add ability to remove bad marker coils in :func:`mne.io.read_raw_kit`, by `Judy D Zhu`_.
diff --git a/mne/io/kit/coreg.py b/mne/io/kit/coreg.py
@@ -114,7 +114,7 @@ def read_sns(fname):
     return locs
 
 
-def _set_dig_kit(mrk, elp, hsp, eeg):
+def _set_dig_kit(mrk, elp, hsp, eeg, *, bad_coils=()):
     """Add landmark points and head shape data to the KIT instance.
 
     Digitizer data (elp and hsp) are represented in [mm] in the Polhemus
@@ -133,6 +133,9 @@ def _set_dig_kit(mrk, elp, hsp, eeg):
         Digitizer head shape points, or path to head shape file. If more
         than 10`000 points are in the head shape, they are automatically
         decimated.
+    bad_coils : list
+        Indices of bad marker coils (up to two). Bad coils will be excluded
+        when computing the device-head transformation.
     eeg : dict
         Ordered dict of EEG dig points.
 
@@ -167,10 +170,18 @@ def _set_dig_kit(mrk, elp, hsp, eeg):
                 f"{elp_points.shape}."
             )
         elp = elp_points
-    elif len(elp) not in (6, 7, 8):
+        if len(bad_coils) > 0:
+            elp = np.delete(elp, np.array(bad_coils) + 3, 0)
+    # check we have at least 3 marker coils (whether read from file or
+    # passed in directly)
+    if len(elp) not in (6, 7, 8):
         raise ValueError(f"ELP should contain 6 ~ 8 points; got shape {elp.shape}.")
     if isinstance(mrk, (str, Path, PathLike)):
         mrk = read_mrk(mrk)
+        if len(bad_coils) > 0:
+            mrk = np.delete(mrk, bad_coils, 0)
+    if len(mrk) not in (3, 4, 5):
+        raise ValueError(f"MRK should contain 3 ~ 5 points; got shape {mrk.shape}.")
 
     mrk = apply_trans(als_ras_trans, mrk)
 

diff --git a/mne/io/kit/kit.py b/mne/io/kit/kit.py
@@ -43,7 +43,7 @@
 INT32 = "<i4"
 
 
-def _call_digitization(info, mrk, elp, hsp, kit_info):
+def _call_digitization(info, mrk, elp, hsp, kit_info, *, bad_coils=()):
     # Use values from kit_info only if all others are None
     if mrk is None and elp is None and hsp is None:
         mrk = kit_info.get("mrk", None)
@@ -62,7 +62,11 @@ def _call_digitization(info, mrk, elp, hsp, kit_info):
     if mrk is not None and elp is not None and hsp is not None:
         with info._unlock():
             info["dig"], info["dev_head_t"], info["hpi_results"] = _set_dig_kit(
-                mrk, elp, hsp, kit_info["eeg_dig"]
+                mrk,
+                elp,
+                hsp,
+                kit_info["eeg_dig"],
+                bad_coils=bad_coils,
             )
     elif mrk is not None or elp is not None or hsp is not None:
         raise ValueError(
@@ -100,6 +104,7 @@ class RawKIT(BaseRaw):
         Force reading old data that is not officially supported. Alternatively,
         read and re-save the data with the KIT MEG Laboratory application.
     %(standardize_names)s
+    %(kit_badcoils)s
     %(verbose)s
 
     Notes
@@ -133,6 +138,8 @@ def __init__(
         stim_code="binary",
         allow_unknown_format=False,
         standardize_names=None,
+        *,
+        bad_coils=(),
         verbose=None,
     ):
         logger.info("Extracting SQD Parameters from %s..." % input_fname)
@@ -160,7 +167,12 @@ def __init__(
             verbose=verbose,
         )
         self.info = _call_digitization(
-            info=self.info, mrk=mrk, elp=elp, hsp=hsp, kit_info=kit_info
+            info=self.info,
+            mrk=mrk,
+            elp=elp,
+            hsp=hsp,
+            kit_info=kit_info,
+            bad_coils=bad_coils,
         )
         logger.info("Ready.")
 
@@ -911,6 +923,8 @@ def read_raw_kit(
     stim_code="binary",
     allow_unknown_format=False,
     standardize_names=False,
+    *,
+    bad_coils=(),
     verbose=None,
 ) -> RawKIT:
     r"""Reader function for Ricoh/KIT conversion to FIF.
@@ -931,6 +945,7 @@ def read_raw_kit(
         Force reading old data that is not officially supported. Alternatively,
         read and re-save the data with the KIT MEG Laboratory application.
     %(standardize_names)s
+    %(kit_badcoils)s
     %(verbose)s
 
     Returns
@@ -965,6 +980,7 @@ def read_raw_kit(
         stim_code=stim_code,
         allow_unknown_format=allow_unknown_format,
         standardize_names=standardize_names,
+        bad_coils=bad_coils,
         verbose=verbose,
     )
 

diff --git a/mne/utils/docs.py b/mne/utils/docs.py
@@ -2215,6 +2215,12 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
                  anonymized. Use with caution.
 """
 
+docdict["kit_badcoils"] = """
+bad_coils : array-like of int | None
+    Indices of (up to two) bad marker coils to be removed.
+    These marker coils must be present in the elp and mrk files.
+"""
+
 docdict["kit_elp"] = """
 elp : path-like | array of shape (8, 3) | None
     Digitizer points representing the location of the fiducials and the
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add ability to remove bad marker coils in :func:`mne.io.read_raw_kit`, by `Judy D Zhu`_.