[ENH] Add option to store and return TFR taper weights

[tsbinns]

Reference issue (if any)

PR for #12851

What does this implement/fix?

Adds an option to return taper weights for complex and phase outputs of the multitaper method in tfr_array_multitaper(), and also ensures taper weights are stored in TFR objects.

Additional information

When working on this, I discovered a couple of other issues with the per-taper TFR implementations (#12851 (comment)), including the fact that the TFR object plotting methods and to_data_frame methods do not account for a taper dimension, leading to errors. Wasn't sure if people want me to also address these here or in a separate PR.

[tsbinns]

I'm also somewhat confused about the design of the _make_dpss function:

mne-python/mne/time_frequency/tfr.py

Lines 285 to 315 in 82fc2f7

	for m in range(n_taps):
	Wm = list()
	Cm = list()
	for k, f in enumerate(freqs):
	if len(n_cycles) != 1:
	this_n_cycles = n_cycles[k]
	else:
	this_n_cycles = n_cycles[0]
	t_win = this_n_cycles / float(f)
	t = np.arange(0.0, t_win, 1.0 / sfreq)
	# Making sure wavelets are centered before tapering
	oscillation = np.exp(2.0 * 1j * np.pi * f * (t - t_win / 2.0))
	# Get dpss tapers
	tapers, conc = dpss_windows(
	t.shape[0], time_bandwidth / 2.0, n_taps, sym=False
	)
	Wk = oscillation * tapers[m]
	if zero_mean: # to make it zero mean
	real_offset = Wk.mean()
	Wk -= real_offset
	Wk /= np.sqrt(0.5) * np.linalg.norm(Wk.ravel())
	Ck = np.sqrt(conc[m])
	Wm.append(Wk)
	Cm.append(Ck)
	Ws.append(Wm)
	Cs.append(Cm)

It is looping over tapers, and then over frequencies. However, the dpss_windows function it calls internally provides the tapers and their weights for all tapers of a given frequency.

Would it not be more efficient to only loop over frequencies and take advantage of the fact that this will also return information for each taper?

[tsbinns]

I also have a question regarding testing: for the I/O tests, we're reading TFR objects that do not have a weights property (just gets assigned to None) when loaded. Do I need to create new TFR objects that actually have some weights, or is the current test sufficient?

Apart from this there are still some tests I need to expand.

[tsbinns]

Thanks for the review @drammock! I will sort out those remaining tests, although I'm in the process of moving at the moment so it might not be for some days.

Regarding those issues I came across with TFR multitapers and converting to dataframes / plotting: would you like me to incorporate that into this PR?

[tsbinns]

Just looking into the sorting the power this morning and I am a little confused by the procedure being used to convert the complex taper coeffs into power, as it seems that no taper weights are ever applied. I opened an issue to try and figure out if this is a mistake, or a misunderstanding on my part: #13023

[tsbinns]

Latest push adds support for plotting of data with a taper dimension (aggregates over tapers before plotting and converts to power (if complex coeffs) or keeps as phase data).
Also has test coverage.

[tsbinns]

Just looking into the sorting the power this morning and I am a little confused by the procedure being used to convert the complex taper coeffs into power, as it seems that no taper weights are ever applied. I opened an issue to try and figure out if this is a mistake, or a misunderstanding on my part: #13023

As discussed there this is a bug but will be addressed in a separate PR once this is merged.

[drammock]

@larsoner this one's ready for your eyes I think. I called out one question from @tsbinns that I'm hoping you can spot the answer to quickly (aggregating over tapers for phase data)

[larsoner]

Just a couple of minor comments otherwise LGTM!

[tsbinns]

So I think that's the comments from both of your reviews addressed @larsoner and @drammock; thanks for that!
Looking through the rest I don't see other outstanding points. Is this good to merge?

[drammock]

So I think that's the comments from both of your reviews addressed @larsoner and @drammock; thanks for that! Looking through the rest I don't see other outstanding points. Is this good to merge?

restarted the failing CI (which should pass this time 🤞🏻) and marked for auto-merge when green. Thanks @tsbinns

[tsbinns]

Thanks for all your help and patience with this @drammock and @larsoner! 🚀