Support specifying start and stop time points for averaging in `evoked.plot_topomap()`

[cbrnr]

The API for evoked.plot_topomap() is rather specific in that the times argument only accepts one or more time points, which are used to create the topomap(s). However, a common (the most common?) approach for analyzing ERP data is to use the mean amplitude within a given time window.

For example, if I wanted to plot the average amplitude from 185ms to 240ms, it would be ideal to directly specify this time range when creating the topomap. Currently, the API requires manually finding the midpoint (185 + (240 - 185) / 2 = 212.5) and passing it to times, and then passing the width (240 - 185 = 55) separately via the average argument, which feels a bit cumbersome.

Unfortunately, I don't have a good idea how to incorporate this use case into the current API (especially because times can already be an array of time points, but these do not specify time windows). I'd be interested in what you think about improving support for computing averages within time windows – or maybe this is already possible and I'm just missing something? Also, this issue might apply to more ERP-related functions, but this was the first one I found.

[drammock]

I'd be interested in what you think about improving support for computing averages within time windows – or maybe this is already possible and I'm just missing something?

another approach might be evoked.copy().crop(tmin, tmax).plot_topomap(average=tmax-tmin, axes=<single instance of axes>). By specifying a single axes, I think that the default times="auto" will pick only one time, and I think it will pick the midpoint. That said, it's still not very elegant / not much better than what you already came up with, and has the extra requirement of instantiating the figure/axes yourself.

TL;DR: I think you're right that this API could use some improvement. I'll think about how we might best do that.

[cbrnr]

One approach would be to allow passing a 2D array (shape N × 2, each row contains a pair of start/stop times) to times. Or maybe a list of 2-tuples. In which case the function should ignore the average argument, because time segments should always be averaged. It's weird, maybe you can come up with something better. Of course, with a breaking change we could probably make it much better.

[drammock]

One approach would be to allow passing a 2D array (shape N × 2, each row contains a pair of start/stop times) to times. Or maybe a list of 2-tuples. In which case the function should ignore the average argument, because time segments should always be averaged. It's weird, maybe you can come up with something better. Of course, with a breaking change we could probably make it much better.

After giving this some thought, I don't think your 2D-array proposal is all that weird. And it preserves backward compatibility, which is a nice advantage. Going further, we could even consider deprecating average once this is implemented, since e.g. times=[[0.25, 0.35]], average=None would be equivalent to times=0.3, average=0.1 (meaning there are now two equivalent ways to get the same result, which seems bad). Here's what the docstring would look like if we did this:

    times : float | array of float | "auto" | "peaks" | "interactive"
        The time point(s) to plot. A single scalar value will yield a topomap at a
        single time point. A one-dimensional sequence will yield topomaps at each time
        in the sequence. A two-dimensional sequence (e.g., an array, or list of tuples)
        must have shape ``(n_times, 2)`` and will be interpreted as (tmin, tmax)
        pairs, yielding a (sequence of) topomap(s) representing the average field in
        each tmin-to-tmax time span. If "auto", the number of ``axes`` determines the
        number of (equally-spaced) time point(s). If ``axes`` is also None, at most 10
        topographies will be shown with a regular time spacing between the first and
        last time instant. If "peaks", time points are selected automatically by
        checking for local maxima in global field power. If "interactive", the time can
        be set interactively at run-time by using a slider.

    average : float | array-like of float, shape (n_times,) | None
        Deprecated. If averaging over time windows is desired, pass a 2D array to
        ``times``.

WDYT?

[cbrnr]

Yes, this is certainly a big improvement over the current status! 👍

[larsoner]

Non-trivial and not a blocker so pushing to 1.12