simdkalman documentation¶
Fast Kalman filters in Python leveraging singleinstruction multipledata vectorization. That is, running n similar Kalman filters on n independent series of observations. Not to be confused with SIMD processor instructions.
See full documentation.
Installation: pip install simdkalman
Source code: https://github.com/oseiskar/simdkalman
License: MIT
Terminology¶
Following the notation in [1], the Kalman filter framework consists of a dynamic model (state transition model)
and a measurement model (observation model)
where the vector \(x\) is the (hidden) state of the system and \(y\) is an observation. A and H are matrices of suitable shape and \(Q\), \(R\) are positivedefinite noise covariance matrices.
[1]  Simo Sarkkä (2013). Bayesian Filtering and Smoothing. Cambridge University Press. https://users.aalto.fi/~ssarkka/pub/cup_book_online_20131111.pdf 
Usage example¶
Define model
import simdkalman
import numpy as np
kf = simdkalman.KalmanFilter(
state_transition = [[1,1],[0,1]], # matrix A
process_noise = np.diag([0.1, 0.01]), # Q
observation_model = np.array([[1,0]]), # H
observation_noise = 1.0) # R
Generate some fake data
import numpy.random as random
# 100 independent time series
data = random.normal(size=(100, 200))
# with 10% of NaNs denoting missing values
data[random.uniform(size=data.shape) < 0.1] = np.nan
Smooth all data
smoothed = kf.smooth(data,
initial_value = [1,0],
initial_covariance = np.eye(2) * 0.5)
# second timeseries, third time step, hidden state x
print('mean')
print(smoothed.states.mean[1,2,:])
print('covariance')
print(smoothed.states.cov[1,2,:,:])
mean
[ 0.29311384 0.06948961]
covariance
[[ 0.19959416 0.00777587]
[0.00777587 0.02528967]]
Predict new data for a single series (1d case)
predicted = kf.predict(data[1,:], 123)
# predicted observation y, third new time step
pred_mean = predicted.observations.mean[2]
pred_stdev = np.sqrt(predicted.observations.cov[2])
print('%g + %g' % (pred_mean, pred_stdev))
1.71543 + 1.65322
For complete code examples with figures, see: https://github.com/oseiskar/simdkalman/blob/master/examples/ and this Gist.
Using multidimensional observations is demonstrated in this example.
Class documentation¶

class
simdkalman.
KalmanFilter
(state_transition, process_noise, observation_model, observation_noise)¶ The main Kalman filter class providing convenient interfaces to vectorized smoothing and filtering operations on multiple independent time series.
As long as the shapes of the given parameters match reasonably according to the rules of matrix multiplication, this class is flexible in their exact nature accepting
 scalars:
process_noise = 0.1
 (2d) numpy matrices:
process_noise = numpy.eye(2)
 2d arrays:
observation_model = [[1,2]]
 3d arrays and matrices for vectorized computations. Unlike the other options, this locks the shape of the inputs that can be processed by the smoothing and prediction methods.
Parameters:  state_transition – State transition matrix \(A\)
 process_noise – Process noise (state transition covariance) matrix \(Q\)
 observation_model – Observation model (measurement model) matrix \(H\)
 observation_noise – Observation noise (measurement noise covariance) matrix \(R\)

compute
(data, n_test, initial_value=None, initial_covariance=None, smoothed=True, filtered=False, states=True, covariances=True, observations=True, likelihoods=False, gains=False, log_likelihood=False, verbose=False)¶ Smoothing, filtering and prediction at the same time. Used internally by other methods, but can also be used directly if, e.g., both smoothed and predicted data is wanted.
See smooth and predict for explanation of the common parameters. With this method, there also exist the following flags.
Parameters:  smoothed (boolean) – compute Kalman smoother (used by smooth)
 filtered (boolean) – return (oneway) filtered data
 likelihoods (boolean) – return likelihoods of each step
 gains (boolean) – return Kalman gains and pairwise covariances (used by
the EM algorithm). If true, the gains are provided as a member of
the relevant subresult
filtered.gains
and/orsmoothed.gains
.  log_likelihood (boolean) – return the loglikelihood(s) for the entire series. If matrix data is given, this will be a vector where each element is the loglikelihood of a single row.
Return type: result object whose fields depend on of the above parameter flags are True. The possible values are:
smoothed
(the return value of smooth, may containsmoothed.gains
),filtered
(likesmoothed
, may also containfiltered.gains
),predicted
(the return value of predict ifn_test > 0
)pairwise_covariances
,likelihoods
andlog_likelihood
.

predict
(data, n_test, initial_value=None, initial_covariance=None, states=True, observations=True, covariances=True, verbose=False)¶ Filter past data and predict a given number of future values. The data can be given as either of
 1d array, like
[1,2,3,4]
. In this case, one Kalman filter is used and the return value structure will contain an 1d array ofobservations
(both.mean
and.cov
will be 1d).  2d matrix, whose each row is interpreted as an independent time
series, all of which are filtered independently. The returned
observations
members will be 2dimensional in this case.  3d matrix, whose the last dimension can be used for multidimensional
observations, i.e,
data[1,2,:]
defines the components of the third observation of the second series. In themultidimensional case the returnedobservations.mean
will be 3dimensional andobservations.cov
4dimensional.
Initial values and covariances can be given as scalars or 2d matrices in which case the same initial states will be used for all rows or 3d arrays for different initial values.
Parameters:  data – Past data
 n_test (integer) – number of future steps to predict.
 initial_value – Initial value \({\mathbb E}[x_0]\)
 initial_covariance – Initial uncertainty \({\rm Cov}[x_0]\)
 states (boolean) – predict states \(x\)?
 observations (boolean) – predict observations \(y\)?
 covariances (boolean) – include covariances in predictions?
Return type: Result object with fields
states
andobservations
, if the respective parameter flags are set to True. Both areGaussian
result objects with fieldsmean
andcov
(if the covariances flag is True) 1d array, like

predict_next
(m, P)¶ Single prediction step
Parameters:  m – \({\mathbb E}[x_{j1}]\), the previous mean
 P – \({\rm Cov}[x_{j1}]\), the previous covariance
Return type: (prior_mean, prior_cov)
predicted mean and covariance \({\mathbb E}[x_j]\), \({\rm Cov}[x_j]\)

predict_observation
(m, P)¶ Probability distribution of observation \(y\) for a given distribution of \(x\)
Parameters:  m – \({\mathbb E}[x]\)
 P – \({\rm Cov}[x]\)
Return type: mean \({\mathbb E}[y]\) and covariance \({\rm Cov}[y]\)

smooth
(data, initial_value=None, initial_covariance=None, observations=True, states=True, covariances=True, verbose=False)¶ Smooth given data, which can be either
 1d array, like
[1,2,3,4]
. In this case, one Kalman filter is used and the return value structure will contain an 1d array ofobservations
(both.mean
and.cov
will be 1d).  2d matrix, whose each row is interpreted as an independent time
series, all of which are smoothed independently. The returned
observations
members will be 2dimensional in this case.  3d matrix, whose the last dimension can be used for multidimensional
observations, i.e,
data[1,2,:]
defines the components of the third observation of the second series. In themultidimensional case the returnedobservations.mean
will be 3dimensional andobservations.cov
4dimensional.
Initial values and covariances can be given as scalars or 2d matrices in which case the same initial states will be used for all rows or 3d arrays for different initial values.
Parameters:  data – 1d or 2d data, see above
 initial_value – Initial value \({\mathbb E}[x_0]\)
 initial_covariance – Initial uncertainty \({\rm Cov}[x_0]\)
 states (boolean) – return smoothed states \(x\)?
 observations (boolean) – return smoothed observations \(y\)?
 covariances (boolean) – include covariances results?
Return type: Result object with fields
states
andobservations
, if the respective parameter flags are set to True. Both areGaussian
result objects with fieldsmean
andcov
(if the covariances flag is True) 1d array, like

smooth_current
(m, P, ms, Ps)¶ Simgle Kalman smoother backwards step
Parameters:  m – \({\mathbb E}[x_jy_1,\ldots,y_j]\), the filtered mean of \(x_j\)
 P – \({\rm Cov}[x_jy_1,\ldots,y_j]\), the filtered covariance of \(x_j\)
 ms – \({\mathbb E}[x_{j+1}y_1,\ldots,y_T]\)
 Ps – \({\rm Cov}[x_{j+1}y_1,\ldots,y_T]\)
Return type: (smooth_mean, smooth_covariance, smoothing_gain)
smoothed mean \({\mathbb E}[x_jy_1,\ldots,y_T]\), and covariance \({\rm Cov}[x_jy_1,\ldots,y_T]\) & smoothing gain \(C\)

update
(m, P, y, log_likelihood=False)¶ Single update step with NaN check.
Parameters:  m – \({\mathbb E}[x_jy_1,\ldots,y_{j1}]\), the prior mean of \(x_j\)
 P – \({\rm Cov}[x_jy_1,\ldots,y_{j1}]\), the prior covariance of \(x_j\)
 y – observation \(y_j\)
 log_likelihood – compute loglikelihood?
Return type: (posterior_mean, posterior_covariance, log_likelihood)
posterior mean \({\mathbb E}[x_jy_1,\ldots,y_j]\) & covariance \({\rm Cov}[x_jy_1,\ldots,y_j]\) and, if requested, loglikelihood. If \(y_j\) is NaN, returns the prior mean and covariance instead
 scalars:
Primitives¶
The simdkalman.primitives
module contains lowlevel Kalman filter computation
steps with multidimensional input arrays. See this page
for full documentation.