read_raw_bids does not use value column from events file

[hstojic]

read_raw_bids seems to define its own values for events.

For example, in the event file I have a value column with events specified as 1,2 and 4 with trial_type defining the names, but then when data is read in they are redefined as 1,2,3 in alphabetical order.

If the (optional) value column is present the reader should use those values instead of imposing generic ones.

[sappelhoff]

Thanks for reporting! I assume you are using mne_bids with version 0.2 and NOT the development version? You can check your version by calling mne_bids --version from the command line.

First of all: I agree with you, in your case read_raw_bids SHOULD use the event values as defined in the value column of your events.tsv file.

That said, read_raw_bids will handle events slightly differently in the next release (0.3):

Instead of returning raw, events, and events_id - read_raw_bids will ONLY return raw in the future.

However, this raw object will have an attribute: raw.annotations, which will give you Annotations, which is a relatively new feature in MNE to handle events. You can check out a nice tutorial here.

If you want events and event_id in the future, you will have to call mne.events_from_annotations

It'll look a bit like this:

import mne
from mne_bids import read_raw_bids

raw = read_raw_bids('./my_bids_fname', './my_bids_root')
events, event_id = mne.events_from_annotations(raw)
# note, events_id is NOT as in events.tsv
# rather, event_id will be consecutive numbers, see the docstring of events_from_annotations

... no where does that leave us with MNE-BIDS being capable to transfer your values from the value column in your events.tsv to Python and MNE? ... I don't know.

Some options:

• make a function event_id = mne_bids.get_event_id(bids_fname)
• make read_raw_bids return not only raw, but raw AND event_id ... then one could do:

import mne
from mne_bids import read_raw_bids

raw, events_id = read_raw_bids('./my_bids_fname', './my_bids_root')
# events_id is according to events.tsv!
events, _ = mne.events_from_annotations(raw)
# use the _ ... because otherwise we would get an events_id that we already have

What are your opinions? Are there more options that I did not mention?

cc @jasmainak @agramfort

[jasmainak]

I thought trial_type was meant to store the text description of events not an event code. So it's more like the key of an event_id dictionary rather than the value. Do I miss something?

[sappelhoff]

Do I miss something?

no, you are right ... but there is a different column in events.tsv files called value (see the table) which refers to the actual value of the TTL trigger / event marker in the raw data.

MNE will give each description (key in event_it) a value ... but this value SHOULD correspond to the value column in events.tsv

[hstojic]

Hmm, I'm not sure I follow the bit about annotations - does that mean when writing the BIDS data event files will be written directly in the raw data? If not, we would still need separate event files and load them when reading in the raw data, attaching them as annotations as new MNE would expect, no?

I used the development version actually, because 0.2 had an error with session names, so instead of just checking out that patch I went for the development version.

[jasmainak]

does that mean when writing the BIDS data event files will be written directly in the raw data?

no, but I agree this is confusing. The confusion arises from the fact that events array is used to write events.tsv but when reading it in, the data goes into raw.annotations. This leads to an inconsistent API in my opinion. This can be fixed by either: a) writing also with raw.annotations b) reverting to returning the events array when reading the raw data. Pinging @agramfort for opinion

[agramfort]

I would expect that read_raw_bids gives me everything I need to build epochs. As events in bids can have durations AFAIK they should be stored as annotations. I also don't expect users to know that events.tsv was read when doing read_raw_bids as this should just work. my 2c

…

[jasmainak]

what's the consensus here? Do we still have an issue?

[agramfort]

it works on my side

[jasmainak]

@hstojic do you agree? Closing issue, feel free to reopen if you disagree

[hstojic]

Suppose I have my own coding scheme for triggers, put them in value column, and rely on them, not event names - in the scripts then if you use event values programmatically when loading various tasks that have some overlap in triggers, you would get errors or worse, accidentally it would find those values but it wouldn't be what you think it is.

Probably it's not going to be many such cases, but to be on the safe side ti does't hurt to use the value column numbers - there is no downside to it, right? Defensive programming

[sappelhoff]

I agree @hstojic.

When reading a BIDS events.tsv we should use the values column as the "value" in a potential events_id dictionary ... and the trial_type column as the "key" in that dictionary.

[hoechenberger]

I just ran into this issue while playing with the new anonymize_dataset() function: event trigger values changed in the anonymized data, which lead me to this issue. Here's a MWE that demonstrates the underlying problem:

# %%
from pathlib import Path
import numpy as np
import mne
import mne_bids

sample_dir = Path(mne.datasets.sample.data_path())
sample_fname = sample_dir / 'MEG' / 'sample' / 'sample_audvis_raw.fif'

raw = mne.io.read_raw_fif(sample_fname)
events = mne.find_events(raw, stim_channel='STI 014')
event_id = {'visual/left': 3, 'visual/right': 4, 'face': 5, 'buttonpress': 32}
# Drop unused events
events = events[np.in1d(events[:, -1], list(event_id.values()))]

bp = mne_bids.BIDSPath(
    subject='foo', task='av', suffix='meg', extension='.fif', datatype='meg',
    root=Path('/tmp/bids-root')
)
mne_bids.write_raw_bids(
    raw=raw,
    bids_path=bp,
    events_data=events,
    event_id=event_id,
    overwrite=True
)
raw_read = mne_bids.read_raw_bids(bids_path=bp)
events_read, event_id_read = mne.events_from_annotations(raw=raw_read)

# %%
print('Original event_id:\n', event_id)
print('Round-tripped event_id:\n', event_id_read)

Produces:

Original event_id:
 {'visual/left': 3, 'visual/right': 4, 'face': 5, 'buttonpress': 32}
Round-tripped event_id:
 {'buttonpress': 1, 'face': 2, 'visual/left': 3, 'visual/right': 4}

I'm afraid the only way to fix this is to allow read_raw_bids to return an event_id dict which can then be passed to events_from_annotations() – or we add our own get_bids_events() function or something?

[hoechenberger]

I'm afraid the only way to fix this is to allow read_raw_bids to return an event_id dict which can then be passed to events_from_annotations()

Or we add this to BIDSPath?

BIDSPath.events
BIDSPath.event_id

(both as @propertys)

And it does the right thing?
This would also free users from having to use events_from_annotations()?