kalman module

class dynamapp.kalman.Kalman(state_space: StateSpace, noise_covariance: jax.numpy.ndarray)

Bases: object

Implementation [1] of a Kalman filter for a state-space model state_space:

\[\begin{split}\begin{cases} x_{k+1} &= A x_k + B u_k + w_k \\ y_k &= C x_k + D u_k + v_k \end{cases}\end{split}\]

The matrices \((A, B, C, D)\) are taken from the state-space model state_space. The measurement-noise \(v_k\) and process-noise \(w_k\) have a covariance matrix noise_covariance defined as

\[\begin{split}\texttt{noise\_covariance} := \mathbb{E} \bigg ( \begin{bmatrix} v \\ w \end{bmatrix} \begin{bmatrix} v \\ w \end{bmatrix}^\mathrm{T} \bigg )\end{split}\]

[1] Verhaegen, Michel, and Vincent Verdult. Filtering and system identification: a least squares approach. Cambridge university press, 2007.

output_label = 'output'

Label given to an output column in self.to_dataframe.

standard_deviation_label = 'standard deviation'

Label given to a standard deviation column in self.to_dataframe.

actual_label = 'actual'

Label given to a column in self.to_dataframe, indicating measured values.

filtered_label = 'filtered'

Label given to a column in self.to_dataframe, indicating the filtered state of the Kalman filter.

next_predicted_label = 'next predicted (no input)'

Label given to a column in self.to_dataframe, indicating the predicted state of the Kalman filter under the absence of further inputs.

next_predicted_corrected_label = 'next predicted (input corrected)'

Label given to a column in self.to_dataframe, indicating the predicted state of the Kalman filter corrected by previous inputs. The inputs to the state-space model are known, but not at the time that the prediction was made. In order to make a fair comparison for prediction performance, the direct effect of the input on the output by the matrix \(D\) is removed in this column.

The latest prediction will have np.nan in this column, since the input is not yet known.

step(y: jax.numpy.ndarray | None, u: jax.numpy.ndarray)

Given an observed input u and output y, update the filtered and predicted states of the Kalman filter. Follows the implementation of the conventional Kalman filter in [1] on page 140.

The output y can be missing by setting y=None. In that case, the Kalman filter will obtain the next internal state by stepping the state space model.

[1] Verhaegen, Michel, and Vincent Verdult. Filtering and system identification: a least squares approach. Cambridge university press, 2007.

extrapolate(timesteps) → pandas.DataFrame

Make a timesteps number of steps ahead prediction about the output of the state-space model self.state_space given no further inputs. The result is a pd.DataFrame where the columns are self.state_space.y_column_names: the output columns of the state-space model self.state_space.

to_dataframe() → pandas.DataFrame

Returns the output of the Kalman filter as a pd.DataFrame. The returned value contains information about filtered and predicted states of the Kalman filter at different timesteps. The expected standard deviation of the output is given, assuming independence (!) of the state estimation error and measurement noise.

The rows of the returned dataframe correspond to timesteps. The columns of the returned dataframe are a 3-dimensional multi-index with the following levels:

1. The output name, in the list self.state_space.y_column_names.

2. An indication of whether the value is

   • a value that was actually measured, these values were given to self.step as the y parameter,

   • a filtered state,

   • a predicted state given no further input or

   • a predicted state where the effect of the next input has been corrected for. This column is useful for comparing prediction performance.

3. Whether the column is a value or the corresponding expected standard deviation.