Calculates estimates from the Kalman filter (A.I. Glaser).

### Option

`PRINT` = string tokens |
Controls printed output (`xpredicted` , `xfiltered` , `deviance` , `residuals` , `gain` , `varpredictions` , `varfiltered` , `varresiduals` ); default `*` |
---|

### Parameters

`Y` = variates, matrices or pointers |
Time series data |
---|---|

`YTRANSITIONMATRIX` = scalars, matrices or pointers |
Observation transition matrix, mapping the relationship between the current value of the state vector and the observation |

`YVCOVARIANCE` = scalars, symmetricmatrices or pointers |
Observation error covariance matrix |

`XSTATETRANSITIONMATRIX` = scalars, matrices or pointers |
State transition matrix, mapping the relationship between the current value of the state vector and its previous value |

`BXVCOVARIANCE` = scalars, matrices or pointers |
State noise coefficient matrix |

`XVCOVARIANCE` = scalars, symmetricmatrices or pointers |
State error covariance matrix |

`MEANINITIAL` = scalars, variates or matrices |
Initial value of the mean of the state vector |

`VARINITIAL` = scalars or symmetricmatrices |
Initial value of the variance-covariance matrix of the state vector |

`DEVIANCE` = scalars |
To save the deviance of the model |

`XPREDICTED` = matrices |
Saves the predicted (a priori) state estimate matrix |

`XFILTERED` = matrices |
Saves the filtered (a posteriori) state estimate matrix |

`RESIDUALS` = matrices |
Saves the matrix of residuals |

`GAIN` = pointers |
Saves the Kalman gain matrix at each iteration |

`VARPREDICTIONS` = pointers |
Saves the variances of the predicted state estimate matrix at each iteration |

`VARFILTERED` = pointers |
Saves the variances of the filtered state estimate matrix at each iteration |

`VARRESIDUALS=` pointers |
Saves the variances of the residuals at each iteration |

`SAVE` = pointers |
Save structure which provides information for use in `DKALMAN` |

### Description

`KALMAN`

performs the iterations from the time-varying or time-invariant Kalman filter using a square-root covariance filter algorithm.

The parameters contain the components of the state space model where data (*Y*) are assumed to be linked to an unknown state vector (*X*), see *Method* for further details.

The `Y`

parameter specifies the values of the observations as a variate, a matrix (where each row contains the values at a specific time point) or a pointer to a set of variates.

The `YTRANSITIONMATRIX`

parameter maps the state vector (*X*) onto the observation vector (*Y*), with residuals assumed to come from a (multivariate) Normal distribution with mean of zero and variance-covariance matrix `YVCOVARIANCE`

.

The `XSTATETRANSITIONMATRIX`

parameter gives the relationship between the state vector *X* at time *t* with that at time *t*-1. This is assumed to have residuals from a Normal distribution with mean zero and variance-covariance matrix specified by the `BXVCOVARIANCE`

and `XVCOVARIANCE`

parameters according to the equation

`T(BXVCOVARIANCE) *+ XVCOVARIANCE *+ BXVCOVARIANCE`

By default `BXVCOVARIANCE`

is the identity matrix. A description of all the default combinations of these parameters is given in the *Method* Section, below.

The state-space parameters `YTRANSITIONMATRIX`

, `XSTATETRANSITIONMATRIX`

and `BXVCOVARIANCE`

can be set to scalars, or to matrices, or to pointers containing scalars or matrices (if they are time-varying) where element *t* of the pointer contains the scalar or matrix at time *t*.

The covariance matrices, `YVCOVARIANCE`

and `XVCOVARIANCE`

, can be set to scalars or to symmetric matrices, or to pointers containing scalars or symmetric matrices (if they are time-varying) where element *t* of the pointer contains the scalar or symmetric matrix at time *t*.

You should only set `XSTATETRANSITIONMATRIX`

, `BXVCOVARIANCE`

and `XVCOVARIANCE`

to scalars when the state vector (*X*) is of dimension one. Likewise `YVCOVARIANCE`

should be set to a scalar only when the data vector (*Y*) is of dimension one, and `YTRANSITIONMATRIX`

should be set to a scalar only when both *Y* and *X* are of dimension one.

You can simplify the input when `YTRANSITIONMATRIX`

, `YVCOVARIANCE`

, `XSTATETRANSITIONMATRIX`

, `BXVCOVARIANCE`

and/or `XVCOVARIANCE`

are set to pointers, if there are only a few different values. You need then specify elements of the pointer only for the times when the values change (the omitted elements are assumed to be the same as the most recent previous value). For example, suppose there is a change at time 20 for the setting (say `ystate`

) of the `YTRANSITIONMATRIX`

parameter. You could then define `ystate`

with elements only for times 1 and 20, as shown below.

`POINTER [SUFFIXES=!(1,20); VALUES=matrix1,matrix20] ystate`

(Note that you must always specify an element for time 1.)

When `YTRANSITIONMATRIX`

, `YVCOVARIANCE`

, `XSTATETRANSITIONMATRIX`

, `BXVCOVARIANCE`

or `XVCOVARIANCE`

are set to pointers, then all elements of each pointer must be of the same type, e.g. if `YTRANSITIONMATRIX`

is a pointer and its first element is a scalar, then all of the other elements of `YTRANSITIONMATRIX`

must be scalars too.

Before running a Kalman filter, values must be defined for the mean and variance of the initial value of the state vector. These are supplied by the `MEANINITIAL`

and `VARINITIAL`

parameters respectively.

The `PRINT`

option controls printed output, with settings:

`xpredicted` |
predicted (a priori) state estimate matrix, |
---|---|

`xfiltered` |
filtered (a posteriori) state estimate matrix, |

`deviance` |
deviance of the model, |

`residuals` |
matrix of residuals, |

`gain` |
Kalman gain matrix at each iteration, |

`varpredictions` |
variance of predicted state estimate matrix, |

`varfiltered` |
variance of filtered state estimate matrix, and |

`varresiduals` |
variance of the residuals. |

By default nothing is printed.

The results can also be saved, using the parameters `DEVIANCE`

, `XPREDICTED`

, `XFILTERED`

, `RESIDUALS`

, `GAIN`

, `VARPREDICTIONS`

, `VARFILTERED`

and `VARRESIDUALS`

. The deviance is saved as a scalar. The `XPREDICTED`

, `XFILTERED`

and `RESIDUALS`

parameters save matrices, where each row corresponds to an individual time point. The others parameters save pointers, suffixed from 1…*n*, where *n* is the number of time points.

The `SAVE`

parameter saves various elements of the output for use by the `DKALMAN`

procedure, which plots fitted and original values of the data.

Option: `PRINT`

.

Parameters: `Y`

, `YTRANSITIONMATRIX`

, `YVCOVARIANCE`

, `XSTATETRANSITIONMATRIX`

, `BXVCOVARIANCE`

, `XVCOVARIANCE`

, `MEANINITIAL`

, `VARINITIAL`

, `DEVIANCE`

, `XPREDICTED`

, `XFILTERED`

, `RESIDUALS`

, `GAIN`

, `VARPREDICTIONS`

, `VARFILTERED`

, `VARRESIDUALS`

, `SAVE`

.

### Method

Kalman filtering is a method of analysing multi-dimensional time series which can be written in the state-space form:

*Y _{t}* =

*C*

_{t}*X*+

_{t}*V*

_{t}*X _{t}* =

*A*

_{t}*X*–

_{t}_{1}+

*B*

_{t}*W*

_{t}where:

*Y _{t}* is the observed measurement vector (

`Y`

),*X _{t}* is the state vector,

*C _{t}* is the observation transition matrix (

`YTRANSITIONMATRIX`

),*V _{t}* is the observation error,

*A _{t}* is the state transition matrix (

`XSTATETRANSITIONMATRIX`

),*B _{t}* is the state noise coefficient matrix (

`BXVCOVARIANCE`

) and*W _{t}* is the state noise,

all measured at time *t*. When *A _{t}*,

*B*and

_{t}*C*are equal for all values of

_{t}*t*, the model is assumed time invariant.

When `BXVCOVARIANCE`

is not set it is assumed to be the identity matrix.

The observation error and state noise terms are assumed to be uncorrelated, with zero mean, and covariance matrices given by `YVCOVARIANCE`

and `XVCOVARIANCE`

respectively. When `XVCOVARIANCE`

is not set, it is assumed to be the identity matrix.

The estimate of *X _{i}* given the observations

*Y*

_{1}to

*Y*–

_{i}_{1}is known as the predicted (a priori) state estimate matrix, and is usually denoted as

*X*

_{i}_{|i-1}. Similarly, the estimate of

*X*given the observations

_{i}*Y*

_{1}to

*Y*is known as the filtered (a posteriori) state estimate matrix and is usually denoted as

_{i}*X*

_{i}_{|i}.

The initial values *X*_{1|0} are assumed to be drawn from a multivariate Normal distribution with mean `MEANINITIAL`

and variance `VARINITIAL`

. If `MEANINITIAL`

is not set, it is assumed to be zero. If `VARINITIAL`

is unset then it is taken to be 100 times the identity matrix.

The `NAG`

algorithms `G13EBF`

(for time invariant matrices) or `G13EAF`

(for time varying matrices) are used to update one iteration from the Kalman filter.

### Action with `RESTRICT`

Input structures must not be restricted.

### See also

Procedure: `DKALMAN`

.

Commands for: Time series.

### Example

CAPTION 'KALMAN example',\ !t('Annual flow of the river Nile at Ashwan 1871-1970. See Durbin &',\ 'Koopman (2001, Time Series Analysis by State Space',\ 'Methods, Oxford University Press).'); STYLE=meta,plain VARIATE [VALUES=1871...1970] Year VARIATE Nile READ Nile 1120 1160 963 1210 1160 1160 813 1230 1370 1140 995 935 1110 994 1020 960 1180 799 958 1140 1100 1210 1150 1250 1260 1220 1030 1100 774 840 874 694 940 833 701 916 692 1020 1050 969 831 726 456 824 702 1120 1100 832 764 821 768 845 864 862 698 845 744 796 1040 759 781 865 845 944 984 897 822 1010 771 676 649 846 812 742 801 1040 860 874 848 890 744 749 838 1050 918 986 797 923 975 815 1020 906 901 1170 912 746 919 718 714 740 : " Random walk plus noise model " SCALAR ytrans,yvcov,xstatetrans,xvcov; VALUE=1,0.8,1,0.1 SCALAR m0,p0; VALUE=1,100 KALMAN [PRINT=xpred] Y=Nile; YTRANSITIONMATRIX=1; YVCOVARIANCE=0.8;\ XSTATETRANSITIONMATRIX=1; XVCOVARIANCE=0.1;\ MEANINITIAL=0; VARINITIAL=100 DKALMAN [TIME=Year]