Next topic

This Page

Quick search

FilterPy is a Python library that implements a number of Bayesian filters,
most notably Kalman filters. I am writing it in conjunction with my book
Kalman and Bayesian Filters in Python[1], a free book written using
Ipython Notebook, hosted on github, and readable via nbviewer. However,
it implements a wide variety of functionality that is not described in
the book.

As such this library has a strong pedalogical flavor. It is rare that I
choose the most efficient way to calculate something unless it does not
obscure exposition of the concepts of the filtering being done. I will always
opt for clarity over speed. I do not mean to imply that this is a toy; I use
it all of the time in my job.

I mainly develop in Python 3.x, but this should support both Python 2.x and
3.x flavors. At the moment I can not tell you the lowest required version;
I tend to develop on the bleeding edge of the Python releases. I am happy to
receive bug reports if it does not work with older versions, but testing
backwards compatibility is not a high priority at the moment. As the package
matures I will shift my focus in that direction.

FilterPy requires Numpy [2] and SciPy [3] to work. The tests and examples
also use matplotlib [4]. For testing I use py.test [5].

FilterPy is available on github (https://github.com/rlabbe/filterpy). However,
it is also hosted on PyPi, and unless you want to be on the bleeding edge of
development I recommend you get it from there. To install from the command line,
merely type:

You can get the very latest code by getting it from GitHub and then performing
the installation. I will say I am not following particularly stringent version
control discipline. I mostly stay on master and commit things that are not
entirely ready for prime-time, mostly because I’m the only one developing.
I do not promise that any check in that is not tagged with a version number is
usable.

There are several submodules, each listed below. But in general you will
need to import which classes and/or functions you need from the correct
submodule, construct the objects, and then execute your code. Something lke

I try to provide examples in the help for each class, but this documentation
needs a lot of work. For now I refer you to my book mentioned above if the
documentation is not adequate. Better yet, write an issue on the GitHub
issue tracker. I will respond with an answer as soon as I am online and
available (minutes to a day, normally), and then revise the documentation.
I shouldn’t have to be prodded like this, but life is limited. So prod.

A word on variable names. I am an advocate for descriptive variable names. In the Kalman filter literature the measurement noise covariance matrix is called R. The name R is not descriptive. I could reasonably call it measurement_noise_covariance, and I’ve seen libraries do that. I’ve chosen not to.

In the end, Kalman filtering is math. To write a Kalman filter you are going to start by sitting down with a piece of paper and doing math. You will be writing and solving normal algebraic equations. Every Kalman filter text and source on the web uses the same equations. You cannot read about the Kalman filter without seeing this equation

\[\dot{\mathbf{x}} = \mathbf{Fx} + \mathbf{Gu} + w\]

One of my goals is to bring you to the point where you can read the original literature on Kalman filtering. For nontrivial problems the difficulty is not the implementation of the equations, but learning how to set up the equations so they solve your problem. In other words, every Kalman filter implements \(\dot{\mathbf{x}} = \mathbf{Fx} + \mathbf{Gu} + w\); the difficult part is figuring out what to put in the matrices \(\mathbf{F}\) and \(\mathbf{G}\) to make your filter work for your problem. Vast amounts of work have been done to apply Kalman filters in various domains, and it would be tragic to be unable to avail yourself of this research.

So, like it or not you will need to learn that \(\mathbf{F}\) is the state transition matrix and that \(\mathbf{R}\) is the measurement noise covariance. Once you know that the code will become readable, and until then Kalman filter
math, and all publications and web articles on Kalman filters will be inaccessible to you.

Finally, I think that mathematical programming is somewhat different than regular programming; what is readable in one domain is not readable in another. q = x + m is opaque in a normal context. On the other hand, x = (.5*a)*t**2 + v_0*t + x_0 is to me the most readable way to program the Newtonian distance equation:

but I feel that obscures readability. This is debatable for this one equation; but most mathematical programs, and certainly Kalman filters, use systems of equations. I can most easily follow the code, and ensure that it does not have bugs, when it reads as close to the math as possible. Consider this equation from the Kalman filter:

which I adapted from a popular library. I grant you this version has more context, but I cannot glance at this and see what math it is implementing. In particular, the linear algebra \(\mathbf{HPH}^\mathsf{T}\) is doing something very specific - multiplying \(\mathbf{P}\) by \(\mathbf{H}\) in a way that converts \(\mathbf{P}\) from world space to measurement space (we’ll learn what that means). It is nearly impossible to see that the Kalman gain (K) is just a ratio of one number divided by a second number which has been converted to a different basis. This statement may not convey a lot of information to you before reading the book, but I assure you that \(\mathbf{K} = \mathbf{PH}^\mathsf{T}[\mathbf{HPH}^\mathsf{T} + \mathbf{R}]^{-1}\) is saying something very succinctly. There are two key pieces of information here - we are finding a ratio, and we are doing it in measurement space. I can see that in my first Python line, I cannot see that in the second line. If you want a counter-argument, my version obscures the information that \(\mathbf{P}\) is in this context is a prior .

These comments apply to library code. Calling code should use names like sensor_noise, or gps_sensor_noise, not R. Math code should read like math, and interface or glue code should read like normal code. Context is important.

I will not win this argument, and some people will not agree with my naming choices. I will finish by stating, very truthfully, that I made two mistakes the first time I typed the second version and it took me awhile to find it. In any case, I aim for using the mathematical symbol names whenever possible, coupled with readable class and function names. So, it is KalmanFilter.P, not KF.P and not KalmanFilter.apriori_state_covariance.

Unless it is deeply private (you don’t want someone else seeing propietary
code, for example), please ask questions and such on the issue tracker,
not by email. This is solely so that everyone gets to see the answer. “Issue”
doesn’t mean bug.

The classes in this submodule implement the various Kalman filters. There is
also support for smoother functions. The smoothers are methods of the classes.
For example, the KalmanFilter class contains rts_smoother to perform
Rauch-Tung-Striebal smoothing.

Implements a polynomial fading memory filter. You can achieve the same
results, and more, using the KalmanFilter class. However, some books
use this form of the fading memory filter, so it is here for completeness.
I suppose some would also find this simpler to use than the standard
Kalman filter.