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

example

``````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,...)`.```

example

``````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.```

example

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

Examples

collapse all

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 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`.

```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 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 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`.

```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

collapse all

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.

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

collapse all

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,...)`.

Version History

Introduced in R2012a