[GSOC] Expand multivariate methods to support >1 component

[tsbinns]

Background

@larsoner @wmvanvliet @drammock

A key limitation with the existing implementation of multivariate connectivity methods in spectral_connectivity_epochs() and spectral_connectivity_time() is the fact that for the CaCoh and MIC methods, the connectivity estimates for only the first, strongest component is returned (i.e. the component with maximised connectivity). However, the other, weaker components of connectivity can still contain relevant information, just as is the case for other eigendecomposition-based optimisation methods like CSP or SSD.

New features

As part of GSoC, we proposed expanding support for the number of connectivity components which can be returned to more than just the first.

One option is to add an n_components argument to spectral_connectivity_epochs() and spectral_connectivity_time(), just like for the CSP and SSD classes of MNE-Python's decoding module. To ensure compatibility with the existing behaviour, this parameter could have a default value of 1 (or also None; not sure if there is convention in MNE that should be followed??). Otherwise, if n_components was specified to be >1:

• we should check that n_components does not exceed the minimum rank of the seeds and targets.
  • e.g. if the seed channels had a rank of 5 and the target channels a rank of 3, n_components must be <= 3; it does not make sense conceptually to expand the number of connectivity components beyond this minimal value, e.g. use seed filters no. 4 & 5 with target filter no. 3.
• when computing connectivity, the specified number of n_components should be taken from the filters (these filters are already computed in the eigendecompositon, just not being used).
• the patterns for each used filter should also be computed (currently only the patterns for the first filter are being computed).
• store the connectivity/pattern components in the returned connectivity object.
  • what dimensions the connectivity results take: [connections x components x frequencies (x times)]? [connections x frequencies (x times) x components]?
  • do we create a new set of classes for storing results with a components dimension, or use the existing classes? Back when we were intially implementing the multivariate methods I recall @adam2392 suggesting the possibility of a connectivity class with an open-ended number of dimensions.

There are definitely some implementation details which will need to be discussed, particularly regarding storage of the results.

Examples/tutorials

I am open to either adding a short section to the existing CaCoh and MIC examples which show how the n_components argument can be used and how the results for different components can be interpreted, or perhaps it makes sense to have a separate tutorial (they are already quite long). Very open to your feedback on this.

Unit tests

This should be a simple case of accounting for the new n_components parameter and expanding the existing tests where necessary.

Timeline

This was estimated to be a small part of the GSoC project, and has been planned to take place for the duration of July, accounting for the fact that this change will also affect the new 'decoding' module (see #182 ) for which unit tests and tutorials will need to be adjusted.

[tsbinns]

Sorted in #213