563 add channelcmb parameter to connectivityanalysis frontend

[tensionhead]

Changes Summary

• new parameter channelcmb=[senders, receivers] for spy.connectivityanalysis
• selectdata now allow non-contiguous and unorderd channel_i and channel_j selections, there was no reason apparent why this was not allowed before (I did not fiddle with any selection mechanics inside the Selector)

Now users can fine tune the channel-pairs for which to compute the connectivity measure as in FieldTrip:

senders = [0, 3] 
receivers = [1, 5, 8]
spy.connectivityanalysis(..., channelcmb=[senders, receivers])

will compute only 6 pairs: (01, 05, 08, 31, 35, 38) and the resulting CrossSpectralData is rectangular in the channel axes with channel_i=senders and channel_j=receivers.

Note: the old way of doing a channel selection on the input:

spy.connectivityanalysis(..., select={'channel': [0, 1, 3, 5, 8]})

would instead compute 20 pairs (+diagonal): the full dyadic (or tensor) product of those 5 channels.

Implementation differs according to the method

Granger causality

• computes all pairs individually, so in the example above this would be 6 spectral factorizations of 2 x 2 matrices. The result gets collected into a single 1 x nFreq x 2 x 3 CrossSpectralData object. The factorization algorithm is most stable when only computing pairs, however for many trials/few channels it would be much more effective to compute more pairs at once.

CSD/PPC

• the sender/receiver pairs get directly indexed within the cF (so the numpy arrays), and the single trial cross-spectra have rectangular shape. It was straightforward inputting this into the PPC algorithm, to compute the PPC only for the desired pairs.

Coherence

• rectangular single trial cross-spectra are not an easy option here, as the individual auto-spectra (diagonal in the full dyadic case) are needed for normalization. However, since computation is extremely cheap, all what is done is a simple post-selection of the channel_i/senders channel_j/receivers combinations which now is possible.

Limitations

• only for spectral methods ('coh', 'csd', 'ppc', 'granger')
• works only for spectral input (SpectralData) as re-writing the whole implicit freqanalysis part when inputting AnalogData into connectivityanalysis would require some bigger refactoring (design is actually bad for historic reasons)
• general inplace selections on the input are still fine of course, but channel selections don't work together with channelcmb

Reviewer Checklist

• Are testing routines present?
• Do objects in the global package namespace perform proper parsing of their input?
• Are all docstrings complete and accurate?
• Is the CHANGELOG.md up to date?

[codecov]

Codecov Report

Patch coverage: 76.10% and project coverage change: +0.01% 🎉

Comparison is base (86234a8) 69.31% compared to head (765cf77) 69.33%.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #565      +/-   ##
==========================================
+ Coverage   69.31%   69.33%   +0.01%     
==========================================
  Files          87       87              
  Lines       10123    10213      +90     
  Branches     2125     2151      +26     
==========================================
+ Hits         7017     7081      +64     
- Misses       2533     2545      +12     
- Partials      573      587      +14     

Files Changed	Coverage Δ
syncopy/shared/parsers.py	74.77% <0.00%> (+1.76%)	⬆️
syncopy/connectivity/connectivity_analysis.py	79.85% <71.11%> (-4.46%)	⬇️
syncopy/connectivity/ST_compRoutines.py	92.56% <100.00%> (+0.53%)	⬆️
syncopy/datatype/selector.py	73.17% <100.00%> (-0.06%)	⬇️
syncopy/shared/computational_routine.py	78.89% <100.00%> (+0.55%)	⬆️

... and 4 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[dfsp-spirit]

Wow, great to hear that you did not have to mess with the Selector logic at all to allow non-contiguous and unorderd channel_i and channel_j selections.

[dfsp-spirit]

Thanks a lot, this will make the code for the paper look a lot better.