getcov

Parameter covariance of identified model

Syntax

cov_data = getcov(sys)

cov_data = getcov(sys,cov_type)

cov_data = getcov(sys,cov_type,'free')

Description

cov_data = getcov(sys) returns the raw covariance of the parameters of an identified model.

• If sys is a single model, then cov_data is an np-by-np matrix. np is the number of parameters of sys.

• If sys is a model array, then cov_data is a cell array of size equal to the array size of sys.

  cov_data(i,j,k,...) contains the covariance data for sys(:,:,i,j,k,...).

cov_data = getcov(sys,cov_type) returns the parameter covariance as either a matrix or a structure, depending on the covariance type that is specified.

cov_data = getcov(sys,cov_type,'free') returns the covariance data of only the free model parameters.

Examples

Obtain Raw Parameter Covariance for Identified Model

Obtain the identified model.

load iddata1 z1
sys = tfest(z1,2);

Get the raw parameter covariance for the model.

cov_data = getcov(sys)

cov_data = 5×5

    1.2131   -4.3949   -0.0309   -0.5531         0
   -4.3949  115.0838    1.8598   10.6660         0
   -0.0309    1.8598    0.0636    0.1672         0
   -0.5531   10.6660    0.1672    1.2433         0
         0         0         0         0         0

cov_data contains the covariance matrix for the parameter vector [sys.Numerator,sys.Denominator(2:end),sys.IODelay].

sys.Denominator(1) is fixed to 1 and not treated as a parameter. The covariance matrix entries corresponding to the delay parameter (fifth row and column) are zero because the delay was not estimated.

Obtain Raw Parameter Covariance for Identified Model Array

Obtain the identified model array.

load iddata1 z1;
sys1 = tfest(z1,2);
sys2 = tfest(z1,3);
sysarr = stack(1,sys1,sys2);

sysarr is a 2-by-1 array of continuous-time, identified transfer functions.

Get the raw parameter covariance for the models in the array.

cov_data = getcov(sysarr)

cov_data=2×1 cell array
    {5x5 double}
    {7x7 double}

cov_data is a 2-by-1 cell array. cov_data{1} and cov_data{2} are the raw parameter covariance matrices for sys1 and sys2.

Obtain Raw Covariance of Estimated Parameters of Identified Model

Load the estimation data.

load iddata1 z1
z1.y = cumsum(z1.y);

Estimate the model.

init_sys = idtf([100 1500],[1 10 10 0]);
init_sys.Structure.Numerator.Minimum = eps;
init_sys.Structure.Denominator.Minimum = eps;
init_sys.Structure.Denominator.Free(end) = false;
opt = tfestOptions('SearchMethod','lm');
sys = tfest(z1,init_sys,opt);

sys is an idtf model with six parameters, four of which are estimated.

Get the covariance matrix for the estimated parameters.

cov_type = 'value';
cov_data = getcov(sys,cov_type,'free')

cov_data = 4×4
105 ×

    0.0269   -0.1237   -0.0001   -0.0017
   -0.1237    1.0221    0.0016    0.0133
   -0.0001    0.0016    0.0000    0.0000
   -0.0017    0.0133    0.0000    0.0002

cov_data is a 4x4 covariance matrix, with entries corresponding to the four estimated parameters.

Obtain Factored Parameter Covariance for Identified Model

Obtain the identified model.

load iddata1 z1
sys = tfest(z1,2);

Get the factored parameter covariance for the model.

cov_type = 'factors';
cov_data = getcov(sys,cov_type);

Obtain Factored Parameter Covariance for Identified Model Array

Obtain the identified model array.

load iddata1 z1
sys1 = tfest(z1,2);
sys2 = tfest(z1,3);
sysarr = stack(1,sys1,sys2);

sysarr is a 2-by-1 array of continuous-time, identified transfer functions.

Get the factored parameter covariance for the models in the array.

cov_type = 'factors';
cov_data = getcov(sysarr,cov_type)

cov_data=2×1 struct array with fields:
    R
    T
    Free

cov_data is a 2-by-1 structure array. cov_data(1) and cov_data(2) are the factored covariance structures for sys1 and sys2.

Obtain Factored Covariance of Estimated Parameters of Identified Model

Load the estimation data.

load iddata1 z1
z1.y = cumsum(z1.y);

Estimate the model.

init_sys = idtf([100 1500],[1 10 10 0]);
init_sys.Structure.Numerator.Minimum = eps;
init_sys.Structure.Denominator.Minimum = eps;
init_sys.Structure.Denominator.Free(end) = false;
opt = tfestOptions('SearchMethod','lm');
sys = tfest(z1,init_sys,opt);

sys, an idtf model, has six parameters, four of which are estimated.

Get the factored covariance for the estimated parameters.

cov_type = 'factors';
cov_data = getcov(sys,cov_type,'free');

Input Arguments

sys — Identified model

idtf, idss, idgrey, idpoly, idproc, idnlarx, idnlhw, or idnlgrey object | model array

Identified model, specified as an idtf, idss, idgrey, idpoly, idproc, idnlarx, idnlhw, or idnlgrey model or an array of such models.

The getcov command returns cov_data as [] for idnlarx and idnlhw models because these models do not store parameter covariance data.

cov_type — Covariance type

'value' (default) | 'factors'

Covariance return type, specified as either 'value' or 'factors'.

• If cov_type is 'value', then cov_data is returned as a matrix (raw covariance).

• If cov_type is 'factors', then cov_data is returned as a structure containing the factors of the covariance matrix.

  Use this option for fetching the covariance data if the covariance matrix contains nonfinite values, is not positive definite, or is ill conditioned. You can calculate the response uncertainty using the covariance factors instead of the numerically disadvantageous covariance matrix.

  This option does not offer a numerical advantage in the following cases:

  • sys is estimated using certain instrument variable methods, such as iv4.

  • You have explicitly specified the parameter covariance of sys using the deprecated CovarianceMatrix model property.

Data Types: char

Output Arguments

cov_data — Parameter covariance of sys

matrix or cell array of matrices | structure or cell array of structures

Parameter covariance of sys, returned as a matrix, cell array of matrices, structure, or cell array of structures. cov_data is [] for idnlarx and idnlhw models.

• If sys is a single model and cov_type is 'value', then cov_data is an np-by-np matrix. np is the number of parameters of sys.

  The value of the nonzero elements of this matrix is equal to sys.Report.Parameters.FreeParCovariance when sys is obtained via estimation. The row and column entries that correspond to fixed parameters are zero.

• If sys is a single model and cov_type is 'factors', then cov_data is a structure with fields:

  • R — Usually an upper triangular matrix.

  • T — Transformation matrix.

  • Free — Logical vector of length np, indicating if a model parameter is free (estimated) or not. np is the number of parameters of sys.

  To obtain the covariance matrix using the factored form, enter:

  Free = cov_factored.Free; 
  T = cov_factored.T;
  R = cov_factored.R;
  np = nparams(sys); 
  cov_matrix = zeros(np);
  cov_matrix(Free, Free) = T*inv(R'*R)*T';

  For numerical accuracy, calculate T*inv(R'*R)*T' as X*X', where X = T/R.

• If sys is a model array, then cov_data is a cell array of size equal to the array size of sys.

  cov_data(i,j,k,...) contains the covariance data for sys(:,:,i,j,k,...).