# IMM Estimator

needs documentation….

Copyright 2015 Roger R Labbe Jr.

FilterPy library. http://github.com/rlabbe/filterpy

Documentation at: https://filterpy.readthedocs.org

Supporting book at: https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python

This is licensed under an MIT license. See the readme.MD file for more information.

class filterpy.kalman.IMMEstimator(filters, mu, M)

  Implements an Interacting Multiple-Model (IMM) estimator.

  Parameters:
    filters(N,) array_like of KalmanFilter objects

      List of N filters. filters[i] is the ith Kalman filter in the IMM estimator.

      Each filter must have the same dimension for the state x and P, otherwise the states of each filter cannot be mixed with each other.

    mu(N,) array_like of float

      mode probability: mu[i] is the probability that filter i is the correct one.

    M(N, N) ndarray of float

      Markov chain transition matrix. M[i,j] is the probability of switching from filter j to filter i.

  Attributes:
    x numpy.array(dim_x, 1)

      Current state estimate. Any call to update() or predict() updates this variable.

    P numpy.array(dim_x, dim_x)

      Current state covariance matrix. Any call to update() or predict() updates this variable.

    x_prior numpy.array(dim_x, 1)

      Prior (predicted) state estimate. The *_prior and *_post attributes are for convienence; they store the prior and posterior of the current epoch. Read Only.

    P_prior numpy.array(dim_x, dim_x)

      Prior (predicted) state covariance matrix. Read Only.

    x_post numpy.array(dim_x, 1)

      Posterior (updated) state estimate. Read Only.

    P_post numpy.array(dim_x, dim_x)

      Posterior (updated) state covariance matrix. Read Only.

    N int

      number of filters in the filter bank

    mu(N,) ndarray of float

      mode probability: mu[i] is the probability that filter i is the correct one.

    M(N, N) ndarray of float

      Markov chain transition matrix. M[i,j] is the probability of switching from filter j to filter i.

    cbar(N,) ndarray of float

      Total probability, after interaction, that the target is in state j. We use it as the # normalization constant.

    likelihood: (N,) ndarray of float

      Likelihood of each individual filter’s last measurement.

    omega(N, N) ndarray of float

      Mixing probabilitity - omega[i, j] is the probabilility of mixing the state of filter i into filter j. Perhaps more understandably, it weights the states of each filter by:

      > x_j = sum(omega[i,j] * x_i)

      with a similar weighting for P_j

  References

  Bar-Shalom, Y., Li, X-R., and Kirubarajan, T. “Estimation with Application to Tracking and Navigation”. Wiley-Interscience, 2001.

  Crassidis, J and Junkins, J. “Optimal Estimation of Dynamic Systems”. CRC Press, second edition. 2012.

  Labbe, R. “Kalman and Bayesian Filters in Python”. https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python

  Examples

      >>> import numpy as np
      >>> from filterpy.common import kinematic_kf
      >>> kf1 = kinematic_kf(2, 2)
      >>> kf2 = kinematic_kf(2, 2)
      >>> # do some settings of x, R, P etc. here, I'll just use the defaults
      >>> kf2.Q *= 0   # no prediction error in second filter
      >>>
      >>> filters = [kf1, kf2]
      >>> mu = [0.5, 0.5]  # each filter is equally likely at the start
      >>> trans = np.array([[0.97, 0.03], [0.03, 0.97]])
      >>> imm = IMMEstimator(filters, mu, trans)
      >>>
      >>> for i in range(100):
      >>>     # make some noisy data
      >>>     x = i + np.random.randn()*np.sqrt(kf1.R[0, 0])
      >>>     y = i + np.random.randn()*np.sqrt(kf1.R[1, 1])
      >>>     z = np.array([[x], [y]])
      >>>
      >>>     # perform predict/update cycle
      >>>     imm.predict()
      >>>     imm.update(z)
      >>>     print(imm.x.T)

  For a full explanation and more examples see my book Kalman and Bayesian Filters in Python https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python

  __init__(filters, mu, M)
  update(z)

    Add a new measurement (z) to the Kalman filter. If z is None, nothing is changed.

    Parameters:
      z np.array

        measurement for this update.

  predict(u=None)

    Predict next state (prior) using the IMM state propagation equations.

    Parameters:
      u np.array, optional

        Control vector. If not None, it is multiplied by B to create the control input into the system.