# Model metrics¶

class sails.mvar_metrics.FourierMvarMetrics[source]

This class for computing various connectivity metrics based on the Fourier transform of the MVAR co-efficients.

This is typically called using the initialise() classmethod to compute the frequency transform and return a class instance with methods for computing different connectivity estimators

classmethod initialise(model, sample_rate, freq_vect, nmodes=None)[source]

Compute some basic values from the Fourier transform of the A matrix. This is a class method which creates and returns a FourierMvarMetrics instance with methods computing various connectivity metrics.

This class computes the transfer function H the Fourier transform.

Parameters: model (sails LinearModel) – SAILS class instance containing a fitted linear model. sample_rate (float) – Sample rate of the dataset freq_vect (ndarray) – Vector of specifying which frequencies to compute connectivity at. sails.FourierMvarMetrics instance
class sails.mvar_metrics.ModalMvarMetrics[source]

This class for computing various connectivity metrics based on a Modal decomposition of a fitted MVAR model

This is typically called using the initialise() or initialise_from_modes() classmethods to compute the decomposition and return a class instance containing them.

classmethod initialise(model, sample_rate, freq_vect, sum_modes=True)[source]

Compute some basic values from the pole-residue decomposition of the A matrix. This is a class method which creates and returns a ModalMvarMetrics instance containing the decomposition parameters with methods computing various connectivity metrics.

This class computes the transfer function H using modal parameters.

Currently only implemented for a single realisation (A.ndim == 3)

Parameters: model (sails LinearModel) – SAILS class instance containing a fitted linear model. sample_rate (float) – Sample rate of the dataset freq_vect (ndarray) – Vector of specifying which frequencies to compute connectivity at. sum_modes (bool) – Flag indicating whether to sum across modes (Default value = True) sails.ModalMvarMetrics instance
classmethod initialise_from_modes(model, modes, sample_rate, freq_vect, mode_inds=None, sum_modes=True)[source]

Compute some basic values from the pole-residue decomposition of the A matrix. This is a class method which creates and returns a sails.ModalMvarMetrics instance containing the decomposition parameters with methods computing various connectivity metrics.

This class computes the transfer function H using modal parameters. A sub-set of modes can be used to compute a reduced H.

Currently only implemented for a single realisation (A.ndim == 3)

Parameters: model (sails LinearModel) – SAILS class instance containing a fitted linear model. modes (sails MvarModalDecomposition) – SAILS class instance containing a fitted modal decomposition sample_rate (float) – The sample rate of the fitted data freq_vect (ndarray) – Vector of specifying which frequencies to compute connectivity at. mode_inds (ndarray) – Which modes to use when constructing H (Default value = None) sum_modes (Boolean) – Flag indicating whether to sum across modes when constructing H (Default value = True) sails.ModalMvarMetrics instance
sails.mvar_metrics.modal_transfer_function(evals, evecl, evecr, nchannels, sample_rate=None, freq_vect=None)[source]

Compute the transfer function in pole-residue form, splitting the system into modes with separate transfer functions. The full system transfer function is then a linear sum of each modal transfer function.

Parameters: evals (ndarray) – Complex valued eigenvalues from an eigenvalue decomposition of an MVAR parameter matrix. evecl (ndarray) – Complex valued left-eigenvectorsfrom an eigenvalue decomposition of an MVAR parameter matrix. evecr (ndarry) – Complex valued right-eigenvectorsfrom an eigenvalue decomposition of an MVAR parameter matrix. nchannels (int) – Number of channels in the decomposed system sample_rate (float) – The sampling rate of the decomposed system (Default value = None) freq_vect (ndarray) – Vector of frequencies at which to evaluate the transfer function (Default value = None) Modal transfer-function (H) of size [nchannels x nchannels x nfrequencies x nmodes] ndarray

## Metric Mathemetical Functions¶

sails.mvar_metrics.sdf_spectrum(A, sigma, sample_rate, freq_vect)[source]

Estimate of the Spectral Density as found on wikipedia and [Quirk1983].

This assumes that the spectral representation of A is invertable

Parameters: A (ndarray) – Matrix of autoregressive parameters, of size [nchannels x nchannels x model order] sigma (ndarray) – Residual covariance matrix of the modelled system sample_rate (float) – The samplingfrequency of the modelled system freq_vect (ndarray) – Vector of frequencies at which to evaluate the spectrum Frequenecy transform of input A, of size [nchannels x nchannels x nfrequencies] ndarray
sails.mvar_metrics.psd_spectrum(A, sigma, sample_rate, freq_vect)[source]

Estimate the PSD representation of a set of MVAR coefficients as stated in [Penny2009] section 7.4.4.

This assumes that the spectral representation of A is invertable

WARNING: does not behave as expected for some data, use with caution. ar_spectrum is recommended.

Parameters: A (ndarray) – Matrix of autoregressive parameters, of size [nchannels x nchannels x model order] sigma (ndarray) – Residual covariance matrix of the modelled system sample_rate (float) – The samplingfrequency of the modelled system freq_vect (ndarray) – Vector of frequencies at which to evaluate the spectrum Frequenecy transform of input A, of size [nchannels x nchannels x nfrequencies] ndarray
sails.mvar_metrics.ar_spectrum(A, sigma, sample_rate, freq_vect)[source]

Estimate the spectral representation of a set of MVAR coefficients as suggested by [Baccala2001], the equation without a number just below equation 13.

Parameters: A (ndarray) – Matrix of autoregressive parameters, of size [nchannels x nchannels x model order] sigma (ndarray) – Residual covariance matrix of the modelled system sample_rate (float) – The samplingfrequency of the modelled system freq_vect (ndarray) – Vector of frequencies at which to evaluate the spectrum Frequenecy transform of input A, of size [nchannels x nchannels x nfrequencies] ndarray
sails.mvar_metrics.transfer_function(Af)[source]

Function for computing the transfer function of a system from the frequency transform of the autoregressive parameters.

Parameters: Af – Frequency domain version of parameters (can be calculated using ar_spectrum function) [nchannels x nchannels x nfreqs x nepochs] System transfer function, of size [nchannels x nchannels x nfreqs x nepochs] ndarray

Note

This function computes this the transfer function $$H$$ as defined by:

$H(f) = ( I - Af(f) )^{-1}$

where $$Af$$ is the frequency transformed autoregessive parameter matrix and $$I$$ is identity.

sails.mvar_metrics.spectral_matrix(H, noise_cov)[source]

Function for computing the spectral matrix, the matrix of spectra and cross-spectra.

Parameters: H (ndarray) – The transfer matrix [nchannels x nchannels x nfreqs x nepochs] noise_cov (ndarray) – The noise covariance matrix of the system [nchannels x nchannels x nepochs] System spectral matrix, of size [nchannels x nchannels x nfreqs x nepochs] ndarray

Note

This function computes the system spectral matrix as defined by:

$S(f) = H(f)\Sigma H(f)^H$

where $$H$$ is the transfer function, $$\Sigma$$ is the residual covariance and $$^H$$ the Hermitian transpose.

sails.mvar_metrics.coherency(S)[source]

Method for computing the Coherency. This is the complex form of coherence, from which metrics such as magnitude squared coherence can be derived

Parameters: S (ndarray) – The system spectral matrix in 3D or 4D form, of size [nchannels x nchannels x nfreqs x nepochs] Complex-valued coherency matrix, of size [nchannels x nchannels x nfreqs x nepochs] ndarray

Note

This function computes the coherency as defined by:

$Coh_{ij}(f) = \frac{S_{ij}(f)}{ \sqrt{ | S_{ii}(f)S_{jj}(f) | } }$

where $$S$$ is the system spectral matrix.

sails.mvar_metrics.partial_coherence(inv_S)[source]

Method for computing the Partial Coherence.

Parameters: inv_S (ndarray) – The system spectral matrix in 3D or 4D form, of size [nchannels x nchannels x nfreqs x nepochs] Complex-valued coherency matrix, of size [nchannels x nchannels x nfreqs x nepochs] ndarray

Note

This function computes the partial coherence using the inverse spectral matrix $$P = S^{-1}$$ where $$S$$ is the system spectral matrix. The partial coherence is then computed as:

$PCoh_{ij}(f) = \frac{ |P_{ij}(f)|^2 }{ \sqrt{ | P_{ii}(f)P_{jj}(f) | } }$
sails.mvar_metrics.partial_directed_coherence(Af)[source]

Function to estimate the partial directed coherence from a set of multivariate parameters as defined in [Baccala2001].

Parameters: Af (ndarray) – Frequency domain version of parameters (can be calculated using ar_spectrum function), of size [nchannels x nchannels x nfrequencies x nrealisations] The partial directed coherence of the system. ndarray

Note

This function computes the partial coherence using the frequency transform of the autoregressive parameters $$Af$$ subtracted from Identity.

$\bar{Af}(f) = I - Af(f)$

The partial directed coherence is then

$PDC_{ij}(f) = \frac{ | \bar{Af}_{ij}(f)| }{ \sqrt{ \sum_i | \bar{Af}_{ij}(f) |^2 } }$
sails.mvar_metrics.isolated_effective_coherence(Af, noise_cov)[source]

Function for estimating the Isolated Effective Coherence as defined in [Pascual-Marqui2014].

Parameters: Af (ndarray) – Frequency domain version of parameters (can be calculated using ar_spectrum function) [nchannels x nchannels x nfreqs x nepochs] noise_cov (ndarray) – The noise covariance matrix of the system [nchannels x nchannels x nepochs] The isolated effective coherence. ndarray
sails.mvar_metrics.directed_transfer_function(H)[source]

Method for computing the Directed Transfer Function as defined in [Kaminski1991].

Parameters: H (ndarray) – The transfer matrix [nchannels x nchannels x nfreqs x nepochs] The directed transfer function of the system. ndarray

Note

This function computes the directed transfer function from the system transfer function $$H$$.

$DTF_{ij}(f) = \frac{ | H_{ij}(f) |^2 }{ \sqrt{ \sum_j | \bar{H}_{ij}(f) |^2 } }$
sails.mvar_metrics.geweke_granger_causality(S, H, sigma)[source]

This function computes the Geweke-Granger causality as defined in [Barrett2010]

Parameters: S (ndarray) – Spectral matrix [nchannels x nchannels x nfreqs x nepochs] H (ndarray) – The transfer matrix [nchannels x nchannels x nfreqs x nepochs] sigma (ndarray) – Residual noise covariance matrix The Geweke-Granger causality ndarray