ENH: Add event_key parameter to read_raw_egi for MFF event metadata

[PragnyaKhandelwal]

Reference issue (if any)

Part of #13926

What does this implement/fix?

EGI MFF event XML files can store arbitrary metadata in <keys> child elements on each event (e.g. cel# written by E-Prime to identify experimental conditions). Previously MNE ignored this metadata.

This PR adds an event_key parameter to read_raw_egi. When passed (e.g. event_key="cel#"), the value of that key is appended to the event code — so AM40 with cel#=3 becomes AM40_3 in annotation descriptions and stim channel names. The raw key values are also stored in annotations.extras as event_key_<keyname>. Defaults to None so existing behaviour is unchanged.

Additional information

[scott-huberty]

@PragnyaKhandelwal I pushed a commit that should hopefully get this over the line.

The upshot is that the information we are trying to extract is user-defined metadata, and so we need to let the user tell us what metadata to look for.

Look at the "Key List" description in EGI's SDK: https://www.egi.com/images/stories/manuals/amp-server-pro-sdk-3-0-network-apis-user-guide-rev-01.pdf

For example in this testing file, we can see that the event name is 'AM30 and that there is a <key> child element with <keyCode>cel#</keyCode>. cel# is not part of the MFF spec, it is arbitrary, it literally could have been foobarbaz instead. In this case it was likely written to the file by the E-prime software that drove the experiment:

https://github.com/mne-tools/mne-testing-data/blob/33ef2a6f6345a1adf8764f8f63725f0ed9e4bb92/EGI/test_egi_multiepoch_paused.mff/Events_ECI%20TCP-IP%2055513.xml#L233-L242

So with this PR, we'd do mne.io.read_raw_egi(fname, events_as_annotations=True, event_key="cel#") which would append the cel# values to the annotations descriptions like AM30_1 or AM30_2 etc.

[viranovskaya]

Nice improvement. Since the PR also stores the MFF event keys in Annotations.extras, would it be worth extending test_read_event_keys to check that as well?

At the moment, the test only verifies the derived annotation description, so a regression in extras could pass unnoticed. For example, it could assert that the expected event_key_cel# values are present in raw.annotations.extras.

[scott-huberty]

@viranovskaya yes that is already on our radar.

FYI this is part of an ongoing GSoC project that @PragnyaKhandelwal is leading. Some reviewer comments on these PR's occur in 1:1 pair programming sessions, and are not always immediately documented here.

I think it's great that you are getting involved with the MNE project but your efforts would go further elsewhere, so that we don't duplicate efforts here!

[viranovskaya]

@scott-huberty Oh, right. Thanks for the context. I didn’t realise some of the review was happening outside the PR. I’ll step back from this one and look for an issue that isn’t already covered. :)

[PragnyaKhandelwal]

@PragnyaKhandelwal I pushed a commit that should hopefully get this over the line.

The upshot is that the information we are trying to extract is user-defined metadata, and so we need to let the user tell us what metadata to look for.

Look at the "Key List" description in EGI's SDK: https://www.egi.com/images/stories/manuals/amp-server-pro-sdk-3-0-network-apis-user-guide-rev-01.pdf

For example in this testing file, we can see that the event name is 'AM30 and that there is a <key> child element with <keyCode>cel#</keyCode>. cel# is not part of the MFF spec, it is arbitrary, it literally could have been foobarbaz instead. In this case it was likely written to the file by the E-prime software that drove the experiment:

https://github.com/mne-tools/mne-testing-data/blob/33ef2a6f6345a1adf8764f8f63725f0ed9e4bb92/EGI/test_egi_multiepoch_paused.mff/Events_ECI%20TCP-IP%2055513.xml#L233-L242

So with this PR, we'd do mne.io.read_raw_egi(fname, events_as_annotations=True, event_key="cel#") which would append the cel# values to the annotations descriptions like AM30_1 or AM30_2 etc.

Thanks @scott-huberty! Really appreciated your commit and the event_key=None opt-in approach — makes sense that since cel# is user-defined metadata (not part of the MFF spec), the user should tell us what key to look for. Good learning for me here.