Support HED (Hierarchical Event Descriptors) for epoching

[VisLab]

Describe the new feature or enhancement

MNE-Python represents events by a set of discrete integer codes, and epoching functions mostly select epochs based on these codes.

I was interested in incorporating some epoching features based on queries of HED strings and was hoping to get some advice (and maybe a little help) on figuring out the best way to do that.

HED is incorporated as an event annotation mechanism in BIDS. We can easily produce a table of event number versus HED string annotations to start with. (Note these would be the original event positions not codes in a particular column, since HED annotations are usually assembled from information in several columns in a BIDS event file.) We can also select numbers based on a HED string query.

Describe your proposed implementation

I'd really appreciate some advice on where to start on this.

Describe possible alternatives

We could extend the Epoch class so that it would store the HED annotations as a function of sample number.

We could also do something with the Annotation class.

Perhaps better, we could write an alternative way of creating Epochs and as part of this attach a HED_assembled column to the Epochs metadata. We could then write a query interface.

Additional context

Note:
In a BIDS dataset the HED annotation for each event is assembled from a combination of the information in the events.tsv HED column and the information in the other columns based on any applicable sidecars. This information is combined during analysis to provide a single HED annotation of each event.

[welcome]

Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴🏽‍♂️

[agramfort]

can you give an example in Python code of manipulating HED? it has remained an obscure thing for me so far

…

Message ID: ***@***.***>

[VisLab]

Factorization based on HED tags is a good example. See https://www.hed-resources.org/en/latest/FileRemodelingTools.html#factor-hed-tags. The goal is to epoch based on a variety of criteria in a dataset-independent manner (This is where the HED tags come in). The remodeling tools shown in the link are one interface to the underlying HEDTools.

Consider the case where the HED tags for each event marker have been assembled into a string in the HED column.
The user creates a HED query string.

Example:

Sensory-event And Visual-presentation

A vector of 0's and 1's is produced of the same length as the original data indicating whether the query matches the corresponding HED string.

Here is some sample code that I've done a quick hack on, removing all of the error checking and other things. This code actually modifies the DataFrame coming in, which we never do. The underlying code is designed to process multiple queries at once, but this example only does one.

def make_factor(df, hed_strings, hed_schema, query_string, query_name):
    query = QueryParser(query_string)
    df_factor = DataFrame(0, index=range(len(hed_strings)), columns=[query_name])
    for index, next_item in enumerate(hed_strings):
        match = query.search(next_item)
        if match:
            df_factor.at[index, query_name] = 1
    df[query_name] = df_factor

[agramfort]

Can you share the dataframe and a self contained example I can just run on my machine?

[VisLab]

Attached is a zip file with a self-contained example.

quickExample.zip

This example just processes a single query to append a factor. We are doing some refactoring on the underlying infrastructure and I'd like to see how we might support HED querying in MNE-Python.

The goal is more flexible, dataset-independent querying.

P.S. You have to pip install hedtools.