Cython

KalmanTV Class

class kalmantv.cython.kalmantv.KalmanTV

Create a Kalman Time-Varying object. The methods of the object can predict, update, sample and smooth the mean and variance of the Kalman Filter. This method is useful if one wants to track an object with streaming observations.

The specific model we are using to approximate the solution \(x_n\) is

\[ \begin{align}\begin{aligned}x_n = Q(x_{n-1} -\lambda) + \lambda + R_n^{1/2} \epsilon_n\\y_n = d + W x_n + \Sigma_n^{1/2} \eta_n\end{aligned}\end{align} \]

where \(\epsilon_n\) and \(\eta_n\) are independent \(N(0,1)\) distributions and \(y_n\) denotes the model interrogation (observation) at time n.

The variables of the model are defined below in the argument section. The methods of this class calculates \(\theta = (\mu, \Sigma)\) for \(x_n\) and the notation for the state at time n given observations from k is given by \(\theta_{n|K}\).

Parameters

n_state (int) – Number of state variables.
n_meas (int) – Number of measurement variables.
mu_state_past (ndarray(n_state)) – Mean estimate for state at time n-1 given observations from times [0…n-1]; \(\mu_{n-1|n-1}\).
var_state_past (ndarray(n_state, n_state)) – Covariance of estimate for state at time n-1 given observations from times [0…n-1]; \(\Sigma_{n-1|n-1}\).
mu_state_pred (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…n-1]; denoted by \(\mu_{n|n-1}\).
var_state_pred (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…n-1]; denoted by \(\Sigma_{n|n-1}\).
mu_state_filt (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…n]; denoted by \(\mu_{n|n}\).
var_state_filt (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…n]; denoted by \(\Sigma_{n|n}\).
mu_state_next (ndarray(n_state)) – Mean estimate for state at time n+1 given observations from times [0…N]; denoted by \(\mu_{n+1|N}\).
var_state_next (ndarray(n_state, n_state)) – Covariance of estimate for state at time n+1 given observations from times [0…N]; denoted by \(\Sigma_{n+1|N}\).
x_state_smooths (ndarray(n_state)) – Sample solution at time n given observations from times [0…N]; denoted by \(X_{n|N}\)
mu_state_smooth (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…N]; denoted by \(\mu_{n|N}\).
var_state_smooth (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…N]; denoted by \(\Sigma_{n|N}\).
x_state (ndarray(n_state)) – Simulated state vector; \(x_n\).
mu_state (ndarray(n_state)) – Transition offsets defining the state variable; denoted by \(\lambda\).
wgt_state (ndarray(n_state, n_state)) – Transition matrix defining the state variable; denoted by \(Q\).
var_state (ndarray(n_state, n_state)) – Variance matrix defining the state variable; denoted by \(R\).
x_meas (ndarray(n_meas)) – Interrogated measurement vector from x_state; \(y_n\).
mu_meas (ndarray(n_meas)) – Transition offsets defining the measurement variable; denoted by \(d\).
wgt_meas (ndarray(n_meas, n_state)) – Transition matrix defining the measurement variable; denoted by \(W\).
var_meas (ndarray(n_meas, n_meas)) – Variance matrix defining the measurement variable; denoted by \(\Sigma_n\).
z_state (ndarray(n_state)) – Random vector simulated from \(N(0, 1)\).
mu_fore (ndarray(n_meas)) – Mean estimate for measurement at n given observations from [0…n-1]
var_fore (ndarray(n_meas, n_meas)) – Covariance of estimate for state at time n given observations from times [0…n-1]

filter(): Perform one step of the Kalman filter. Combines KalmanTV.predict() and KalmanTV.update() steps to get \(\theta_{n|n}\) from \(\theta_{n-1|n-1}\).

forecast(): Forecasts the mean and variance of the measurement variable at time step n given observations from times [0…n-1].

predict(): Perform one prediction step of the Kalman filter. Calculates \(\theta_{n|n-1}\) from \(\theta_{n-1|n-1}\).

smooth(): Perform one step of both Kalman mean/variance and sampling smoothers. Combines KalmanTV.smooth_mv() and KalmanTV.smooth_sim() steps to get \(x_{n|N}\) and \(\theta_{n|N}\) from \(\theta_{n+1|N}\), \(\theta_{n|n}\), and \(\theta_{n+1|n}\).

smooth_mv(): Perform one step of the Kalman mean/variance smoother. Calculates \(\theta_{n|N}\) from \(\theta_{n+1|N}\), \(\theta_{n|n}\), and \(\theta_{n+1|n}\).

smooth_sim(): Perform one step of the Kalman sampling smoother. Calculates a draw \(x_{n|N}\) from \(x_{n+1|N}\), \(\theta_{n|n}\), and \(\theta_{n+1|n}\).

update(): Perform one update step of the Kalman filter. Calculates \(\theta_{n|n}\) from \(\theta_{n|n-1}\).

kalmantv.cython.kalmantv.state_sim()

Simulates from a normal distribution with mean mu_state, variance var_state, and randomness z_state drawn from \(N(0, 1)\).

Parameters

x_state (ndarray(n_state)) – Simulated state.
llt_state (ndarray(n_state, n_state)) – Temporary matrix to store cholesky factorization.
mu_state (ndarray(n_state)) – Mean vector.
var_state (ndarray(n_state, n_state)) – Variance matrix.
z_state (ndarray(n_state)) – Random vector simulated from \(N(0, 1)\).

Returns

x_state (ndarray(n_state)): Simulated state.
llt_state (ndarray(n_state, n_state)): Temporary matrix to store cholesky factorization.

Return type

(tuple)

BLAS Operations

kalmantv.cython.blas.chol_fact()

Computes the cholesky factorization of variance matrix V.

Parameters

L (ndarray(N, M)) – Returned matrix.
V (ndarray(N, N)) – Variance matrix.

Returns

Cholesky factorization of variance matrix V.

Return type

(ndarray(N, M))

kalmantv.cython.blas.mat_add()

Calculates \(B = \alpha A + \beta B\).

Parameters

B (ndarray(N)) – Returned matrix.
alpha (double) – Scalar \(\alpha\).
beta (double) – Scalar \(\beta\).
A (ndarray(N)) – Matrix A.

Returns

\(B = \alpha A + \beta B\).

Return type

(ndarray(M))

kalmantv.cython.blas.mat_copy()

Copies Matrix A to B.

Parameters

B (ndarray(N)) – Returned matrix.
A (ndarray(N)) – Matrix A.

Returns

Copied matrix B.

Return type

(ndarray(M))

kalmantv.cython.blas.mat_mult()

Calculates \(C = \alpha A B + \beta C\).

Parameters

C (ndarray(M, N)) – Returned matrix.
transa (char) – Specifies if matrix A should be transposed.
transb (char) – Specifies if matrix B should be transposed.
alpha (double) – Scalar \(\alpha\).
beta (double) – Scalar \(\beta\).
A (ndarray(M, K)) – First matrix.
B (ndarray(K, N)) – Second matrix.

Returns

\(C = \alpha A B + \beta C\).

Return type

(ndarray(M, N))

kalmantv.cython.blas.mat_triple_mult()

Calculates \(D = \alpha A B C + \beta D\).

Parameters

D (ndarray(L, N)) – Returned matrix.
temp (ndarray(M, L)) – Temp matrix for intermediate matrix multiplication; \(AB\).
transa (char) – Specifies if matrix A should be transposed.
transb (char) – Specifies if matrix B should be transposed.
transc (char) – Specifies if matrix C should be transposed.
alpha (double) – Scalar \(\alpha\).
beta (double) – Scalar \(\beta\).
A (ndarray(M, K)) – First matrix.
B (ndarray(K, L)) – Second matrix.
C (ndarray(L, N)) – Third matrix.

Returns

D (ndarray(M, N)): \(D = \alpha A B C + \beta D\).
temp (ndarray(M, L)): \(AB\).

Return type

(tuple)

kalmantv.cython.blas.mat_vec_mult()

Calculates \(y = \alpha A x + \beta y\).

Parameters

y (ndarray(M)) – Returned vector.
trans (char) – Specifies if matrix A should be transposed.
alpha (double) – Scalar \(\alpha\).
beta (double) – Scalar \(\beta\).
A (ndarray(M, N)) – Matrix A.
x (ndarray(N)) – Vector x.

Returns

\(y = \alpha A x + \beta y\).

Return type

(ndarray(M))

kalmantv.cython.blas.solveV()

Solves X in \(VX = B\), where V is a variance matrix.

Parameters

U (ndarray(N, M)) – Temp matrix for intermediate storage; cholesky factorization of V.
X (ndarray(N, M)) – Returned matrix.
V (ndarray(N, N)) – Variance matrix.
B (ndarray(N, M)) – Second matrix.

Returns

U (ndarray(N, M)): Temp matrix.
X (ndarray(N, M)): X in \(VX = B\).

Return type

(tuple)

kalmantv.cython.blas.tri_vec_mult()

Calculates \(x = A x\) where A is a triangular matrix.

Parameters

x (ndarray(N)) – Vector x.
uplo (char) – Specifies if matrix A is upper or lower triangular.
trans (char) – Specifies if matrix A should be transposed.
diag (char) – Specifies if matrix A is unit triangular.
A (ndarray(M, N)) – Matrix A.

Returns

\(x = A x\).

Return type

(ndarray(M))

kalmantv.cython.blas.vec_add()

Calculates \(y = \alpha x + y\).

Parameters

y (ndarray(N)) – Returned vector.
alpha (double) – Scalar \(\alpha\).
x (ndarray(N)) – Vector x.

Returns

\(y = \alpha x + y\).

Return type

(ndarray(M))

kalmantv.cython.blas.vec_copy()

Copies vector x to y.

Parameters

y (ndarray(N)) – Returned vector.
x (ndarray(N)) – Vector x.

Returns

Copied vector y.

Return type

(ndarray(M))

Numba

KalmanTV Class

class kalmantv.numba.kalmantv.KalmanTV(*args, **kwargs)

Create a Kalman Time-Varying object. The methods of the object can predict, update, sample and smooth the mean and variance of the Kalman Filter. This method is useful if one wants to track an object with streaming observations.

The specific model we are using to approximate the solution \(x_n\) is

\[ \begin{align}\begin{aligned}x_n = Q(x_{n-1} -\lambda) + \lambda + R_n^{1/2} \epsilon_n\\y_n = d + W x_n + \Sigma_n^{1/2} \eta_n\end{aligned}\end{align} \]

where \(\epsilon_n\) and \(\eta_n\) are independent \(N(0,1)\) distributions and \(y_n\) denotes the model interrogation (observation) at time n.

The variables of the model are defined below in the argument section. The methods of this class calculates \(\theta = (\mu, \Sigma)\) for \(x_n\) and the notation for the state at time n given observations from k is given by \(\theta_{n|K}\).

Notes

For best performance, all input arrrays should have contiguous memory in fortran-order.
Avoids memory allocation whenever possible. One place this does not happen is in calculations of A += B C. This is done with A += np.dot(B, C), which involves malloc before the addition.

Parameters

n_state (int) – Number of state variables.
n_meas (int) – Number of measurement variables.
mu_state_past (ndarray(n_state)) – Mean estimate for state at time n-1 given observations from times [0…n-1]; \(\mu_{n-1|n-1}\).
var_state_past (ndarray(n_state, n_state)) – Covariance of estimate for state at time n-1 given observations from times [0…n-1]; \(\Sigma_{n-1|n-1}\).
mu_state_pred (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…n-1]; denoted by \(\mu_{n|n-1}\).
var_state_pred (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…n-1]; denoted by \(\Sigma_{n|n-1}\).
mu_state_filt (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…n]; denoted by \(\mu_{n|n}\).
var_state_filt (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…n]; denoted by \(\Sigma_{n|n}\).
mu_state_next (ndarray(n_state)) – Mean estimate for state at time n+1 given observations from times [0…N]; denoted by \(\mu_{n+1|N}\).
var_state_next (ndarray(n_state, n_state)) – Covariance of estimate for state at time n+1 given observations from times [0…N]; denoted by \(\Sigma_{n+1|N}\).
x_state_smooths (ndarray(n_state)) – Sample solution at time n given observations from times [0…N]; denoted by \(X_{n|N}\)
mu_state_smooth (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…N]; denoted by \(\mu_{n|N}\).
var_state_smooth (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…N]; denoted by \(\Sigma_{n|N}\).
x_state (ndarray(n_state)) – Simulated state vector; \(x_n\).
mu_state (ndarray(n_state)) – Transition offsets defining the state variable; denoted by \(\lambda\).
wgt_state (ndarray(n_state, n_state)) – Transition matrix defining the state variable; denoted by \(Q\).
var_state (ndarray(n_state, n_state)) – Variance matrix defining the state variable; denoted by \(R\).
x_meas (ndarray(n_meas)) – Interrogated measurement vector from x_state; \(y_n\).
mu_meas (ndarray(n_meas)) – Transition offsets defining the measurement variable; denoted by \(d\).
wgt_meas (ndarray(n_meas, n_state)) – Transition matrix defining the measurement variable; denoted by \(W\).
var_meas (ndarray(n_meas, n_meas)) – Variance matrix defining the measurement variable; denoted by \(\Sigma_n\).
z_state (ndarray(n_state)) – Random vector simulated from \(N(0, 1)\).
mu_fore (ndarray(n_meas)) – Mean estimate for measurement at n given observations from [0…n-1]
var_fore (ndarray(n_meas, n_meas)) – Covariance of estimate for state at time n given observations from times [0…n-1]

BLAS Operations

kalmantv.numba.scipy_linalg.jit_cho_factor(a, lower=False, overwrite_a=False, check_finite=True)[source]

njit implementation of scipy.linalg.cho_factor().

As with the original scipy implementation, overwrite_a only “works” if the input array is in contiguous fortran order. Otherwise a copy is created.

Parameters: a (ndarray(dim1, dim2)) – 2-dimensional matrix.
Returns: Cholesky factorization of matrix a and indicator if it is lower triangular.
Return type: (tuple)

kalmantv.numba.scipy_linalg.jit_cho_solve(c_and_lower, b, overwrite_b=False, check_finite=True)[source]

njit implementation of scipy.linalg.cho_solve().

Parameters

c_and_lower (tuple) – 2-d Matrix and indicator if it is lower triangular.
b (ndarray(dim1, dim2)) – 2-d Matrix.

Returns

Solved matrix.

Return type

(ndarray(dim1, dim2))

kalmantv.numba.scipy_linalg.jit_tri_mult(a_and_lower, x, overwrite_x=False, check_finite=True)[source]

Triangular matrix multiplication \(a x\).

Parameters

a_and_lower (tuple) – 2-d Matrix and indicator if it is lower triangular.
x (ndarray(dim1, dim2)) – 2-d Matrix.

Returns

\(a x\).

Return type

(ndarray(dim1, dim2))

Eigen

KalmanTV Class

class kalmantv.eigen.kalmantv._KalmanTV

Create a Kalman Time-Varying object. The methods of the object can predict, update, sample and smooth the mean and variance of the Kalman Filter. This method is useful if one wants to track an object with streaming observations.

The specific model we are using to approximate the solution \(x_n\) is

\[ \begin{align}\begin{aligned}x_n = Q(x_{n-1} -\lambda) + \lambda + R_n^{1/2} \epsilon_n\\y_n = d + W x_n + \Sigma_n^{1/2} \eta_n\end{aligned}\end{align} \]

where \(\epsilon_n\) and \(\eta_n\) are independent \(N(0,1)\) distributions and \(y_n\) denotes the model interrogation (observation) at time n.

The variables of the model are defined below in the argument section. The methods of this class calculates \(\theta = (\mu, \Sigma)\) for \(x_n\) and the notation for the state at time n given observations from k is given by \(\theta_{n|K}\).

Parameters

n_state (int) – Number of state variables.
n_meas (int) – Number of measurement variables.
mu_state_past (ndarray(n_state)) – Mean estimate for state at time n-1 given observations from times [0…n-1]; \(\mu_{n-1|n-1}\).
var_state_past (ndarray(n_state, n_state)) – Covariance of estimate for state at time n-1 given observations from times [0…n-1]; \(\Sigma_{n-1|n-1}\).
mu_state_pred (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…n-1]; denoted by \(\mu_{n|n-1}\).
var_state_pred (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…n-1]; denoted by \(\Sigma_{n|n-1}\).
mu_state_filt (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…n]; denoted by \(\mu_{n|n}\).
var_state_filt (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…n]; denoted by \(\Sigma_{n|n}\).
mu_state_next (ndarray(n_state)) – Mean estimate for state at time n+1 given observations from times [0…N]; denoted by \(\mu_{n+1|N}\).
var_state_next (ndarray(n_state, n_state)) – Covariance of estimate for state at time n+1 given observations from times [0…N]; denoted by \(\Sigma_{n+1|N}\).
x_state_smooths (ndarray(n_state)) – Sample solution at time n given observations from times [0…N]; denoted by \(X_{n|N}\)
mu_state_smooth (ndarray(n_state)) – Mean estimate for state at time n given observations from times [0…N]; denoted by \(\mu_{n|N}\).
var_state_smooth (ndarray(n_state, n_state)) – Covariance of estimate for state at time n given observations from times [0…N]; denoted by \(\Sigma_{n|N}\).
x_state (ndarray(n_state)) – Simulated state vector; \(x_n\).
mu_state (ndarray(n_state)) – Transition offsets defining the state variable; denoted by \(\lambda\).
wgt_state (ndarray(n_state, n_state)) – Transition matrix defining the state variable; denoted by \(Q\).
var_state (ndarray(n_state, n_state)) – Variance matrix defining the state variable; denoted by \(R\).
x_meas (ndarray(n_meas)) – Interrogated measurement vector from x_state; \(y_n\).
mu_meas (ndarray(n_meas)) – Transition offsets defining the measurement variable; denoted by \(d\).
wgt_meas (ndarray(n_meas, n_state)) – Transition matrix defining the measurement variable; denoted by \(W\).
var_meas (ndarray(n_meas, n_meas)) – Variance matrix defining the measurement variable; denoted by \(\Sigma_n\).
z_state (ndarray(n_state)) – Random vector simulated from \(N(0, 1)\).
mu_fore (ndarray(n_meas)) – Mean estimate for measurement at n given observations from [0…n-1]
var_fore (ndarray(n_meas, n_meas)) – Covariance of estimate for state at time n given observations from times [0…n-1]

filter(): Perform one step of the Kalman filter. Combines KalmanTV.predict() and KalmanTV.update() steps to get \(\theta_{n|n}\) from \(\theta_{n-1|n-1}\).

forecast(): Forecasts the mean and variance of the measurement variable at time step n given observations from times [0…n-1].

predict(): Perform one prediction step of the Kalman filter. Calculates \(\theta_{n|n-1}\) from \(\theta_{n-1|n-1}\).

smooth(): Perform one step of both Kalman mean/variance and sampling smoothers. Combines KalmanTV.smooth_mv() and KalmanTV.smooth_sim() steps to get \(x_{n|N}\) and \(\theta_{n|N}\) from \(\theta_{n+1|N}\), \(\theta_{n|n}\), and \(\theta_{n+1|n}\).

smooth_mv(): Perform one step of the Kalman mean/variance smoother. Calculates \(\theta_{n|N}\) from \(\theta_{n+1|N}\), \(\theta_{n|n}\), and \(\theta_{n+1|n}\).

smooth_sim(): Perform one step of the Kalman sampling smoother. Calculates a draw \(x_{n|N}\) from \(x_{n+1|N}\), \(\theta_{n|n}\), and \(\theta_{n+1|n}\).

state_sim(): Simulates from a normal distribution with mean mu_state, variance var_state, and randomness z_state drawn from \(N(0, 1)\).

update(): Perform one update step of the Kalman filter. Calculates \(\theta_{n|n}\) from \(\theta_{n|n-1}\).

Gaussian Model

kalmantv.mv_gaussian.mv_gaussian(wgt_genss, mu_genss, chol_genss)[source]

Calculate the mean and variance of the joint density \(Y=(Y_0, Y_1, \ldots, Y_n)\) where \(Y_n\) is the Gaussian process.

Parameters

wgt_genss (ndarray(n_genss, n_genss, steps)) – Transition matrices in the Gaussian process; denoted by \(A_n\).
mu_genss (ndarray(n_genss, steps)) – Transition offsets in the Gaussian process; denoted by \(b_n\).
chol_genss (ndarray(n_genss, n_genss, steps)) – Cholesky of the variance matrices in the Gaussian process; denoted by \(C_n\).

Returns

gaussian_mu (ndarray(n_genss, n_genss, steps)): Mean of the joint density.
gaussian_var (ndarray(n_genss, steps)): Variance of the joint density.

Return type

(tuple)

kalmantv.mv_gaussian.ss2genss(wgt_state, mu_state, var_state, wgt_meas, mu_meas, var_meas)[source]

Converts the state-space parameters:

\[ \begin{align}\begin{aligned}X_n = c_n + T_n X_{n-1} + R_n^{1/2} \epsilon_n\\y_n = d_n + W_n x_n + H_n^{1/2} \eta_n\end{aligned}\end{align} \]

to the Gaussian process parameters with the model:

\[Y_n = b_n + A_n Y_{n-1} + C_n \epsilon_n\]

Parameters

wgt_state (ndarray(n_states, n_states, n_steps)) – Transition matrices defining the solution prior; denoted by \(T_n\).
mu_state (ndarray(n_state, n_steps)) – Transition offsets defining the solution prior; denoted by \(c_n\).
var_state (ndarray(n_state, n_state, n_steps)) – Variance matrices defining the solution prior; denoted by \(R_n\).
wgt_meas (ndarray(n_meas, n_meas, n_steps)) – Transition matrices defining the measure prior; denoted by \(W_n\).
mu_meas (ndarray(n_meas, n_steps)) – Transition offsets defining the measure prior; denoted by \(d_n\).
var_meas (ndarray(n_meas, n_meas, n_steps)) – Variance matrice defining the measure prior; denoted by \(H_n\).

Returns

wgt_genss (ndarray(n_genss, n_genss, steps)): Transition matrices in the Gaussian process; denoted by \(A_n\).
mu_genss (ndarray(n_genss, steps)): Transition offsets in the Gaussian process; denoted by \(b_n\).
chol_genss (ndarray(n_genss, n_genss, steps)): Cholesky of the variance matrices in the Gaussian process; denoted by \(C_n\).

Return type

(tuple)