PyKalman

Common errors

• TypeError: 'numpy.ndarray' object is not callable

  cause This error often occurs when an older version of `pykalman` (e.g., <0.10.0 or <0.11.1) is used with `numpy` 2.x, due to breaking API changes in NumPy.
  fix Update `pykalman` to the latest version (`pip install --upgrade pykalman`). If you cannot upgrade `pykalman`, downgrade `numpy` to a 1.x version (e.g., `pip install 'numpy<2'`).

• AttributeError: 'KalmanFilter' object has no attribute 'filter'

  cause This usually means you're trying to call a method like `filter()` or `smooth()` on an incorrectly initialized `KalmanFilter` object, or perhaps from an outdated fork, or you made a typo.
  fix Ensure you are using `from pykalman import KalmanFilter` and that your `KalmanFilter` instance (`kf`) is properly created before calling its methods. Check the official documentation for correct method names and parameters.

• ValueError: operands could not be broadcast together with shapes (X) (Y)

  cause This error indicates a mismatch in the dimensions of the matrices provided to the KalmanFilter constructor (e.g., `transition_matrices`, `observation_matrices`, `covariance` matrices).
  fix Carefully check the shapes of your input matrices. Ensure `transition_matrices` is (n_dim_state, n_dim_state), `observation_matrices` is (n_dim_obs, n_dim_state), and covariance matrices are symmetric with appropriate dimensions (e.g., `transition_covariance` is (n_dim_state, n_dim_state), `observation_covariance` is (n_dim_obs, n_dim_obs)).

Warnings

• breaking Python 3.8 (and earlier) is no longer supported as of v0.10.0, and Python 3.9 is no longer supported as of v0.11.0. Ensure your Python environment meets the `pykalman` requirements (>=3.10, <3.15).
  Fix: Upgrade your Python interpreter to version 3.10 or higher. Use a virtual environment to manage dependencies: `python3.10 -m venv .venv && source .venv/bin/activate`
• gotcha Older versions of `pykalman` (prior to v0.10.0 and v0.11.1) may experience compatibility issues with `numpy` 2.x due to significant API changes in NumPy. This can lead to unexpected errors or incorrect behavior.
  Fix: Upgrade `pykalman` to the latest version (0.11.1 or higher) to ensure full compatibility with `numpy` 2.x. If upgrading `pykalman` is not an option, you may need to pin `numpy` to a `1.x` version (e.g., `numpy<2`).
• gotcha When using `KalmanFilter.em()` with `n_timesteps=1`, versions prior to v0.11.2 may encounter a crash. This specific edge case was resolved in a recent bugfix.
  Fix: Upgrade `pykalman` to version 0.11.2 or higher. If unable to upgrade, ensure `n_timesteps` is greater than 1 when using `em()`.
• gotcha A bug existed in versions prior to v0.10.2 where time-varying transition covariance could be incorrectly overwritten by the initial matrix in the standard Kalman filter.
  Fix: Upgrade `pykalman` to version 0.10.2 or higher to resolve this issue. If using an older version, manually ensure that time-varying transition covariance is correctly handled or explicitly set if it's not meant to vary.

Install

• pip install pykalman Install stable version

Imports

• KalmanFilter

  from pykalman import KalmanFilter

• UnscentedKalmanFilter

  from pykalman import UnscentedKalmanFilter

  Used for non-linear state estimation problems.

Quickstart

This quickstart demonstrates the basic usage of `KalmanFilter` to estimate states from noisy measurements. It defines a simple linear system, generates synthetic data, and then applies the `filter` and `smooth` methods to estimate the underlying states.

import numpy as np
from pykalman import KalmanFilter

# Define the parameters of a simple linear system
transition_matrices = [[1, 1], [0, 1]] # State transition matrix
observation_matrices = [[1, 0]]       # Observation matrix (we observe position only)
transition_covariance = np.eye(2) * 0.1 # Small process noise
observation_covariance = np.eye(1) * 1.0 # Larger observation noise
initial_state_mean = [0, 1]           # Initial state (position=0, velocity=1)
initial_state_covariance = np.eye(2) * 1.0 # Initial uncertainty

# Create a Kalman Filter instance
kf = KalmanFilter(
    transition_matrices=transition_matrices,
    observation_matrices=observation_matrices,
    transition_covariance=transition_covariance,
    observation_covariance=observation_covariance,
    initial_state_mean=initial_state_mean,
    initial_state_covariance=initial_state_covariance
)

# Generate some noisy 'measurements' for a simple linear motion
n_timesteps = 50
true_states = np.zeros((n_timesteps, 2))
measurements = np.zeros((n_timesteps, 1))
true_states[0] = initial_state_mean
for t in range(1, n_timesteps):
    true_states[t] = np.dot(transition_matrices, true_states[t-1]) + np.random.multivariate_normal([0, 0], transition_covariance)
    measurements[t] = np.dot(observation_matrices, true_states[t]) + np.random.normal(0, np.sqrt(observation_covariance[0,0]))

# Use the Kalman Filter to estimate the states from measurements
(filtered_state_means, filtered_state_covariances) = kf.filter(measurements)
(smoothed_state_means, smoothed_state_covariances) = kf.smooth(measurements)

print("First 5 filtered state means (position, velocity):")
print(filtered_state_means[:5])
print("\nFirst 5 smoothed state means (position, velocity):")
print(smoothed_state_means[:5])