# Support routines¶

## Abstract Classes¶

class sails.modelfit.AbstractLinearModel[source]

This is a base class defining data storage and generic methods for LinearModel classes. New LinearModels should inherit from AbstractLinearModel and overload the fit_model method

companion

Parameter matrix in companion form

compute_diagnostics(data, compute_pc=False)[source]

Compute several diagnostic metrics from a fitted MVAR model and a dataset.

Parameters: data (ndarrat) – The data to compute the model diagnostics with, typically the same data used during model fit. compute_pc (bool) – Flag indicating whether the compute the percent consistency, this is typically the the longest computation of all the metrics here (Default value = False) object containing LL, AIC, BIC, stability ratio, durbin-watson, R squared and percent consistency measures sails.ModelDiagnostics
get_residuals(data, mode='valid')[source]

Returns the prediction error from a fitted model. This is a wrapper function for get_residuals()

Parameters: data (ndarray) – Data to compute the residuals of, of size [nchannels x nsamples x nrealisations] Residual data ndarray
nsignals

Number of signals in fitted model

order

Order of fitted model

class sails.mvar_metrics.AbstractMVARMetrics[source]

This is a base class for computing various connectivity metrics from fitted autoregressive models

PSD

Power Spectral Density matrix

S

Spectral Matrix of shape [nsignals, nsignals, order, epochs]

coherency

Complex-valued coherency

d_directed_transfer_function

Direct directed transfer function

directed_transfer_function

Directed transfer function

ff_directed_transfer_function

Full-frequency directed transfer function

get_node_weight(metric='S')[source]

Compute the node weight for a given connectivity metric.

Parameters: metric (str) – Name of the connectivity metric to plot (Default value = ‘S’) Node-weight matrix of size [nchannels x nchannels] ndarray
get_spectral_generalisation(metric='S')[source]

Compute the spectral generalisation matrix for a given metric. Returns the spatial similarity of different frequencies.

Parameters: metric (str) – Name of the connectivity metric to plot (Default value = ‘S’) Matrix of spectral generalisation [nfrequencies x nfrequencies] ndarray
geweke_granger_causality

Geweke granger causality

imaginary_coherence

Imaginary part of complex coherency

inv_S

Inverse Power Spectrl Density matrix

isolated_effective_coherence

Isolated effective coherence

magnitude_squared_coherence

Magnitude squared coherence

partial_coherence

Partialled magnitude-squared coherence

partial_directed_coherence

Partial directed coherence

phase_coherence

Phase angle of complex coherency

plot_diags(metric='S', inds=None, F=None, ax=None)[source]

Helper function for plotting the diagonal part of a connectivty metric. Calls sails.plotting.plot_diagonal.

Parameters: metric (str) – Name of the connectivity metric to plot (Default value = ‘S’) F (matplotlib figure handle) – Handle for matplotlib figure to plot in (Default value = None) ax (matplotlib axes handle) – Handle for matplotlib axes to plot in (Default value = None)
plot_summary(metric='S', ind=1)[source]

Helper function for plotting a summary of a connectivty metric. Calls sails.plotting.plot_summary.

Parameters: metric (str) – Name of the connectivity metric to plot (Default value = ‘S’) ind (int) – Index into frequency dimension to plot connectivity matrix (Default value = 1)

## Statistical Functions¶

sails.stats.find_cov_multitrial(a, b, ddof=1)[source]

Estimate the average covariance between two datasets across many trials

Parameters: a (ndarray) – a multivariate time series of shape nsignals x nsamples x ntrials b (ndarray) – a multivariate time series of shape nsignals x nsamples x ntrials ddof (int) – if None, no normalisation will be performed. If an integer, covariance will be normalised by (nsamples - ddof) (Default value = 1) A covariance matrix between a and b of shape nsignals x nsignals type
sails.stats.find_cov(a, b, ddof=1)[source]

Estimate the covariance between two datasets.

Parameters: a (ndarray) – a multivariate time series of shape nsignals x nsamples b (ndarray) – a multivariate time series of shape nsignals x nsamples ddof (int) – if None, no normalisation will be performed. If an integer, covariance will be normalised by (nsamples - ddof) (Default value = 1) A covariance matrix between a and b of shape nsignals x nsignals type
sails.stats.mutual_information(A, B, r=None, nbins=21, base=<ufunc 'log2'>)[source]

Calculate the mutual information between two signals.

Parameters: A (ndarray) – First signal, of shape [channels x samples] B (ndarray) – Second signal, of shape [channels x samples] r (tuple (min,max)) – Range of the random variables used for bin calculations. If not set, takes the minimum and maximum values from the combination of A and B (Default value = None) nbins (int) – Number of bins to compute the frequencies within (Default value = 21) base (function) – Base to use for MI calculation - defaults to np.log2 the mutual information within each signal passed type
sails.stats.durbin_watson(residuals, step=1)[source]

Test for autocorrelation in the residuals of a model (see [Durbin1950] and [Durbin1951])

The result is a value between 0 and 4. A value of 0 indicates a positive autocorrelaiton, 2 indicates no correlation and a value of 4 indicates a negative autocorrelation.

If many trials are found the statistic is estimated for each trial separately.

Parameters: residuals (ndarray) – Residuals of shape [channels, samples, ntrials] If only two dimensions, will be treated as [channels, samples] If only one dimension, will be treated as [samples] step (int) – step-size to use through residuals when calculating DW. Defaults to 1. durbin-watson index type
sails.stats.percent_consistency(data, residuals)[source]

Estimate how well a model retains the correlational structure of a dataset.

This uses the percent consistency measure outlined in [Ding2000]. All auto and cross correlations within a multivariate data set are computed and compared to the auto and cross correlations of the data as predicted by a model (in this case the data - model residuals, as these are easily obtained).

Parameters: data (ndarray) – An array containing the observed data, of shape [nsignals x nsamples x ntrials] residuals (ndarray) – An array containing the remaining variance of data after model fitting, of shape [nsignals x nsamples x ntrials] A value between 0 and 100 indicating the percentage of the autocorrelation in the data that is retained in the model. type
sails.stats.rsquared_from_residuals(data, residuals, per_signal=False)[source]

Estimate the variance explained by a model from the original data and the model residuals

If data and residuals are 2D, they will be treated as [channels, nsamples]

If data and residuals are 1D, they will be treated as [nsamples]

Parameters: data (ndarray) – Array containing the original data, of shape [channels, nsamples, ntrials] residuals (ndarray) – Array containing the model residuals, of shape [channels, nsamples, ntrials] per_signal (bool) – Boolean indicating whether the variance explained should be computed separately per channel (Default value = False) Value between 0 and 1 indicating the proportion of variance explained by the model. type
sails.stats.mahalanobis(X, Y=None, sigma=None)[source]

Estimate the Mahalanobis distance of each point in an array across the samples dimension.

Parameters: X (ndarray) – Array containing data of points: shape [channels x samples] Y (ndarray (Optional)) – Optional Array containing data of second points: shape [channels x samples]. If not provided, the origin will be used as the point for comparison. (Default value = None) sigma (ndarray (Optional)) – A precomputed covariance matrix to use in the calculation, of shape [channels x channels]. If not provided, sigma will be calculated from X (Default value = None) The Mahalanobis distance for each sample, of shape [samples] type
sails.stats.profile_likelihood(X)[source]

Find the ‘elbow’ point in a curve.

This function uses the automatic dimensionality selection method from [Zhu2006] to estimate the elbow or inflection point in a given curve.

Parameters: X (ndarray) – 1d array containing the curve to be analysed, of shape [samples] The log likelihood that each point on the curve separates the distributions to the left and right, of shape [samples] type
sails.stats.stability_index(A)[source]

Compute the stability index as defined in [Lutkephol2006] pages 15-16.

This is a proxy for the stationarity assumption of MVAR models, if the magnitude of the largest principal component of the model parameters is less than 1, the model is stable and thus, stationary.

Parameters: A (ndarray) – The MVAR parameter matrix of size [nchannels x nchannels x model_order] The stability index type
sails.stats.stability_ratio(A)[source]

Compute the stability ratio as a measure of stationarity

A stronger test for stationarity than the stability index. Computes the ratio between the largest eigenvalue of the parameters and all the others. If the largest parameter is larger than all other parameters (indicated by a value < 1) we have a super-stable system.

Parameters: A (ndarray) – The MVAR parameter matrix of size [nchannels x nchannels x model_order] The stability ratio type
sails.modelvalidation.approx_model_selection_criteria(A, EF, method='ss')[source]

Estimate Akaike’s Information Criterion and Bayes Information Criterion from a model fit using an approximation of the loglikelihood.

Two approximations are available:
‘ss’: The sum square of the residuals. This approximation is outlined in [Burnham2002] and [Chatfield2003]. ‘det’: The determinant of the residual covariance matrix.

The sum squares method is used as default.

Parameters: A (ndarray) – Array containing the parameters of a fitted model, of shape [channels x channels x maxorder] EF (ndarray) – Array containing the residuals of the fitted model, of shape [channels x samples x trials] method ({'ss','det'}) – string indicating which method should be used to approximate the loglikelihood (‘ss’ or ‘det’) (Default value = ‘ss’) tuple of (aLL, AIC, BIC) aLL: Approximation of the loglikelihood (determined by the method defined above) AIC: Estimate of Akaike’s Information Criterion BIC: Estimate of the Bayesian Information Criterion tuple

## Data Processing Functions¶

sails.modal.adjust_phase(x)[source]

Method for normalising eigenvector matrices to meet the conditions in eqn 21 of [Neumaier2001].

Parameters: x (ndarray) – Vector of complex numbers to adjust the phase of Vector of numbers with adjusted phase type
sails.orthogonalise.symmetric_orthonormal(A, maintain_mag=False)[source]

Implement the [Colclough2015] algorithm for multivariate leakage correction in MEG. Also see the OHBA toolbox (https://github.com/OHBA-analysis/MEG-ROI-nets) and http://empslocal.ex.ac.uk/people/staff/reverson/uploads/Site/procrustes.pdf

Parameters: A (ndarray) – Data matrix to orthogonalise, of size [channels, samples] verbose (bool) – Flag indicating whether to show detailed output (Default value = False) maintain_mag (bool) – Flag indicating whether to maintain magnitudes (Default value = False) data (numpy.ndarray) – [channels, samples] of orthogonalised data W (numpy.ndarray)
sails.orthogonalise.innovations(A, order, mvar_class=None, verbose=False)[source]

Implementation of the innovations-orthogonalisation defined in [Pascual-Marqui2017] . This creates the mixing matrix on the input data after variance explained by an MVAR model is removed. The orthogonalisation is defined on the residuals but applied to the raw data.

Parameters: A (ndarray) – Data matrix to orthogonalise, of size [channels, samples] order (int) – Model order used during MVAR model fit mvar_class (sails LinearModel class) – Model class to do model fitting (Default value = None) verbose (bool) – Flag indicating whether to show detailed output (Default value = False) Orthogonalised data matrix, of size [channels, samples] ndarray

## Tutorial helper functions¶

sails.tutorial_utils.generate_pink_roots(power, order=24)[source]

Generates the poles of a system with a pink spectrum according to eqn 116 in [Kasdin1995]

Parameters: power (float) – Power of pole must be between -2 and 2. order – Order of system to generate (Default value = 24) Roots of the system (length of order) ndarray
sails.tutorial_utils.model_from_roots(roots)[source]

Sets up a univariate model based on the roots of a polynomial

Parameters: roots (ndarray) – Vector of polynomial roots. Model fit class containing the parameters defined by the input roots AbstractLinearModel
sails.tutorial_utils.find_support_path()[source]

Returns the path to the support files directory

sails.tutorial_utils.find_example_path()[source]

Returns the path to the tutorial example data directory (if available)

sails.tutorial_utils.set_sail()[source]