Simplify storage of trial_type levels (event descriptions)

[hoechenberger]

Describe the problem

I'm storing data for an ERP experiment. We have events like the following:

event_name_to_code_map = {
    "fixation": 110,
    "cue/low": 120,
    "cue/high": 122,
    "scale/intensity": 200,
    "scale/pleasantness": 201,
    ...
}

I would like to describe what these events actually mean. BIDS suggests to store this information as trial_type levels inside events.json (example copied from the BIDS spec):

{
    "trial_type": {
        "LongName": "Event category",
        "Description": "Indicator of type of action that is expected",
        "Levels": {
            "start": "A red square is displayed to indicate starting",
            "stop": "A blue square is displayed to indicate stopping"
        }
    }
}

Currently, MNE-BIDS doesn't provide an easy way to write this data.

Describe your solution

Allow users to pass a mapping from event names (trial_type levels) to an event description. I imagine something like:

event_name_to_code_map = {
    "fixation": 110,
    "cue/low": 120,
    ...
}
event_name_to_description_map = {
    "fixation": "A fixation cross displayed in the center of the screen.",
    "cue/low": "A visual cue indicating low intensity."
}

write_raw_bids(
    ...,
    event_id=event_name_to_code_map,  # existing param
    event_descr=event_name_to_description_map  # new param
)

Describe possible alternatives

Users can update the JSON file manually after calling write_raw_bids(). However, this is cumbersome and error-prone.

Additional context

No response