Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_tsa_multi_kalman_sqrt_var (g13ea)

## Purpose

nag_tsa_multi_kalman_sqrt_var (g13ea) performs a combined measurement and time update of one iteration of the time-varying Kalman filter using a square root covariance filter.

## Syntax

[s, k, h, ifail] = g13ea(a, b, stq, q, c, r, s, 'n', n, 'm', m, 'l', l, 'tol', tol)
[s, k, h, ifail] = nag_tsa_multi_kalman_sqrt_var(a, b, stq, q, c, r, s, 'n', n, 'm', m, 'l', l, 'tol', tol)

## Description

The Kalman filter arises from the state space model given by:
 $Xi+1=AiXi+BiWi, VarWi=Qi Yi=CiXi+Vi, VarVi=Ri$
where ${X}_{i}$ is the state vector of length $n$ at time $i$, ${Y}_{i}$ is the observation vector of length $m$ at time $i$, and ${W}_{i}$ of length $l$ and ${V}_{i}$ of length $m$ are the independent state noise and measurement noise respectively.
The estimate of ${X}_{i}$ given observations ${Y}_{1}$ to ${Y}_{i-1}$ is denoted by ${\stackrel{^}{X}}_{i\mid i-1}$ with state covariance matrix $\mathrm{Var}\left({\stackrel{^}{X}}_{i\mid i-1}\right)={P}_{i\mid i-1}={S}_{i}{S}_{i}^{\mathrm{T}}$, while the estimate of ${X}_{i}$ given observations ${Y}_{1}$ to ${Y}_{i}$ is denoted by ${\stackrel{^}{X}}_{i\mid i}$ with covariance matrix $\mathrm{Var}\left({\stackrel{^}{X}}_{i\mid i}\right)={P}_{i\mid i}$. The update of the estimate, ${\stackrel{^}{X}}_{i\mid i-1}$, from time $i$ to time $\left(i+1\right)$, is computed in two stages. First, the measurement-update is given by
 $X^i∣i=X^i∣i-1+KiYi-CiX^i∣i-1$ (1)
and
 $Pi∣i=I-KiCiPi∣i-1$ (2)
where ${K}_{i}={P}_{i\mid i-1}{C}_{i}^{\mathrm{T}}{\left[{C}_{i}{P}_{i\mid i-1}{C}_{i}^{\mathrm{T}}+{R}_{i}\right]}^{-1}$ is the Kalman gain matrix. The second stage is the time-update for $X$ which is given by
 $X^i+1∣i=AiX^i∣i+DiUi$ (3)
and
 $Pi+1∣i=AiPi∣i AiT +BiQi BiT$ (4)
where ${D}_{i}{U}_{i}$ represents any deterministic control used.
The square root covariance filter algorithm provides a stable method for computing the Kalman gain matrix and the state covariance matrix. The algorithm can be summarised as
 $Ri1/2 CiSi 0 0 AiSi BiQi1/2 U= Hi1/2 0 0 Gi Si+1 0$ (5)
where $U$ is an orthogonal transformation triangularizing the left-hand pre-array to produce the right-hand post-array. The relationship between the Kalman gain matrix, ${K}_{i}$, and ${G}_{i}$ is given by
 $AiKi=Gi Hi1/2 -1.$
nag_tsa_multi_kalman_sqrt_var (g13ea) requires the input of the lower triangular Cholesky factors of the noise covariance matrices ${R}_{i}^{1/2}$ and, optionally, ${Q}_{i}^{1/2}$ and the lower triangular Cholesky factor of the current state covariance matrix, ${S}_{i}$, and returns the product of the matrices ${A}_{i}$ and ${K}_{i}$, ${A}_{i}{K}_{i}$, the Cholesky factor of the updated state covariance matrix ${S}_{i+1}$ and the matrix ${H}_{i}^{1/2}$ used in the computation of the likelihood for the model.

## References

Vanbegin M, van Dooren P and Verhaegen M H G (1989) Algorithm 675: FORTRAN subroutines for computing the square root covariance filter and square root information filter in dense or Hessenberg forms ACM Trans. Math. Software 15 243–256
Verhaegen M H G and van Dooren P (1986) Numerical aspects of different Kalman filter implementations IEEE Trans. Auto. Contr. AC-31 907–917

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{a}\left(\mathit{lds},{\mathbf{n}}\right)$ – double array
lds, the first dimension of the array, must satisfy the constraint $\mathit{lds}\ge {\mathbf{n}}$.
The state transition matrix, ${A}_{i}$.
2:     $\mathrm{b}\left(\mathit{lds},{\mathbf{l}}\right)$ – double array
lds, the first dimension of the array, must satisfy the constraint $\mathit{lds}\ge {\mathbf{n}}$.
The noise coefficient matrix ${B}_{i}$.
3:     $\mathrm{stq}$ – logical scalar
If ${\mathbf{stq}}=\mathit{true}$, the state noise covariance matrix ${Q}_{i}$ is assumed to be the identity matrix. Otherwise the lower triangular Cholesky factor, ${Q}_{i}^{1/2}$, must be provided in q.
4:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – double array
The first dimension, $\mathit{ldq}$, of the array q must satisfy
• if ${\mathbf{stq}}=\mathit{false}$, $\mathit{ldq}\ge {\mathbf{l}}$;
• otherwise $\mathit{ldq}\ge 1$.
The second dimension of the array q must be at least ${\mathbf{l}}$ if ${\mathbf{stq}}=\mathit{false}$ and at least $1$ if ${\mathbf{stq}}=\mathit{true}$.
If ${\mathbf{stq}}=\mathit{false}$, q must contain the lower triangular Cholesky factor of the state noise covariance matrix, ${Q}_{i}^{1/2}$. Otherwise q is not referenced.
5:     $\mathrm{c}\left(\mathit{ldm},{\mathbf{n}}\right)$ – double array
ldm, the first dimension of the array, must satisfy the constraint $\mathit{ldm}\ge {\mathbf{m}}$.
The measurement coefficient matrix, ${C}_{i}$.
6:     $\mathrm{r}\left(\mathit{ldm},{\mathbf{m}}\right)$ – double array
ldm, the first dimension of the array, must satisfy the constraint $\mathit{ldm}\ge {\mathbf{m}}$.
The lower triangular Cholesky factor of the measurement noise covariance matrix ${R}_{i}^{1/2}$.
7:     $\mathrm{s}\left(\mathit{lds},{\mathbf{n}}\right)$ – double array
lds, the first dimension of the array, must satisfy the constraint $\mathit{lds}\ge {\mathbf{n}}$.
The lower triangular Cholesky factor of the state covariance matrix, ${S}_{i}$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the arrays a, b, s and the second dimension of the arrays a, c, s. (An error is raised if these dimensions are not equal.)
$n$, the size of the state vector.
Constraint: ${\mathbf{n}}\ge 1$.
2:     $\mathrm{m}$int64int32nag_int scalar
Default: the first dimension of the arrays c, r and the second dimension of the array r. (An error is raised if these dimensions are not equal.)
$m$, the size of the observation vector.
Constraint: ${\mathbf{m}}\ge 1$.
3:     $\mathrm{l}$int64int32nag_int scalar
Default: the second dimension of the array b.
$l$, the dimension of the state noise.
Constraint: ${\mathbf{l}}\ge 1$.
4:     $\mathrm{tol}$ – double scalar
Default: $0.0$
The tolerance used to test for the singularity of ${H}_{i}^{1/2}$. If , then  is used instead. The inverse of the condition number of ${H}^{1/2}$ is estimated by a call to nag_lapack_dtrcon (f07tg). If this estimate is less than tol then ${H}^{1/2}$ is assumed to be singular.
Constraint: ${\mathbf{tol}}\ge 0.0$.

### Output Parameters

1:     $\mathrm{s}\left(\mathit{lds},{\mathbf{n}}\right)$ – double array
The lower triangular Cholesky factor of the state covariance matrix, ${S}_{i+1}$.
2:     $\mathrm{k}\left(\mathit{lds},{\mathbf{m}}\right)$ – double array
The Kalman gain matrix, ${K}_{i}$, premultiplied by the state transition matrix, ${A}_{i}$, ${A}_{i}{K}_{i}$.
3:     $\mathrm{h}\left(\mathit{ldm},{\mathbf{m}}\right)$ – double array
The lower triangular matrix ${H}_{i}^{1/2}$.
4:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{n}}<1$, or ${\mathbf{m}}<1$, or ${\mathbf{l}}<1$, or $\mathit{lds}<{\mathbf{n}}$, or $\mathit{ldm}<{\mathbf{m}}$, or ${\mathbf{stq}}=\mathit{true}$ and $\mathit{ldq}<1$, or ${\mathbf{stq}}=\mathit{false}$ and $\mathit{ldq}<{\mathbf{l}}$, or ${\mathbf{tol}}<0.0$.
${\mathbf{ifail}}=2$
The matrix ${H}_{i}^{1/2}$ is singular.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The use of the square root algorithm improves the stability of the computations as compared with the direct coding of the Kalman filter. The accuracy will depend on the model.

For models with time-invariant $A,B$ and $C$, nag_tsa_multi_kalman_sqrt_invar (g13eb) can be used.
If ${W}_{i}$ and ${V}_{i}$ are independent multivariate Normal variates then the log-likelihood for observations $i=1,2,\dots ,t$ is given by
 $lθ = κ - 12 ∑ i=1 t l n detHi - 12 ∑ i=1 t Yi - Ci X i∣i-1 T H i -1 Yi - Ci X i∣i-1$
where $\kappa$ is a constant.
The Cholesky factors of the covariance matrices can be computed using nag_lapack_dpotrf (f07fd).
Note that the model
 $Xi+1=AiXi+Wi, VarWi=Qi Yi=CiXi+Vi, VarVi=Ri$
can be specified either with b set to the identity matrix and ${\mathbf{stq}}=\mathit{false}$ and the matrix ${Q}^{1/2}$ input in q or with ${\mathbf{stq}}=\mathit{true}$ and b set to ${Q}^{1/2}$.
The algorithm requires $\frac{7}{6}{n}^{3}+{n}^{2}\left(\frac{5}{2}m+l\right)+n\left(\frac{1}{2}{l}^{2}+{m}^{2}\right)$ operations and is backward stable (see Verhaegen and van Dooren (1986)).

## Example

This example first inputs the number of updates to be computed and the problem sizes. The initial state vector and state covariance matrix are input followed by the model matrices ${A}_{i},{B}_{i},{C}_{i},{R}_{i}$ and optionally ${Q}_{i}$. The Cholesky factors of the covariance matrices can be computed if required. The model matrices can be input at each update or only once at the first step. At each update the observed values are input and the residuals are computed and printed and the estimate of the state vector, ${\stackrel{^}{X}}_{i\mid i-1}$, and the deviance are updated. The deviance is $-2×\text{}$log-likelihood ignoring the constant. After the final update the state covariance matrix is computed from s and printed along with final estimate of the state vector and the value of the deviance.
The data is for a two-dimensional time series to which a VARMA$\left(1,1\right)$ has been fitted. For the specification of a VARMA model as a state space model see the G13 Chapter Introduction. The initial value of $P$, ${P}_{0}$, is the solution to
 $P0=A1P0 A1T +B1Q1 B1T .$
For convenience, the mean of each series is input before the first update and subtracted from the observations before the measurement update is computed.
```function g13ea_example

fprintf('g13ea example results\n\n');

% Constant matrices
s = [ 8.2068  2.0599  1.4807  0.3627;
2.0599  7.9645  0.9703  0.2136;
1.4807  0.9703  0.9253  0.2236;
0.3627  0.2136  0.2236  0.0542];
a = [ 0.607, -0.033,  1,      0;
0,      0.543,  0,      1;
0,      0,      0,      0;
0,      0,      0,      0];
b = [ 1,      0;
0,      1;
0.543,  0.125;
0.134,  0.026];
stq = false;
q = [ 2.598,  0.56;
0.560,  5.33];
c = [ 1,      0,      0,      0;
0,      1,      0,      0];
r = [ 0,      0;
0,      0];
% Need to factorize S and Q
s = chol(s,'lower');
q = chol(q,'lower');

n = size(s,1);
m = 2;

% Data
x = zeros(n,1);
ym = [-1.49  7.34; -1.62  6.35;  5.20  6.96;  6.23  8.54;  6.21  6.62;
5.86  4.97;  4.09  4.55;  3.18  4.81;  2.62  4.75;  1.49  4.76;
1.17 10.88;  0.85 10.01; -0.35 11.62;  0.24 10.36;  2.44  6.40;
2.58  6.24;  2.04  7.93;  0.40  4.04;  2.26  3.73;  3.34  5.60;
5.09  5.35;  5.00  6.81;  4.78  8.27;  4.11  7.68;  3.45  6.65;
1.65  6.08;  1.29 10.25;  4.09  9.14;  6.32 17.75;  7.50 13.30;
3.89  9.63;  1.58  6.80;  5.21  4.08;  5.25  5.06;  4.93  4.94;
7.38  6.65;  5.87  7.94;  5.81 10.76;  9.68 11.89;  9.07  5.85;
7.29  9.01;  7.84  7.50;  7.55 10.02;  7.32 10.38;  7.97  8.15;
7.76  8.37;  7.00 10.73;  8.35 12.14];
ymean = [4.404; 7.991];
ny = size(ym,1);

% Loop over data
fprintf('      Residuals\n\n');
dev = 0;
for j = 1:ny
y = ym(j,:)';
[s, K, H, ifail] = g13ea( ...
a, b, stq, q, c, r, s);

% subtract the mean
y = y - ymean;
% Time and measurement update
y = y-c*x;
x = a*x + K*y;

fprintf('%10.4f%10.4f\n',y);

% Update Loglikelihood
y = H\y;
dev = dev + dot(y,y);
for i = 1:m
dev = dev + 2*log(H(i,i));
end

end

% P from S
p = s*s';

% Final results

fprintf('\nFinal x\n\n')
disp (x');

[ifail] = x04ca(...
'Lower','N', p, 'Final Value of P');

fprintf('\nDeviance = %13.4e\n', dev);

```
```g13ea example results

Residuals

-5.8940   -0.6510
-1.4710   -1.0407
5.1658    0.0447
-1.3280    0.4580
1.3652   -1.5066
-0.2337   -2.4192
-0.8685   -1.7065
-0.4624   -1.1519
-0.7510   -1.4218
-1.3526   -1.3335
-0.6707    4.8593
-1.7389    0.4138
-1.6376    2.7549
-0.6137    0.5463
0.9067   -2.8093
-0.8255   -0.9355
-0.7494    1.0247
-2.2922   -3.8441
1.8812   -1.7085
-0.7112   -0.2849
1.6747   -1.2400
-0.6619    0.0609
0.3271    1.0074
-0.8165   -0.5325
-0.2759   -1.0489
-1.9383   -1.1186
-0.3131    3.5855
1.3726   -0.1289
1.4153    8.9545
0.3672   -0.4126
-2.3659   -1.2823
-1.0130   -1.7306
3.2472   -3.0836
-1.1501   -1.1623
0.6855   -1.2751
2.3432    0.2570
-1.6892    0.3565
1.3871    3.0138
3.3840    2.1312
-0.5118   -4.7670
0.8569    2.3741
0.9558   -1.2209
0.6778    2.1993
0.4304    1.1393
1.4987   -1.2255
0.5361    0.1237
0.2649    2.4582
2.0095    2.5623

Final x

3.6698    2.5888         0         0

Final Value of P
1          2          3          4
1      2.5980
2      0.5600     5.3300
3      1.4807     0.9703     0.9253
4      0.3627     0.2136     0.2236     0.0542

Deviance =    2.2287e+02
```