ENH: Support concatenate_epochs() for EpochsTFR

[aman-coder03]

Reference issue (if any)

towards #13191

What does this implement/fix?

concatenate_epochs() now works with EpochsTFR objects. Before this, passing a list of EpochsTFR instances would just crash with a TypeError because EpochsTFR isn't a subclass of BaseEpochs

fix adds a helper function _concatenate_epochs_tfr() in mne/epochs.pythat takes care of stacking the data, merging event IDs, offsetting event timestamps, and handling metadata, basically the same things the existing concatenation does for regular epochs
concatenate_epochs() now checks if it's dealing with EpochsTFR objects and routes to this helper automatically
tests are added in mne/time_frequency/tests/test_tfr.py

Additional information

task 1 of 3 from #13191 (as discussed with @drammock)
tasks 2 and 3(EpochsSpectrum support and allowing EpochsTFR to accept RawTFR as input) will come in follow up PRs

[drammock]

Suggested change

	shift = np.int64((10 + ref.times[-1]) * ref.info["sfreq"])
	events_offset = int(np.max(epochs_list[0].events[:, 0])) + shift
	shift = len(ref.times)
	events_offset = ref.events[-1, 0] + shift

[nordme]

Hi @aman-coder03 ! Thanks for the PR.

I took a look at the concatenation function and tests, and it's looking pretty good so nice work. I spotted a few more EpochsTFR attributes that need handling.

Attributes to check:

1. ep.baseline
   Even if the times arrays are equivalent across epochs instances, some instances could have baselines where others have none, and that's a problem. For concatenation, baselines should be the same across instances.
2. ep.method
   We should check that the method of construction is the same for all our epochs instances (e.g. not mixing multitaper and morlet wavelet TFR results for example).
3. ep.weights
   This attribute stores weights for tapers. If applicable, these need to be equivalent across epochs instances.

Attributes that need concatenation:

1. ep.comment
   This attribute typically stores trial descriptions of some sort and might not be the same across epochs instances (e.g. 'run 1', 'run2', 'run 3'). These need to be put together for the returned epochs instance.

Cheers.

[aman-coder03]

thanks for the reviews...
@drammock i have applied your suggested change for the shift/offset calculation,

shift = len(ref.times)
events_offset = ref.events[-1, 0] + shift

addressed all three attribute checks @nordme

• ep.baseline now validated; raises ValueError if baselines don't match
• ep.method now validated; raises ValueError if methods don't match (e.g. mixing morlet and multitaper)
• ep.weights now validated using np.array_equal; raises ValueError if weights don't match

regarding ep.comment after investigation, EpochsTFR does not have a comment attribute (it lives only on AverageTFR), so there is nothing to concatenate here. If this should be added to EpochsTFR itself, that could be a separate issue...

[nordme]

@aman-coder03 I think you're right we can ignore the comment attribute since the average method sets it and averaged instances are excluded from concatenation. LGTM.

[aman-coder03]

README.rst dependency sync fix has been applied in #13748

[drammock]

merging main should clear up the CI failures (fixed in #13832)

[aman-coder03]

@drammock yes the errors are fixed now!

[drammock]

for some reason GitHub thinks I don't have access to this repo 🙄 so this is a "comment" review, but FWIW I am REQUESTING CHANGES.

I think there's too much duplicated code between _concatenate_epochs and _concatenate_epochs_tfr. Prefer refactoring _concatenate_epochs to triage function behavior based on type of the first element in the concatenation list.

[drammock]

Suggested change

	Add support for :func:`mne.concatenate_epochs` with :class:`~mne.time_frequency.EpochsTFR` instances, by ``aman-coder03``. (:gh:`13745`)
	Add support for :func:`mne.concatenate_epochs` with :class:`~mne.time_frequency.EpochsTFR` instances, by ``aman-coder03``.

[drammock]

Suggested change

	if not np.array_equal(ep.weights, ref.weights):
	if not np.array_equal(ep.weights, ref.weights): # NB: array_equal(None, None) == True

[drammock]

Suggested change

	events_offset += int(np.max(ep.events[:, 0])) + shift
	events_offset += ep.events[-1, 0] + shift

[drammock]

not safe. See corresponding code in existing _concatenate_epochs func:

mne-python/mne/epochs.py

Lines 4620 to 4629 in 692ecce

	# compare event_id
	common_keys = list(set(event_id).intersection(set(epochs.event_id)))
	for key in common_keys:
	if not event_id[key] == epochs.event_id[key]:
	msg = (
	"event_id values must be the same for identical keys "
	'for all concatenated epochs. Key "{}" maps to {} in '
	"some epochs and to {} in others."
	)
	raise ValueError(msg.format(key, event_id[key], epochs.event_id[key]))