[MRG] Allow electrodes.tsv to not fully match Raw object

.mailmap

@@ -25,4 +25,5 @@ Fu-Te Wong <[email protected]>
 Matt Sanderson <[email protected]>
 Robert Luke <[email protected]>
 Evgenii Kalenkovich <[email protected]>
-Eduard Ort <[email protected]>
+Eduard Ort <[email protected]>
+Eduard Ort <[email protected]> <[email protected]>

doc/whats_new.rst

@@ -34,7 +34,7 @@ Enhancements
 
 - Some datasets out in the real world have a non-standard ``stim_type`` instead of a ``trial_type`` column in ``*_events.tsv``. :func:`mne_bids.read_raw_bids` now makes use of this column, and emits a warning, encouraging users to rename it, by `Richard Höchenberger`_ (:gh:`680`)
 - When reading data where the same event name or trial type refers to different event or trigger values, we will now create a hierarchical event name in the form of ``trial_type/value``, e.g. ``stimulus/110``  by `Richard Höchenberger`_ (:gh:`688`)
-- When reading data via :func:`mne_bids.read_raw_bids`, the channel names specified in the BIDS ``*_channels.tsv`` files now always take precedence (and do not need to match) the channel names stored in the raw files anymore, by `Richard Höchenberger`_ (:gh:`691`)
+- When reading data via :func:`mne_bids.read_raw_bids`, the channel names specified in the BIDS ``*_channels.tsv`` and ``*_electrodes.tsv`` files now always take precedence (and do not need to match) the channel names stored in the raw files anymore, by `Adam Li`_ and `Richard Höchenberger`_ (:gh:`691`, :gh:`704`)
 
 API changes
 ^^^^^^^^^^^
@@ -58,7 +58,8 @@ Bug fixes
 - :func:`mne_bids.read_raw_bids` now ignores ``exclude`` parameters passed via ``extra_params``, by `Richard Höchenberger`_ (:gh:`703`)
 - :func:`mne_bids.write_raw_bids` now retains original event IDs in the ``value`` column of ``*_events.tsv``, by `Richard Höchenberger`_ (:gh:`708`)
 - Fix writing correct ``iEEGCoordinateSystemDescription``, by `Stefan Appelhoff`_ (:gh:`706`)
-- FIF files that were split due to filesize limitations (using the ``_split-<label>`` entity, are now all listed in ``scans.tsv``, as recommended by BIDS, by `Eduard Ort`_ (:gh:`710`)
+- FIF files that were split due to filesize limitations (using the ``_split-<label>`` entity), are now all listed in ``scans.tsv``, as recommended by BIDS, by `Eduard Ort`_ (:gh:`710`)
+
 
 :doc:`Find out what was new in previous releases <whats_new_previous_releases>`
 

examples/convert_ieeg_to_bids.py

@@ -83,10 +83,13 @@
     elec[:, ind] = list(map(float, electrode_tsv[axis]))
 
 ###############################################################################
-# Now we make a montage stating that the iEEG contacts are in MRI
-# coordinate system.
+# Now we make a montage stating that the iEEG contacts are in the MNI
+# coordinate system, which corresponds to the `fsaverage` subject in
+# FreeSurfer. For example, one can look at how mne-python deals with iEEG data
+# at `Working with SEEG
+# <https://mne.tools/stable/auto_tutorials/misc/plot_seeg.html>`_
 montage = mne.channels.make_dig_montage(ch_pos=dict(zip(ch_names, elec)),
-                                        coord_frame='mri')
+                                        coord_frame='mni_tal')
 print('Created %s channel positions' % len(ch_names))
 print(dict(zip(ch_names, elec)))
 

mne_bids/config.py

@@ -161,32 +161,42 @@
 
 # accepted BIDS formats, which may be subject to change
 # depending on the specification
-BIDS_IEEG_COORDINATE_FRAMES = ['acpc', 'pixels', 'other']
-BIDS_MEG_COORDINATE_FRAMES = ['ctf', 'elektaneuromag',
-                              '4dbti', 'kityokogawa',
-                              'chietiitab', 'other']
-BIDS_EEG_COORDINATE_FRAMES = ['captrak']
+BIDS_IEEG_COORDINATE_FRAMES = ['ACPC', 'Pixels', 'Other']
+BIDS_MEG_COORDINATE_FRAMES = ['CTF', 'ElektaNeuromag',
+                              '4DBti', 'KitYokogawa',
+                              'ChietiItab', 'Other']
+BIDS_EEG_COORDINATE_FRAMES = ['CapTrak']
 
 # accepted coordinate SI units
 BIDS_COORDINATE_UNITS = ['m', 'cm', 'mm']
 
-# mapping from BIDs coordinate frames -> MNE
+# mapping from supported BIDs coordinate frames -> MNE
 BIDS_TO_MNE_FRAMES = {
-    'ctf': 'ctf_head',
-    '4dbti': 'ctf_head',
-    'kityokogawa': 'ctf_head',
-    'elektaneuromag': 'head',
-    'chietiitab': 'head',
-    'captrak': 'head',
-    'acpc': 'ras',
-    'mni': 'mni_tal',
-    'fs': 'fs_tal',
-    'ras': 'ras',
-    'voxel': 'mri_voxels',
-    'mri': 'mri',
-    'unknown': 'unknown'
+    'CTF': 'ctf_head',
+    '4DBti': 'ctf_head',
+    'KitYokogawa': 'ctf_head',
+    'ElektaNeuromag': 'head',
+    'ChietiItab': 'head',
+    'CapTrak': 'head',
+    'ACPC': 'ras',  # XXX: there is no ACPC in mne-python and so this is a one-way mapping from BIDS -> MNE  # noqa
+    'fsaverage': 'mni_tal',  # XXX: note fsaverage and MNI305 are the same  # noqa
+    'MNI305': 'mni_tal',
+    'Other': 'unknown'
+}
+
+# mapping from supported MNE coordinate frames -> BIDS
+# XXX: note that there are a lot fewer MNE available coordinate
+# systems so the range of BIDS supported coordinate systems we
+# can write is limited.
+MNE_TO_BIDS_FRAMES = {
+    'ctf_head': 'CTF',
+    'head': 'CapTrak',
+    'mni_tal': 'fsaverage',
+    # 'fs_tal': 'fsaverage',  # XXX: not used
+    'unknown': 'Other',
+    'ras': 'Other',
+    'mri': 'Other'
 }
-MNE_TO_BIDS_FRAMES = {val: key for key, val in BIDS_TO_MNE_FRAMES.items()}
 
 # these coordinate frames in mne-python are related to scalp/meg
 # 'meg', 'ctf_head', 'ctf_meg', 'head', 'unknown'
@@ -206,7 +216,7 @@
 MNE_FRAME_TO_STR = {val: key for key, val in MNE_STR_TO_FRAME.items()}
 
 # see BIDS specification for description we copied over from each
-COORD_FRAME_DESCRIPTIONS = {
+BIDS_COORD_FRAME_DESCRIPTIONS = {
     'ctf': 'ALS orientation and the origin between the ears',
     'elektaneuromag': 'RAS orientation and the origin between the ears',
     '4dbti': 'ALS orientation and the origin between the ears',
@@ -221,18 +231,9 @@
         'This corresponds to a "RAS" orientation with the origin of the '
         'coordinate system approximately between the ears. '
         'See Appendix VIII in the BIDS specification.'),
-    'mri': 'Defined by Freesurfer, the MRI (surface RAS) origin is at the '
-           'center of a 256×256×256 1mm anisotropic volume '
-           '(may not be in the center of the head).',
-    'mri_voxel': 'Defined by Freesurfer, the MRI (surface RAS) origin '
-                 'is at the center of a 256×256×256 voxel anisotropic '
-                 'volume (may not be in the center of the head).',
-    'mni_tal': 'MNI template in Talairach coordinates',
-    'fs_tal': 'Freesurfer template in Talairach coordinates',
-    'ras': 'RAS means that the first dimension (X) points towards '
-           'the right hand side of the head, the second dimension (Y) '
-           'points towards the Anterior aspect of the head, and the '
-           'third dimension (Z) points towards the top of the head.',
+    'fsaverage': 'Defined by FreeSurfer, the MRI (surface RAS) origin is '
+                 'at the center of a 256×256×256 mm^3 anisotropic volume '
+                 '(may not be in the center of the head).',
 }
 
 REFERENCES = {'mne-bids':