[WIP] Allow all tfr_functions to operate on Raw object

[adam2392]

Reference issue

Addresses tfr discussion in: #8773

What does this implement/fix?

1. Allows tfr functions to operate on Raw object that returns and AverageTFR object.
2. Adds an API to AverageTFR for plotting a spectrogram and averaging frequencies between two ranges

Additional information

API is draft just to show what it would be like. I have not implemented 2. yet, and can take that out if you think it is not necessary/useful.

Related discussion on discourse: https://mne.discourse.group/t/is-there-a-way-to-obtain-the-time-points-from-time-frequency-stft/2682/3

[adam2392]

@agramfort this is something along what I would propose for what we disucced in #8773

[adam2392]

@agramfort just wanted to check in with you to see if this is going in the right direction? The main point is to allow tfr functions to operate on Raw objects with a disclaimer in the docstring about size/runtime.

Then a few questions regarding unimplemented functions:

• average_freqs: the intention is to provide a way to average within the frequency range too for things like computing "gamma band power", or something like that.
• plot_spectrogram: the intention here is to provide a plotting mechanism for plotting channels X time with frequency power (possibly in dB) as the color

^ Are these two functionalities desirable in the _BaseTFR class?

[agramfort]

@agramfort <https://github.com/agramfort> just wanted to check in with you to see if this is going in the right direction? The main point is to allow tfr functions to operate on Raw objects with a disclaimer in the docstring about size/runtime. Then a few questions regarding unimplemented functions: - average_freqs: the intention is to provide a way to average within the frequency range too for things like computing "gamma band power", or something like that.

for this usecase I would raw.filter(...).apply_hilbert(envelope=False) it's much faster than an STFT and averaging. It's also much easier to explain.

- plot_spectrogram: the intention here is to provide a plotting mechanism for plotting channels X time with frequency power (possibly in dB) as the color ^ Are these two functionalities desirable in the _BaseTFR class?

how would it look like? you would display minutes of data? would you have a way to scroll?

[adam2392]

The main point is to allow tfr functions to operate on Raw objects with a disclaimer in the docstring about size/runtime. Then a few questions regarding unimplemented functions: - average_freqs: the intention is to provide a way to average within the frequency range too for things like computing "gamma band power", or something like that.
for this usecase I would raw.filter(...).apply_hilbert(envelope=False) it's much faster than an STFT and averaging. It's also much easier to explain.

I might not be an expert in time-freq signal processing, but aren't there some advantages to using FFT like techniques and then averaging (https://mne.tools/stable/auto_examples/time_frequency/plot_time_frequency_simulated.html), or is Hilbert Transform envelope considered the best for showing things like frequency bands?

I might be lacking some basic working knowledge here... Lmk if instead you would prefer I post a more general question on the Discourse.

• plot_spectrogram: the intention here is to provide a plotting mechanism for plotting channels X time with frequency power (possibly in dB) as the color ^ Are these two functionalities desirable in the _BaseTFR class?
  how would it look like? you would display minutes of data? would you have a way to scroll?

It would just be a static heatmap

[agramfort]

I might not be an expert in time-freq signal processing, but aren't there some advantages to using FFT like techniques and then averaging ( https://mne.tools/stable/auto_examples/time_frequency/plot_time_frequency_simulated.html), or is Hilbert Transform envelope considered the best for showing things like frequency bands?

do your own experiments if you have doubts.

I might be lacking some basic working knowledge here... Lmk if instead you would prefer I post a more general question on the Discourse. - plot_spectrogram: the intention here is to provide a plotting mechanism for plotting channels X time with frequency power (possibly in dB) as the color ^ Are these two functionalities desirable in the _BaseTFR class? how would it look like? you would display minutes of data? would you have a way to scroll? It would just be a static heatmap

honestly I would encourage you to develop this tool for your own needs and once doing a few iterations on your side see what's best for MNE-Python.

[adam2392]

Okay sounds good! Thanks @agramfort for answering questions. I've updated the PR now to just reflect the title of allowing TFR funcs to operate on Raw objects. Lmk if this is good?

[agramfort]

you miss a what's new entry and I would strongly recommend to update a tutorial on time frequency to document this option

[agramfort]

should you also do this:

mne-python/mne/time_frequency/tfr.py

Line 2204 in 8bc55d7

if return_itc:

I am thinking that maybe you can use the same code path for Evoked and Raw? They basically both contain 2D data arrays

[adam2392]

Like what's done here: c14d080?

Is this what you meant?

[adam2392]

Added an extension to an existing tutorial. Lmk if you think this is good, or if I should add more?

[agramfort]

@adam2392 can you share some rendered doc page when you have one on CI? thx