Repository: mne-tools/mne-python

Issue:
read_dig_captrack should be renamed: CapTrak (k, not ck)
The function [mne.channels.read_dig_captrack](https://mne.tools/stable/generated/mne.channels.read_dig_captrack.html#mne.channels.read_dig_captrack) is for reading Brain Products electrode digitization data in the `bvct` format (=**B**rain**V**ision **C**ap**T**rak).

Apparently we had a typo at some point and now our function reads "captra**ck**" instead of "captra**k**".

I don't know why Brain Products decided to name their device [CapTrak](https://pressrelease.brainproducts.com/captrak/) instead of CapTrack ... but I think we should rename our function to fit the actual device/system that it supports.


Discussion:
+1 with deprecation cycle

>


Resolving patch:
diff --git a/mne/channels/__init__.py b/mne/channels/__init__.py
--- a/mne/channels/__init__.py
+++ b/mne/channels/__init__.py
@@ -8,7 +8,8 @@
                      find_layout, generate_2d_layout)
 from .montage import (DigMontage,
                       get_builtin_montages, make_dig_montage, read_dig_dat,
-                      read_dig_egi, read_dig_captrack, read_dig_fif,
+                      read_dig_egi, read_dig_captrak, read_dig_fif,
+                      read_dig_captrack,  # XXX: Remove in 0.22
                       read_dig_polhemus_isotrak, read_polhemus_fastscan,
                       compute_dev_head_t, make_standard_montage,
                       read_custom_montage, read_dig_hpts,
@@ -26,7 +27,7 @@
     'make_standard_montage',
 
     # Readers
-    'read_ch_connectivity', 'read_dig_captrack', 'read_dig_dat',
+    'read_ch_connectivity', 'read_dig_captrak', 'read_dig_dat',
     'read_dig_egi', 'read_dig_fif', 'read_dig_montage',
     'read_dig_polhemus_isotrak', 'read_layout', 'read_montage',
     'read_polhemus_fastscan', 'read_custom_montage', 'read_dig_hpts',
diff --git a/mne/channels/montage.py b/mne/channels/montage.py
--- a/mne/channels/montage.py
+++ b/mne/channels/montage.py
@@ -33,7 +33,7 @@
 from ..io.constants import FIFF
 from ..utils import (warn, copy_function_doc_to_method_doc, _pl,
                      _check_option, _validate_type, _check_fname,
-                     fill_doc)
+                     fill_doc, deprecated)
 
 from ._dig_montage_utils import _read_dig_montage_egi
 from ._dig_montage_utils import _parse_brainvision_dig_montage
@@ -109,7 +109,7 @@ def make_dig_montage(ch_pos=None, nasion=None, lpa=None, rpa=None,
     See Also
     --------
     DigMontage
-    read_dig_captrack
+    read_dig_captrak
     read_dig_egi
     read_dig_fif
     read_dig_polhemus_isotrak
@@ -144,7 +144,7 @@ class DigMontage(object):
 
     See Also
     --------
-    read_dig_captrack
+    read_dig_captrak
     read_dig_dat
     read_dig_egi
     read_dig_fif
@@ -342,7 +342,7 @@ def read_dig_dat(fname):
 
     See Also
     --------
-    read_dig_captrack
+    read_dig_captrak
     read_dig_dat
     read_dig_egi
     read_dig_fif
@@ -407,7 +407,7 @@ def read_dig_fif(fname):
     DigMontage
     read_dig_dat
     read_dig_egi
-    read_dig_captrack
+    read_dig_captrak
     read_dig_polhemus_isotrak
     read_dig_hpts
     make_dig_montage
@@ -445,7 +445,7 @@ def read_dig_hpts(fname, unit='mm'):
     See Also
     --------
     DigMontage
-    read_dig_captrack
+    read_dig_captrak
     read_dig_dat
     read_dig_egi
     read_dig_fif
@@ -536,7 +536,7 @@ def read_dig_egi(fname):
     See Also
     --------
     DigMontage
-    read_dig_captrack
+    read_dig_captrak
     read_dig_dat
     read_dig_fif
     read_dig_hpts
@@ -559,7 +559,7 @@ def read_dig_egi(fname):
     return make_dig_montage(**data)
 
 
-def read_dig_captrack(fname):
+def read_dig_captrak(fname):
     """Read electrode locations from CapTrak Brain Products system.
 
     Parameters
@@ -589,6 +589,36 @@ def read_dig_captrack(fname):
     return make_dig_montage(**data)
 
 
+@deprecated('read_dig_captrack is deprecated and will be removed in 0.22; '
+            'please use read_dig_captrak instead '
+            '(note the spelling correction: captraCK -> captraK).')
+def read_dig_captrack(fname):
+    """Read electrode locations from CapTrak Brain Products system.
+
+    Parameters
+    ----------
+    fname : path-like
+        BrainVision CapTrak coordinates file from which to read EEG electrode
+        locations. This is typically in XML format with the .bvct extension.
+
+    Returns
+    -------
+    montage : instance of DigMontage
+        The montage.
+
+    See Also
+    --------
+    DigMontage
+    read_dig_dat
+    read_dig_egi
+    read_dig_fif
+    read_dig_hpts
+    read_dig_polhemus_isotrak
+    make_dig_montage
+    """
+    return read_dig_captrak(fname)
+
+
 def _get_montage_in_head(montage):
     coords = set([d['coord_frame'] for d in montage.dig])
     if len(coords) == 1 and coords.pop() == FIFF.FIFFV_COORD_HEAD:
@@ -793,7 +823,7 @@ def read_dig_polhemus_isotrak(fname, ch_names=None, unit='m'):
     DigMontage
     make_dig_montage
     read_polhemus_fastscan
-    read_dig_captrack
+    read_dig_captrak
     read_dig_dat
     read_dig_egi
     read_dig_fif
@@ -1098,7 +1128,7 @@ def make_standard_montage(kind, head_size=HEAD_SIZE_DEFAULT):
     Notes
     -----
     Individualized (digitized) electrode positions should be read in using
-    :func:`read_dig_captrack`, :func:`read_dig_dat`, :func:`read_dig_egi`,
+    :func:`read_dig_captrak`, :func:`read_dig_dat`, :func:`read_dig_egi`,
     :func:`read_dig_fif`, :func:`read_dig_polhemus_isotrak`,
     :func:`read_dig_hpts` or made with :func:`make_dig_montage`.
 


Test patch:
diff --git a/mne/channels/tests/test_montage.py b/mne/channels/tests/test_montage.py
--- a/mne/channels/tests/test_montage.py
+++ b/mne/channels/tests/test_montage.py
@@ -19,7 +19,8 @@
 from mne import __file__ as _mne_file, create_info, read_evokeds
 from mne.utils._testing import _dig_sort_key
 from mne.channels import (get_builtin_montages, DigMontage, read_dig_dat,
-                          read_dig_egi, read_dig_captrack, read_dig_fif,
+                          read_dig_egi, read_dig_captrak, read_dig_fif,
+                          read_dig_captrack,  # XXX: remove with 0.22
                           make_standard_montage, read_custom_montage,
                           compute_dev_head_t, make_dig_montage,
                           read_dig_polhemus_isotrak,
@@ -836,8 +837,8 @@ def _pop_montage(dig_montage, ch_name):
 
 
 @testing.requires_testing_data
-def test_read_dig_captrack(tmpdir):
-    """Test reading a captrack montage file."""
+def test_read_dig_captrak(tmpdir):
+    """Test reading a captrak montage file."""
     EXPECTED_CH_NAMES_OLD = [
         'AF3', 'AF4', 'AF7', 'AF8', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'CP1',
         'CP2', 'CP3', 'CP4', 'CP5', 'CP6', 'CPz', 'Cz', 'F1', 'F2', 'F3', 'F4',
@@ -857,10 +858,18 @@ def test_read_dig_captrack(tmpdir):
         'C6', 'FT8'
     ]
     assert set(EXPECTED_CH_NAMES) == set(EXPECTED_CH_NAMES_OLD)
-    montage = read_dig_captrack(
+    montage = read_dig_captrak(
         fname=op.join(data_path, 'montage', 'captrak_coords.bvct')
     )
 
+    # XXX: remove with 0.22 once captrCK is deprecated
+    with pytest.warns(DeprecationWarning,
+                      match='read_dig_captrack is deprecated'):
+        montage2 = read_dig_captrack(
+            fname=op.join(data_path, 'montage', 'captrak_coords.bvct')
+        )
+        assert repr(montage) == repr(montage2)
+
     assert montage.ch_names == EXPECTED_CH_NAMES
     assert repr(montage) == (
         '<DigMontage | '