[GSOC] Add `EpochsTFR` support to spectral connectivity functions #232

tsbinns · 2024-09-06T17:19:36Z

WIP follow up of #225 to finalise GSoC work.

So far adds support for coefficients from Epochs.compute_tfr(method="morlet", output="complex") to spectral_connectivity_epochs(), equivalent to the cwt_morlet mode. Still to be done is adding support for EpochsTFR objects in spectral_connectivity_time().

In addition to the Morlet approach, spectral_connectivity_time() supports the time-freq. multitaper mode. #126 could also be addressed by adding support for this to spectral_connectivity_epochs(), in the form of EpochsTFR objects.

However, when trying this I discovered a bug that prevents the time-freq. multitaper mode being computed from epoched data (mne-tools/mne-python#12831), but that seems like an easy fix.

Will continue to work on this next week.

tsbinns · 2024-09-10T12:43:49Z

Have now added support for EpochsTFR to spectral_connectivity_time (using a custom MNE branch with the bug in #12831 fixed).

mne_connectivity/spectral/time.py

This reverts commit 6fd0861.

tsbinns · 2024-09-17T09:49:56Z

Resetting tests to main mne branch now that mne-tools/mne-python#12842 is merged

mne_connectivity/spectral/epochs.py

mne_connectivity/spectral/time.py

tsbinns · 2024-09-19T14:20:22Z

Thanks for the detailed review @drammock! Until those wider API questions are addressed I'll double check the unit tests and try to find where the deviation in Fourier/Welch pipelines.

Co-authored-by: Daniel McCloy <[email protected]>

for more information, see https://pre-commit.ci

tsbinns · 2024-09-30T10:26:32Z

Conda test keeps freezing on the micromamba setup step, seems similar to this: mamba-org/setup-micromamba#225
Is it worth trying to fix now?

larsoner · 2024-09-30T17:28:13Z

Yeah feel free! Sounds like there might be a workaround via pinning in some of those issue comments

tsbinns · 2024-12-09T12:06:57Z

Haven't forgotten about this, just need to sort mne-tools/mne-python#12910 before I can finalise the changes and tests here.

tsbinns · 2025-01-13T20:56:46Z

mne-tools/mne-python#12910 is now merged, so I can fix the outstanding issues here.

tsbinns · 2025-01-16T17:48:31Z

mne_connectivity/spectral/epochs.py

+def _tfr_csd_from_mt(x_mt, y_mt, weights_x, weights_y):
+    """Compute time-frequency CSD from tapered spectra.
+
+    Parameters
+    ----------
+    x_mt : array, shape (..., n_tapers, n_freqs, n_times)
+        The tapered time-frequency spectra for signals x.
+    y_mt : array, shape (..., n_tapers, n_freqs, n_times)
+        The tapered time-frequency spectra for signals y.
+    weights_x : array, shape (n_tapers, n_freqs)
+        Weights to use for combining the tapered spectra of x_mt.
+    weights_y : array, shape (n_tapers, n_freqs)
+        Weights to use for combining the tapered spectra of y_mt.
+
+    Returns
+    -------
+    csd : array, shape (..., n_freqs, n_times)
+        The CSD between x and y.
+    """
+    # expand weights dims to match x_mt and y_mt
+    weights_x = np.expand_dims(weights_x, axis=(*np.arange(x_mt.ndim - 3), -1))
+    weights_y = np.expand_dims(weights_y, axis=(*np.arange(y_mt.ndim - 3), -1))
+    # compute CSD
+    csd = np.sum(weights_x * x_mt * (weights_y * y_mt).conj(), axis=-3)
+    denom = np.sqrt((weights_x * weights_x.conj()).real.sum(axis=-3)) * np.sqrt(
+        (weights_y * weights_y.conj()).real.sum(axis=-3)
+    )
+    csd *= 2 / denom
+    return csd


There isn't a _csd_from_mt equivalent for TFR data in MNE. Would people be open to me adding this to the main MNE package in a small PR?
Otherwise it can just remain here.

I think even if you put it there you'd need some sort of try/except based on MNE version with a fallback to this code (in this codebase) anyway.

Good point. So we should keep this here for now.

tsbinns · 2025-01-16T17:50:36Z

mne_connectivity/spectral/epochs.py

+                if not is_tfr_con:  # normal spectra (multitaper or Fourier)
+                    this_psd = _psd_from_mt(x_t, weights)
+                else:  # TFR spectra (multitaper)
+                    this_psd = np.array([_tfr_from_mt(epo_x, weights) for epo_x in x_t])


Realising now that the way I implemented _tfr_from_mt in mne-tools/mne-python#12910 works fine there, but isn't flexible to an epochs dimension (in contrast _psd_from_mt is).

Would people be open to a small PR in the main package to fix this?

mne_connectivity/spectral/time.py

tsbinns · 2025-01-16T18:09:54Z

I've addressed the previous issues.

There should now be full support for EpochsSpectrum and EpochsTFR data in spectral_connectivity_epochs (including time-resolved multitaper coeffs) and for EpochsTFR in spectral_connectivity_time, along with unit tests covering the changes.

tsbinns · 2025-01-16T18:15:39Z

Given that the multitaper TFR requires the unreleased MNE 1.10, is it worth holding off on merging (once it's checked and ready to go) until after MNE-Conn 0.8 is released?

On that note, since the last major part of the GSoC project in #223 was merged, there's a decent amount for a new release: https://mne.tools/mne-connectivity/dev/whats_new.html
What do people think?

Opened an issue here -> #276

larsoner · 2025-01-17T20:24:34Z

Given that the multitaper TFR requires the unreleased MNE 1.10, is it worth holding off on merging (once it's checked and ready to go) until after MNE-Conn 0.8 is released?

You could, but even then you'll need to add a version guard to the mne-connectivity that checks the MNE version. You have them in tests but you also need them in the user-facing function. You can use something like _soft_import("mne", "multitaper connectivity", min_version="1.10") for it

larsoner · 2025-01-17T20:25:25Z

... although I think the min_version in _soft_import was added recently, so better just to use

if not check_version("mne", "1.10):
    raise ...

in the user-facing code

tsbinns · 2025-01-17T20:33:15Z

You could, but even then you'll need to add a version guard to the mne-connectivity that checks the MNE version. You have them in tests but you also need them in the user-facing function. You can use something like _soft_import("mne", "multitaper connectivity", min_version="1.10") for it

Currently I'm checking compatibility based on the object attrs. Do you think an explicit version check is cleaner?

mne-connectivity/mne_connectivity/spectral/epochs.py

Lines 1225 to 1233 in 73ce0a6

    
           # Extract weights from the EpochsSpectrum/TFR object 
        
           if not hasattr(data, "weights"): 
        
               if mode == "multitaper": 
        
                   # XXX: Remove logic when support for mne<1.10 is dropped 
        
                   raise AttributeError( 
        
                       "weights are required for multitaper coefficients stored in " 
        
                       "EpochsSpectrum (requires mne >= 1.8) and EpochsTFR (requires " 
        
                       "mne >= 1.10) objects" 
        
                   )

drammock · 2025-01-17T20:51:42Z

Currently I'm checking compatibility based on the object attrs. Do you think an explicit version check is cleaner?

Is the issue just about which MNE version is currently installed? Or is it to do with which version of MNE the data were saved to disk with? If the latter plays a role, then attr-based checking seems right to me (though I'd tweak the error message to explicitly reference the possibility of loaded data that were saved by an older version of MNE). On the other hand if it's just about the currently installed version of MNE, then checking that (rather than object attrs) makes for easier-to-maintain code IMO (as the code more directly reflects the source of the problem).

tsbinns · 2025-01-17T21:04:32Z

Is the issue just about which MNE version is currently installed? Or is it to do with which version of MNE the data were saved to disk with?

Moreso the latter, whatever MNE version was used to compute the coefficients.
But thinking about it, could be the case that a multitaper EpochsSpectrum/TFR object saved from an older MNE version and loaded with a newer version has a weights attr that is None, so that check would fail. A more thorough check would be:

if not hasattr(data, "weights") or (data.weights is None and mode == "multitaper"):
    # XXX: Remove logic when support for mne<1.10 is dropped 
    raise AttributeError( 
       "weights are required for multitaper coefficients stored in " 
       "EpochsSpectrum (requires mne >= 1.8) and EpochsTFR (requires " 
       "mne >= 1.10) objects" 
    )

I'd tweak the error message to explicitly reference the possibility of loaded data that were saved by an older version of MNE

Yeah good call, I'll add this.

drammock · 2025-01-23T17:31:33Z

@larsoner this one LGTM, I'll let you merge if happy

larsoner · 2025-01-24T17:39:58Z

mne_connectivity/spectral/epochs.py

+                if not is_tfr_con:  # normal spectra (multitaper or Fourier)
+                    this_psd = _psd_from_mt(x_t, weights)
+                else:  # TFR spectra (multitaper)
+                    this_psd = np.array([_tfr_from_mt(epo_x, weights) for epo_x in x_t])


mne_connectivity/spectral/time.py

larsoner · 2025-01-24T17:43:06Z

mne_connectivity/spectral/epochs.py

+def _tfr_csd_from_mt(x_mt, y_mt, weights_x, weights_y):
+    """Compute time-frequency CSD from tapered spectra.
+
+    Parameters
+    ----------
+    x_mt : array, shape (..., n_tapers, n_freqs, n_times)
+        The tapered time-frequency spectra for signals x.
+    y_mt : array, shape (..., n_tapers, n_freqs, n_times)
+        The tapered time-frequency spectra for signals y.
+    weights_x : array, shape (n_tapers, n_freqs)
+        Weights to use for combining the tapered spectra of x_mt.
+    weights_y : array, shape (n_tapers, n_freqs)
+        Weights to use for combining the tapered spectra of y_mt.
+
+    Returns
+    -------
+    csd : array, shape (..., n_freqs, n_times)
+        The CSD between x and y.
+    """
+    # expand weights dims to match x_mt and y_mt
+    weights_x = np.expand_dims(weights_x, axis=(*np.arange(x_mt.ndim - 3), -1))
+    weights_y = np.expand_dims(weights_y, axis=(*np.arange(y_mt.ndim - 3), -1))
+    # compute CSD
+    csd = np.sum(weights_x * x_mt * (weights_y * y_mt).conj(), axis=-3)
+    denom = np.sqrt((weights_x * weights_x.conj()).real.sum(axis=-3)) * np.sqrt(
+        (weights_y * weights_y.conj()).real.sum(axis=-3)
+    )
+    csd *= 2 / denom
+    return csd


I think even if you put it there you'd need some sort of try/except based on MNE version with a fallback to this code (in this codebase) anyway.

larsoner · 2025-01-24T17:43:23Z

Thanks @tsbinns !

tsbinns · 2025-01-24T17:55:17Z

Thanks @drammock and @larsoner for the patience with this!

tsbinns added 6 commits September 6, 2024 18:59

Add TFR support spec_conn_epochs

a9dc973

Update epochs docstring

535db69

Update rank check comments

14428f6

Add TFR support spec_conn_time

1b1456d

Switch tests to custom MNE branch

6fd0861

Merge branch 'main' into specconn_tfr_support

fc55d70

tsbinns added 3 commits September 10, 2024 14:46

Fix failing tfr_error test

a38f8fd

Fix time_tfr tolerances

9c04f81

Fix misleading error message

c861449

tsbinns commented Sep 10, 2024

View reviewed changes

mne_connectivity/spectral/time.py Outdated Show resolved Hide resolved

tsbinns commented Sep 10, 2024

View reviewed changes

mne_connectivity/spectral/time.py Outdated Show resolved Hide resolved

Fix spec_conn_time docstring error

7013e19

tsbinns force-pushed the specconn_tfr_support branch from a86f9b9 to 7013e19 Compare September 10, 2024 14:13

tsbinns mentioned this pull request Sep 16, 2024

Store n_cycles and time_bandwidth params in *TFR objects mne-tools/mne-python#12851

Closed

Revert "Switch tests to custom MNE branch"

160bc64

This reverts commit 6fd0861.

Merge branch 'main' into specconn_tfr_support

23dc1f2

drammock reviewed Sep 18, 2024

View reviewed changes

tsbinns and others added 5 commits September 20, 2024 14:34

Apply suggestions from code review

8e79c9f

Co-authored-by: Daniel McCloy <[email protected]>

[pre-commit.ci] auto fixes from pre-commit.com hooks

23fd89c

for more information, see https://pre-commit.ci

Name expected conn values

641fa1d

Update Welch-Fourier variation message

232c0e9

Merge branch 'main' into specconn_tfr_support

4898673

Merge branch 'main' into specconn_tfr_support

269d209

Update TFR support in spec_conn_time

c354385

tsbinns commented Jan 16, 2025

View reviewed changes

Clean up class checking

73ce0a6

tsbinns commented Jan 16, 2025

View reviewed changes

mne_connectivity/spectral/time.py Show resolved Hide resolved

tsbinns commented Jan 16, 2025

View reviewed changes

mne_connectivity/spectral/time.py Show resolved Hide resolved

tsbinns mentioned this pull request Jan 16, 2025

Release v0.8? #276

Open

Merge branch 'main' into specconn_tfr_support

4dba53e

Update weights check logic

f4c087c

drammock approved these changes Jan 23, 2025

View reviewed changes

Merge branch 'main' into specconn_tfr_support

cba4d6e

larsoner approved these changes Jan 24, 2025

View reviewed changes

larsoner merged commit 94da387 into mne-tools:main Jan 24, 2025
13 checks passed

tsbinns deleted the specconn_tfr_support branch January 27, 2025 09:20

tsbinns mentioned this pull request Jan 27, 2025

[BUG] Fix issue in decomposition plotting to specified axes #280

Merged

tsbinns mentioned this pull request Feb 10, 2025

Change calls to _tfr_from_mt with support for ndarrays #286

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[GSOC] Add `EpochsTFR` support to spectral connectivity functions #232

[GSOC] Add `EpochsTFR` support to spectral connectivity functions #232

tsbinns commented Sep 6, 2024

tsbinns commented Sep 10, 2024

tsbinns commented Sep 17, 2024

tsbinns commented Sep 19, 2024

tsbinns commented Sep 30, 2024

larsoner commented Sep 30, 2024

tsbinns commented Dec 9, 2024

tsbinns commented Jan 13, 2025 •

edited

Loading

tsbinns Jan 16, 2025 •

edited

Loading

larsoner Jan 24, 2025

tsbinns Jan 24, 2025

tsbinns Jan 16, 2025

larsoner Jan 24, 2025

tsbinns commented Jan 16, 2025

tsbinns commented Jan 16, 2025 •

edited

Loading

larsoner commented Jan 17, 2025

larsoner commented Jan 17, 2025

tsbinns commented Jan 17, 2025

drammock commented Jan 17, 2025

tsbinns commented Jan 17, 2025

drammock commented Jan 23, 2025

larsoner Jan 24, 2025

larsoner Jan 24, 2025

larsoner commented Jan 24, 2025

tsbinns commented Jan 24, 2025

[GSOC] Add EpochsTFR support to spectral connectivity functions #232

[GSOC] Add EpochsTFR support to spectral connectivity functions #232

Conversation

tsbinns commented Sep 6, 2024

tsbinns commented Sep 10, 2024

tsbinns commented Sep 17, 2024

tsbinns commented Sep 19, 2024

tsbinns commented Sep 30, 2024

larsoner commented Sep 30, 2024

tsbinns commented Dec 9, 2024

tsbinns commented Jan 13, 2025 • edited Loading

tsbinns Jan 16, 2025 • edited Loading

Choose a reason for hiding this comment

larsoner Jan 24, 2025

Choose a reason for hiding this comment

tsbinns Jan 24, 2025

Choose a reason for hiding this comment

tsbinns Jan 16, 2025

Choose a reason for hiding this comment

larsoner Jan 24, 2025

Choose a reason for hiding this comment

tsbinns commented Jan 16, 2025

tsbinns commented Jan 16, 2025 • edited Loading

larsoner commented Jan 17, 2025

larsoner commented Jan 17, 2025

tsbinns commented Jan 17, 2025

drammock commented Jan 17, 2025

tsbinns commented Jan 17, 2025

drammock commented Jan 23, 2025

larsoner Jan 24, 2025

Choose a reason for hiding this comment

larsoner Jan 24, 2025

Choose a reason for hiding this comment

larsoner commented Jan 24, 2025

tsbinns commented Jan 24, 2025

[GSOC] Add `EpochsTFR` support to spectral connectivity functions #232

[GSOC] Add `EpochsTFR` support to spectral connectivity functions #232

tsbinns commented Jan 13, 2025 •

edited

Loading

tsbinns Jan 16, 2025 •

edited

Loading

tsbinns commented Jan 16, 2025 •

edited

Loading