FilterPy - Kalman filters and other optimal and non-optimal estimation filters in Python.
-----------------------------------------------------------------------------------------
.. image:: https://img.shields.io/pypi/v/filterpy.svg
:target: https://pypi.python.org/pypi/filterpy
.. image:: https://readthedocs.org/projects/pip/badge/?version=latest&style=flat
:target: https://filterpy.readthedocs.io/en/latest/
**NOTE**: Imminent drop of support of Python 2.7, 3.4. See section below for details.
This library provides Kalman filtering and various related optimal and
non-optimal filtering software written in Python. It contains Kalman
filters, Extended Kalman filters, Unscented Kalman filters, Kalman
smoothers, Least Squares filters, fading memory filters, g-h filters,
discrete Bayes, and more.
This is code I am developing in conjunction with my book Kalman and
Bayesian Filter in Python, which you can read/download at
https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python/
My aim is largely pedalogical - I opt for clear code that matches the
equations in the relevant texts on a 1-to-1 basis, even when that has a
performance cost. There are places where this tradeoff is unclear - for
example, I find it somewhat clearer to write a small set of equations
using linear algebra, but numpy's overhead on small matrices makes it
run slower than writing each equation out by hand. Furthermore, books
such Zarchan present the written out form, not the linear algebra form.
It is hard for me to choose which presentation is 'clearer' - it depends
on the audience. In that case I usually opt for the faster implementation.
I use NumPy and SciPy for all of the computations. I have experimented
with Numba and it yields impressive speed ups with minimal costs, but I
am not convinced that I want to add that requirement to my project. It
is still on my list of things to figure out, however.
Sphinx generated documentation lives at http://filterpy.readthedocs.org/.
Generation is triggered by git when I do a check in, so this will always
be bleeding edge development version - it will often be ahead of the
released version.
Plan for dropping Python 2.7 support
------------------------------------
I haven't finalized my decision on this, but NumPy is dropping
Python 2.7 support in December 2018. I will certainly drop Python
2.7 support by then; I will probably do it much sooner.
At the moment FilterPy is on version 1.x. I plan to fork the project
to version 2.0, and support only Python 3.5+. The 1.x version
will still be available, but I will not support it. If I add something
amazing to 2.0 and someone really begs, I might backport it; more
likely I would accept a pull request with the feature backported
to 1.x. But to be honest I don't forsee this happening.
Why 3.5+, and not 3.4+? 3.5 introduced the matrix multiply symbol,
and I want my code to take advantage of it. Plus, to be honest,
I'm being selfish. I don't want to spend my life supporting this
package, and moving as far into the present as possible means
a few extra years before the Python version I choose becomes
hopelessly dated and a liability. I recognize this makes people
running the default Python in their linux distribution more
painful. All I can say is I did not decide to do the Python
3 fork, and I don't have the time to support the bifurcation
any longer.
I am making edits to the package now in support of my book;
once those are done I'll probably create the 2.0 branch.
I'm contemplating a SLAM addition to the book, and am not
sure if I will do this in 3.5+ only or not.
Installation
------------
The most general installation is just to use pip, which should come with
any modern Python distribution.
.. image:: https://img.shields.io/pypi/v/filterpy.svg
:target: https://pypi.python.org/pypi/filterpy
::
pip install filterpy
If you prefer to download the source yourself
::
cd <directory you want to install to>
git clone http://github.com/rlabbe/filterpy
python setup.py install
If you use Anaconda, you can install from the conda-forge channel. You
will need to add the conda-forge channel if you haven't already done so:
::
conda config --add channels conda-forge
and then install with:
::
conda install filterpy
And, if you want to install from the bleeding edge git version
::
pip install git+https://github.com/rlabbe/filterpy.git
Note: I make no guarantees that everything works if you install from here.
I'm the only developer, and so I don't worry about dev/release branches and
the like. Unless I fix a bug for you and tell you to get this version because
I haven't made a new release yet, I strongly advise not installing from git.
Basic use
---------
Full documentation is at
https://filterpy.readthedocs.io/en/latest/
First, import the filters and helper functions.
.. code-block:: python
import numpy as np
from filterpy.kalman import KalmanFilter
from filterpy.common import Q_discrete_white_noise
Now, create the filter
.. code-block:: python
my_filter = KalmanFilter(dim_x=2, dim_z=1)
Initialize the filter's matrices.
.. code-block:: python
my_filter.x = np.array([[2.],
[0.]]) # initial state (location and velocity)
my_filter.F = np.array([[1.,1.],
[0.,1.]]) # state transition matrix
my_filter.H = np.array([[1.,0.]]) # Measurement function
my_filter.P *= 1000. # covariance matrix
my_filter.R = 5 # state uncertainty
my_filter.Q = Q_discrete_white_noise(dim=2, dt=0.1, var=0.1) # process uncertainty
Finally, run the filter.
.. code-block:: python
while True:
my_filter.predict()
my_filter.update(get_some_measurement())
# do something with the output
x = my_filter.x
do_something_amazing(x)
Sorry, that is the extent of the documentation here. However, the library
is broken up into subdirectories: gh, kalman, memory, leastsq, and so on.
Each subdirectory contains python files relating to that form of filter.
The functions and methods contain pretty good docstrings on use.
My book https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python/
uses this library, and is the place to go if you are trying to learn
about Kalman filtering and/or this library. These two are not exactly in
sync - my normal development cycle is to add files here, test them, figure
out how to present them pedalogically, then write the appropriate section
or chapter in the book. So there is code here that is not discussed
yet in the book.
Requirements
------------
This library uses NumPy, SciPy, Matplotlib, and Python.
I haven't extensively tested backwards compatibility - I use the
Anaconda distribution, and so I am on Python 3.6 and 2.7.14, along with
whatever version of NumPy, SciPy, and matplotlib they provide. But I am
using pretty basic Python - numpy.array, maybe a list comprehension in
my tests.
I import from **__future__** to ensure the code works in Python 2 and 3.
Testing
-------
All tests are written to work with py.test. Just type ``py.test`` at the
command line.
As explained above, the tests are not robust. I'm still at the stage
where visual plots are the best way to see how things are working.
Apologies, but I think it is a sound choice for development. It is easy
for a filter to perform within theoretical limits (which we can write a
non-visual test for) yet be 'off' in some way. The code itself contains
tests in the form of asserts and properties that ensure that arrays are
of the proper dimension, etc.
References
----------
I use three main texts as my refererence, though I do own the majority
of the Kalman filtering literature. First is Paul Zarchan's
'Fundamentals of Kalman Filtering: A Practical Approach'. I think it by
far the best Kalman filtering book out there if you are interested in
practical applications more than writing a thesis. The second book I use
is Eli Brookner's 'Tracking and Kalman Filtering Made Easy'. This is an
astonishingly good book; its first chapter is actually readable by the
layperson! Brookner starts from the g-h filter, and shows how all other
filters - the Kalman filter, least squares, fading memory, etc., all
derive from the g-h filter. It greatly simplifies many aspects of
analysis and/or intuitive understanding of your problem. In contrast,
Zarchan starts from least squares, and then moves on to Kalman
filtering. I find that he downplays the predict-update aspect of the
algorithms, but he has a wealth of worked examples and comparisons
between different methods. I think both viewpoints are needed, and so I
can't imagine discarding one book. Brookner also focuses on issues that
are ignored in other books - track initialization, detecting and
discarding noise, tracking multiple objects, an so on.
I said three books. I also like and use Bar-Shalom's Estimation with
Applications to Tracking and Navigation. Much more mathematical than the
previous two books, I would not recommend it as a first text unless you
already have a background in control theory or optimal estimation. Once
you have that experience, this book is a gem. Every sentence is crystal
clear, his language is precise, but each abstract mathematical statement
is followed with something like "and this means...".
License
-------
.. image:: https://anaconda.org/rlabbe/filterpy/badges/license.svg :target: https://anaconda.org/rlabbe/filterpy
The MIT License (MIT)
Copyright (c) 2015 Roger R. Labbe Jr
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.TION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Raw data
{
"_id": null,
"home_page": "https://github.com/rlabbe/filterpy",
"name": "filterpywhl",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Kalman filters filtering optimal estimation tracking",
"author": "Roger Labbe",
"author_email": "rlabbejr@gmail.com",
"download_url": null,
"platform": null,
"description": "FilterPy - Kalman filters and other optimal and non-optimal estimation filters in Python.\r\n-----------------------------------------------------------------------------------------\r\n\r\n.. image:: https://img.shields.io/pypi/v/filterpy.svg\r\n :target: https://pypi.python.org/pypi/filterpy\r\n \r\n.. image:: https://readthedocs.org/projects/pip/badge/?version=latest&style=flat\r\n :target: https://filterpy.readthedocs.io/en/latest/ \r\n \r\n\r\n**NOTE**: Imminent drop of support of Python 2.7, 3.4. See section below for details.\r\n\r\nThis library provides Kalman filtering and various related optimal and\r\nnon-optimal filtering software written in Python. It contains Kalman\r\nfilters, Extended Kalman filters, Unscented Kalman filters, Kalman\r\nsmoothers, Least Squares filters, fading memory filters, g-h filters,\r\ndiscrete Bayes, and more.\r\n\r\nThis is code I am developing in conjunction with my book Kalman and\r\nBayesian Filter in Python, which you can read/download at\r\nhttps://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python/\r\n\r\nMy aim is largely pedalogical - I opt for clear code that matches the\r\nequations in the relevant texts on a 1-to-1 basis, even when that has a\r\nperformance cost. There are places where this tradeoff is unclear - for\r\nexample, I find it somewhat clearer to write a small set of equations\r\nusing linear algebra, but numpy's overhead on small matrices makes it\r\nrun slower than writing each equation out by hand. Furthermore, books\r\nsuch Zarchan present the written out form, not the linear algebra form.\r\nIt is hard for me to choose which presentation is 'clearer' - it depends\r\non the audience. In that case I usually opt for the faster implementation.\r\n\r\nI use NumPy and SciPy for all of the computations. I have experimented\r\nwith Numba and it yields impressive speed ups with minimal costs, but I \r\nam not convinced that I want to add that requirement to my project. It \r\nis still on my list of things to figure out, however.\r\n\r\nSphinx generated documentation lives at http://filterpy.readthedocs.org/.\r\nGeneration is triggered by git when I do a check in, so this will always\r\nbe bleeding edge development version - it will often be ahead of the\r\nreleased version. \r\n\r\n\r\nPlan for dropping Python 2.7 support\r\n------------------------------------\r\n\r\nI haven't finalized my decision on this, but NumPy is dropping\r\nPython 2.7 support in December 2018. I will certainly drop Python\r\n2.7 support by then; I will probably do it much sooner.\r\n\r\nAt the moment FilterPy is on version 1.x. I plan to fork the project\r\nto version 2.0, and support only Python 3.5+. The 1.x version \r\nwill still be available, but I will not support it. If I add something\r\namazing to 2.0 and someone really begs, I might backport it; more\r\nlikely I would accept a pull request with the feature backported\r\nto 1.x. But to be honest I don't forsee this happening.\r\n\r\nWhy 3.5+, and not 3.4+? 3.5 introduced the matrix multiply symbol,\r\nand I want my code to take advantage of it. Plus, to be honest,\r\nI'm being selfish. I don't want to spend my life supporting this\r\npackage, and moving as far into the present as possible means\r\na few extra years before the Python version I choose becomes\r\nhopelessly dated and a liability. I recognize this makes people\r\nrunning the default Python in their linux distribution more\r\npainful. All I can say is I did not decide to do the Python\r\n3 fork, and I don't have the time to support the bifurcation\r\nany longer.\r\n\r\nI am making edits to the package now in support of my book;\r\nonce those are done I'll probably create the 2.0 branch. \r\nI'm contemplating a SLAM addition to the book, and am not\r\nsure if I will do this in 3.5+ only or not.\r\n\r\n\r\nInstallation\r\n------------\r\n\r\nThe most general installation is just to use pip, which should come with\r\nany modern Python distribution.\r\n\r\n.. image:: https://img.shields.io/pypi/v/filterpy.svg\r\n :target: https://pypi.python.org/pypi/filterpy\r\n \r\n::\r\n\r\n pip install filterpy\r\n\r\nIf you prefer to download the source yourself\r\n\r\n::\r\n\r\n cd <directory you want to install to>\r\n git clone http://github.com/rlabbe/filterpy\r\n python setup.py install\r\n\r\nIf you use Anaconda, you can install from the conda-forge channel. You\r\nwill need to add the conda-forge channel if you haven't already done so:\r\n\r\n::\r\n conda config --add channels conda-forge\r\n \r\nand then install with:\r\n\r\n::\r\n conda install filterpy\r\n \r\n \r\nAnd, if you want to install from the bleeding edge git version\r\n\r\n::\r\n\r\n pip install git+https://github.com/rlabbe/filterpy.git\r\n\r\nNote: I make no guarantees that everything works if you install from here.\r\nI'm the only developer, and so I don't worry about dev/release branches and\r\nthe like. Unless I fix a bug for you and tell you to get this version because\r\nI haven't made a new release yet, I strongly advise not installing from git.\r\n\r\n\r\n \r\n\r\nBasic use\r\n---------\r\n\r\nFull documentation is at\r\nhttps://filterpy.readthedocs.io/en/latest/\r\n\r\n\r\nFirst, import the filters and helper functions.\r\n\r\n.. code-block:: python\r\n\r\n import numpy as np\r\n from filterpy.kalman import KalmanFilter\r\n from filterpy.common import Q_discrete_white_noise\r\n\r\nNow, create the filter\r\n\r\n.. code-block:: python\r\n\r\n my_filter = KalmanFilter(dim_x=2, dim_z=1)\r\n\r\n\r\nInitialize the filter's matrices.\r\n\r\n.. code-block:: python\r\n\r\n my_filter.x = np.array([[2.],\r\n [0.]]) # initial state (location and velocity)\r\n\r\n my_filter.F = np.array([[1.,1.],\r\n [0.,1.]]) # state transition matrix\r\n\r\n my_filter.H = np.array([[1.,0.]]) # Measurement function\r\n my_filter.P *= 1000. # covariance matrix\r\n my_filter.R = 5 # state uncertainty\r\n my_filter.Q = Q_discrete_white_noise(dim=2, dt=0.1, var=0.1) # process uncertainty\r\n\r\n\r\nFinally, run the filter.\r\n\r\n.. code-block:: python\r\n\r\n while True:\r\n my_filter.predict()\r\n my_filter.update(get_some_measurement())\r\n\r\n # do something with the output\r\n x = my_filter.x\r\n do_something_amazing(x)\r\n\r\nSorry, that is the extent of the documentation here. However, the library\r\nis broken up into subdirectories: gh, kalman, memory, leastsq, and so on.\r\nEach subdirectory contains python files relating to that form of filter.\r\nThe functions and methods contain pretty good docstrings on use.\r\n\r\nMy book https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python/\r\nuses this library, and is the place to go if you are trying to learn\r\nabout Kalman filtering and/or this library. These two are not exactly in \r\nsync - my normal development cycle is to add files here, test them, figure \r\nout how to present them pedalogically, then write the appropriate section\r\nor chapter in the book. So there is code here that is not discussed\r\nyet in the book.\r\n\r\n\r\nRequirements\r\n------------\r\n\r\nThis library uses NumPy, SciPy, Matplotlib, and Python. \r\n\r\nI haven't extensively tested backwards compatibility - I use the\r\nAnaconda distribution, and so I am on Python 3.6 and 2.7.14, along with\r\nwhatever version of NumPy, SciPy, and matplotlib they provide. But I am\r\nusing pretty basic Python - numpy.array, maybe a list comprehension in\r\nmy tests.\r\n\r\nI import from **__future__** to ensure the code works in Python 2 and 3.\r\n\r\n\r\nTesting\r\n-------\r\n\r\nAll tests are written to work with py.test. Just type ``py.test`` at the\r\ncommand line.\r\n\r\nAs explained above, the tests are not robust. I'm still at the stage\r\nwhere visual plots are the best way to see how things are working.\r\nApologies, but I think it is a sound choice for development. It is easy\r\nfor a filter to perform within theoretical limits (which we can write a\r\nnon-visual test for) yet be 'off' in some way. The code itself contains\r\ntests in the form of asserts and properties that ensure that arrays are\r\nof the proper dimension, etc.\r\n\r\nReferences\r\n----------\r\n\r\nI use three main texts as my refererence, though I do own the majority\r\nof the Kalman filtering literature. First is Paul Zarchan's\r\n'Fundamentals of Kalman Filtering: A Practical Approach'. I think it by\r\nfar the best Kalman filtering book out there if you are interested in\r\npractical applications more than writing a thesis. The second book I use\r\nis Eli Brookner's 'Tracking and Kalman Filtering Made Easy'. This is an\r\nastonishingly good book; its first chapter is actually readable by the\r\nlayperson! Brookner starts from the g-h filter, and shows how all other\r\nfilters - the Kalman filter, least squares, fading memory, etc., all\r\nderive from the g-h filter. It greatly simplifies many aspects of\r\nanalysis and/or intuitive understanding of your problem. In contrast,\r\nZarchan starts from least squares, and then moves on to Kalman\r\nfiltering. I find that he downplays the predict-update aspect of the\r\nalgorithms, but he has a wealth of worked examples and comparisons\r\nbetween different methods. I think both viewpoints are needed, and so I\r\ncan't imagine discarding one book. Brookner also focuses on issues that\r\nare ignored in other books - track initialization, detecting and\r\ndiscarding noise, tracking multiple objects, an so on.\r\n\r\nI said three books. I also like and use Bar-Shalom's Estimation with\r\nApplications to Tracking and Navigation. Much more mathematical than the\r\nprevious two books, I would not recommend it as a first text unless you\r\nalready have a background in control theory or optimal estimation. Once\r\nyou have that experience, this book is a gem. Every sentence is crystal\r\nclear, his language is precise, but each abstract mathematical statement\r\nis followed with something like \"and this means...\".\r\n\r\n\r\nLicense\r\n-------\r\n.. image:: https://anaconda.org/rlabbe/filterpy/badges/license.svg :target: https://anaconda.org/rlabbe/filterpy\r\n\r\nThe MIT License (MIT)\r\n\r\nCopyright (c) 2015 Roger R. Labbe Jr\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy\r\nof this software and associated documentation files (the \"Software\"), to deal\r\nin the Software without restriction, including without limitation the rights\r\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\ncopies of the Software, and to permit persons to whom the Software is\r\nfurnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in\r\nall copies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\r\nTHE SOFTWARE.TION OF CONTRACT,\r\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\r\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Kalman filtering and optimal estimation library",
"version": "1.4.5",
"project_urls": {
"Homepage": "https://github.com/rlabbe/filterpy"
},
"split_keywords": [
"kalman",
"filters",
"filtering",
"optimal",
"estimation",
"tracking"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "906eb656d688124b43b6377034a1cd8ae2a8ea0293237c63f0fcf8008758a4b9",
"md5": "2a09d18b7a3668b31c73945bd895b266",
"sha256": "3c4f070668e7d7d6fb5b044afa7fb7ebfd647be82f2ff13a6c92940bf7e42ae5"
},
"downloads": -1,
"filename": "filterpywhl-1.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a09d18b7a3668b31c73945bd895b266",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 111301,
"upload_time": "2024-04-08T21:12:46",
"upload_time_iso_8601": "2024-04-08T21:12:46.507186Z",
"url": "https://files.pythonhosted.org/packages/90/6e/b656d688124b43b6377034a1cd8ae2a8ea0293237c63f0fcf8008758a4b9/filterpywhl-1.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-08 21:12:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rlabbe",
"github_project": "filterpy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "scipy",
"specs": []
}
],
"lcname": "filterpywhl"
}
JSON
