Deprecate write_raw_bids()'s events_data parameter in favor of "events"

For more consistency with MNE-Python.

This is WIP.

WDYT?

mne_bids/commands/mne_bids_raw_to_bids.py

@@ -36,7 +36,9 @@ def run():
                       help='run number for this dataset')
     parser.add_option('--acq', dest='acq',
                       help='acquisition parameter for this dataset')
-    parser.add_option('--events_data', dest='events_data',
+    parser.add_option('--events_data', dest='events',
+                      help='Deprecated. Pass --events instead.')
+    parser.add_option('--events', dest='events',
                       help='events file (events.tsv)')
     parser.add_option('--event_id', dest='event_id',
                       help='event id dict', metavar='eid')
@@ -81,7 +83,7 @@ def run():
         line_freq = None if opt.line_freq == "None" else opt.line_freq
         raw.info['line_freq'] = line_freq
     write_raw_bids(raw, bids_path, event_id=opt.event_id,
-                   events_data=opt.events_data, overwrite=opt.overwrite,
+                   events=opt.events, overwrite=opt.overwrite,
                    verbose=True)
 
 

mne_bids/inspect.py

@@ -239,7 +239,7 @@ def _save_annotations(*, annotations, bids_path):
     raw = read_raw_bids(bids_path=bids_path, extra_params=extra_params,
                         verbose='warning')
     raw.set_annotations(annotations)
-    events, durs, descrs = _read_events(events_data=None, event_id=None,
+    events, durs, descrs = _read_events(events=None, event_id=None,
                                         bids_path=bids_path, raw=raw)
 
     # Write sidecar – or remove it if no events are left.

mne_bids/read.py

@@ -74,12 +74,12 @@ def _read_raw(raw_path, electrode=None, hsp=None, hpi=None,
     return raw
 
 
-def _read_events(events_data, event_id, raw, bids_path=None):
+def _read_events(events, event_id, raw, bids_path=None):
     """Retrieve events (for use in *_events.tsv) from FIFF/array & Annotations.
 
     Parameters
     ----------
-    events_data : path-like | np.ndarray | None
+    events : path-like | np.ndarray | None
         If a string, a path to an events file. If an array, an MNE events array
         (shape n_events, 3). If None, events will be generated from
         ``raw.annotations``.
@@ -107,19 +107,19 @@ def _read_events(events_data, event_id, raw, bids_path=None):
         the values to the event IDs.
 
     """
-    # get events from events_data
-    if isinstance(events_data, np.ndarray):
-        if events_data.ndim != 2:
+    # retrieve events
+    if isinstance(events, np.ndarray):
+        if events.ndim != 2:
             raise ValueError('Events must have two dimensions, '
-                             f'found {events_data.ndim}')
-        if events_data.shape[1] != 3:
+                             f'found {events.ndim}')
+        if events.shape[1] != 3:
             raise ValueError('Events must have second dimension of length 3, '
-                             f'found {events_data.shape[1]}')
-        events = events_data
-    elif events_data is None:
+                             f'found {events.shape[1]}')
+        events = events
+    elif events is None:
         events = np.empty(shape=(0, 3), dtype=int)
     else:
-        events = read_events(events_data).astype(int)
+        events = read_events(events).astype(int)
 
     if events.size > 0:
         # Only keep events for which we have an ID <> description mapping.
@@ -129,7 +129,7 @@ def _read_events(events_data, event_id, raw, bids_path=None):
                 f'No description was specified for the following event(s): '
                 f'{", ".join([str(x) for x in sorted(ids_without_desc)])}. '
                 f'Please add them to the event_id dictionary, or drop them '
-                f'from the events_data array.'
+                f'from the events array.'
             )
         del ids_without_desc
         mask = [e in list(event_id.values()) for e in events[:, 2]]
@@ -175,7 +175,7 @@ def _read_events(events_data, event_id, raw, bids_path=None):
         )
     ):
         warn('No events found or provided. Please add annotations to the raw '
-             'data, or provide the events_data and event_id parameters. For '
+             'data, or provide the events and event_id parameters. For '
              'resting state data, BIDS recommends naming the task using '
              'labels beginning with "rest".')
 

mne_bids/tests/data/tiny_bids/code/make_tiny_bids_dataset.py

@@ -46,7 +46,7 @@
 # %%
 
 write_raw_bids(
-    raw, bids_path, events_data=events, event_id=event_id, overwrite=True
+    raw, bids_path, events=events, event_id=event_id, overwrite=True
 )
 
 # %%

mne_bids/tests/test_inspect.py

@@ -47,7 +47,7 @@ def setup_bids_test_dir(bids_root):
     events = events[events[:, 2] != 0]
 
     bids_path = _bids_path.copy().update(root=bids_root)
-    write_raw_bids(raw, bids_path=bids_path, events_data=events,
+    write_raw_bids(raw, bids_path=bids_path, events=events,
                    event_id=event_id, overwrite=True)
     write_meg_calibration(cal_fname, bids_path=bids_path)
     write_meg_crosstalk(crosstalk_fname, bids_path=bids_path)

mne_bids/tests/test_path.py

@@ -64,7 +64,7 @@ def return_bids_test_dir(tmp_path_factory):
     # Write multiple runs for test_purposes
     for run_idx in [run, '02']:
         name = bids_path.copy().update(run=run_idx)
-        write_raw_bids(raw, name, events_data=events,
+        write_raw_bids(raw, name, events=events,
                        event_id=event_id, overwrite=True)
 
     write_meg_calibration(cal_fname, bids_path=bids_path)

mne_bids/tests/test_read.py

@@ -229,7 +229,7 @@ def test_get_head_mri_trans(tmp_path):
     bids_path = _bids_path.copy().update(
         root=tmp_path, datatype='meg', suffix='meg'
     )
-    write_raw_bids(raw, bids_path, events_data=events, event_id=event_id,
+    write_raw_bids(raw, bids_path, events=events, event_id=event_id,
                    overwrite=False)
 
     # We cannot recover trans if no MRI has yet been written
@@ -293,7 +293,7 @@ def test_get_head_mri_trans(tmp_path):
     # test we are permissive for different casings of landmark names in the
     # sidecar, and also accept "nasion" instead of just "NAS"
     raw = _read_raw_fif(raw_fname)
-    write_raw_bids(raw, bids_path, events_data=events, event_id=event_id,
+    write_raw_bids(raw, bids_path, events=events, event_id=event_id,
                    overwrite=True)  # overwrite with new acq
     t1w_bids_path = write_anat(
         t1w_mgh, bids_path=t1w_bids_path, landmarks=landmarks, overwrite=True

mne_bids/tests/test_update.py

@@ -58,7 +58,7 @@ def _get_bids_test_dir(tmp_path_factory):
     # Write multiple runs for test_purposes
     for run_idx in [run, '02']:
         name = bids_path.copy().update(run=run_idx)
-        write_raw_bids(raw, name, events_data=events,
+        write_raw_bids(raw, name, events=events,
                        event_id=event_id, overwrite=True)
 
     write_meg_calibration(cal_fname, bids_path=bids_path)