MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/_modules/mne_bids/copyfiles.html b/dev/_modules/mne_bids/copyfiles.html index f25f2c7d5..eb47d28fe 100644 --- a/dev/_modules/mne_bids/copyfiles.html +++ b/dev/_modules/mne_bids/copyfiles.html @@ -7,7 +7,7 @@ -MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/_modules/mne_bids/dig.html b/dev/_modules/mne_bids/dig.html index 29566132c..a1ebe5e29 100644 --- a/dev/_modules/mne_bids/dig.html +++ b/dev/_modules/mne_bids/dig.html @@ -7,7 +7,7 @@ -MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/_modules/mne_bids/inspect.html b/dev/_modules/mne_bids/inspect.html index e5a655317..aebbce71c 100644 --- a/dev/_modules/mne_bids/inspect.html +++ b/dev/_modules/mne_bids/inspect.html @@ -7,7 +7,7 @@ -MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/_modules/mne_bids/path.html b/dev/_modules/mne_bids/path.html index c9645aafb..7678f7810 100644 --- a/dev/_modules/mne_bids/path.html +++ b/dev/_modules/mne_bids/path.html @@ -7,7 +7,7 @@ -MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/_modules/mne_bids/read.html b/dev/_modules/mne_bids/read.html index 33eeb5b4b..31d625c02 100644 --- a/dev/_modules/mne_bids/read.html +++ b/dev/_modules/mne_bids/read.html @@ -7,7 +7,7 @@ -MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
@@ -679,7 +679,7 @@
# If we have events, convert them to Annotations so they can be easily
# merged with existing Annotations.
- if events.size > 0:
+ if events.size > 0 and event_id is not None:
ids_without_desc = set(events[:, 2]) - set(event_id.values())
if ids_without_desc:
raise ValueError(
@@ -710,6 +710,22 @@ Source code for mne_bids.read
raw.set_annotations(annotations)
del id_to_desc_map, annotations, new_annotations
+ if events.size > 0 and event_id is None:
+ new_annotations = mne.annotations_from_events(
+ events=events,
+ sfreq=raw.info["sfreq"],
+ orig_time=raw.annotations.orig_time,
+ )
+
+ raw = raw.copy() # Don't alter the original.
+ annotations = raw.annotations.copy()
+
+ # We use `+=` here because `Annotations.__iadd__()` does the right
+ # thing and also performs a sanity check on `Annotations.orig_time`.
+ annotations += new_annotations
+ raw.set_annotations(annotations)
+ del annotations, new_annotations
+
# Now convert the Annotations to events.
all_events, all_desc = events_from_annotations(
raw,
diff --git a/dev/_modules/mne_bids/report/_report.html b/dev/_modules/mne_bids/report/_report.html
index a08b046d3..ae8e928c1 100644
--- a/dev/_modules/mne_bids/report/_report.html
+++ b/dev/_modules/mne_bids/report/_report.html
@@ -7,7 +7,7 @@
- mne_bids.report._report — MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ mne_bids.report._report — MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
@@ -40,7 +40,7 @@
-
+
@@ -147,7 +147,7 @@
- MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/_modules/mne_bids/sidecar_updates.html b/dev/_modules/mne_bids/sidecar_updates.html
index cb34a49fc..a16965f49 100644
--- a/dev/_modules/mne_bids/sidecar_updates.html
+++ b/dev/_modules/mne_bids/sidecar_updates.html
@@ -7,7 +7,7 @@
- mne_bids.sidecar_updates — MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ mne_bids.sidecar_updates — MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
@@ -40,7 +40,7 @@
-
+
@@ -147,7 +147,7 @@
- MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/_modules/mne_bids/utils.html b/dev/_modules/mne_bids/utils.html index c245dc3b8..771be0eab 100644 --- a/dev/_modules/mne_bids/utils.html +++ b/dev/_modules/mne_bids/utils.html @@ -7,7 +7,7 @@ -MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/_modules/mne_bids/write.html b/dev/_modules/mne_bids/write.html index df9fac4e8..3bfc604ba 100644 --- a/dev/_modules/mne_bids/write.html +++ b/dev/_modules/mne_bids/write.html @@ -7,7 +7,7 @@ -MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
@@ -776,7 +776,9 @@
return fid_coords, coord_frame
-def _events_tsv(events, durations, raw, fname, trial_type, overwrite=False):
+def _events_tsv(
+ events, durations, raw, fname, trial_type, event_metadata=None, overwrite=False
+):
"""Create an events.tsv file and save it.
This function will write the mandatory 'onset', and 'duration' columns as
@@ -800,6 +802,9 @@ Source code for mne_bids.write
trial_type : dict | None
Dictionary mapping a brief description key to an event id (value). For
example {'Go': 1, 'No Go': 2}.
+ event_metadata : pandas.DataFrame | None
+ Additional metadata to be stored in the events.tsv file. Must have one
+ row per event.
overwrite : bool
Whether to overwrite the existing file.
Defaults to False.
@@ -829,19 +834,30 @@ Source code for mne_bids.write
else:
del data["trial_type"]
+ if event_metadata is not None:
+ for key, values in event_metadata.items():
+ data[key] = values
+
_write_tsv(fname, data, overwrite)
-def _events_json(fname, overwrite=False):
+def _events_json(fname, extra_columns=None, has_trial_type=True, overwrite=False):
"""Create participants.json for non-default columns in accompanying TSV.
Parameters
----------
fname : str | mne_bids.BIDSPath
Output filename.
+ extra_columns : dict | None
+ Dictionary with additional columns to be added to the events.json file.
+ has_trial_type : bool
+ Whether the events.tsv file should contain a 'trial_type' column.
overwrite : bool
Whether to overwrite the output file if it exists.
"""
+ if extra_columns is None:
+ extra_columns = dict()
+
new_data = {
"onset": {
"Description": (
@@ -871,9 +887,16 @@ Source code for mne_bids.write
"associated with the event."
)
},
- "trial_type": {"Description": "The type, category, or name of the event."},
}
+ if has_trial_type:
+ new_data["trial_type"] = {
+ "Description": "The type, category, or name of the event."
+ }
+
+ for key, value in extra_columns.items():
+ new_data[key] = {"Description": value}
+
# make sure to append any JSON fields added by the user
fname = Path(fname)
if fname.exists():
@@ -1893,6 +1916,8 @@ Source code for mne_bids.write
bids_path,
events=None,
event_id=None,
+ event_metadata=None,
+ extra_columns_descriptions=None,
*,
anonymize=None,
format="auto",
@@ -1978,8 +2003,9 @@ Source code for mne_bids.write
call ``raw.set_annotations(None)`` before invoking this function.
.. note::
- Descriptions of all event codes must be specified via the
- ``event_id`` parameter.
+ Either, descriptions of all event codes must be specified via the
+ ``event_id`` parameter or each event must be accompanied by a
+ row in ``event_metadata``.
event_id : dict | None
Descriptions or names describing the event codes, if you passed
@@ -1990,6 +2016,11 @@ Source code for mne_bids.write
contains :class:`~mne.Annotations`, you can use this parameter to
assign event codes to each unique annotation description (mapping from
description to event code).
+ event_metadata : pandas.DataFrame | None
+ Metadata for each event in ``events``. Each row corresponds to an event.
+ extra_columns_descriptions : dict | None
+ A dictionary that maps column names of the ``event_metadata`` to descriptions.
+ Each column of ``event_metadata`` must have a corresponding entry in this.
anonymize : dict | None
If `None` (default), no anonymization is performed.
If a dictionary, data will be anonymized depending on the dictionary
@@ -2193,8 +2224,24 @@ Source code for mne_bids.write
'"bids_path.task = <task>"'
)
- if events is not None and event_id is None:
- raise ValueError("You passed events, but no event_id dictionary.")
+ if events is not None and event_id is None and event_metadata is None:
+ raise ValueError(
+ "You passed events, but no event_id dictionary " "or event_metadata."
+ )
+
+ if event_metadata is not None and extra_columns_descriptions is None:
+ raise ValueError(
+ "You passed event_metadata, but no "
+ "extra_columns_descriptions dictionary."
+ )
+
+ if event_metadata is not None:
+ for column in event_metadata.columns:
+ if column not in extra_columns_descriptions:
+ raise ValueError(
+ f"Extra column {column} in event_metadata "
+ f"is not described in extra_columns_descriptions."
+ )
_validate_type(
item=empty_room, item_name="empty_room", types=(mne.io.BaseRaw, BIDSPath, None)
@@ -2489,8 +2536,15 @@ Source code for mne_bids.write
# Write events.
if not data_is_emptyroom:
events_array, event_dur, event_desc_id_map = _read_events(
- events, event_id, raw, bids_path=bids_path
+ events,
+ event_id,
+ raw,
+ bids_path=bids_path,
)
+
+ if event_metadata is not None:
+ event_desc_id_map = None
+
if events_array.size != 0:
_events_tsv(
events=events_array,
@@ -2498,9 +2552,17 @@ Source code for mne_bids.write
raw=raw,
fname=events_tsv_path.fpath,
trial_type=event_desc_id_map,
+ event_metadata=event_metadata,
+ overwrite=overwrite,
+ )
+ has_trial_type = event_desc_id_map is not None
+
+ _events_json(
+ fname=events_json_path.fpath,
+ extra_columns=extra_columns_descriptions,
+ has_trial_type=has_trial_type,
overwrite=overwrite,
)
- _events_json(fname=events_json_path.fpath, overwrite=overwrite)
# Kepp events_array around for BrainVision writing below.
del event_desc_id_map, events, event_id, event_dur
diff --git a/dev/_static/documentation_options.js b/dev/_static/documentation_options.js
index c343efb25..9ac2df90f 100644
--- a/dev/_static/documentation_options.js
+++ b/dev/_static/documentation_options.js
@@ -1,5 +1,5 @@
const DOCUMENTATION_OPTIONS = {
- VERSION: '0.16.0.dev28+gf9199621',
+ VERSION: '0.16.0.dev29+g471bd0cd',
LANGUAGE: 'en',
COLLAPSE_INDEX: false,
BUILDER: 'html',
diff --git a/dev/api.html b/dev/api.html
index a9038cf94..f18c43e55 100644
--- a/dev/api.html
+++ b/dev/api.html
@@ -8,7 +8,7 @@
- API Documentation — MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ API Documentation — MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
@@ -41,7 +41,7 @@
-
+
@@ -150,7 +150,7 @@
- MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/authors.html b/dev/authors.html
index 05ff1c7ae..caaf72778 100644
--- a/dev/authors.html
+++ b/dev/authors.html
@@ -8,7 +8,7 @@
- <no title> — MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ <no title> — MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
@@ -41,7 +41,7 @@
-
+
@@ -148,7 +148,7 @@
- MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
diff --git a/dev/auto_examples/anonymize_dataset.html b/dev/auto_examples/anonymize_dataset.html
index 56bcc7075..361c016e6 100644
--- a/dev/auto_examples/anonymize_dataset.html
+++ b/dev/auto_examples/anonymize_dataset.html
@@ -8,7 +8,7 @@
- 13. Anonymizing a BIDS dataset — MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ 13. Anonymizing a BIDS dataset — MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
@@ -41,7 +41,7 @@
-
+
@@ -151,7 +151,7 @@
- MNE-BIDS 0.16.0.dev28+gf9199621 documentation
+ MNE-BIDS 0.16.0.dev29+g471bd0cd documentation
@@ -667,7 +667,7 @@ Basic anonymizationSpecifying subject IDsSpecifying subject IDsSpecifying subject IDs
@@ -922,9 +922,9 @@ ReproducibilityTotal running time of the script: (0 minutes 11.713 seconds)
+Total running time of the script: (0 minutes 11.992 seconds)
@@ -772,8 +772,9 @@ Convert to BIDShttps://bids-standard.github.io/bids-validator/
Command line tool: https://www.npmjs.com/package/bids-validator
-Total running time of the script: (0 minutes 0.356 seconds)
+Total running time of the script: (0 minutes 0.355 seconds)
-Total running time of the script: (0 minutes 2.037 seconds)
+Total running time of the script: (0 minutes 2.147 seconds)
-Total running time of the script: (0 minutes 1.282 seconds)
+Total running time of the script: (0 minutes 1.281 seconds)