Phase-slope index using spectral_connectivity_time instead of spectral_connectivity_epochs #210

seqasim · 2024-06-28T21:16:58Z

Thanks for contributing. If this is your first time,
make sure to read contributing.md

PR Description

Currently, the function for computing phase-slope index is hard-coded to be computed over epochs to produce time-resolved PSI, and there's no option for computing the phase-slope index over time to produce PSI per epoch. This would be useful if you think the average directionality between two signals over the entire timecourse is informative. You could compute this by binning your trials into categories (i.e. good trials v. bad trials) and then computing PSI, but there's no way to compute PSI per epoch and relate it to continuous trial-level predictors.

Here, I add a new function phase_slope_index_time to mne_connectivity.effective that compute PSI over time. I should note that I wasn't able to test this function directly as I'm having trouble getting the forked repo installed, in editable mode, with all necessary dependencies, but have written a test function in tests.test_effective to facilitate this.

Merge checklist

Maintainer, please confirm the following before merging:

…arallel_con

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

tsbinns · 2024-08-01T21:28:42Z

Hi @seqasim, thanks for the PR and sorry for not getting back to you sooner on this. I have a few comments/suggestions which I'll post below, but it's a really good start!

If this is something you're still interested in working on, your contributions are of course very welcome, however I realise it's been a while. If you're not able to invest time into this anymore and you don't want your hard work to go to waste, I can pick things up and we can make sure the changes are added.

Just let us know. Cheers!

tsbinns · 2024-08-01T21:37:39Z

Just need to make sure that the new cohy method is described in the docstring for spectral_connectivity_time():

mne-connectivity/mne_connectivity/spectral/time.py

Lines 72 to 75 in ef0a484

    
               method : str | list of str 
        
                   Connectivity measure(s) to compute. These can be ``['coh', 'cacoh', 
        
                   'mic', 'mim', 'plv', 'ciplv', 'pli', 'wpli', 'gc', 'gc_tr']``. These 
        
                   are:

And also an equation entry like for coh:

mne-connectivity/mne_connectivity/spectral/time.py

Lines 245 to 256 in ef0a484

    
               **Supported Connectivity Measures** 
        
               The connectivity method(s) is specified using the ``method`` parameter. The 
        
               following methods are supported (note: ``E[]`` denotes average over 
        
               epochs). Multiple measures can be computed at once by using a list/tuple, 
        
               e.g., ``['coh', 'pli']`` to compute coherence and PLI. 
        
                   'coh' : Coherence given by:: 
        
                                | E[Sxy] | 
        
                       C = --------------------- 
        
                           sqrt(E[Sxx] * E[Syy])

tsbinns · 2024-08-01T21:58:07Z

A more general comment for the new phase_slope_index_time: Even if we are not averaging over epochs in the call to spectral_connectivity_time(), do you think it makes sense to add an average option which would allow averaging over epochs after PSI has been computed?

tsbinns

So just pretty minor comments. There are a couple formatting things (mainly line length) that I would have thought pre-commit would sort (if you've set that up). Would recommend doing so otherwise getting that CI check to pass will be very tedious...

tsbinns · 2024-08-01T21:30:23Z

mne_connectivity/spectral/time.py

@@ -559,7 +559,7 @@ def spectral_connectivity_time(
    conn_patterns = dict()
    for m in method:
        # CaCoh complex-valued, all other methods real-valued


Let's update the comment to keep it accurate

Suggested change

# CaCoh complex-valued, all other methods real-valued

# Cohy and CaCoh complex-valued, all other methods real-valued

tsbinns · 2024-08-01T21:31:38Z

mne_connectivity/spectral/time.py

+def _cohy(s_xx, s_yy, s_xy):
+    """Compute coherencey given the cross spectral density and PSD.
+
+    Parameters
+    ----------
+    s_xx : array-like, shape (n_freqs, n_times)
+        The PSD of channel 'x'.
+    s_yy : array-like, shape (n_freqs, n_times)
+        The PSD of channel 'y'.
+    s_xy : array-like, shape (n_freqs, n_times)
+        The cross PSD between channel 'x' and channel 'y' across
+        frequency and time points.
+
+    Returns
+    -------
+    cohy : array-like, shape (n_freqs, n_times)
+        The estimated COHY.
+    """
+    con_num = s_xy.mean(axis=-1, keepdims=True)
+    con_den = np.sqrt(
+        s_xx.mean(axis=-1, keepdims=True) * s_yy.mean(axis=-1, keepdims=True)
+    )
+    cohy = con_num / con_den
+    return cohy


Looks good!

tsbinns · 2024-08-01T21:39:13Z

mne_connectivity/effective.py

+from .base import (
+    EpochSpectralConnectivity,
+    SpectralConnectivity,
+    SpectroTemporalConnectivity,
+)


Formatting stuff

Suggested change

from .base import (

EpochSpectralConnectivity,

SpectralConnectivity,

SpectroTemporalConnectivity,

)

from .base import (

EpochSpectralConnectivity, SpectralConnectivity, SpectroTemporalConnectivity

)

tsbinns · 2024-08-01T21:42:56Z

mne_connectivity/effective.py

+                           padding=0,
+                           n_jobs=1,
+                           ):
+    """Compute the Phase Slope Index (PSI) connectivity measure across time rather than epochs.


Would need to shorten this. How about something like "Compute the Phase Slope Index (PSI) connectivity measure across time."?

tsbinns · 2024-08-01T21:46:10Z

mne_connectivity/effective.py

+    This function computes PSI over time from epoched data.
+    The data may consist of a single epoch.


I like this, keeps things consistent with spectral_connectivity_time(), but what about also having this be the first thing in the docstring, like in the spectral connectivity function?
That would help make it clearer sooner how this func differs to phase_slope_index().

tsbinns · 2024-08-01T22:02:36Z

mne_connectivity/effective.py

+    See Also
+    --------
+    mne_connectivity.EpochSpectralConnectivity


I'm wondering if it's good to reiterate that spectral_connectivity_time() is a relevant function. Though I realise you based this on the existing function docstring which doesn't link to spec_conn_epochs().

tsbinns · 2024-08-01T22:05:45Z

mne_connectivity/effective.py

+
+    Returns
+    -------
+    conn : instance of Connectivity


#214 made a lot of these typehints more explicit (i.e. EpochSpectralConnectivity instead).

Suggested change

conn : instance of Connectivity

conn : instance of EpochSpectralConnectivity

tsbinns · 2024-08-01T22:07:33Z

mne_connectivity/effective.py

+@verbose
+@fill_doc
+def phase_slope_index_time(data,
+                           names=None,
+                           indices=None,
+                           sfreq=2 * np.pi,
+                           mode="multitaper",
+                           fmin=None,
+                           fmax=np.inf,
+                           mt_bandwidth=None,
+                           freqs=None,
+                           n_cycles=7,
+                           padding=0,
+                           n_jobs=1,
+                           ):
+    """Compute the Phase Slope Index (PSI) connectivity measure across time rather than epochs.


Just make sure you add a verbose parameter. That should get the tests running.

Also you shouldn't need both verbose and fill_doc decorators. Verbose will trigger the same things as fill_doc

tsbinns · 2024-08-01T22:10:22Z

mne_connectivity/effective.py

+
+    Parameters
+    ----------
+    data : array-like, shape=(n_epochs, n_signals, n_times)


This should also include Epochs (again, I realise you took this from the existing function which doesn't have this, so should change there too).

tsbinns · 2024-08-01T22:18:55Z

mne_connectivity/tests/test_effective.py

+def test_psi_time():
+    """Test Phase Slope Index (PSI) estimation across time."""


From a quick glance the test looks good to me, let's see if it passes once the verbose param is added to the new function.

seqasim · 2024-08-02T04:04:47Z

Hi @seqasim, thanks for the PR and sorry for not getting back to you sooner on this. I have a few comments/suggestions which I'll post below, but it's a really good start!

If this is something you're still interested in working on, your contributions are of course very welcome, however I realise it's been a while. If you're not able to invest time into this anymore and you don't want your hard work to go to waste, I can pick things up and we can make sure the changes are added.

Just let us know. Cheers!

Hey,

Thanks for reviewing things! It's super illuminating for me to see the details I missed. I sadly won't have time to follow through on this for a few months, so if you feel you can wrap it up quickly, please don't wait for me! But if not, I'm happy to pick it up with all your helpful comments later in the year.

tsbinns · 2024-08-02T11:46:40Z

But if not, I'm happy to pick it up with all your helpful comments later in the year.

Yeah sounds good, there's no rush!

seqasim and others added 8 commits June 28, 2024 14:53

added _cohy to spectral.time

2631a83

list cohy method in spectral.time

388ab8c

Mimic conditional statements for coh for cohy in _pairwise_con and _p…

c38374a

…arallel_con

initial add of phase_slope_index_time to effective.py

b44da50

remove unused code from phase_slope_index_time

75a72b5

fixing documentation for phase_slope_index_time

6cef3cb

added test_psi_time to test_effective

dffda01

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

ef0a484

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

seqasim mentioned this pull request Jun 28, 2024

Phase-slope index using spectral_connectivity_time instead of spectral_connectivity_epochs? #178

Open

tsbinns reviewed Aug 1, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Phase-slope index using spectral_connectivity_time instead of spectral_connectivity_epochs #210

Phase-slope index using spectral_connectivity_time instead of spectral_connectivity_epochs #210

seqasim commented Jun 28, 2024

tsbinns commented Aug 1, 2024

tsbinns commented Aug 1, 2024

tsbinns commented Aug 1, 2024

tsbinns left a comment

tsbinns Aug 1, 2024

tsbinns Aug 1, 2024

tsbinns Aug 1, 2024

tsbinns Aug 1, 2024

tsbinns Aug 1, 2024

tsbinns Aug 1, 2024

tsbinns Aug 1, 2024

tsbinns Aug 1, 2024

drammock Aug 2, 2024

tsbinns Aug 1, 2024

tsbinns Aug 1, 2024

seqasim commented Aug 2, 2024

tsbinns commented Aug 2, 2024

	# CaCoh complex-valued, all other methods real-valued
	# Cohy and CaCoh complex-valued, all other methods real-valued

		This function computes PSI over time from epoched data.
		The data may consist of a single epoch.

	conn : instance of Connectivity
	conn : instance of EpochSpectralConnectivity

		def test_psi_time():
		"""Test Phase Slope Index (PSI) estimation across time."""

Phase-slope index using spectral_connectivity_time instead of spectral_connectivity_epochs #210

Are you sure you want to change the base?

Phase-slope index using spectral_connectivity_time instead of spectral_connectivity_epochs #210

Conversation

seqasim commented Jun 28, 2024

PR Description

Merge checklist

tsbinns commented Aug 1, 2024

tsbinns commented Aug 1, 2024

tsbinns commented Aug 1, 2024

tsbinns left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seqasim commented Aug 2, 2024

tsbinns commented Aug 2, 2024