dyconnmap.fc package¶
Submodules¶
dyconnmap.fc.aec module¶
Amplitude Envelope Correlation
Amplitude Envelope Correlation (AEC), estimates the coupling (without phase coherence and even among different frequencies [Bruns2000]) by computing the correlation coefficient of a signal’s amplitude envelope.
Where \(\alpha\) denotes the Instantaneous Amplitude of a given signal, filtered in a specfic frequency band (\(lo\) or \(hi\)).
- Bruns2000
Bruns, A., Eckhorn, R., Jokeit, H., & Ebner, A. (2000). Amplitude envelope correlation detects coupling among incoherent brain signals. Neuroreport, 11(7), 1509-1514.
- Penny2008
Penny, W. D., Duzel, E., Miller, K. J., & Ojemann, J. G. (2008). Testing for nested oscillation. Journal of neuroscience methods, 174(1), 50-61.
- Friston1996
Friston, K. J. (1997). Another neural code?. Neuroimage, 5(3), 213-220.
- dyconnmap.fc.aec.aec(data, fb_lo, fb_hi, fs)[source]¶
Amplitude Envelope Correlation
Estimate the Amplitude-Envelope Correlation for the given
data
.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
- Returns
r – Estimated Pearson correlation coefficient.
- Return type
array-like, shape(n_channels, n_channels)
dyconnmap.fc.biplv module¶
Bi-Phase Locking Value
- Darvas2009
Darvas, F., Ojemann, J. G., & Sorensen, L. B. (2009). Bi-phase locking—a tool for probing non-linear interaction in the human brain. NeuroImage, 46(1), 123-132.
- dyconnmap.fc.biplv.biplv(data, fb_lo, fb_hi, fs, pairs=None)[source]¶
Bi-Phase Locking Value
Estimate the Bi-Phase Locking Value for the given
data
, between the :attr:`pairs (if given) of channels- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
dyconnmap.fc.coherence module¶
Coherence
Coherence (Coh) is one of the most commonly utilized connectivity estimators; it is a measurement of the linear relationship of two signals at a specific frequency [Nolte2004].
Given two time series \(x\) and \(y\), coherece is given by:
Where \(G_{xy}(f)\) is the estimated cross-spectral density between \(x\) and \(y\), while \(G_{xx}(f)\) and \(G_{yy}(f)\) are the autospectrum of \(x\) and \(y\) respectively.
The result is a symmetric matrix of size \([n\_channels \times n\_channels]\) bearing no information about the directionality of the interaction, with values within the range \([0,1]\).
- Nolte2004
Nolte, G., Bai, O., Wheaton, L., Mari, Z., Vorbach, S., & Hallett, M. (2004). Identifying true brain interaction from EEG data using the imaginary part of coherency. Clinical neurophysiology, 115(10), 2292-2307.
- Thatcher2005
Thatcher, R. W., North, D., & Biver, C. (2005). EEG and intelligence: relations between EEG coherence, EEG phase delay and power. Clinical neurophysiology, 116(9), 2129-2141.
- Vinck2011
Vinck, M., Oostenveld, R., van Wingerden, M., Battaglia, F., & Pennartz, C. M. (2011). An improved index of phase-synchronization for electrophysiological data in the presence of volume-conduction, noise and sample-size bias. Neuroimage, 55(4), 1548-1565.
- class dyconnmap.fc.coherence.Coherence(fb, fs, pairs=None, **kwargs)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
An
dyconnmap.fc.Estimator
class that implementsdyconnmap.fc.coherence
.See also
dyconnmap.fc.coherence
Coherence
dyconnmap.tvfcg
Time-Varying Functional Connectivity Graphs
- estimate(data, data_against=None)[source]¶
- Returns
ts (complex array-like, shape(n_channels, n_channels, n_samples)) – Estimated PLV time series (complex valued).
avg (array-like, shape(n_channels, n_channels)) – Average PLV.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- dyconnmap.fc.coherence.coherence(data, fb, fs, pairs=None, **kwargs)[source]¶
Coherence
Estimate the Coherence for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
**kwargs – Keyword arguments to be passed to
matplotlib.mlab.csd()
.
- Returns
coh – Estimated Coherence.
- Return type
array-like, shape(n_channels, n_channels)
See also
dyconnmap.fc.Coherece
Coherece (Class Estimator)
dyconnmap.fc.icoherence
Imaginary Coherence
dyconnmap.fc.corr module¶
Correlation
@see https://docs.scipy.org/doc/numpy/reference/generated/numpy.corrcoef.html
- class dyconnmap.fc.corr.Corr(fb=None, fs=None, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Correlation
See also
dyconnmap.fc.corr
Correlation
dyconnmap.tvfcg
Time-Varying Functional Connectivity Graphs
- estimate(data, data_against=None)[source]¶
- Returns
r – Estimated correlation values.
- Return type
array-like, shape(n_rois, n_rois, n_samples)
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- estimate_pair(signal1, signal2)[source]¶
- Returns
r (array-like, shape(1, n_samples)) – Estimated correlation values (real valued).
_ (None) – None.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- dyconnmap.fc.corr.corr(data, fb=None, fs=None, pairs=None)[source]¶
Correlation
Compute the correlation for the given
data
, between thepairs
(if given) of channels.- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
r – Estimated correlation values.
- Return type
array-like, shape(n_rois, n_rois)
See also
dyconnmap.fc.Corr
Correlation
dyconnmap.fc.cos module¶
Cosine
- dyconnmap.fc.cos.cos(data: numpy.ndarray, fb: Optional[float] = None, fs: Optional[float] = None, pairs: Optional[List[List[int]]] = None)[source]¶
Cosine
Compute the correlation for the given
data
, between thepairs
(if given) of channels.- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
c – Estimated connectivity matrix.
- Return type
array-like, shape(n_rois, n_rois)
dyconnmap.fc.crosscorr module¶
Cross Correlation
see @https://docs.scipy.org/doc/numpy/reference/generated/numpy.correlate.html
dyconnmap.fc.dpli module¶
Directed Phase Lag Index
Directed Phase Lag Index (dPLI) was introduced in [Stam2012] to capture the phase and lag relationship as a measure of directed functional connectivity.
if \(0.5 \le dPLI_{xy} \leq 1.0\), \(x\) is leading \(y\)
if \(0.0 \leq dPLI_{xy} = 0.5\), \(y\) is leading \(x\)
if \(dPLI_{xy} = 0.5\), neither \(x\) nor \(y\) is leading or lagging
- Stam2012
Stam, C. J., & van Straaten, E. C. (2012). Go with the flow: use of a directed phase lag index (dPLI) to characterize patterns of phase relations in a large-scale model of brain dynamics. Neuroimage, 62(3), 1415-1428.
- dyconnmap.fc.dpli.dpli(data, fb, fs, pairs=None)[source]¶
Directed Phase Lag Index
Estimate the Directed Phase Lag Index for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
dpliv – Estimated Directed PLI.
- Return type
array-like, shape(n_channels, n_channels)
See also
dyconnmap.fc.PLI
Phase Lag Index
dyconnmap.fc.esc module¶
Envelope-to-Signal Correlation
Proposed by Bruns and Eckhorn [Bruns2004_], Envelope-to-Signal Correlation (ESC)
is similar to Amplitude Envelope Correlation (dyconnmap.fc.aec
), but the
the amplitude of the lower frequency oscillation is signed; and thus the phase
information is preserved.
Where \(\chi\) is the input signal filtered to the frequency band \(lo\) and \(\alpha\) denotes the Instantaneous Amplitude of the same input signal at the frequency band \(hi\).
- Bruns2004
Bruns, A., & Eckhorn, R. (2004). Task-related coupling from high-to low-frequency signals among visual cortical areas in human subdural recordings. International Journal of Psychophysiology, 51(2), 97-116.
- Penny2008
Penny, W. D., Duzel, E., Miller, K. J., & Ojemann, J. G. (2008). Testing for nested oscillation. Journal of neuroscience methods, 174(1), 50-61. Chicago
- dyconnmap.fc.esc.esc(data, fb_lo, fb_hi, fs)[source]¶
Envelope-Signal-Correlation
Estimate the Envelope-Signal-Correlation the given
data
.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
r – Estimated Pearson correlation coefficient.
- Return type
array-like, shape(n_channels, n_channels)
dyconnmap.fc.estimator module¶
Base class for estimators
- class dyconnmap.fc.estimator.Estimator(fb: Optional[float] = None, fs: Optional[float] = None, pairs: Optional[List[List[int]]] = None)[source]¶
Bases:
object
Base class for estimators.
Through this abstract class, an estimator can provide the necessary methods to be used for a time-varying functional connectivity analysis.
See also
dynfunconn.tvfcgs.tvfcgs
Time-Varying Functional Connectivity Graphs
dynfunconn.tvfcgs.tvfcgs_cfc
Time-Varying Functional Connectivity Graphs (for Cross frequency Coupling)
dynfunconn.tvfcgs.tvfcgs_ts
Time-Varying Functional Connectivity Graphs (from time series)
- estimate(data: numpy.ndarray, data_against: Optional[numpy.ndarray] = None)[source]¶
Estimate the connectivity within the given dataset.
- estimate_pair(signal1: numpy.ndarray, signal2: numpy.ndarray)[source]¶
Estimate the connectivity between two signals (time series).
Notes
This is invoked from cross-frequency coupling methods.
- mean(ts: numpy.ndarray)[source]¶
The function used to compute the mean synchronization in a timeseries.
This is needed because some estimators produce complex (imaginary), and special treatment is needed (i.e. taking only the real part).
- Returns
mtx – The average synchronization.
- Return type
array-like
dyconnmap.fc.glm module¶
General Linear Model
General linear modeling (GLM) is used widely in neuroimaging [Penny2006] to detect coupling between a low and higher frequency.
Where \(\beta\) are the corresponding regression coefficients and \(e\) is the additive Gaussian noise. Finally, \(X\) is the design matrix of size \(n \times 3\) (\(n\) the number of samples). Columns 1 and 2, contain the cosines and sines counterparts of the instantaneous phases (of the low frequency) of the predictors, while the third row only 1s.
- Penny2006
Penny, W. D., Friston, K. J., Ashburner, J. T., Kiebel, S. J., & Nichols, T. E. (Eds.). (2011). Statistical parametric mapping: the analysis of functional brain images. Academic press.
- Penny2008
Penny, W. D., Duzel, E., Miller, K. J., & Ojemann, J. G. (2008). Testing for nested oscillation. Journal of neuroscience methods, 174(1), 50-61.
- dyconnmap.fc.glm.glm(data, fb_lo, fb_hi, fs, pairs=None, window_size=- 1)[source]¶
General Linear Model
Estimate the \(r^2\) for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
window_size (int) – The number of samples that will be used in each window.
- Returns
ts (complex array-like, shape(n_windows, n_channels, n_channels)) – Estimated \(r^2\) time series (in each window).
ts_avg (complex array-like, shape(n_channels, n_channels)) – Average \(r^2\) (across all windows).
dyconnmap.fc.icoherence module¶
Imaginary Coherence
Imaginary Coherence (ICoh)
Nolte, G., Bai, O., Wheaton, L., Mari, Z., Vorbach, S., & Hallett, M. (2004). Identifying true brain interaction from EEG data using the imaginary part of coherency. Clinical neurophysiology, 115(10), 2292-2307. Chicago
- class dyconnmap.fc.icoherence.ICoherence(fb, fs, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Imaginary Coherence
- dyconnmap.fc.icoherence.icoherence(data, fb, fs, pairs=None, **kwargs)[source]¶
Imaginary Coherence
Compute the Imaginary part of Coherence for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
**kwargs – Keyword arguments to be passed to
matplotlib.mlab.csd()
.
- Returns
icoh – Estimated Imaginary part of Coherence.
- Return type
array-like, shape(n_channels, n_channels)
See also
dyconnmap.fc.coherence
Coherence
dyconnmap.fc.iplv module¶
Imaginary part of Phase Locking Value
Imaginary Phase Locking Value (IPLV) was proposed to resolve PLV’s sensitivity to volume conduction and common reference effects.
IPLV is computed similarly as PLV, but taking the imaginary part of the summation:
- Sadaghiani2012
Sadaghiani, S., Scheeringa, R., Lehongre, K., Morillon, B., Giraud, A. L., D’Esposito, M., & Kleinschmidt, A. (2012). Alpha-band phase synchrony is related to activity in the fronto-parietal adaptive control network. The Journal of Neuroscience, 32(41), 14305-14310.
- class dyconnmap.fc.iplv.IPLV(fb=None, fs=None, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Imaginary part of PLV (iPLV)
See also
dyconnmap.fc.iplv
Imaginary part of PLV
dyconnmap.fc.plv
Phase Locking Value
dyconnmap.tvfcg
Time-Varying Functional Connectivity Graphs
- estimate(data)[source]¶
- Returns
ts
avg
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- estimate_pair(ts1, ts2)[source]¶
- Returns
ts (array-like, shape(1, n_samples)) – Estimated iPLV time series.
avg (float) – Average iPLV.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- dyconnmap.fc.iplv.iplv(data, fb=None, fs=None, pairs=None)[source]¶
Imaginary part of Phase Locking Value
Compute the Imaginary part of Phase Locking Value for the given data, between the pairs (if given) of rois.
- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
ts (array-like, shape(n_rois, n_rois, n_samples)) – Estimated IPLV time series.
avg (array-like, shape(n_rois, n_rois)) – Average IPLV.
dyconnmap.fc.mui module¶
Mutual Information
Mutual Information (MI),
- Vinck2011
Vinck, M., Oostenveld, R., van Wingerden, M., Battaglia, F., & Pennartz, C. M. (2011). An improved index of phase-synchronization for electrophysiological data in the presence of volume-conduction, noise and sample-size bias. Neuroimage, 55(4), 1548-1565.
dyconnmap.fc.nesc module¶
Amplitude-Normalized Envelope-to-Signal Correlation
- Penny2008
Penny, W. D., Duzel, E., Miller, K. J., & Ojemann, J. G. (2008). Testing for nested oscillation. Journal of neuroscience methods, 174(1), 50-61. Chicago
- Bruns2004
Bruns, A., & Eckhorn, R. (2004). Task-related coupling from high-to low-frequency signals among visual cortical areas in human subdural recordings. International Journal of Psychophysiology, 51(2), 97-116.
- dyconnmap.fc.nesc.nesc(data, f_lo, f_hi, fs, pairs=None)[source]¶
Amplitude-Normalized Envelope-to-Signal-Correlation
- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
r – Estimated Pearson correlation coefficient.
- Return type
array-like, shape(n_channels, n_channels)
dyconnmap.fc.pac module¶
Phase-Amplitude Coupling
Phase-Amplitude Coupling (PAC) is the most famous and prominent approach for studuying the Cross Frequency Coupling between slow and faster oscillations. The phase of a low frequency drive the power of a higher frequency.
- class dyconnmap.fc.pac.PAC(f_lo, f_hi, fs, estimator, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Phase Amplitude Coupling (PAC)
- estimate_pair(phase1, phase1_lohi)[source]¶
Estimate the connectivity between two signals (time series).
Notes
This is invoked from cross-frequency coupling methods.
- dyconnmap.fc.pac.pac(data, f_lo, f_hi, fs, estimator, pairs=None)[source]¶
Phase-Amplitude Coupling
Compute the Phase Amplitude Couplgin using the given estimator for the given data, between the specified pairs of channels.
- Parameters
data (array-like, shape = [n_electrodes, n_samples]) – Multichannel recording data.
pairs (array-like) – Each element is a tuple of length two.
f_lo (list of length 2) – The low and high frequencies.
f_hi (list of length 2) – The low and high frequencies.
fs (float) – Sampling frequency.
estimator (iplv | plv | pli | corr) –
Estimator used Valid options:
’iplv’ : Imaginary Phase Locking Value ‘plv’ : Phase Locking Value ‘pli’ : Phase Lag Index
- Returns
ts (complex array-like, shape = [n_electrodes, n_electrodes, n_samples]) – The PAC computed each time series.
avg (complex array-like, shape = [n_electrodes, n_electrodes]) – The average PAC across all samples.
dyconnmap.fc.partcorr module¶
Partial Correlation
dyconnmap.fc.pec module¶
Power-Envelope Correlation
Similarly to dyconnmap.fc.aec
, we can use the followig formula to estimate the correlations in power
between the different frequency bands [Friston1996].
- Hipp2012
Hipp, J. F., Hawellek, D. J., Corbetta, M., Siegel, M., & Engel, A. K. (2012). Large-scale cortical correlation structure of spontaneous oscillatory activity. Nature neuroscience, 15(6), 884-890.
- dyconnmap.fc.pec.pec(data, fb_lo, fb_hi, fs)[source]¶
Power Envelope Correlation
- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
- Returns
r – Estimated Pearson correlation coefficient.
- Return type
array-like, shape(n_channels, n_channels)
dyconnmap.fc.pli module¶
Phase Lag Index
Phase Lag Index (PLI) [Stam2007], proposed as an alternative (to PLV) phase synchronization estimator that is less prone to the effects of common sources (namely, volume conduction and active reference electrodes). These effects can artificially generate functional connectivity as the same signal signal is measured at different electrodes [Hardmeier2014].
PLI estimates the asymmetry in the distribution of two time series’ instantaneous phase differences.
Given two time series of equal length \(x(t)\) and \(y(t)\), we extract
their respective instantaneous phases \(\phi_x(t)\) and \(\phi_y(t)\)
using the Hilbert transform (consult dyconnmap.analytic_signal
for
more details).
Then, for such a pair of phases, PLI is computed as follows:
Where, \(sign\) refers to the signum function, left langle right rangle denotes the mean value and || the absolute value.
- Stam2007
Stam, C. J., Nolte, G., & Daffertshofer, A. (2007). Phase lag index: assessment of functional connectivity from multi channel EEG and MEG with diminished bias from common sources. Human brain mapping, 28(11), 1178-1193.
- Hardmeier2014
Hardmeier, M., Hatz, F., Bousleiman, H., Schindler, C., Stam, C. J., & Fuhr, P. (2014). Reproducibility of functional connectivity and graph measures based on the phase lag index (PLI) and weighted phase lag index (wPLI) derived from high resolution EEG. PloS one, 9(10), e108648.
- class dyconnmap.fc.pli.PLI(fb=None, fs=None, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Phase Lag Index (PLI)
- estimate_pair(signal1, signal2)[source]¶
Estimate the connectivity between two signals (time series).
Notes
This is invoked from cross-frequency coupling methods.
- dyconnmap.fc.pli.pli(data, fb=None, fs=None, pairs=None)[source]¶
Phase Lag Index
Compute the PLI for the given
data
, between thepairs
(if given) of channels.- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
ts (array-like, shape(n_rois, n_rois, n_samples)) – Estimated PLI time series.
avg (array-like, shape(n_rois, n_rois)) – Average PLI.
See also
dyconnmap.fc.PLI
Phase Lag Index
dyconnmap.fc.plv module¶
Phase Locking Value
One of the pioneer methods called Phase Locking Value (PLV) is discussed in
[Lachaux1998]; it utilizes the Hilbert representation (consult
dyconnmap.analytic_signal
for more details) an EEG time
series (of \(N_{sensors}\)) and quantifies their interaction based on their
instantaneous phase in a specific band frequency.
So, for a pair of Instantaneous Phases of two time series of equal length, \(\phi_{j1}(t)\) and \(\phi_{j2}(t)\), the Phase Locking Value for each sample in time (\(t\)) is computed as:
A value of zero means that no coupling (or negligible) observed between two phases, while a value of one denotes a perfect synchronization.
- Lachaux1998
Lachaux, J., Rodriguez, E., Martinerie, J., Varela, F., & others,. (1999). Measuring phase synchrony in brain signals. Human Brain Mapping, 8(4), 194-208.
- class dyconnmap.fc.plv.PLV(fb=None, fs=None, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Phase Locking Value (PLV)
See also
dyconnmap.fc.plv
Phase Locking Value
dyconnmap.tvfcg
Time-Varying Functional Connectivity Graphs
- estimate(data, data_against=None)[source]¶
- Returns
ts (complex array-like, shape(n_channels, n_channels, n_samples)) – Estimated PLV time series (complex valued).
avg (array-like, shape(n_channels, n_channels)) – Average PLV.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- estimate_pair(signal1, signal2)[source]¶
- Returns
ts (array-like, shape(1, n_samples)) – Estimated PLV time series (real valued).
avg (float) – Average PLV.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- dyconnmap.fc.plv.plv(data, fb=None, fs=None, pairs=None)[source]¶
Phase Locking Value
Compute the PLV for the given
data
, between thepairs
(if given) of channels.- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
ts (array-like, shape(n_rois, n_rois, n_samples)) – Estimated PLV time series.
avg (array-like, shape(n_rois, n_rois)) – Average PLV.
See also
dyconnmap.fc.PLV
Phase Locking Value (Class Estimator)
dyconnmap.fc.iplv
Imaginary part of PLV
dyconnmap.fc.pli
Phase Lag Index
dyconnmap.fc.rho_index module¶
ρ index
Where \(H\) is the Shannon entropy estimated within \(M\) number of phase bins, and \(H_{max} = ln(M)\) is the maximal entropy and and \(p_k\) is the relative frequency of finding frequency difference in the \(k\) th phase bin.
The computed value varies within the range \([0, 1]\)
- Tass1998
Tass, P., Rosenblum, M. G., Weule, J., Kurths, J., Pikovsky, A., Volkmann, J., … & Freund, H. J. (1998). Detection of n: m phase locking from noisy data: application to magnetoencephalography. Physical review letters, 81(15), 3291.
- dyconnmap.fc.rho_index.rho_index(data, n_bins, fb, fs, pairs=None)[source]¶
Synchronization Index
Compute the synchronization index for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
n_bins (int) – Number of bins.
fb (list of length 2) – The low and high frequencies.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
rho – Estimated rho index.
- Return type
array-likem, shape(n_channels, n_channels)
dyconnmap.fc.wpli module¶
Weighted Phase Lag Index and Debiased Weighted Phase Lag Index
PLI is prone to noise and volume conduction effects; thus, Weighted Lag Index (wPLI) [Vinck2011] was proposed in [Vinck, 2011] alongside with an alternative, debiased design (dwPLI). Similar to PLI, wPLI operates on the cross-spectrum of two real-valued signals; but, it furthermore weights the cross-spectrum with the magnitude of the imaginary component.
Furthermore, to overcome the possible sample-bias, the authors defined a debiased variant of wPLI:
- Vinck2011
Vinck, M., Oostenveld, R., van Wingerden, M., Battaglia, F., & Pennartz, C. M. (2011). An improved index of phase-synchronization for electrophysiological data in the presence of volume-conduction, noise and sample-size bias. Neuroimage, 55(4), 1548-1565.
- dyconnmap.fc.wpli.dwpli(data, fb, fs, pairs=None, **kwargs)[source]¶
Debiased Weighted Phase Lag Index
Compute the Debiased Weight Phase Lad Index for the given data, between the specified pairs of channels.
- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
**kwargs – Keyword arguments to be passed to
matplotlib.mlab.csd()
.
- Returns
dwpli – Estimated Debiased Weighted PLI.
- Return type
array-like, shape(n_channels, n_channels)
dyconnmap.wpli.wpli: Weighted Phase Lag Index
- dyconnmap.fc.wpli.wpli(data, fb, fs, pairs=None, **kwargs)[source]¶
Weighted Phase Lag Index
Compute the Weight Phase Lad Index for the given data, between the specified pairs of channels.
- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
**kwargs – Keyword arguments to be passed to
matplotlib.mlab.csd()
.
- Returns
wpli – Estimated Weighted PLI.
- Return type
array-like, shape(n_channels, n_channels)
Notes
The resulting wpli value has a phase shift.
The results do not match those from MATLAB because of the mlab.cpsd.
dyconnmap.wpli.dwpli: Debiased Weighted Phase Lag Index
Module contents¶
- class dyconnmap.fc.Coherence(fb, fs, pairs=None, **kwargs)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
An
dyconnmap.fc.Estimator
class that implementsdyconnmap.fc.coherence
.See also
dyconnmap.fc.coherence
Coherence
dyconnmap.tvfcg
Time-Varying Functional Connectivity Graphs
- estimate(data, data_against=None)[source]¶
- Returns
ts (complex array-like, shape(n_channels, n_channels, n_samples)) – Estimated PLV time series (complex valued).
avg (array-like, shape(n_channels, n_channels)) – Average PLV.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- class dyconnmap.fc.Corr(fb=None, fs=None, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Correlation
See also
dyconnmap.fc.corr
Correlation
dyconnmap.tvfcg
Time-Varying Functional Connectivity Graphs
- estimate(data, data_against=None)[source]¶
- Returns
r – Estimated correlation values.
- Return type
array-like, shape(n_rois, n_rois, n_samples)
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- estimate_pair(signal1, signal2)[source]¶
- Returns
r (array-like, shape(1, n_samples)) – Estimated correlation values (real valued).
_ (None) – None.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- class dyconnmap.fc.Estimator(fb: Optional[float] = None, fs: Optional[float] = None, pairs: Optional[List[List[int]]] = None)[source]¶
Bases:
object
Base class for estimators.
Through this abstract class, an estimator can provide the necessary methods to be used for a time-varying functional connectivity analysis.
See also
dynfunconn.tvfcgs.tvfcgs
Time-Varying Functional Connectivity Graphs
dynfunconn.tvfcgs.tvfcgs_cfc
Time-Varying Functional Connectivity Graphs (for Cross frequency Coupling)
dynfunconn.tvfcgs.tvfcgs_ts
Time-Varying Functional Connectivity Graphs (from time series)
- estimate(data: numpy.ndarray, data_against: Optional[numpy.ndarray] = None)[source]¶
Estimate the connectivity within the given dataset.
- estimate_pair(signal1: numpy.ndarray, signal2: numpy.ndarray)[source]¶
Estimate the connectivity between two signals (time series).
Notes
This is invoked from cross-frequency coupling methods.
- mean(ts: numpy.ndarray)[source]¶
The function used to compute the mean synchronization in a timeseries.
This is needed because some estimators produce complex (imaginary), and special treatment is needed (i.e. taking only the real part).
- Returns
mtx – The average synchronization.
- Return type
array-like
- class dyconnmap.fc.IPLV(fb=None, fs=None, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Imaginary part of PLV (iPLV)
See also
dyconnmap.fc.iplv
Imaginary part of PLV
dyconnmap.fc.plv
Phase Locking Value
dyconnmap.tvfcg
Time-Varying Functional Connectivity Graphs
- estimate(data)[source]¶
- Returns
ts
avg
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- estimate_pair(ts1, ts2)[source]¶
- Returns
ts (array-like, shape(1, n_samples)) – Estimated iPLV time series.
avg (float) – Average iPLV.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- class dyconnmap.fc.PAC(f_lo, f_hi, fs, estimator, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Phase Amplitude Coupling (PAC)
- estimate_pair(phase1, phase1_lohi)[source]¶
Estimate the connectivity between two signals (time series).
Notes
This is invoked from cross-frequency coupling methods.
- class dyconnmap.fc.PLI(fb=None, fs=None, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Phase Lag Index (PLI)
- estimate_pair(signal1, signal2)[source]¶
Estimate the connectivity between two signals (time series).
Notes
This is invoked from cross-frequency coupling methods.
- class dyconnmap.fc.PLV(fb=None, fs=None, pairs=None)[source]¶
Bases:
dyconnmap.fc.estimator.Estimator
Phase Locking Value (PLV)
See also
dyconnmap.fc.plv
Phase Locking Value
dyconnmap.tvfcg
Time-Varying Functional Connectivity Graphs
- estimate(data, data_against=None)[source]¶
- Returns
ts (complex array-like, shape(n_channels, n_channels, n_samples)) – Estimated PLV time series (complex valued).
avg (array-like, shape(n_channels, n_channels)) – Average PLV.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- estimate_pair(signal1, signal2)[source]¶
- Returns
ts (array-like, shape(1, n_samples)) – Estimated PLV time series (real valued).
avg (float) – Average PLV.
Notes
Called from
dyconnmap.tvfcgs.tvfcg
.
- dyconnmap.fc.aec(data, fb_lo, fb_hi, fs)[source]¶
Amplitude Envelope Correlation
Estimate the Amplitude-Envelope Correlation for the given
data
.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
- Returns
r – Estimated Pearson correlation coefficient.
- Return type
array-like, shape(n_channels, n_channels)
- dyconnmap.fc.coherence(data, fb, fs, pairs=None, **kwargs)[source]¶
Coherence
Estimate the Coherence for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
**kwargs – Keyword arguments to be passed to
matplotlib.mlab.csd()
.
- Returns
coh – Estimated Coherence.
- Return type
array-like, shape(n_channels, n_channels)
See also
dyconnmap.fc.Coherece
Coherece (Class Estimator)
dyconnmap.fc.icoherence
Imaginary Coherence
- dyconnmap.fc.corr(data, fb=None, fs=None, pairs=None)[source]¶
Correlation
Compute the correlation for the given
data
, between thepairs
(if given) of channels.- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
r – Estimated correlation values.
- Return type
array-like, shape(n_rois, n_rois)
See also
dyconnmap.fc.Corr
Correlation
- dyconnmap.fc.cos(data: numpy.ndarray, fb: Optional[float] = None, fs: Optional[float] = None, pairs: Optional[List[List[int]]] = None)[source]¶
Cosine
Compute the correlation for the given
data
, between thepairs
(if given) of channels.- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
c – Estimated connectivity matrix.
- Return type
array-like, shape(n_rois, n_rois)
- dyconnmap.fc.dpli(data, fb, fs, pairs=None)[source]¶
Directed Phase Lag Index
Estimate the Directed Phase Lag Index for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
dpliv – Estimated Directed PLI.
- Return type
array-like, shape(n_channels, n_channels)
See also
dyconnmap.fc.PLI
Phase Lag Index
- dyconnmap.fc.dwpli(data, fb, fs, pairs=None, **kwargs)[source]¶
Debiased Weighted Phase Lag Index
Compute the Debiased Weight Phase Lad Index for the given data, between the specified pairs of channels.
- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
**kwargs – Keyword arguments to be passed to
matplotlib.mlab.csd()
.
- Returns
dwpli – Estimated Debiased Weighted PLI.
- Return type
array-like, shape(n_channels, n_channels)
dyconnmap.wpli.wpli: Weighted Phase Lag Index
- dyconnmap.fc.esc(data, fb_lo, fb_hi, fs)[source]¶
Envelope-Signal-Correlation
Estimate the Envelope-Signal-Correlation the given
data
.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
r – Estimated Pearson correlation coefficient.
- Return type
array-like, shape(n_channels, n_channels)
- dyconnmap.fc.glm(data, fb_lo, fb_hi, fs, pairs=None, window_size=- 1)[source]¶
General Linear Model
Estimate the \(r^2\) for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
window_size (int) – The number of samples that will be used in each window.
- Returns
ts (complex array-like, shape(n_windows, n_channels, n_channels)) – Estimated \(r^2\) time series (in each window).
ts_avg (complex array-like, shape(n_channels, n_channels)) – Average \(r^2\) (across all windows).
- dyconnmap.fc.icoherence(data, fb, fs, pairs=None, **kwargs)[source]¶
Imaginary Coherence
Compute the Imaginary part of Coherence for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
**kwargs – Keyword arguments to be passed to
matplotlib.mlab.csd()
.
- Returns
icoh – Estimated Imaginary part of Coherence.
- Return type
array-like, shape(n_channels, n_channels)
See also
dyconnmap.fc.coherence
Coherence
- dyconnmap.fc.iplv(data, fb=None, fs=None, pairs=None)[source]¶
Imaginary part of Phase Locking Value
Compute the Imaginary part of Phase Locking Value for the given data, between the pairs (if given) of rois.
- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
ts (array-like, shape(n_rois, n_rois, n_samples)) – Estimated IPLV time series.
avg (array-like, shape(n_rois, n_rois)) – Average IPLV.
- dyconnmap.fc.nesc(data, f_lo, f_hi, fs, pairs=None)[source]¶
Amplitude-Normalized Envelope-to-Signal-Correlation
- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
r – Estimated Pearson correlation coefficient.
- Return type
array-like, shape(n_channels, n_channels)
- dyconnmap.fc.pac(data, f_lo, f_hi, fs, estimator, pairs=None)[source]¶
Phase-Amplitude Coupling
Compute the Phase Amplitude Couplgin using the given estimator for the given data, between the specified pairs of channels.
- Parameters
data (array-like, shape = [n_electrodes, n_samples]) – Multichannel recording data.
pairs (array-like) – Each element is a tuple of length two.
f_lo (list of length 2) – The low and high frequencies.
f_hi (list of length 2) – The low and high frequencies.
fs (float) – Sampling frequency.
estimator (iplv | plv | pli | corr) –
Estimator used Valid options:
’iplv’ : Imaginary Phase Locking Value ‘plv’ : Phase Locking Value ‘pli’ : Phase Lag Index
- Returns
ts (complex array-like, shape = [n_electrodes, n_electrodes, n_samples]) – The PAC computed each time series.
avg (complex array-like, shape = [n_electrodes, n_electrodes]) – The average PAC across all samples.
- dyconnmap.fc.pec(data, fb_lo, fb_hi, fs)[source]¶
Power Envelope Correlation
- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb_lo (list of length 2) – The low and high frequencies of the lower band.
fb_hi (list of length 2) – The low and high frequencies of the upper band.
fs (float) – Sampling frequency.
- Returns
r – Estimated Pearson correlation coefficient.
- Return type
array-like, shape(n_channels, n_channels)
- dyconnmap.fc.pli(data, fb=None, fs=None, pairs=None)[source]¶
Phase Lag Index
Compute the PLI for the given
data
, between thepairs
(if given) of channels.- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
ts (array-like, shape(n_rois, n_rois, n_samples)) – Estimated PLI time series.
avg (array-like, shape(n_rois, n_rois)) – Average PLI.
See also
dyconnmap.fc.PLI
Phase Lag Index
- dyconnmap.fc.plv(data, fb=None, fs=None, pairs=None)[source]¶
Phase Locking Value
Compute the PLV for the given
data
, between thepairs
(if given) of channels.- Parameters
data (array-like, shape(n_rois, n_samples)) – Multichannel recording data.
fb (list of length 2, optional) – The low and high frequencies.
fs (float, optional) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
ts (array-like, shape(n_rois, n_rois, n_samples)) – Estimated PLV time series.
avg (array-like, shape(n_rois, n_rois)) – Average PLV.
See also
dyconnmap.fc.PLV
Phase Locking Value (Class Estimator)
dyconnmap.fc.iplv
Imaginary part of PLV
dyconnmap.fc.pli
Phase Lag Index
- dyconnmap.fc.rho_index(data, n_bins, fb, fs, pairs=None)[source]¶
Synchronization Index
Compute the synchronization index for the given
data
, between the :attr:`pairs (if given) of channels.- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
n_bins (int) – Number of bins.
fb (list of length 2) – The low and high frequencies.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
- Returns
rho – Estimated rho index.
- Return type
array-likem, shape(n_channels, n_channels)
- dyconnmap.fc.wpli(data, fb, fs, pairs=None, **kwargs)[source]¶
Weighted Phase Lag Index
Compute the Weight Phase Lad Index for the given data, between the specified pairs of channels.
- Parameters
data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.
fb (list of length 2) – The lower and upper frequency.
fs (float) – Sampling frequency.
pairs (array-like or None) –
If an array-like is given, notice that each element is a tuple of length two.
If None is passed, complete connectivity will be assumed.
**kwargs – Keyword arguments to be passed to
matplotlib.mlab.csd()
.
- Returns
wpli – Estimated Weighted PLI.
- Return type
array-like, shape(n_channels, n_channels)
Notes
The resulting wpli value has a phase shift.
The results do not match those from MATLAB because of the mlab.cpsd.
dyconnmap.wpli.dwpli: Debiased Weighted Phase Lag Index