Connectivity¶
Connectivity methods classes.
-
connectivipy.conn.
spectrum
(acoef, vcoef, fs=1, resolution=100)[source]¶ Generating data point from matrix A with MVAR coefficients. Args:
- acoef : numpy.array
- array of shape (k, k, p) where k is number of channels and p is a model order.
- vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- Returns:
- A_z : numpy.array
- z-transformed A(f) complex matrix in shape (resolution, k, k)
- H_z : numpy.array
- inversion of A_z
- S_z : numpy.array
- spectrum matrix (resolution, k, k)
References: .. [1] K. J. Blinowska, R. Kus, M. Kaminski (2004) “Granger causality
and information flow in multivariate processes” Physical Review E 70, 050902.
-
connectivipy.conn.
spectrum
(acoef, vcoef, fs=1, resolution=100)[source] Generating data point from matrix A with MVAR coefficients. Args:
- acoef : numpy.array
- array of shape (k, k, p) where k is number of channels and p is a model order.
- vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- Returns:
- A_z : numpy.array
- z-transformed A(f) complex matrix in shape (resolution, k, k)
- H_z : numpy.array
- inversion of A_z
- S_z : numpy.array
- spectrum matrix (resolution, k, k)
References: .. [1] K. J. Blinowska, R. Kus, M. Kaminski (2004) “Granger causality
and information flow in multivariate processes” Physical Review E 70, 050902.
-
connectivipy.conn.
spectrum_inst
(acoef, vcoef, fs=1, resolution=100)[source]¶ Generating data point from matrix A with MVAR coefficients taking into account zero-lag effects. Args:
- acoef : numpy.array
- array of shape (k, k, p+1) where k is number of channels and p is a model order. acoef[0] - is (k, k) matrix for zero lag, acoef[1] for one data point lag and so on.
- vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- Returns:
- A_z : numpy.array
- z-transformed A(f) complex matrix in shape (resolution, k, k)
- H_z : numpy.array
- inversion of A_z
- S_z : numpy.array
- spectrum matrix (resolution, k, k)
References: .. [1] Erla S. et all, Multivariate Autoregressive Model with
Instantaneous Effects to Improve Brain Connectivity Estimation, Int. J. Bioelectromagn. 11, 74–79 (2009).
-
connectivipy.conn.
spectrum_inst
(acoef, vcoef, fs=1, resolution=100)[source] Generating data point from matrix A with MVAR coefficients taking into account zero-lag effects. Args:
- acoef : numpy.array
- array of shape (k, k, p+1) where k is number of channels and p is a model order. acoef[0] - is (k, k) matrix for zero lag, acoef[1] for one data point lag and so on.
- vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- Returns:
- A_z : numpy.array
- z-transformed A(f) complex matrix in shape (resolution, k, k)
- H_z : numpy.array
- inversion of A_z
- S_z : numpy.array
- spectrum matrix (resolution, k, k)
References: .. [1] Erla S. et all, Multivariate Autoregressive Model with
Instantaneous Effects to Improve Brain Connectivity Estimation, Int. J. Bioelectromagn. 11, 74–79 (2009).
-
class
connectivipy.conn.
Connect
[source]¶ Abstract class governing calculation of various connectivity estimators with concrete methods: short_time, significance and abstract calculate.
-
short_time
(data, nfft=None, no=None, **params)[source]¶ Short-tme version of estimator, where data is windowed into parts of length nfft and overlap no. params catch additional parameters specific for estimator. Args:
- data : numpy.array
- data matrix (kXN) or (kXNxR) where k - channels, N - data points, R - nr of trials
- nfft = None : int
- window length (if None it’s N/5)
- no = None : int
- overlap length (if None it’s N/10)
- params :
- additional parameters specific for chosen estimator
- Returns:
- stvalues : numpy.array
- short time values (time points, frequency, k, k), where k is number of channels
-
short_time_significance
(data, Nrep=10, alpha=0.05, nfft=None, no=None, verbose=True, **params)[source]¶ Significance of short-tme versions of estimators. It base on bootstrap
Connect.bootstrap()
for multitrial case and surrogate dataConnect.surrogate()
for one trial. Args:- data : numpy.array
- data matrix (kXN) or (kXNxR) where k - channels, N - data points, R - nr of trials
- Nrep = 100 : int
- number of resamples
- alpha = 0.05 : float
- type I error rate (significance level)
- nfft = None : int
- window length (if None it’s N/5)
- no = None : int
- overlap length (if None it’s N/10)
- verbose = True : bool
- if True it prints dot on every realization, if False it’s quiet.
- params :
- additional parameters specific for chosen estimator
- Returns:
- signi_st : numpy.array
- short time significance values in shape of - (tp, k, k) for one sided estimator - (tp, 2, k, k) for two sided where k is number of channels and tp number of time points
-
significance
(data, Nrep=10, alpha=0.05, verbose=True, **params)[source]¶ Significance of connectivity estimators. It base on bootstrap
Connect.bootstrap()
for multitrial case and surrogate dataConnect.surrogate()
for one trial. Args:- data : numpy.array
- data matrix (kXN) or (kXNxR) where k - channels, N - data points, R - nr of trials
- Nrep = 100 : int
- number of resamples
- alpha = 0.05 : float
- type I error rate (significance level)
- verbose = True : bool
- if True it prints dot on every realization, if False it’s quiet.
- params :
- additional parameters specific for chosen estimator
- Returns:
- signific : numpy.array
- significance values, check
Connect.levels()
-
levels
(signi, alpha, k)[source]¶ Levels of significance Args:
- signi : numpy.array
- bootstraped values of each channel
- alpha : float
- type I error rate (significance level) - from 0 to 1 - (1-alpha) for onesided estimators (e.g. class:DTF) - alpha and (1-alpha) for twosided (e.g. class:PSI)
- k : int
- number of channels
- Returns:
- ficance : numpy.array
- maximal value throughout frequency of score at percentile at level 1-alpha - (k, k) for one sided estimator - (2, k, k) for two sided
-
bootstrap
(data, Nrep=100, alpha=0.05, verbose=True, **params)[source]¶ Bootstrap - random sampling with replacement of trials. Args:
- data : numpy.array
- multichannel data matrix
- Nrep = 100 : int
- number of resamples
- alpha = 0.05 : float
- type I error rate (significance level)
- verbose = True : bool
- if True it prints dot on every realization, if False it’s quiet.
- params :
- additional parameters specific for chosen estimator
- Returns:
- levelsigni : numpy.array
- significance values, check
Connect.levels()
-
surrogate
(data, Nrep=100, alpha=0.05, verbose=True, **params)[source]¶ Surrogate data testing. Mixing data points in each channel. Significance level in calculated over all Nrep surrogate sets. Args:
- data : numpy.array
- multichannel data matrix
- Nrep = 100 : int
- number of resamples
- alpha = 0.05 : float
- type I error rate (significance level)
- verbose = True : bool
- if True it prints dot on every realization, if False it’s quiet.
- params :
- additional parameters specific for chosen estimator
- Returns:
- levelsigni : numpy.array
- significance values, check
Connect.levels()
-
-
class
connectivipy.conn.
ConnectAR
[source]¶ Inherits from Connect class and governs calculation of various connectivity estimators basing on MVAR model methods. It overloads short_time, significance methods but calculate remains abstract.
-
short_time
(data, nfft=None, no=None, mvarmethod='yw', order=None, resol=None, fs=1)[source]¶ It overloads
ConnectAR
methodConnect.short_time()
. Short-tme version of estimator, where data is windowed into parts of length nfft and overlap no. params catch additional parameters specific for estimator. Args:- data : numpy.array
- data matrix (kXN) or (kXNxR) where k - channels, N - data points, R - nr of trials
- nfft = None : int
- window length (if None it’s N/5)
- no = None : int
- overlap length (if None it’s N/10)
- mvarmethod = ‘yw’ :
- MVAR parameters estimation method
all avaiable methods you can find in fitting_algorithms
- order = None:
- MVAR model order; it None, it is set automatically basing on default criterion.
- resol = None:
- frequency resolution; if None, it is 100.
- fs = 1 :
- sampling frequency
- Returns:
- stvalues : numpy.array
- short time values (time points, frequency, k, k), where k is number of channels
-
short_time_significance
(data, Nrep=100, alpha=0.05, method='yw', order=None, fs=1, resolution=None, nfft=None, no=None, verbose=True, **params)[source]¶ Significance of short-tme versions of estimators. It base on bootstrap
ConnectAR.bootstrap()
for multitrial case and surrogate dataConnectAR.surrogate()
for one trial. Args:- data : numpy.array
- data matrix (kXN) or (kXNxR) where k - channels, N - data points, R - nr of trials
- Nrep = 100 : int
- number of resamples
- alpha = 0.05 : float
- type I error rate (significance level)
- method = ‘yw’: str
- method of MVAR parameters estimation all avaiable methods you can find in fitting_algorithms
- order = None : int
- MVAR model order, if None, it’s chosen using default criterion
- fs = 1 : int
- sampling frequency
- resolution = None : int
- resolution (if None, it’s 100 points)
- nfft = None : int
- window length (if None it’s N/5)
- no = None : int
- overlap length (if None it’s N/10)
- verbose = True : bool
- if True it prints dot on every realization, if False it’s quiet.
- params :
- additional parameters specific for chosen estimator
- Returns:
- signi_st : numpy.array
- short time significance values in shape of - (tp, k, k) for one sided estimator - (tp, 2, k, k) for two sided where k is number of channels and tp number of time points
-
significance
(data, method, order=None, resolution=None, Nrep=10, alpha=0.05, verbose=True, **params)[source]¶ Significance of connectivity estimators. It base on bootstrap
ConnectAR.bootstrap()
for multitrial case and surrogate dataConnectAR.surrogate()
for one trial. Args:- data : numpy.array
- data matrix
- method = ‘yw’: str
- method of MVAR parametersestimation all avaiable methods you can find in fitting_algorithms
- order = None : int
- MVAR model order, if None, it’s chosen using default criterion
- Nrep = 100 : int
- number of resamples
- alpha = 0.05 : float
- type I error rate (significance level)
- resolution = None : int
- resolution (if None, it’s 100 points)
- verbose = True : bool
- if True it prints dot on every realization, if False it’s quiet.
- params :
- additional parameters specific for chosen estimator
- Returns:
- signi_st : numpy.array
- significance values, check
Connect.levels()
-
bootstrap
(data, method, order=None, Nrep=10, alpha=0.05, fs=1, verbose=True, **params)[source]¶ Bootstrap - random sampling with replacement of trials for ConnectAR. Args:
- data : numpy.array
- multichannel data matrix
- method : str
- method of MVAR parametersestimation all avaiable methods you can find in fitting_algorithms
- Nrep = 100 : int
- number of resamples
- alpha = 0.05 : float
- type I error rate (significance level)
- order = None : int
- MVAR model order, if None, it’s chosen using default criterion
- verbose = True : bool
- if True it prints dot on every realization, if False it’s quiet.
- params :
- additional parameters specific for chosen estimator
- Returns:
- levelsigni : numpy.array
- significance values, check
Connect.levels()
-
surrogate
(data, method, Nrep=10, alpha=0.05, order=None, fs=1, verbose=True, **params)[source]¶ Surrogate data testing for ConnectAR . Mixing data points in each channel. Significance level in calculated over all Nrep surrogate sets. Args:
- data : numpy.array
- multichannel data matrix
- method : str
- method of MVAR parameters estimation all avaiable methods you can find in fitting_algorithms
- Nrep = 100 : int
- number of resamples
- alpha = 0.05 : float
- type I error rate (significance level)
- order = None : int
- MVAR model order, if None, it’s chosen using default criterion
- verbose = True : bool
- if True it prints dot on every realization, if False it’s quiet.
- params :
- additional parameters specific for chosen estimator
- Returns:
- levelsigni : numpy.array
- significance values, check
Connect.levels()
-
-
connectivipy.conn.
dtf_fun
(Acoef, Vcoef, fs, resolution, generalized=False)[source]¶ Directed Transfer Function estimation from MVAR parameters. Args:
- Acoef : numpy.array
- array of shape (k, k, p) where k is number of channels and p is a model order.
- Vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- generalized = False : bool
- generalized version or not
- Returns:
- DTF : numpy.array
- matrix with estimation results (resolution, k, k)
References: .. [1] M. Kaminski, K.J. Blinowska. A new method of the description
of the information flow. Biol.Cybern. 65:203-210, (1991).
-
connectivipy.conn.
pdc_fun
(Acoef, Vcoef, fs, resolution, generalized=False)[source]¶ Partial Directed Coherence estimation from MVAR parameters. Args:
- Acoef : numpy.array
- array of shape (k, k, p) where k is number of channels and p is a model order.
- Vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- generalized = False : bool
- generalized version or not
- Returns:
- PDC : numpy.array
- matrix with estimation results (resolution, k, k)
References: .. [1] Sameshima, K., Baccala, L. A., Partial directed
coherence: a new concept in neural structure determination., 2001, Biol. Cybern. 84, 463–474.
-
class
connectivipy.conn.
PartialCoh
[source]¶ PartialCoh - class inherits from
ConnectAR
and overloadsConnect.calculate()
method.-
calculate
(Acoef=None, Vcoef=None, fs=None, resolution=None)[source]¶ Partial Coherence estimation from MVAR parameters. Args:
- Acoef : numpy.array
- array of shape (k, k, p) where k is number of channels and p is a model order.
- Vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- generalized = False : bool
- generalized version or not
- Returns:
- PC : numpy.array
- matrix with estimation results (resolution, k, k)
References: .. [1] G. M. Jenkins, D. G. Watts. Spectral Analysis and its
Applications. Holden-Day, USA, 1969
-
-
class
connectivipy.conn.
PDC
[source]¶ PDC - class inherits from
ConnectAR
and overloadsConnect.calculate()
method.
-
class
connectivipy.conn.
gPDC
[source]¶ gPDC - class inherits from
ConnectAR
and overloadsConnect.calculate()
method.
-
class
connectivipy.conn.
DTF
[source]¶ DTF - class inherits from
ConnectAR
and overloadsConnect.calculate()
method.
-
class
connectivipy.conn.
gDTF
[source]¶ gDTF - class inherits from
ConnectAR
and overloadsConnect.calculate()
method.
-
class
connectivipy.conn.
ffDTF
[source]¶ ffDTF - class inherits from
ConnectAR
and overloadsConnect.calculate()
method.-
calculate
(Acoef=None, Vcoef=None, fs=None, resolution=100)[source]¶ full-frequency Directed Transfer Function estimation from MVAR parameters. Args:
- Acoef : numpy.array
- array of shape (k, k, p) where k is number of channels and p is a model order.
- Vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- generalized = False : bool
- generalized version or not
- Returns:
- ffDTF : numpy.array
- matrix with estimation results (resolution, k, k)
References: .. [1] Korzeniewska, A.et. all. Determination of information flow direction
among brain structures by a modified directed transfer function (dDTF) method. J. Neurosci. Methods 125, 195–207 (2003).
-
-
class
connectivipy.conn.
dDTF
[source]¶ dDTF - class inherits from
ConnectAR
and overloadsConnect.calculate()
method.-
calculate
(Acoef=None, Vcoef=None, fs=None, resolution=100)[source]¶ direct Directed Transfer Function estimation from MVAR parameters. dDTF is a DTF multiplied in each frequency by Patrial Coherence. Args:
- Acoef : numpy.array
- array of shape (k, k, p) where k is number of channels and p is a model order.
- Vcoef : numpy.array
- prediction error matrix (k, k)
- fs = 1 : int
- sampling rate
- resolution = 100 : int
- number of spectrum data points
- generalized = False : bool
- generalized version or not
- Returns:
- dDTF : numpy.array
- matrix with estimation results (resolution, k, k)
References: .. [1] Korzeniewska, A.et. all. Determination of information flow direction
among brain structures by a modified directed transfer function (dDTF) method. J. Neurosci. Methods 125, 195–207 (2003).
-
-
class
connectivipy.conn.
Coherency
[source]¶ Coherency - class inherits from
Connect
and overloadsConnect.calculate()
method and values_range attribute.-
calculate
(data, cnfft=None, cno=None, window=<function hanning>, im=False)[source]¶ Coherency calculation using FFT mehtod. Args:
- data : numpy.array
- array of shape (k, N) where k is number of channels and N is number of data points.
- cnfft = None : int
- number of data points in window; if None, it is N/5
- cno = 0 : int
- overlap; if None, it is N/10
- window = np.hanning : <function> generating window with 1 arg n
- window function
- im = False : bool
- if False it return absolute value, otherwise complex number
- Returns:
- COH : numpy.array
- matrix with estimation results (resolution, k, k)
References: .. [1] M. B. Priestley Spectral Analysis and Time Series.
Academic Press Inc. (London) LTD., 1981
-
-
class
connectivipy.conn.
PSI
[source]¶ PSI - class inherits from
Connect
and overloadsConnect.calculate()
method.-
calculate
(data, band_width=4, psinfft=None, psino=0, window=<function hanning>)[source]¶ Phase Slope Index calculation using FFT mehtod. Args:
- data : numpy.array
- array of shape (k, N) where k is number of channels and N is number of data points.
- band_width = 4 : int
- width of frequency band where PSI values are summed
- psinfft = None : int
- number of data points in window; if None, it is N/5
- psino = 0 : int
- overlap; if None, it is N/10
- window = np.hanning : <function> generating window with 1 arg n
- window function
- Returns:
- COH : numpy.array
- matrix with estimation results (resolution, k, k)
References: .. [1] Nolte G. et all, Comparison of Granger Causality and
Phase Slope Index. 267–276 (2009).
-
-
class
connectivipy.conn.
GCI
[source]¶ GCI - class inherits from
Connect
and overloadsConnect.calculate()
method.-
calculate
(data, gcimethod='yw', gciorder=None)[source]¶ Granger Causality Index calculation from MVAR model. Args:
- data : numpy.array
- array of shape (k, N) where k is number of channels and N is number of data points.
- gcimethod = ‘yw’ : int
- MVAR parameters estimation model
- gciorder = None : int
- model order, if None appropiate value is chosen basic on default criterion
- Returns:
- gci : numpy.array
- matrix with estimation results (resolution, k, k)
References: .. [1] Nolte G. et all, Comparison of Granger Causality and
Phase Slope Index. 267–276 (2009).
-