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.

calculate()[source]

Abstract method to calculate values of estimators from specific parameters

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 data Connect.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 data Connect.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 method Connect.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 data ConnectAR.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 data ConnectAR.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 overloads Connect.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 overloads Connect.calculate() method.

calculate(Acoef=None, Vcoef=None, fs=None, resolution=100)[source]

More in pdc_fun().

class connectivipy.conn.gPDC[source]

gPDC - class inherits from ConnectAR and overloads Connect.calculate() method.

calculate(Acoef=None, Vcoef=None, fs=None, resolution=100)[source]

More in pdc_fun()

class connectivipy.conn.DTF[source]

DTF - class inherits from ConnectAR and overloads Connect.calculate() method.

calculate(Acoef=None, Vcoef=None, fs=None, resolution=100)[source]

More in dtf_fun().

class connectivipy.conn.gDTF[source]

gDTF - class inherits from ConnectAR and overloads Connect.calculate() method.

calculate(Acoef=None, Vcoef=None, fs=None, resolution=100)[source]

More in dtf_fun().

class connectivipy.conn.ffDTF[source]

ffDTF - class inherits from ConnectAR and overloads Connect.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 overloads Connect.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 overloads Connect.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 overloads Connect.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 overloads Connect.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).