kalman

README

⚡️Kalman Filter

A package implementing Kalman filtering and smoothing for continuous time-indexed models with non-uniform time transitions. A collection of models are also provided, including a constant velocity motion model and a Brownian motion model. Support for prediction, filtering, smoothing and sensor fusion are currently implemented.

Design

The package has two main components

Kalman Filter/Smoother

These implement state space estimation for a given model and measurements.

Model

The model (such as models.LinearModel) provide common example models for modelling time series data. For example models.ConstantVelocityModel, models the position and velocity of a particle over time.

Examples

For runnable examples, see /examples. Below, a full runnable example of filtering a noisy time series. The model here is just a Brownian motion model, which assumes that the time series represents a hidden value that is static apart from a Brownian noise component.

package main

import (
	"fmt"
	"time"
	"github.com/rosshemsley/kalman"
	"github.com/rosshemsley/kalman/models"
)

func main() {
	var t time.Time
	values := []float64{1.3, 10.2, 5.0, 3.4}

	model := models.NewSimpleModel(t, values[0], models.SimpleModelConfig{
		InitialVariance:     1.0,
		ProcessVariance:     1.0,
		ObservationVariance: 2.0,
	})
	filter := kalman.NewKalmanFilter(model)

	for _, v := range values {
		t = t.Add(time.Second)
		filter.Update(t, model.NewMeasurement(v))
		fmt.Printf("filtered value: %f\n", model.Value(filter.State()))
	}
}

Documentation

Overview

Package kalman implements estimation for time series with non-uniform time steps. Implementations of the Kalman Filter and Kalman Smoother are provided, along with several built-in models for modelling common dynamic systems, such as the constant-velocity model and a Brownian model.

Index

• type KalmanFilter
  • func NewKalmanFilter(model models.LinearModel) *KalmanFilter
  • func (kf *KalmanFilter) Covariance() mat.Matrix
  • func (kf *KalmanFilter) Predict(t time.Time) error
  • func (kf *KalmanFilter) SetCovariance(covariance mat.Matrix)
  • func (kf *KalmanFilter) SetState(state mat.Vector)
  • func (kf *KalmanFilter) State() mat.Vector
  • func (kf *KalmanFilter) Time() time.Time
  • func (kf *KalmanFilter) Update(t time.Time, m *models.Measurement) error
• type KalmanSmoother
  • func NewKalmanSmoother(model models.LinearModel) *KalmanSmoother
  • func (kf *KalmanSmoother) Smooth(measurements ...*MeasurementAtTime) ([]models.State, error)
• type MeasurementAtTime
  • func NewMeasurementAtTime(t time.Time, m *models.Measurement) *MeasurementAtTime

Types

type KalmanFilter

type KalmanFilter struct {
	// contains filtered or unexported fields
}

KalmanFilter is responsible for prediction and filtering of a given linear model. It is assumed that the process being modelled is a time series, and that the time steps are non-uniform and specified for each update and prediction operation.

func NewKalmanFilter

func NewKalmanFilter(model models.LinearModel) *KalmanFilter

NewKalmanFilter returns a new KalmanFilter for the given linear model.

func (*KalmanFilter) Covariance

func (kf *KalmanFilter) Covariance() mat.Matrix

Covariance returns the current covaraince of the model.

func (*KalmanFilter) Predict

func (kf *KalmanFilter) Predict(t time.Time) error

Predict advances the KalmanFilter from the internal current time to the given time using the built-in linear model. The state of the filter is updated and the current time is updated. Each time can be no earlier than the current time of the filter.

func (*KalmanFilter) SetCovariance

func (kf *KalmanFilter) SetCovariance(covariance mat.Matrix)

SetCovariance resets the covariance of the Kalman Filter to the given value.

func (*KalmanFilter) SetState

func (kf *KalmanFilter) SetState(state mat.Vector)

SetState resets the state of the Kalman Filter to the given value.

func (*KalmanFilter) State

func (kf *KalmanFilter) State() mat.Vector

State returns the current hidden state of the KalmanFilter. Example models provided with this package often provide functions to extract meaningful information from the state vector, such as .Velocity() for the provided constant velocity model.

func (*KalmanFilter) Time

func (kf *KalmanFilter) Time() time.Time

Time returns the time for which the current hidden state is an estimate. The time is monotone increasing.

func (*KalmanFilter) Update

func (kf *KalmanFilter) Update(t time.Time, m *models.Measurement) error

Update is used to take a new measurement from a sensor and fuse it to the model. The time field must be no earlier than the current time of the filter.

type KalmanSmoother

type KalmanSmoother struct {
	// contains filtered or unexported fields
}

KalmanSmoother implements Rauch–Tung–Striebel smoothing.

func NewKalmanSmoother

func NewKalmanSmoother(model models.LinearModel) *KalmanSmoother

NewKalmanSmoother creates a new smoother for the given model.

func (*KalmanSmoother) Smooth

func (kf *KalmanSmoother) Smooth(measurements ...*MeasurementAtTime) ([]models.State, error)

Smooth computes optimal estimates of the model states by using all measurements. This is done by running a regular Kalman Filter and then performing a backwards pass using the Rauch–Tung–Striebel algorithm. Better results can be achieved since each state is estimated based on the entire history of the process, including the future and past observations.

type MeasurementAtTime

type MeasurementAtTime struct {
	models.Measurement
	Time time.Time
}

MeasurementAtTime represents a measurement taken at a given time.

func NewMeasurementAtTime

func NewMeasurementAtTime(t time.Time, m *models.Measurement) *MeasurementAtTime

NewMeasurementAtTime is a helper for initializing measurement at time structs.