Allow Epochs.equalize_event_counts() to operate based on metadata, not only on events

[hoechenberger]

This was brought up by @Zhouyu0206 in https://mne.discourse.group/t/how-to-use-equalize-event-counts-combined-with-metadata-instead-of-event-ids/

[larsoner]

This to me is an enhancement and shouldn't block 0.23 so I'm re-milestoning for 0.24

[sappelhoff]

I wrote a tiny suggestion about this in #9509 which I now closed as a duplicate of this present issue. Let me copy paste for convenience:

Describe the new feature or enhancement

equalize_event_counts is a handy method for epochs to sensibly drop epoch "kinds", making the distribution of "kinds" uniform.

My epochs have very basic events (1, 2, 3) and complex/rich epochs.metadata. I would like to equalize event counts based on a column in epochs.metadata. Unfortunately, currently equalize_event_counts seems to only work on events, and not metadata.

Describe your proposed implementation

I suggest we extend the equalize_event_counts method to have a new parameter metadata_column (or similar), to equalize event counts based on that column.

For example, in my case each epoch is one of three "event types" (as mentioned above: 1, 2, 3) - but each epoch also has a metadata column called "outcome" (1, 2, 3, ..., 9). I would like to equalize the epochs based on the "outcome" metadata, so I would like to do something like:

epochs.equalize_event_counts(metadata_column="outcome", method="mintime")

Describe possible alternatives

An alternative would be to document (or create) a simple way to:

1. select columns from metatdata
2. merge existing event_types (1, 2, 3 in my example) with the metadata from the columns to ...
3. ... come up with a new lst of event types (tags) --> in my case that'd be a mix of the current types (1, 2, 3) and the "outcome" column from the metadata, so something like: 1/outcome2, 1/outcome4, 2/outcome9, 3/outcome1, 3/outcome1, ...
4. then equalize_event_counts can be used on the newly created tags

However this alternative seems potentially more complex than my proposed implementation