Segmentation based on event attributes

[ephathaway]

Event annotations in the MFF file format can be complex. For example, when performing an ERP experiment with stimulus presentation, a single trial spec event can contain many fields:

<event>
        <beginTime>2018-09-27T14:15:52.842072-07:00</beginTime>
        <duration>1000</duration>
        <code>TRSP</code>
        <label></label>
        <description></description>
        <sourceDevice>Multi-Port ECI</sourceDevice>
        <keys>
            <key>
                <keyCode>cel#</keyCode>
                <description></description>
                <data dataType="short">1</data>
            </key>
            <key>
                <keyCode>obs#</keyCode>
                <description></description>
                <data dataType="short">2</data>
            </key>
            <key>
                <keyCode>rsp#</keyCode>
                <description></description>
                <data dataType="short">4</data>
            </key>
            <key>
                <keyCode>eval</keyCode>
                <description></description>
                <data dataType="short">0</data>
            </key>
            <key>
                <keyCode>rtim</keyCode>
                <description></description>
                <data dataType="long">696</data>
            </key>
            <key>
                <keyCode>trl#</keyCode>
                <description></description>
                <data dataType="short">2</data>
            </key>
...

These fields are important. Say you want to average all trials with response time < 100 ms. If you want to do this programmatically, you would need to be able to parse the rtim key for each event.

mffpy is able to thoroughly parse event track XML files (https://github.com/BEL-Public/mffpy/blob/master/mffpy/xml_files.py), but we are lacking an API to easily extract events based on a certain key value or criteria. If you take a look at worfklows/erp/erp.py, you will see we do some very light event parsing based on the event code. This is a bit unwieldy to have in a script, and could get even more unwieldy if one were to implement some more complex logic.

I propose adding an event extraction module in eegwlib with some helpful functions that utilize mffpy event parsing to extract events based on certain criteria.