Time-domain asymmetric dynamical connectivity - data structure storage and basic OLS algorithms

[adam2392]

Describe the new feature or enhancement

This is related to a goal of mine to add generic "connectivity" function to MNE for the code-sprint.

Right now, there are a decent amount of "spectral connectivity" (possibly over time) metrics derived from raw EEG/MEG/iEEG data.There are alternative characterizations, such as dynamical system perspective, which models the data as:

x(t+1) = Ax(t)

where A is possibly an asymmetric matrix characterized by its eigenvalues. Note this is different then just looking at the "pearson correlation" (or covariances) over time, since correlation matrices are PSD and symmetric.

Since a linear dynamical system representation of the MEEG data is useful, it would be nice to have a "data structure" to store such a representation and also expose basic algorithms for estimating this model from the raw data. I'm opening this issue to have a discussion to see if this is feasible to add.

Describe your proposed implementation

One can leverage scikit-learn to add an option to say Raw, or Epochs.

One can add regularization as a result. The algorithm would essentially consist of a window_size and step_size, which takes a sliding window and estimates sequences of these A matrices.

To make this a "nice" and "useful" workflow, I would argue that we need a:

• general Connectivity container (e.g. generalize what Connectivity data structures mne already has)
• a simple API for computing the sequence of A matrices

Describe possible alternatives

In a related viewpoint, this is related to what is known as Dynamic Mode Decomposition (DMD), which is also useful, but the representation of the data is different, because there one is interested in not only the A matrix, but also the "DMD modes". This is related to the linear Koopman operator in dynamical systems theory; DMD is a finite approximation of Koopman.

Example paper:

• https://arxiv.org/pdf/1409.5496.pdf

Additional comments

Example papers using A matrix:

• https://pubmed.ncbi.nlm.nih.gov/29060480/
• https://www.biorxiv.org/content/10.1101/862797v4.full

In addition https://arxiv.org/pdf/1802.08334.pdf talks about the convergence of such OLS estimates for A, giving some sort of theoretical guarantees on how "estimable" an A matrix is from MEEG data.

Comparisons to spectral connectivity

Spectral connectivity generally are defined as some correlation measure over frequency domain, and is generally symmetric. Here, I am proposing a time-domain and possibly `asymmetric "connectivity" derivative of the raw MEEG data.

Testing

Datasets can be tested against A matrices I've computed using numpy.

[adam2392]

@alexrockhill

[alexrockhill]

Is there a replication we can do from one of these papers with real data available to make sure it works properly?

[adam2392]

Is there a replication we can do from one of these papers with real data available to make sure it works properly?

Yep, I have these in the form of numpy arrays, with specific sliding windows and reference schemes.

[alexrockhill]

Great, I think this would be a good first thing to get going on when you get back if you want help

[alexrockhill]

Maybe it would be easier to start with the A matrix being returned and plan to iterate on having it be an internal variable once there are more functions that depend on it. That would save a lot of coding on the front end by just adding a function to raw and then making an example using it...

[adam2392]

Some additional niceties that can come about:

This can be useful for:

1. repairing short time Epochs: fit A matrix before this Epoch, fit backwards operator after this Epoch, and estimate the noisy epoch for all channels
2. repairing channel Epoch: same procedure as above, but only done for a select channel

[alexrockhill]

Maybe it would be good to start with repairing an epoch as an example and work backwards to all the functions needed to do that

[adam2392]

Maybe it would be easier to start with the A matrix being returned and plan to iterate on having it be an internal variable once there are more functions that depend on it. That would save a lot of coding on the front end by just adding a function to raw and then making an example using it...

Is the proposal then to:

1. add a mixin function to do this on Raw
2. unit test this using pt01 in https://openneuro.org/datasets/ds003029
3. make an example with the repairing epochs?

[alexrockhill]

Yeah maybe we can pop in to talk to @larsoner to make sure this isn't redundant with anything or not helpful to add

[adam2392]

To bring this under a statistical framework and treat "repairing" of Epochs as a regression problem for out-of-sample using the "not-noisy" epochs as our training data, we can also see if it is possible to add some basic "model-selection" procedure using cross-validation AIC/BIC (not sure if we can get a likelihood function here).

That is for repairing noisy data:

1. fit A matrix using a specific window size and other hyperparameters
2. compute cross-validation error
3. repeat fits for a few models
4. choose model w/ best cv error and use this model to repair

[adam2392]

https://www.dropbox.com/sh/bsufh5npukzqe59/AAC4G3RilD-sSA3jH1SL_qhpa?dl=0

[larsoner]

Rough summary of off-GH discussion:

1. PR to add ECoG seizure data, take care of dataset integration, "paradigm" narrative, show anything useful about the dataset: follow https://github.com/mne-tools/mne-python/pull/8867 for files to change
2. Implement new method, probably in mne/connectivity/spectral.py, probably as ndarray input, raw, or epochs data, and ndarray output of state-space A (estimate_lds or so?)

[agramfort]

do you know about this https://scot-dev.github.io/scot-doc/index.html?

I am wondering if we should not move / consolidate the connectivity stuff in a dedicated package outside of mne-python. Personally I would recommend to use the enveloppe correlation but the rest not sure. Maybe we just need a convincing tutorial on a relevant dataset?

[alexrockhill]

I think it's Adam's project so he probably thinks we should all use it for all our connectivity needs ;)

Looks really good but I do wonder if there aren't many ecog-specific connectivity methods that aren't better in a more generalized package although it does look as if scot is electrophysiology-specific.

We were talking about the other reasons for having good ieeg sample data so worth a try even if the good times of all connectivity methods accepted stop with us :)

[adam2392]

Related to just this PR, we simply want to expose tutorial of how to compute such things and how they might be useful in EEG/MEG/iEEG type analyses. As noted above, it has the added bonus of enabling dynamical system representations for "repairing" bad channel/epochs.

do you know about this https://scot-dev.github.io/scot-doc/index.html? I am wondering if we should not move / consolidate the connectivity stuff in a dedicated package outside of mne-python. Personally I would recommend to use the enveloppe correlation but the rest not sure. Maybe we just need a convincing tutorial on a relevant dataset?

Downstream this would be useful imo, since it would lower cognitive load. I could see there being use for having a separate package altogether for "mne-connectivity", where things such as correlation, coherence are implemented. In addition, notions of dynamical systems (i.e. linear dynamical system) can be implemented as well. The only issue is that one of the main reasons I love mne is the consistency that I can get the "data" matched with "metadata" such as the info object, and related that make working with this one data structure very easy.

I actually then wonder if something like mne-python can create a "DerivativeEEG" container that is analagous to BaseEstimator in sklearn? Then downstream packages can leverage this to implement resulting algorithms that work with mne-python?

[agramfort]

let's try to chat it will be easier

[adam2392]

Btw @alexrockhill spoke with @agramfort and he's opposed to adding this type of functionality into MNE-python. He thinks that it might be useful for a sub-group of us to try to band together w/ scot, and ppl here https://github.com/mne-tools/mne-python/issues/9030#issuecomment-802110862 to basically implement a 3rd-party mne-connectivity stand-alone package that:

1. takes out the current mne.connectivity module
2. implements anything suggested here e.g. state-space / lds modeling

I'm pretty open to this idea if there's enough ppl game. However, for my purposes I really only use lds modeling...

[adam2392]

Additional notes, so I dont' forget:

ask all people in scot/new connectivity indexes about forming into something like mne-connectivity, or outside the mne.tools even

• separate package
• see where ppl are at and how interested they are in developing/maintaing
• power_envelope_correlation: acknowledged as something that works
• how can we quantitatively evaluate algorithms in this package

Incentive: paper?

[drammock]

crossref to mne-tools/mne-connectivity#50 and cc @cmista and @jshanna100

[agramfort]

+100

[alexrockhill]

Additional notes, so I dont' forget:

ask all people in scot/new connectivity indexes about forming into something like mne-connectivity, or outside the mne.tools even

• separate package
• see where ppl are at and how interested they are in developing/maintaing
• power_envelope_correlation: acknowledged as something that works
• how can we quantitatively evaluate algorithms in this package

Incentive: paper?

I'm not sure I understand all the technical details for this implementation, but, to me, this seems a bit like a 'thin'/single-function API that wouldn't be suitable in JOSS for instance. Maybe I am mistaken about the scope of the implementation though.

There is somewhat of a precedent for gists that live outside of the package like the write edf function. Maybe there could be a bit of effort that I would be willing to help with/spearhead organizing these maybe somewhat like opencv-contrib-python where less stable, younger development projects are stored separately from the stable repository. I think this is what you were talking about with the idea of an mne-connectivity package which would be a bit more effort than just a gist but a good idea in the long run I think.

[drammock]

There is already https://github.com/mne-tools/mne-sandbox although it's been stagnant for a while...

[agramfort]

I would start from https://github.com/mne-tools/mne-project-template

and start putting there the various connectivity measure we have in mne-python and elsewhere

after the first release of "mne-connectivity" we should start deprecating the mne.connectivity module.

my 2c