Model Decomposition#

class sails.modal.MvarModalDecomposition[source]#

Object which calculates the modal decomposition of a fitted model derived from the AbstractLinearModel class. This is typically created using the initialise() classmethod which computes the decomposition and returns a populated object instance.

compute_modal_parameters()[source]#

Compute the order 1 or 2 autoregressive coefficients associated with each pole or conjugate pair.

Warning

This function is a work in progress and has not been fully validated.

Returns:

Array containing the time-domain AR parameters for each mode

Return type:

ndarray

compute_residues()[source]#

Compute the residue matrix from the eigenvectors associated with each pole.

Returns:

Array containing residue matrices for each pole.

Return type:

ndarray

excitation(resid_cov)[source]#

Compute the mode excitation as defined in [Neumaier2001]. This is a metric to quantify the dynamical importance of each mode in the decomposition.

Warning

This function is a work in progress and has not been fully validated.

Parameters:

resid_cov (ndarray) – Residual covariance matrix for modelled system

Returns:

Vector containing modal excitation values

Return type:

ndarray

get_mode_inds(fmin=0, fmax=None, mag_thresh=0, resid_thresh=0, index_mode='inclusive')[source]#

Helper function to identify mode indices based on given criteria.

Parameters:
  • fmin (float) – Minimum frequency of modes to include (Default value = 0)

  • fmax (float) – Maximum frequency of modes to include (Default value = None)

  • mag_thresh (float ( 0 > mag_thresh > 1 )) – Minimum pole magnitude to include (Default value = 0)

  • resid_thresh (float) – Minimum value of mode residue norm to include (Default value = 0)

  • index_mode ({'inclusive','exclusive'}) – Flag indicating whether mode selection limits should be inclusive or exclusive (Default value = ‘inclusive’)

Returns:

Array of integers indexing the included poles

Return type:

ndarray

classmethod initialise(model, sample_rate=None, normalise=False)[source]#

Compute the modal pole-residue decomposition of the A matrix from a fitted MVAR model.

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

Parameters:
  • model (LinearModel) – Fitted model object. Must be derived from AbstractLinearModel.

  • sample_rate (float) – sample rate of system in Hz (Default value = None)

  • normalise (bool) – Whether to adjust the phase of the eigenvectors (Default value = False)

Returns:

Modal decomposition object

Return type:

type

modal_freqz()[source]#

Compute filter characteristics for each pole

modal_timecourse(data)[source]#

Compute the modal time-course from a dataset and a fitted model. This is the transformation of a set of [nsignals x time] data observations into modal coordinates of shape [nmodes x time].

Warning

This function is a work in progress and has not been fully validated.

Parameters:

data (ndarray) – Input data to convert into modal co-ordinates

Returns:

Data transformed into modal time-series

Return type:

ndarray

modal_transfer_function(sample_rate, modes=None)[source]#

Compute a transfer function matrix based on the excitation period for each mode

Parameters:
  • sample_rate (float) – sample rate of system in Hz

  • modes (list of int) – List of mode indices to evaluate over (optional) (Default value = None)

Returns:

Transfer function computed for each mode

Return type:

ndarray

property mode_indices#

Returns a list of tuples of mode indices where each tuple contains the indices of either a pole-pair or an unpaired pole

Returns:

list of tuples containing indices into the modes

Return type:

List

per_mode_transfer_function(sample_rate, freq_vect)[source]#

Extracts the transfer function for each mode by summing the transfer function across pole-pairs where necessary

The transfer function is computed for each pole using transfer_function() before summing individual modes (real valued poles or complex-conjugate pairs).

Parameters:
  • sample_rate – sample rate of system in Hz

  • freq_vect – Vector of frequencies at which to evaluate function

Returns:

Array containing the transfer function for each individual mode

Return type:

ndarray

property period_hz#

This is an old and deprecated way of accessing peak_frequency

pole_plot(ax=None, normscale=50, plottype='unitcircle')[source]#

Plot the poles of the current system.

Parameters:
  • ax (matplotlib axes handle) – Optional axis on which to plot (Default value = None)

  • normscale (float) – Scaling factor for points on plot (Default value = 50)

  • plottype ({'unitcircle','eigenspectrum'}) – Flag indicating whether to plot results on a unit-circle or an eigenspectrum (Default value = ‘unitcircle’)

Returns:

Reference to axes on which plot was drawn

Return type:

matplotlib axes handle

property residue_norm#

The matrix-norm of the residue matrix of each mode

transfer_function(sample_rate, freq_vect, modes=None, sum_modes=True)[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.

When sum_modes is False, this function returns the transfer function for each individual pole (ie will return a transfer function for each pole in a conjugate pair). Please use per_mode_transfer_function to compute the transfer function for individual modes (ie one transfer function for each real pole or complex-conjugate pair)

Parameters:
  • sample_rate (float) – sample rate of system in Hz

  • freq_vect (ndarray) – Vector of frequencies at which to evaluate function

  • modes (list of ints) – List of mode indices to evaluate over (optional) (Default value = None)

  • sum_modes (bool) – Boolean indicating whether to sum modes or return all (Default value = True)

Returns:

Array containing the transfer function for each individual pole

Return type:

ndarray