`KalmanFilter`¶

class pykalman.KalmanFilter(transition_matrices=None, observation_matrices=None, transition_covariance=None, observation_covariance=None, transition_offsets=None, observation_offsets=None, initial_state_mean=None, initial_state_covariance=None, random_state=None, em_vars=['transition_covariance', 'observation_covariance', 'initial_state_mean', 'initial_state_covariance'], n_dim_state=None, n_dim_obs=None)¶

Implements the Kalman Filter, Kalman Smoother, and EM algorithm.

This class implements the Kalman Filter, Kalman Smoother, and EM Algorithm for a Linear Gaussian model specified by,

$x_{t+1} &= A_{t} x_{t} + b_{t} + \text{Normal}(0, Q_{t}) \\ z_{t} &= C_{t} x_{t} + d_{t} + \text{Normal}(0, R_{t})$

The Kalman Filter is an algorithm designed to estimate $P(x_t | z_{0:t})$ . As all state transitions and observations are linear with Gaussian distributed noise, these distributions can be represented exactly as Gaussian distributions with mean filtered_state_means[t] and covariances filtered_state_covariances[t].

Similarly, the Kalman Smoother is an algorithm designed to estimate $P(x_t | z_{0:T-1})$ .

The EM algorithm aims to find for $\theta = (A, b, C, d, Q, R, \mu_0, \Sigma_0)$

$\max_{\theta} P(z_{0:T-1}; \theta)$

If we define $L(x_{0:T-1},\theta) = \log P(z_{0:T-1}, x_{0:T-1}; \theta)$ , then the EM algorithm works by iteratively finding,

$P(x_{0:T-1} | z_{0:T-1}, \theta_i)$

then by maximizing,

$\theta_{i+1} = \arg\max_{\theta} \mathbb{E}_{x_{0:T-1}} [ L(x_{0:T-1}, \theta)| z_{0:T-1}, \theta_i ]$

Parameters :

transition_matrices : [n_timesteps-1, n_dim_state, n_dim_state] or [n_dim_state,n_dim_state] array-like

Also known as $A$ . state transition matrix between times t and t+1 for t in [0...n_timesteps-2]

observation_matrices : [n_timesteps, n_dim_obs, n_dim_obs] or [n_dim_obs, n_dim_obs] array-like

Also known as $C$ . observation matrix for times [0...n_timesteps-1]

transition_covariance : [n_dim_state, n_dim_state] array-like

Also known as $Q$ . state transition covariance matrix for times [0...n_timesteps-2]

observation_covariance : [n_dim_obs, n_dim_obs] array-like

Also known as $R$ . observation covariance matrix for times [0...n_timesteps-1]

transition_offsets : [n_timesteps-1, n_dim_state] or [n_dim_state] array-like

Also known as $b$ . state offsets for times [0...n_timesteps-2]

observation_offsets : [n_timesteps, n_dim_obs] or [n_dim_obs] array-like

Also known as $d$ . observation offset for times [0...n_timesteps-1]

initial_state_mean : [n_dim_state] array-like

Also known as $\mu_0$ . mean of initial state distribution

initial_state_covariance : [n_dim_state, n_dim_state] array-like

Also known as $\Sigma_0$ . covariance of initial state distribution

random_state : optional, numpy random state

random number generator used in sampling

em_vars : optional, subset of [‘transition_matrices’, ‘observation_matrices’, ‘transition_offsets’, ‘observation_offsets’, ‘transition_covariance’, ‘observation_covariance’, ‘initial_state_mean’, ‘initial_state_covariance’] or ‘all’

if em_vars is an iterable of strings only variables in em_vars will be estimated using EM. if em_vars == ‘all’, then all variables will be estimated.

n_dim_state: optional, integer :

the dimensionality of the state space. Only meaningful when you do not specify initial values for transition_matrices, transition_offsets, transition_covariance, initial_state_mean, or initial_state_covariance.

n_dim_obs: optional, integer :

the dimensionality of the observation space. Only meaningful when you do not specify initial values for observation_matrices, observation_offsets, or observation_covariance.

Methods

`em`(X[, y, n_iter, em_vars])	Apply the EM algorithm
`filter`(X)	Apply the Kalman Filter
`filter_update`(filtered_state_mean, ...[, ...])	Update a Kalman Filter state estimate
`loglikelihood`(X)	Calculate the log likelihood of all observations
`sample`(n_timesteps[, initial_state, ...])	Sample a state sequence $n_{\text{timesteps}}$ timesteps in length.
`smooth`(X)	Apply the Kalman Smoother

em(X, y=None, n_iter=10, em_vars=None)¶

Apply the EM algorithm

Apply the EM algorithm to estimate all parameters specified by em_vars. Note that all variables estimated are assumed to be constant for all time. See _em() for details.

Parameters :

X : [n_timesteps, n_dim_obs] array-like

observations corresponding to times [0...n_timesteps-1]. If X is a masked array and any of X[t]‘s components is masked, then X[t] will be treated as a missing observation.

n_iter : int, optional

number of EM iterations to perform

em_vars : iterable of strings or ‘all’

variables to perform EM over. Any variable not appearing here is left untouched.

filter(X)¶

Apply the Kalman Filter

Apply the Kalman Filter to estimate the hidden state at time $t$ for $t = [0...n_{\text{timesteps}}-1]$ given observations up to and including time t. Observations are assumed to correspond to times $[0...n_{\text{timesteps}}-1]$ . The output of this method corresponding to time $n_{\text{timesteps}}-1$ can be used in KalmanFilter.filter_update() for online updating.

Parameters :

X : [n_timesteps, n_dim_obs] array-like

observations corresponding to times [0...n_timesteps-1]. If X is a masked array and any of X[t] is masked, then X[t] will be treated as a missing observation.

Returns :

filtered_state_means : [n_timesteps, n_dim_state]

mean of hidden state distributions for times [0...n_timesteps-1] given observations up to and including the current time step

filtered_state_covariances : [n_timesteps, n_dim_state, n_dim_state] array

covariance matrix of hidden state distributions for times [0...n_timesteps-1] given observations up to and including the current time step

filter_update(filtered_state_mean, filtered_state_covariance, observation=None, transition_matrix=None, transition_offset=None, transition_covariance=None, observation_matrix=None, observation_offset=None, observation_covariance=None)¶

Update a Kalman Filter state estimate

Perform a one-step update to estimate the state at time $t+1$ give an observation at time $t+1$ and the previous estimate for time $t$ given observations from times $[0...t]$ . This method is useful if one wants to track an object with streaming observations.

Parameters :

filtered_state_mean : [n_dim_state] array

mean estimate for state at time t given observations from times [1...t]

filtered_state_covariance : [n_dim_state, n_dim_state] array

covariance of estimate for state at time t given observations from times [1...t]

observation : [n_dim_obs] array or None

observation from time t+1. If observation is a masked array and any of observation‘s components are masked or if observation is None, then observation will be treated as a missing observation.

transition_matrix : optional, [n_dim_state, n_dim_state] array

state transition matrix from time t to t+1. If unspecified, self.transition_matrices will be used.

transition_offset : optional, [n_dim_state] array

state offset for transition from time t to t+1. If unspecified, self.transition_offset will be used.

transition_covariance : optional, [n_dim_state, n_dim_state] array

state transition covariance from time t to t+1. If unspecified, self.transition_covariance will be used.

observation_matrix : optional, [n_dim_obs, n_dim_state] array

observation matrix at time t+1. If unspecified, self.observation_matrices will be used.

observation_offset : optional, [n_dim_obs] array

observation offset at time t+1. If unspecified, self.observation_offset will be used.

observation_covariance : optional, [n_dim_obs, n_dim_obs] array

observation covariance at time t+1. If unspecified, self.observation_covariance will be used.

Returns :

next_filtered_state_mean : [n_dim_state] array

mean estimate for state at time t+1 given observations from times [1...t+1]

next_filtered_state_covariance : [n_dim_state, n_dim_state] array

covariance of estimate for state at time t+1 given observations from times [1...t+1]

loglikelihood(X)¶

Calculate the log likelihood of all observations

Parameters :

X : [n_timesteps, n_dim_obs] array

observations for time steps [0...n_timesteps-1]

Returns :

likelihood : float

likelihood of all observations

sample(n_timesteps, initial_state=None, random_state=None)¶

Sample a state sequence $n_{\text{timesteps}}$ timesteps in length.

Parameters :

n_timesteps : int

number of timesteps

Returns :

states : [n_timesteps, n_dim_state] array

hidden states corresponding to times [0...n_timesteps-1]

observations : [n_timesteps, n_dim_obs] array

observations corresponding to times [0...n_timesteps-1]

smooth(X)¶

Apply the Kalman Smoother

Apply the Kalman Smoother to estimate the hidden state at time $t$ for $t = [0...n_{\text{timesteps}}-1]$ given all observations. See _smooth() for more complex output

Parameters :

X : [n_timesteps, n_dim_obs] array-like

observations corresponding to times [0...n_timesteps-1]. If X is a masked array and any of X[t] is masked, then X[t] will be treated as a missing observation.

Returns :

smoothed_state_means : [n_timesteps, n_dim_state]

mean of hidden state distributions for times [0...n_timesteps-1] given all observations

smoothed_state_covariances : [n_timesteps, n_dim_state]

covariances of hidden state distributions for times [0...n_timesteps-1] given all observations

`UnscentedKalmanFilter`¶

class pykalman.UnscentedKalmanFilter(transition_functions=None, observation_functions=None, transition_covariance=None, observation_covariance=None, initial_state_mean=None, initial_state_covariance=None, n_dim_state=None, n_dim_obs=None, random_state=None)¶

Implements the General (aka Augmented) Unscented Kalman Filter governed by the following equations,

$x_0 &\sim \text{Normal}(\mu_0, \Sigma_0) \\ x_{t+1} &= f_t(x_t, \text{Normal}(0, Q)) \\ z_{t} &= g_t(x_t, \text{Normal}(0, R))$

Notice that although the input noise to the state transition equation and the observation equation are both normally distributed, any non-linear transformation may be applied afterwards. This allows for greater generality, but at the expense of computational complexity. The complexity of UnscentedKalmanFilter.filter() is $O(T(2n+m)^3)$ where $T$ is the number of time steps, $n$ is the size of the state space, and $m$ is the size of the observation space.

If your noise is simply additive, consider using the AdditiveUnscentedKalmanFilter

Parameters :

transition_functions : function or [n_timesteps-1] array of functions

transition_functions[t] is a function of the state and the transition noise at time t and produces the state at time t+1. Also known as $f_t$ .

observation_functions : function or [n_timesteps] array of functions

observation_functions[t] is a function of the state and the observation noise at time t and produces the observation at time t. Also known as $g_t$ .

transition_covariance : [n_dim_state, n_dim_state] array

transition noise covariance matrix. Also known as $Q$ .

observation_covariance : [n_dim_obs, n_dim_obs] array

observation noise covariance matrix. Also known as $R$ .

initial_state_mean : [n_dim_state] array

mean of initial state distribution. Also known as $\mu_0$

initial_state_covariance : [n_dim_state, n_dim_state] array

covariance of initial state distribution. Also known as $\Sigma_0$

n_dim_state: optional, integer :

the dimensionality of the state space. Only meaningful when you do not specify initial values for transition_covariance, or initial_state_mean, initial_state_covariance.

n_dim_obs: optional, integer :

the dimensionality of the observation space. Only meaningful when you do not specify initial values for observation_covariance.

random_state : optional, int or RandomState

seed for random sample generation

Methods

`filter`(Z)	Run Unscented Kalman Filter
`sample`(n_timesteps[, initial_state, ...])	Sample from model defined by the Unscented Kalman Filter
`smooth`(Z)	Run Unscented Kalman Smoother

filter(Z)¶

Run Unscented Kalman Filter

Parameters :

Z : [n_timesteps, n_dim_state] array

Z[t] = observation at time t. If Z is a masked array and any of Z[t]’s elements are masked, the observation is assumed missing and ignored.

Returns :

filtered_state_means : [n_timesteps, n_dim_state] array

filtered_state_means[t] = mean of state distribution at time t given observations from times [0, t]

filtered_state_covariances : [n_timesteps, n_dim_state, n_dim_state] array

filtered_state_covariances[t] = covariance of state distribution at time t given observations from times [0, t]

sample(n_timesteps, initial_state=None, random_state=None)¶

Sample from model defined by the Unscented Kalman Filter

Parameters :

n_timesteps : int

number of time steps

initial_state : optional, [n_dim_state] array

initial state. If unspecified, will be sampled from initial state distribution.

random_state : optional, int or Random

random number generator

smooth(Z)¶

Run Unscented Kalman Smoother

Parameters :

Z : [n_timesteps, n_dim_state] array

Z[t] = observation at time t. If Z is a masked array and any of Z[t]’s elements are masked, the observation is assumed missing and ignored.

Returns :

smoothed_state_means : [n_timesteps, n_dim_state] array

filtered_state_means[t] = mean of state distribution at time t given observations from times [0, n_timesteps-1]

smoothed_state_covariances : [n_timesteps, n_dim_state, n_dim_state] array

filtered_state_covariances[t] = covariance of state distribution at time t given observations from times [0, n_timesteps-1]

`AdditiveUnscentedKalmanFilter`¶

class pykalman.AdditiveUnscentedKalmanFilter(transition_functions=None, observation_functions=None, transition_covariance=None, observation_covariance=None, initial_state_mean=None, initial_state_covariance=None, n_dim_state=None, n_dim_obs=None, random_state=None)¶

Implements the Unscented Kalman Filter with additive noise. Observations are assumed to be generated from the following process,

$x_0 &\sim \text{Normal}(\mu_0, \Sigma_0) \\ x_{t+1} &= f_t(x_t) + \text{Normal}(0, Q) \\ z_{t} &= g_t(x_t) + \text{Normal}(0, R)$

While less general the general-noise Unscented Kalman Filter, the Additive version is more computationally efficient with complexity $O(Tn^3)$ where $T$ is the number of time steps and $n$ is the size of the state space.

Parameters :

transition_functions : function or [n_timesteps-1] array of functions

transition_functions[t] is a function of the state at time t and produces the state at time t+1. Also known as $f_t$ .

observation_functions : function or [n_timesteps] array of functions

observation_functions[t] is a function of the state at time t and produces the observation at time t. Also known as $g_t$ .

transition_covariance : [n_dim_state, n_dim_state] array

transition noise covariance matrix. Also known as $Q$ .

observation_covariance : [n_dim_obs, n_dim_obs] array

observation noise covariance matrix. Also known as $R$ .

initial_state_mean : [n_dim_state] array

mean of initial state distribution. Also known as $\mu_0$ .

initial_state_covariance : [n_dim_state, n_dim_state] array

covariance of initial state distribution. Also known as $\Sigma_0$ .

n_dim_state: optional, integer :

the dimensionality of the state space. Only meaningful when you do not specify initial values for transition_covariance, or initial_state_mean, initial_state_covariance.

n_dim_obs: optional, integer :

the dimensionality of the observation space. Only meaningful when you do not specify initial values for observation_covariance.

random_state : optional, int or RandomState

seed for random sample generation

Methods

`filter`(Z)	Run Unscented Kalman Filter
`sample`(n_timesteps[, initial_state, ...])	Sample from model defined by the Unscented Kalman Filter
`smooth`(Z)	Run Unscented Kalman Smoother

filter(Z)¶

Run Unscented Kalman Filter

Parameters :

Z : [n_timesteps, n_dim_state] array

Z[t] = observation at time t. If Z is a masked array and any of Z[t]’s elements are masked, the observation is assumed missing and ignored.

Returns :

filtered_state_means : [n_timesteps, n_dim_state] array

filtered_state_means[t] = mean of state distribution at time t given observations from times [0, t]

filtered_state_covariances : [n_timesteps, n_dim_state, n_dim_state] array

filtered_state_covariances[t] = covariance of state distribution at time t given observations from times [0, t]

sample(n_timesteps, initial_state=None, random_state=None)¶

Sample from model defined by the Unscented Kalman Filter

Parameters :

n_timesteps : int

number of time steps

initial_state : optional, [n_dim_state] array

initial state. If unspecified, will be sampled from initial state distribution.

smooth(Z)¶

Run Unscented Kalman Smoother

Parameters :

Z : [n_timesteps, n_dim_state] array

Z[t] = observation at time t. If Z is a masked array and any of Z[t]’s elements are masked, the observation is assumed missing and ignored.

Returns :

smoothed_state_means : [n_timesteps, n_dim_state] array

filtered_state_means[t] = mean of state distribution at time t given observations from times [0, n_timesteps-1]

smoothed_state_covariances : [n_timesteps, n_dim_state, n_dim_state] array

filtered_state_covariances[t] = covariance of state distribution at time t given observations from times [0, n_timesteps-1]

`KalmanFilter`¶

`UnscentedKalmanFilter`¶

`AdditiveUnscentedKalmanFilter`¶

Table Of Contents

This Page

Navigation

KalmanFilter¶

UnscentedKalmanFilter¶

AdditiveUnscentedKalmanFilter¶

Table Of Contents

This Page

Quick search

Navigation

`KalmanFilter`¶

`UnscentedKalmanFilter`¶

`AdditiveUnscentedKalmanFilter`¶