# Optimized Kalman Filter
## Summary
**This repo implements an Optimized Kalman Filter (OKF), which optimizes the parameters $Q,R$ to minimize the MSE.**
**Motivation**: The KF parameters $Q,R$ are usually estimated as the covariances of the noise.
However, such estimation is usually sub-optimal, hence explicit MSE optimization is preferable, as discussed in the *NeurIPS 2023* paper [Optimization or Architecture: How to Hack Kalman Filtering](https://arxiv.org/abs/2310.00675), by Ido Greenberg, Netanel Yannay and Shie Mannor.
**Problem setup**: A dataset of trajectories is required, with *both* observations and true system-states (learning from observations alone is currently not supported). The parameters $Q,R$ are optimized with respect to this dataset, and then can be used to make predictions on new trajectories.
**Installation**: `pip install Optimized-Kalman-Filter`
**Usage example**: [`example.ipynb`](https://github.com/ido90/Optimized-Kalman-Filter/blob/master/example.ipynb).
- [Background](#background-the-kalman-filter)
- [When to use](#when-to-use-this-package)
- [Why to use](#why-to-use)
- [How to use](#how-to-use)
- [Cite us](#cite-us)
| <img src="https://idogreenberg.neocities.org/linked_images/okf_errors.png" width="280"> <img src="https://idogreenberg.neocities.org/linked_images/okf_sample.png" width="270"> |
| :--: |
| The standard KF (tuned by noise-estimation) vs. the Optimized KF, in the test data of the simple-lidar example problem: errors summary (left) and a sample of models predictions against the actual target (right) (images from `example.ipynb`) |
## Background: the Kalman Filter
The Kalman Filter (KF) is a popular algorithm for filtering problems such as state estimation, smoothing, tracking and navigation. For example, consider tracking a plane using noisy measurements (observations) from a radar. Every time-step, we try to predict the motion of the plane, then receive a new measurement from the radar and update our belief accordingly.
| <img src="https://idogreenberg.neocities.org/linked_images/KF_illustration.png" width="320"> |
| :--: |
| An illustration of a single step of the Kalman Filter: predict the next state (black arrow); receive a new observation (green ellipse); update your belief about the state (mixing the two right ellipses) (image by Ido Greenberg) |
| <img src="https://idogreenberg.neocities.org/linked_images/KF_diagram.png" width="360"> |
| :--: |
| A diagram of the Kalman Filter algorithm (image by Ido Greenberg) |
To tune the KF, one has to determine the parameters representing the measurement (observation) noise and the motion-prediction noise, expressed as covariance matrices R and Q. Given a dataset of measurements {z_t} (e.g. from the radar), tuning these parameters may be a difficult task, and has been studied for many decades. However, given data of *both* measurements {z_t} and true-states {x_t} (e.g. true plane locations), the parameters R,Q are usually estimated from the data as the sample covariance matrices of the noise.
## When to use this package
When you want to build a Kalman Filter for your problem, and you have a training dataset with sequences of both states {x_t} and observations {z_t}.
## Why to use
Tuning the KF parameters through noise estimation (as explained above) yields optimal model predictions - under the KF assumptions. However, as shown in the paper, whenever the assumptions do not hold, optimization of the parameters may lead to more accurate predictions. Since most practical problems do not satisfy the assumptions, and since assumptions violations are often not noticed at all by the user, optimization of the parameters is a good practice whenever a corresponding dataset is available.
## How to use
**Installation**: `pip install Optimized-Kalman-Filter`
**Import**: `import okf`
**Usage example**: [`example.ipynb`](https://github.com/ido90/Optimized-Kalman-Filter/blob/master/example.ipynb).
#### Data
The data consists of 2 lists of length n, where n is the number of trajectories in the data:
1. X[i] = a numpy array of type double and shape (n_time_steps(trajectory i), state_dimension).
2. Z[i] = a numpy array of type double and shape (n_time_steps(trajectory i), observation_dimension).
For example, if a state is 4-dimensional (e.g. (x,y,vx,vy)) and an observation is 2-dimensional (e.g. (x,y)), and the i'th trajectory has 30 time-steps, then `X[i].shape` is (30,4) and `Z[i].shape` is (30,2).
Below we assume that `Xtrain, Ztrain, Xtest, Ztest` correspond to train and test datasets of the format specified above.
#### KF configuration
The configuration of the KF has to be specified as a dict `model_args` containing the following entries:
- `dim_x`: the number of entries in a state
- `dim_z`: the number of entries in an observation
- `F`: the dynamics model: a pytorch tensor of type double and shape (dim_x, dim_x)
- `H`: the observation model: a pytorch tensor of type double and shape (dim_z, dim_x); or a function that returns such a tensor given the estimated state and the current observation
- `loss_fun`: function(predicted_x, true_x) used as loss for training and evaluation
- State initialization: initialize either explicitly via `x0` (tensor of shape dim_x); or from the first observation via the function `init_z2x`
See an example [here](https://github.com/ido90/Optimized-Kalman-Filter/blob/master/okf/example/simple_lidar_model.py).
#### Train and test
```
import okf
model = okf.OKF(**model_args) # set optimize=False for the standard KF baseline
okf.train(model, Ztrain, Xtrain)
loss = okf.test_model(model, Ztest, Xtest, loss_fun=model_args['loss_fun'])
```
#### Analysis
See [`example.ipynb`](https://github.com/ido90/Optimized-Kalman-Filter/blob/master/example.ipynb).
## Cite us
```
@article{greenberg2023okf,
title={Optimization or architecture: how to hack Kalman filtering},
author={Greenberg, Ido and Yannay, Netanel and Mannor, Shie},
journal={Advances in Neural Information Processing Systems},
year={2023}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ido90/Optimized-Kalman-Filter",
"name": "Optimized-Kalman-Filter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "OKF,Optimized Kalman Filter,Kalman Filter",
"author": "Ido Greenberg",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# Optimized Kalman Filter\n\n## Summary\n\n**This repo implements an Optimized Kalman Filter (OKF), which optimizes the parameters $Q,R$ to minimize the MSE.**\n\n**Motivation**: The KF parameters $Q,R$ are usually estimated as the covariances of the noise.\nHowever, such estimation is usually sub-optimal, hence explicit MSE optimization is preferable, as discussed in the *NeurIPS 2023* paper [Optimization or Architecture: How to Hack Kalman Filtering](https://arxiv.org/abs/2310.00675), by Ido Greenberg, Netanel Yannay and Shie Mannor.\n\n**Problem setup**: A dataset of trajectories is required, with *both* observations and true system-states (learning from observations alone is currently not supported). The parameters $Q,R$ are optimized with respect to this dataset, and then can be used to make predictions on new trajectories.\n\n**Installation**: `pip install Optimized-Kalman-Filter`\n\n**Usage example**: [`example.ipynb`](https://github.com/ido90/Optimized-Kalman-Filter/blob/master/example.ipynb).\n\n- [Background](#background-the-kalman-filter)\n- [When to use](#when-to-use-this-package)\n- [Why to use](#why-to-use)\n- [How to use](#how-to-use)\n- [Cite us](#cite-us)\n\n| <img src=\"https://idogreenberg.neocities.org/linked_images/okf_errors.png\" width=\"280\"> <img src=\"https://idogreenberg.neocities.org/linked_images/okf_sample.png\" width=\"270\"> |\n| :--: |\n| The standard KF (tuned by noise-estimation) vs. the Optimized KF, in the test data of the simple-lidar example problem: errors summary (left) and a sample of models predictions against the actual target (right) (images from `example.ipynb`) |\n\n## Background: the Kalman Filter\n\nThe Kalman Filter (KF) is a popular algorithm for filtering problems such as state estimation, smoothing, tracking and navigation. For example, consider tracking a plane using noisy measurements (observations) from a radar. Every time-step, we try to predict the motion of the plane, then receive a new measurement from the radar and update our belief accordingly.\n\n| <img src=\"https://idogreenberg.neocities.org/linked_images/KF_illustration.png\" width=\"320\"> |\n| :--: |\n| An illustration of a single step of the Kalman Filter: predict the next state (black arrow); receive a new observation (green ellipse); update your belief about the state (mixing the two right ellipses) (image by Ido Greenberg) |\n\n| <img src=\"https://idogreenberg.neocities.org/linked_images/KF_diagram.png\" width=\"360\"> |\n| :--: |\n| A diagram of the Kalman Filter algorithm (image by Ido Greenberg) |\n\nTo tune the KF, one has to determine the parameters representing the measurement (observation) noise and the motion-prediction noise, expressed as covariance matrices R and Q. Given a dataset of measurements {z_t} (e.g. from the radar), tuning these parameters may be a difficult task, and has been studied for many decades. However, given data of *both* measurements {z_t} and true-states {x_t} (e.g. true plane locations), the parameters R,Q are usually estimated from the data as the sample covariance matrices of the noise.\n\n## When to use this package\n\nWhen you want to build a Kalman Filter for your problem, and you have a training dataset with sequences of both states {x_t} and observations {z_t}.\n\n## Why to use\n\nTuning the KF parameters through noise estimation (as explained above) yields optimal model predictions - under the KF assumptions. However, as shown in the paper, whenever the assumptions do not hold, optimization of the parameters may lead to more accurate predictions. Since most practical problems do not satisfy the assumptions, and since assumptions violations are often not noticed at all by the user, optimization of the parameters is a good practice whenever a corresponding dataset is available.\n\n## How to use\n\n**Installation**: `pip install Optimized-Kalman-Filter`\n\n**Import**: `import okf`\n\n**Usage example**: [`example.ipynb`](https://github.com/ido90/Optimized-Kalman-Filter/blob/master/example.ipynb).\n\n#### Data\nThe data consists of 2 lists of length n, where n is the number of trajectories in the data:\n1. X[i] = a numpy array of type double and shape (n_time_steps(trajectory i), state_dimension).\n2. Z[i] = a numpy array of type double and shape (n_time_steps(trajectory i), observation_dimension).\n\nFor example, if a state is 4-dimensional (e.g. (x,y,vx,vy)) and an observation is 2-dimensional (e.g. (x,y)), and the i'th trajectory has 30 time-steps, then `X[i].shape` is (30,4) and `Z[i].shape` is (30,2).\n\nBelow we assume that `Xtrain, Ztrain, Xtest, Ztest` correspond to train and test datasets of the format specified above.\n\n#### KF configuration\nThe configuration of the KF has to be specified as a dict `model_args` containing the following entries:\n- `dim_x`: the number of entries in a state\n- `dim_z`: the number of entries in an observation\n- `F`: the dynamics model: a pytorch tensor of type double and shape (dim_x, dim_x)\n- `H`: the observation model: a pytorch tensor of type double and shape (dim_z, dim_x); or a function that returns such a tensor given the estimated state and the current observation\n- `loss_fun`: function(predicted_x, true_x) used as loss for training and evaluation\n- State initialization: initialize either explicitly via `x0` (tensor of shape dim_x); or from the first observation via the function `init_z2x`\n\nSee an example [here](https://github.com/ido90/Optimized-Kalman-Filter/blob/master/okf/example/simple_lidar_model.py).\n\n#### Train and test\n```\nimport okf\nmodel = okf.OKF(**model_args) # set optimize=False for the standard KF baseline\nokf.train(model, Ztrain, Xtrain)\nloss = okf.test_model(model, Ztest, Xtest, loss_fun=model_args['loss_fun'])\n```\n\n#### Analysis\nSee [`example.ipynb`](https://github.com/ido90/Optimized-Kalman-Filter/blob/master/example.ipynb).\n\n\n## Cite us\n```\n@article{greenberg2023okf,\n title={Optimization or architecture: how to hack Kalman filtering},\n author={Greenberg, Ido and Yannay, Netanel and Mannor, Shie},\n journal={Advances in Neural Information Processing Systems},\n year={2023}\n}\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Optimization of a Kalman Filter from data of states and their observations.",
"version": "0.0.9",
"project_urls": {
"Homepage": "https://github.com/ido90/Optimized-Kalman-Filter"
},
"split_keywords": [
"okf",
"optimized kalman filter",
"kalman filter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5aac9bd376f7c692f7ff397c910c8ff2ded78a810393a4463bf2be179f3cf483",
"md5": "8c90159511d6179173aec35ee8f3918e",
"sha256": "ab74ad8e0e5dd91dc885133f2eb1d1e10bf34beab81d6e0b4f1f34f1495728d7"
},
"downloads": -1,
"filename": "Optimized_Kalman_Filter-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c90159511d6179173aec35ee8f3918e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 20532,
"upload_time": "2023-10-03T05:44:35",
"upload_time_iso_8601": "2023-10-03T05:44:35.948238Z",
"url": "https://files.pythonhosted.org/packages/5a/ac/9bd376f7c692f7ff397c910c8ff2ded78a810393a4463bf2be179f3cf483/Optimized_Kalman_Filter-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-03 05:44:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ido90",
"github_project": "Optimized-Kalman-Filter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "optimized-kalman-filter"
}
JSON
