[pull] main from mne-tools:main

doc/changes/dev/13903.apichange.rst

@@ -0,0 +1 @@
+Rename ``standard_1005`` and ``standard_1020`` montages to ``colin27_1005`` and ``colin27_1020``, respectively. If you used ``standard_1005`` or ``standard_1020``, either switch to the new names ``colin27_1005`` and ``colin27_1020`` or use the new spherical montages ``spherical_1005``, ``spherical_1010``, or ``spherical_1020``, which provide idealized template locations on a sphere (useful for plotting). By `Clemens Brunner`_.

doc/changes/dev/13903.newfeature.rst

@@ -0,0 +1 @@
+Add idealized spherical 10–05, 10–10, and 10–20 montages (``spherical_1005``, ``spherical_1010``, ``spherical_1020``), by `Clemens Brunner`_.

examples/decoding/decoding_csp_eeg.py

@@ -48,7 +48,7 @@
 raw_fnames = eegbci.load_data(subjects, runs)
 raw = concatenate_raws([read_raw_edf(f, preload=True) for f in raw_fnames])
 eegbci.standardize(raw)  # set channel names
-montage = make_standard_montage("standard_1005")
+montage = make_standard_montage("spherical_1005")
 raw.set_montage(montage)
 raw.annotations.rename(dict(T1="hands", T2="feet"))  # as documented on PhysioNet
 raw.set_eeg_reference(projection=True)

examples/io/read_impedances.py

@@ -46,7 +46,7 @@
 # We can visualize the impedances on a topographic map; below we show a topography of
 # impedances before and after the recording for the EEG channels only.
 
-raw.pick("eeg").set_montage("standard_1020")
+raw.pick("eeg").set_montage("colin27_1020")
 impedances = [{ch: imp[ch] for ch in raw.ch_names} for imp in impedances]
 
 f, ax = plt.subplots(1, 2, layout="constrained", figsize=(10, 5))

examples/preprocessing/eeg_bridging.py

@@ -60,7 +60,7 @@
 #           bridging so using the last segment of the data will
 #           give the most conservative estimate.
 
-montage = mne.channels.make_standard_montage("standard_1005")
+montage = mne.channels.make_standard_montage("spherical_1005")
 ed_data = dict()  # electrical distance/bridging data
 raw_data = dict()  # store infos for electrode positions
 for sub in range(1, 11):

examples/preprocessing/muscle_ica.py

@@ -98,7 +98,7 @@
         mne.datasets.eegbci.load_data(subjects=sub, runs=(1,))[0], preload=True
     )
     mne.datasets.eegbci.standardize(raw)  # set channel names
-    montage = mne.channels.make_standard_montage("standard_1005")
+    montage = mne.channels.make_standard_montage("spherical_1005")
     raw.set_montage(montage)
     raw.filter(l_freq=1.0, h_freq=None)
 

examples/preprocessing/plot_epoch_quality.py

@@ -32,7 +32,7 @@
 raw_fname = eegbci.load_data(subjects=3, runs=(3,))[0]
 raw = mne.io.read_raw(raw_fname, preload=True)
 eegbci.standardize(raw)
-montage = mne.channels.make_standard_montage("standard_1005")
+montage = mne.channels.make_standard_montage("spherical_1005")
 raw.set_montage(montage)
 
 events, event_id = mne.events_from_annotations(raw)

examples/visualization/roi_erpimage_by_rt.py

@@ -72,7 +72,7 @@
 }
 raw.rename_channels(mapping)
 raw.set_channel_types({"EOG1": "eog", "EOG2": "eog"})
-raw.set_montage("standard_1020")
+raw.set_montage("spherical_1005")
 
 events = mne.events_from_annotations(raw, event_id)[0]
 

mne/_fiff/tests/test_meas_info.py

@@ -1468,19 +1468,19 @@ def test_info_bad():
 
 def test_get_montage():
     """Test ContainsMixin.get_montage()."""
-    ch_names = make_standard_montage("standard_1020").ch_names
+    ch_names = make_standard_montage("spherical_1005").ch_names
     sfreq = 512
     data = np.zeros((len(ch_names), sfreq * 2))
     raw = RawArray(data, create_info(ch_names, sfreq, "eeg"))
-    raw.set_montage("standard_1020")
+    raw.set_montage("spherical_1005")
 
     assert len(raw.get_montage().ch_names) == len(ch_names)
     raw.info["bads"] = [ch_names[0]]
     assert len(raw.get_montage().ch_names) == len(ch_names)
 
     # test info
     raw = RawArray(data, create_info(ch_names, sfreq, "eeg"))
-    raw.set_montage("standard_1020")
+    raw.set_montage("spherical_1005")
 
     assert len(raw.info.get_montage().ch_names) == len(ch_names)
     raw.info["bads"] = [ch_names[0]]

mne/_fiff/tests/test_pick.py

@@ -730,7 +730,7 @@ def test_pick_types_csd():
         names, 256, ["eeg", "eeg", "eeg", "eeg", "mag", "mag", "misc", "csd"]
     )
     raw = RawArray(np.zeros((8, 512)), info1)
-    raw.set_montage(make_standard_montage("standard_1020"), verbose="error")
+    raw.set_montage(make_standard_montage("spherical_1005"), verbose="error")
     raw_csd = compute_current_source_density(raw, verbose="error")
 
     assert_array_equal(pick_types(info1, csd=True), [7])

mne/channels/_standard_montage_utils.py

@@ -20,10 +20,6 @@
 _str = "U100"
 
 
-# In standard_1020, T9=LPA, T10=RPA, Nasion is the same as Iz with a
-# sign-flipped Y value
-
-
 def _egi_256(head_size):
     fname = op.join(MONTAGE_PATH, "EGI_256.csd")
     montage = _read_csd(fname, head_size)
@@ -118,6 +114,37 @@ def _mgh_or_standard(basename, head_size, coord_frame="unknown"):
     )
 
 
+def _read_spherical_tsv(fname, head_size):
+    ch_names = []
+    pos = []
+    with open(fname) as f:
+        f.readline()  # skip header
+        for row in csv.reader(f, delimiter="\t"):
+            ch_name, x, y, z, *_ = row
+            ch_names.append(ch_name)
+            pos.append((x, y, z))
+    pos = np.array(pos, dtype=float)
+    ch_pos = _check_dupes_odict(ch_names, pos)
+
+    nasion = ch_pos.pop("NAS")
+    lpa = ch_pos.pop("LPA")
+    rpa = ch_pos.pop("RPA")
+
+    if head_size is not None:
+        scale = head_size / np.median(
+            np.linalg.norm(np.array(list(ch_pos.values())), axis=1)
+        )
+        for value in ch_pos.values():
+            value *= scale
+        nasion = nasion * scale
+        lpa = lpa * scale
+        rpa = rpa * scale
+
+    return make_dig_montage(
+        ch_pos=ch_pos, coord_frame="unknown", nasion=nasion, lpa=lpa, rpa=rpa
+    )
+
+
 standard_montage_look_up_table = {
     "EGI_256": _egi_256,
     "easycap-M1": partial(_easycap, basename="easycap-M1.txt"),
@@ -138,23 +165,23 @@ def _mgh_or_standard(basename, head_size, coord_frame="unknown"):
     "biosemi64": partial(_biosemi, basename="biosemi64.txt"),
     "mgh60": partial(_mgh_or_standard, basename="mgh60.elc", coord_frame="mri"),
     "mgh70": partial(_mgh_or_standard, basename="mgh70.elc", coord_frame="mri"),
-    "standard_1005": partial(
-        _mgh_or_standard, basename="standard_1005.elc", coord_frame="mri"
+    "colin27_1005": partial(
+        _mgh_or_standard, basename="colin27_1005.elc", coord_frame="mri"
     ),
-    "standard_1020": partial(
-        _mgh_or_standard, basename="standard_1020.elc", coord_frame="mri"
+    "colin27_1020": partial(
+        _mgh_or_standard, basename="colin27_1020.elc", coord_frame="mri"
     ),
-    "standard_alphabetic": partial(
-        _mgh_or_standard, basename="standard_alphabetic.elc", coord_frame="mri"
+    "colin27_alphabetic": partial(
+        _mgh_or_standard, basename="colin27_alphabetic.elc", coord_frame="mri"
     ),
-    "standard_postfixed": partial(
-        _mgh_or_standard, basename="standard_postfixed.elc", coord_frame="mri"
+    "colin27_postfixed": partial(
+        _mgh_or_standard, basename="colin27_postfixed.elc", coord_frame="mri"
     ),
-    "standard_prefixed": partial(
-        _mgh_or_standard, basename="standard_prefixed.elc", coord_frame="mri"
+    "colin27_prefixed": partial(
+        _mgh_or_standard, basename="colin27_prefixed.elc", coord_frame="mri"
     ),
-    "standard_primed": partial(
-        _mgh_or_standard, basename="standard_primed.elc", coord_frame="mri"
+    "colin27_primed": partial(
+        _mgh_or_standard, basename="colin27_primed.elc", coord_frame="mri"
     ),
     "artinis-octamon": partial(
         _mgh_or_standard, coord_frame="mri", basename="artinis-octamon.elc"
@@ -165,6 +192,15 @@ def _mgh_or_standard(basename, head_size, coord_frame="unknown"):
     "brainproducts-RNP-BA-128": partial(
         _easycap, basename="brainproducts-RNP-BA-128.txt"
     ),
+    "spherical_1005": partial(
+        _read_spherical_tsv, op.join(MONTAGE_PATH, "spherical_1005.tsv")
+    ),
+    "spherical_1010": partial(
+        _read_spherical_tsv, op.join(MONTAGE_PATH, "spherical_1010.tsv")
+    ),
+    "spherical_1020": partial(
+        _read_spherical_tsv, op.join(MONTAGE_PATH, "spherical_1020.tsv")
+    ),
 }
 
 

mne/channels/data/montages/README.md

@@ -0,0 +1,18 @@
+The idealized spherical montages (`spherical_1005`, `spherical_1010`, `spherical_1020`) are taken from the [eeg-positions](https://github.com/sappelhoff/eeg_positions) package, which provides these pre-computed locations as TSV files:
+
+- https://github.com/sappelhoff/eeg_positions/blob/main/data/Nz-T10-Iz-T9/standard_1005_3D.tsv
+- https://github.com/sappelhoff/eeg_positions/blob/main/data/Nz-T10-Iz-T9/standard_1010_3D.tsv
+- https://github.com/sappelhoff/eeg_positions/blob/main/data/Nz-T10-Iz-T9/standard_1020_3D.tsv
+
+The `colin27_*` montages are also based on the 10–05 system, but the idealized locations were fit on the Colin27 head model (a high-resolution MRI scan of a single subject), similar to the description in [this tutorial](https://www.fieldtriptoolbox.org/tutorial/sensor/opm_helmet_design/).
+
+They are available in [FieldTrip](https://github.com/fieldtrip/fieldtrip):
+
+- https://github.com/fieldtrip/fieldtrip/blob/release/template/electrode/standard_1020.elc
+- https://github.com/fieldtrip/fieldtrip/blob/release/template/electrode/standard_1005.elc
+- https://github.com/fieldtrip/fieldtrip/blob/release/template/electrode/standard_alphabetic.elc
+- https://github.com/fieldtrip/fieldtrip/blob/release/template/electrode/standard_postfixed.elc
+- https://github.com/fieldtrip/fieldtrip/blob/release/template/electrode/standard_prefixed.elc
+- https://github.com/fieldtrip/fieldtrip/blob/release/template/electrode/standard_primed.elc
+
+The two `easycap-M1.txt` and `easycap-M10.txt` montages as well as the `GSN-HydroCel-*` montages are also taken from FieldTrip (https://github.com/fieldtrip/fieldtrip/tree/release/template/electrode).