Ensemble Kalman Filter Algorithm and Data Type

[0sm1um]

Here is my implementation of the EnKF which I presented at last year's Fusion Conference.

A full writeup of the algorithm itself, as well as design philosophy can be found in my paper titled "Implementation of Ensemble Kalman Filters in Stone Soup". The short version is that the EnKF is a numerical approximation of the Kalman Filter, which can also be used for nonlinear estimation.

The key component of this contribution is a new State Type is introduced known as EnsembleState. This state bears a resemblence to the GaussianState, except instead of being composed of a single StateVector and CovarianceMatrix, it represents the state as a single StateVectors instance which is referred to as the ensemble in the code. This data type has class methods which allow the user to return the mean of the ensemble(as a numpy array or as a state vector), and sample covariance matrix. This allows users familliar with GaussianState to interact with it in all the ways they are used to as the syntax to retrieve this information is the same for both.

This pull request includes this new state type, as well as a new EnsemblePredictor and EnsembleUpdater.

[codecov]

Codecov Report

Merging #625 (85be6fa) into main (d38a196) will increase coverage by 0.06%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##             main     #625      +/-   ##
==========================================
+ Coverage   94.22%   94.29%   +0.06%     
==========================================
  Files         158      160       +2     
  Lines        7832     7919      +87     
  Branches     1506     1519      +13     
==========================================
+ Hits         7380     7467      +87     
  Misses        343      343              
  Partials      109      109              

Flag	Coverage Δ
integration	67.62% <53.33%> (-0.18%)	⬇️
unittests	92.06% <100.00%> (+0.08%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
stonesoup/predictor/ensemble.py	100.00% <100.00%> (ø)
stonesoup/types/prediction.py	100.00% <100.00%> (ø)
stonesoup/types/state.py	99.64% <100.00%> (+0.05%)	⬆️
stonesoup/types/update.py	100.00% <100.00%> (ø)
stonesoup/updater/ensemble.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d38a196...85be6fa. Read the comment docs.

[jwragg-dstl]

Looks really good. Some documentation for the Ensemble KF is required e.g: .. automodule:: stonesoup.updater.EnsembleKalmanFiter
:show-inheritance:

taken from the Stone Soup source documentation.

[0sm1um]

Thank you! I believe I have added the proper headers in the updater and predictor sections. I also fixed a docstring not rendering properly on the EnsembleState class. Please let me know if I missed any other errors in the documentation.

I have two other questions I would like to ask.

First is since I have my paper available to reference; is there a prescribed way to reference or cite them them in the documentation itself?

Second, after speaking with a co author of my paper, is that I believe it may be necessary to update or add copyrights/liscence disclaimer which states something along the lines of:

"Copyright © 2020-2021 John Hiles
Portions of this work were created while John Hiles was employed by Wright State University under Contract No. FA8650-18-2-1645 to the Air Force Research Laboratory, and the University has released its rights to this Student work."

My understanding is that this is neccisary to ensure that the public release that I obtained is properly acknowledged. Do you all have a set protocol on how you would like this to be done? I would suggest that I add a file or put this in the LISCENCE file on my branch which has this information and it can be removed after the merge.

[sdhiscocks]

I have two other questions I would like to ask.

First is since I have my paper available to reference; is there a prescribed way to reference or cite them them in the documentation itself?

You can include a reference in the doc string. There are example in the code like the square root Kalman filter.

We also have #199 on the TODO list, where we'd like to include list of references to papers that use or about Stone Soup. We'll be sure to include your paper.

Second, after speaking with a co author of my paper, is that I believe it may be necessary to update or add copyrights/liscence disclaimer which states something along the lines of:

"Copyright © 2020-2021 John Hiles Portions of this work were created while John Hiles was employed by Wright State University under Contract No. FA8650-18-2-1645 to the Air Force Research Laboratory, and the University has released its rights to this Student work."

My understanding is that this is neccisary to ensure that the public release that I obtained is properly acknowledged. Do you all have a set protocol on how you would like this to be done? I would suggest that I add a file or put this in the LISCENCE file on my branch which has this information and it can be removed after the merge.

Please go ahead and edit the LICENSE file to include this on the PR. As the code will remain in the code base, it can remain in the file going forwards.

[0sm1um]

I updated the license file and added reference to our paper in the docstring(as well as making the docstrings just generally better).

[sdhiscocks]

Looks good 👍

Testing, I think we could do with adding an initiator for ensemble states, even if initially like the GaussianParticleInitiator, where we can use existing Gaussian initiators and EnsembleState.from_gaussian_state method. I'll raise an issue for this, and can be done separately to this PR.

[jwragg-dstl]

All the Docstrings and methods look great. Nothing else to add from me. Thanks.