mne_bids.events_file_to_annotation_kwargs#

mne_bids.events_file_to_annotation_kwargs(events_fname: str | Path) → dict[source]#

Read the events.tsv file and extract onset, duration, and description.

Parameters:
events_fnamestr

The file path to the events.tsv file.

Returns:
kwargs_dictdict

A dictionary containing the following keys:

  • ‘onset’np.ndarray

    The onset times of the events in seconds.

  • ‘duration’np.ndarray

    The durations of the events in seconds.

  • ‘description’np.ndarray

    The descriptions of the events.

  • ‘event_id’dict

    A dictionary mapping event descriptions to integer event IDs.

Notes

The function handles the following cases:

  • If the trial_type column is available, it uses it for event descriptions.

  • If the stim_type column is available, it uses it for backward compatibility.

  • If the value column is available, it uses it to create the event_id.

  • If none of the above columns are available, it defaults to using ‘n/a’ for descriptions and 1 for event IDs.

Examples

>>> import pandas as pd
>>> from pathlib import Path
>>> import tempfile
>>>
>>> # Create a sample DataFrame
>>> data = {
...     'onset': [0.1, 0.2, 0.3],
...     'duration': [0.1, 0.1, 0.1],
...     'trial_type': ['event1', 'event2', 'event1'],
...     'value': [1, 2, 1],
...     'sample': [10, 20, 30]
... }
>>> df = pd.DataFrame(data)
>>>
>>> # Write the DataFrame to a temporary file
>>> temp_dir = tempfile.gettempdir()
>>> events_file = Path(temp_dir) / 'events.tsv'
>>> df.to_csv(events_file, sep='\t', index=False)
>>>
>>> # Read the events file using the function
>>> events_dict = events_file_to_annotation_kwargs(events_file)
>>> events_dict
{'onset': array([0.1, 0.2, 0.3]),
'duration': array([0.1, 0.1, 0.1]),
'description': array(['event1', 'event2', 'event1'], dtype='<U6'),
'event_id': {'event1': 1, 'event2': 2}}