Model metrics¶

class
sails.mvar_metrics.
FourierMvarMetrics
[source]¶ This class for computing various connectivity metrics based on the Fourier transform of the MVAR coefficients.
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.
Returns: Return type: sails.FourierMvarMetrics instance

classmethod

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()
orinitialise_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 poleresidue 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)
Returns: Return type: 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 poleresidue 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 subset 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)
Returns: Return type: sails.ModalMvarMetrics instance

classmethod

sails.mvar_metrics.
modal_transfer_function
(evals, evecl, evecr, nchannels, sample_rate=None, freq_vect=None)[source]¶ Compute the transfer function in poleresidue 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 lefteigenvectorsfrom an eigenvalue decomposition of an MVAR parameter matrix.
 evecr (ndarry) – Complex valued righteigenvectorsfrom 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)
Returns: Modal transferfunction (H) of size [nchannels x nchannels x nfrequencies x nmodes]
Return type: 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
Returns: Frequenecy transform of input A, of size [nchannels x nchannels x nfrequencies]
Return type: 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
Returns: Frequenecy transform of input A, of size [nchannels x nchannels x nfrequencies]
Return type: 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
Returns: Frequenecy transform of input A, of size [nchannels x nchannels x nfrequencies]
Return type: 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] Returns: System transfer function, of size [nchannels x nchannels x nfreqs x nepochs] Return type: 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 crossspectra.
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]
Returns: System spectral matrix, of size [nchannels x nchannels x nfreqs x nepochs]
Return type: 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] Returns: Complexvalued coherency matrix, of size [nchannels x nchannels x nfreqs x nepochs] Return type: 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] Returns: Complexvalued coherency matrix, of size [nchannels x nchannels x nfreqs x nepochs] Return type: 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] Returns: The partial directed coherence of the system. Return type: 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 [PascualMarqui2014].
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]
Returns: The isolated effective coherence.
Return type: 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] Returns: The directed transfer function of the system. Return type: 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 GewekeGranger 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
Returns: The GewekeGranger causality
Return type: ndarray