Adding new connectivity indexes

[cmista]

Describe the new feature or enhancement

The simplest way to check the relation between two signals is using correlation or a similar a similar approach. However, there are connectivity indexes that don't need to make the assumption of linearity between the interaction of the signals. These kind of indexes can be developed based on the information theory.

Describe your proposed implementation

New functions in the Connectivity Estimation group would be nice to be incorporated.

Describe possible alternatives

Mutual information is a good option as a non-directed measure. Transfer entropy seems to be a good option for a directed measure (causal) - although this most likely is too complex to handle myself alone

Additional comments

A review about connectivity indexes Bastos André M., Schoffelen Jan-Mathijs. A Tutorial Review of Functional Connectivity Analysis Methods and Their Interpretational Pitfalls. Frontiers in Systems Neuroscience

Transfer entropy paper Thomas Schreiber. Measuring Information Transfer. https://arxiv.org/abs/nlin/0001042v1

A nice article about information theory in neuroscience Nicholas M. Timme and Christopher Lapish. A Tutorial for Information Theory in Neuroscience. Eneuro

[agramfort]

is there existing python code for this already?

[cmista]

Yes, there are for python and for Matlab. Probably the word "new" in the tittle is confusing.

[agramfort]

can you provide links to it?

[drammock]

@cmista next steps are:

1. if there is existing python / matlab code, give links to it and make sure its license is one that allows us to adapt / incorporate it (MNE-Python is BSD license)
2. propose what the API for this would look like (what would be the function/method name, what would its arguments be, what would the return value look like)

[cmista]

@cmista next steps are:

1. if there is existing python / matlab code, give links to it and make sure its license is one that allows us to adapt / incorporate it (MNE-Python is BSD license)

2. propose what the API for this would look like (what would be the function/method name, what would its arguments be, what would the return value look like)

Thank you for clarifying the steps.

Point 1 I propose to start with the Mi, and surely trying the sklearn implementation (https://scikit-learn.org/stable/modules/generated/sklearn.feature_selection.mutual_info_regression.html) using channels for features.

I been looking for TE through the toolboxes, pondering license, support, and features. Best candidate is Python IDTxl (https://github.com/pwollstadt/IDTxl). The toolbox is open, but couldn't find the terms of use agreement. The toolboxes based on Matlab (MuTE and TRENTOOL https://github.com/trentool/TRENTOOL3) are GPL, but they seems to require a LOT of effort to be adapted.

Point 2
Working on that.

[drammock]

For mutual info, wrapping scikit-learn should be fine, it is already a dependency for some of our functionality.

ITDxl has a license file in the root of their repository. It is GPL licensed, which means we can't adapt or incorporate it without getting permission from the author(s) first.

[jshanna100]

I made an implementation of directed Phase Transfer Entropy (dPTE) last year, and have been wanting to integrate it with MNE Python for a while, but could never find the time. I would be happy to contribute my code as the starting point - it would also be a good opportunity to make sure everything works correctly.

[agramfort]

can you point to your implementation? just to see how long and complex the code is? just curious :)

[jshanna100]

Yes, gladly. It's currently buried here in an otherwise very disorganised repo.

The main function, epo_dPTE, takes an epoch array of data [n,c,t], where n is number of epochs, c is channels, and t is time, and produces [n,c,c] directed connectivity matrices for the desired frequency range. It already has parallel support, and also allows one to choose wavelet or hilbert transforms for instantaneous phase estimation.

The implementation is based on Lobier et al, 2014, Neuroimage, and Hillebrand et al 2016, PNAS.

[agramfort]

ok it's based on multivariate binning.

[agramfort]

Honestly I would say we need some evidence that this should be used by MNE users. In a word before adding this I feel we need "the why". I would like to avoid the argument that it should be added to MNE just but it’s not yet in MNE. Is there some example, some paper, some dataset that would be convincing?

my 2c

[cmista]

Good point @agramfort , because it give rise to 2 questions. One is whether it's worth studying nonlinear coupling in brain activity (which I'm biased to say yes). The second point is whether this feature will be useful for MNE-python users. I guess some users might be confused with so many indexes, and they could ending p-hacking their results in the worst-case scenario. I'll leave it as it, and pick another issue.

[jshanna100]

The primary benefit in my view is the addition of directed connectivity to the MNE repertoire. As far as I know, there are still only non-directed methods available in MNE. Secondarily, it would be nice to offer an information theory based method.

As far as papers go, I think a case is already more than adequately made in the two citations I gave above. I would personally name dPTE's robustness against signal leakage as its primary, distinctive strength.

Stepping back a bit, I have thought for a while that explicitly comparing available connectivity measures on the same dataset would make an excellent example/tutorial - preferably using something like synthetically generated coupled oscillators (e.g. kuramoto or neural mass models) as a sort of ground truth.

[agramfort]

I like what you say Jeff ! let's give this a try then. I am super curious to see who the benchmark on synthetic data will reveal !

[adam2392]

@jshanna100 are you interested in attempting a PR here on this topic? We recently moved the connectivity sub-module to a new repo here. There have been some data structure improvements as well. Happy to help where I can.

[jshanna100]

Yes, very much, and it's been on my mind since the summer, but I've been very busy lately. Realistically I think I could find some time for it in December.

[brovelli]

Hi all,

Thanks to @adam2392 I got to know the mne-connectivity module you are working on. Great initiative!

Concerning FC measures, you may be interested in the implementation of Frites, which is based on gaussian-copula MI estimates, but it also accepts binning and more complex kernel-based methods (see the estimator parameter) in here for example:

https://github.com/brainets/frites/blob/master/frites/conn/conn_dfc.py

Here are the estimators https://github.com/brainets/frites/tree/master/frites/estimator

Looking forward to collaborate on this topic. And maybe find a way to coordinate between Frites and mne-connectivity. Also with @EtienneCmb and @ViniciusLima94

[brovelli]

You may also be interested in the gcmi- and covariance-based implementations of Granger causality: https://github.com/brainets/frites/blob/master/frites/conn/conn_covgc.py

Here is the full set of measures currently available https://github.com/brainets/frites/tree/master/frites/conn

[adam2392]

Hi @brovelli thanks for pointing those out! I'll definitely have to take a look at the implemented FC measures. Perhaps even port them over here if it makes sense?

For Frites, what is the general direction of the repo? Are you mainly interested in implementing more connectivity measures, or also interested in consolidating the API?

We have mainly been focused on abstractions of connectivity data structures that cleanly and seamlessly carry over from MNE-Python Raw/Epochs objects.

[brovelli]

Hi @adam2392,

I think @EtienneCmb can answer you more precisely concerning the future of the API of Frites and data structures. I don't think they will evolve much.

For what concerns complementary FC measures, indeed together with @EtienneCmb and @ViniciusLima94 , we are currently working on single trial estimates. We are particularly interested in single-trial FC measures, because they allow information theoretical with behavioral variables as a second step.

We are currently testing single-trial time-frequency coherence. As soon as we push it to Frites, we will let you know (decembre?).

Concerning your questions about porting such measures into MNE-connectivity from Frites, franckly I don't know what would be the best strategy. Problems with porting them may arises when the FC measures are not completely finalised and fully tested, and incompatibilities may occur between Frites and MNE-connectivity, if we keep developping them on our side... but again, I am not the best person to ask about this issue.

Fully open to coordinate and share our efforts between MNE-connectivity and FRITES.

What is your view on this? @agramfort

[agramfort]

I think that any collaborative effort is great. Alone you go fast but together we go far !

however I really don't have the bandwidth to coordinate collaboration here.

I suggest you guys plan a short call to discuss your visions and maybe a plan a short code sprint (even remote) to see how far you can go together

[brovelli]

Ok, thanks Alex. I can try to coordinate this. Indeed a Zoom meeting would help.

So far:

1. @brovelli
2. @adam2392
3. @EtienneCmb
4. @ViniciusLima94

Who else woudl like to join?

[jshanna100]

I would, as well.

[adam2392]

That sounds good to me

[adam2392]

@brovelli just wanted to follow up to see if perhaps we might want to schedule something by next week (before Thanksgiving for us USA folks :p)?

My email is adam2392 at gmail dot com so feel free to email me as well / send me a gcal invite.