Added Saver class, many documentation changes

This is an unfortunately large check in.

Big change is moved the Saver class to common and made it work
with any filter, not just the KalmanFilter class.

Along the way many docstrings were modified.

Author: rlabbe

filterpy/__init__.py

@@ -14,4 +14,4 @@
 for more information.
 """
 
-__version__ = "1.3.1"
+__version__ = "1.3.2"

filterpy/changelog.txt

@@ -1,3 +1,23 @@
+Version 1.3.2
+=============
+
+Fixed build error in Python 2.7 due to using print function without importing
+it from future.
+
+Added filterpy.common.Saver class, which can save all the attribute of any
+filtering class. Replaces KalmanFilter.Saver, which only worked for the
+KalmanFilter class.
+
+Added optional parameter specifying a Saver object to be passed into all of the
+batch_filter() functions/methods.
+
+Added attribute z to most of the filter classes. This is mostly so the
+
+
+
+Changes to documentation - mostly making it more consistent.
+
+
 Version 1.3.1
 =============
 
@@ -10,7 +30,7 @@ Version 1.3
 
 * #113 added plotting of 3D covariance ellipsoid with plot_3d_covariance
 * Fixed bug where multivariate_gaussian accepted negative covariances
-* #108 used pylint symbolic names 
+* #108 used pylint symbolic names
 * Got code in compliance with pylint
 * Fixed #105 - this was just test code, and it turns out the code as was was correct, so I deleted the second return statement
 * #88 fixed HInfinity.batch_filter to not use R
@@ -20,7 +40,7 @@ Version 1.3
 Version 1.2.5
 =============
 
-#102 - Bug: UKF was using slow code path when using np.subtract. 
+#102 - Bug: UKF was using slow code path when using np.subtract.
 
 
 Version 1.2.4
@@ -73,7 +93,7 @@ while performing filtering.
 
 * Fixed bug where likelihood() returned None
 
-* Altered RTS_smoother algorithm to also return the 
+* Altered RTS_smoother algorithm to also return the
 predicted covariances
 
 
@@ -89,17 +109,17 @@ Version 0.1.5
 
 * Fix #53: UKF rts_smoother does not use residual functions
 * Fixed #54: Comments in multivariate_multiply incorrectly called the
-  covariance the mean. 
+  covariance the mean.
 * Added logpdf to stats. Computes logpdf - mostly a wrapper around
-  stats.multivariate_normal.logpdf as older versions of that function 
+  stats.multivariate_normal.logpdf as older versions of that function
   do not support the allow_singular keyword. But it also flattens out the
   vectors for you so you do not have to do anything special with column vectors.
 
 Version 0.1.4
 =============
 
 * Added Cubature Kalman filter.
-* Bug in Q_continuous_white_noise(). The first term in the matrix should be (dt**3)/3, not (dt**4)/3. 
+* Bug in Q_continuous_white_noise(). The first term in the matrix should be (dt**3)/3, not (dt**4)/3.
 * Added log-likelihood computation to UKF.
 * Added simplex points for UKF
 * fixed bug in KF matrix size check
@@ -113,7 +133,7 @@ time varying.
 
 
 * Github issue #40. Fixed behavior of multivariate_gaussian to accept list as
-the covariance matrix. 
+the covariance matrix.
 
 
 Version 0.1.2
@@ -132,8 +152,8 @@ Version 0.1.1
 * Brought docstrings (mostly) into compliance with NumPy documentation style.
 This requires installation of numpy doc with
     pip install numpydoc
-    
-docs\conf.py has been modified to use numpydoc. 
+
+docs\conf.py has been modified to use numpydoc.
 
 
 
@@ -149,7 +169,7 @@ I finish the book and flesh out a few points.
 
 Color on this: There are various recusive equations for the fixed point
 filter that I have found in various book - Simon, Crassidis, and Grewal.
-None seem to work very well. I have code that works pretty good when R 
+None seem to work very well. I have code that works pretty good when R
 is < 0.5 or so, but then the filter diverges when R is larger. I'm not seeing
 much in the literature that explains this very well, nor any evidence of
 this smoother actually being used in practice. I will give this a bit
@@ -185,12 +205,12 @@ correlated process and measurement noise.
 
 * various bug fixes
 
- 
+
 Version 0.0.26
 ==============
 
 * Added likelihood and log-likelihood to the KalmanFilter
-class. 
+class.
 
 * Added an MMAE filter bank class.
 
@@ -243,8 +263,8 @@ from filterpy.common to filterpy.stats and everything should work.
 Version 0.0.21
 ==============
 
-Added monte_carlo module which contains routines for MCMC - mostly 
-for particle filtering. 
+Added monte_carlo module which contains routines for MCMC - mostly
+for particle filtering.
 
 
 Version 0.0.20
@@ -268,7 +288,7 @@ Version 0.0.19
 BREAKING CHANGES!!
 
 The unscented kalman filter code has been significantly altered. Your
-existing code will no longer run. Sorry, but it had to be done. 
+existing code will no longer run. Sorry, but it had to be done.
 
 As of version 0.0.18 there were separate classes for the UKF (Julier's)
 original formulation, and for the scaled UKF. But they are all the same thing,
@@ -294,7 +314,7 @@ Version 0.0.18
 ==============
 
 * Added args parameters to Hx and HJacobian of the ExtendedKalmanFilter
-class so you can pass additional data to them. 
+class so you can pass additional data to them.
 
 * Made an exception more human readable by including the size of the
 matrix that caused the shape error.
@@ -309,7 +329,7 @@ Version 0.0.16
 ==============
 
 * Added multivariate_multiply to stats module.
-* IMPORTANT: bug fix in the UKF RTS smoother routine. 
+* IMPORTANT: bug fix in the UKF RTS smoother routine.
 * various typo fixes.
 
 Version 0.0.15
@@ -321,8 +341,8 @@ A bunch of small changes and bug fixes. Documentation improvements.
 Version 0.0.14
 ==============
 
-The change to _dt was stupid in 0.0.13 . I put it back to _dt, and 
-then added an optional dt parameter to the predict() function. 
+The change to _dt was stupid in 0.0.13 . I put it back to _dt, and
+then added an optional dt parameter to the predict() function.
 
 
 Version 0.0.13
@@ -364,7 +384,7 @@ function call. On the other hand, failures are obsucre. This will be
 finalized in few releases.
 
 
- 
+
 Version 0.0.9
 =============
 

filterpy/common/helpers.py

@@ -16,6 +16,162 @@
 for more information.
 """
 
+from __future__ import print_function
+from collections import defaultdict
+import copy
+import numpy as np
+
+
+class Saver(object):
+    """
+    Helper class to save the states of any filter object.
+    Each time you call save() all of the attributes (state, covariances, etc)
+    are appended to lists.
+
+    Generally you would do this once per epoch - predict/update.
+
+    Then, you can access any of the states by using the [] syntax or by
+    using the . operator.
+
+    .. code-block:: Python
+
+        my_saver = Saver()
+        ... do some filtering
+
+        x = my_saver['x']
+        x = my_save.x
+
+    Either returns a list of all of the state `x` values for the entire
+    filtering process.
+
+    If you want to convert all saved lists into numpy arrays, call to_array().
+
+
+    Parameters
+    ----------
+
+    kf : object
+        any object with a __dict__ attribute, but intended to be one of the
+        filtering classes
+
+    save_current : bool, default=True
+        save the current state of `kf` when the object is created;
+
+    skip_private: bool, default=False
+        Control skipping any private attribute (anything starting with '_')
+        Turning this on saves memory, but slows down execution a bit.
+
+    skip_callable: bool, default=False
+        Control skipping any attribute which is a method. Turning this on
+        saves memory, but slows down execution a bit.
+
+    ignore: (str,) tuple of strings
+        list of keys to ignore.
+
+    Examples
+    --------
+
+    .. code-block:: Python
+
+        kf = KalmanFilter(...whatever)
+        # initialize kf here
+
+        saver = Saver(kf) # save data for kf filter
+        for z in zs:
+            kf.predict()
+            kf.update(z)
+            saver.save()
+
+        x = np.array(s.x) # get the kf.x state in an np.array
+        plt.plot(x[:, 0], x[:, 2])
+
+        # ... or ...
+        s.to_array()
+        plt.plot(s.x[:, 0], s.x[:, 2])
+
+    """
+
+    def __init__(self, kf, save_current=False,
+                 skip_private=False,
+                 skip_callable=False,
+                 ignore=()):
+        """ Construct the save object, optionally saving the current
+        state of the filter"""
+
+        self._kf = kf
+        self._DL = defaultdict(list)
+        self._skip_private = skip_private
+        self._skip_callable = skip_callable
+        self._ignore = ignore
+        self._len = 0
+
+        if save_current:
+            self.save()
+
+
+    def save(self):
+        """ save the current state of the Kalman filter"""
+
+        kf = self._kf
+        v = copy.deepcopy(kf.__dict__)
+
+        if self._skip_private:
+            for key in list(v.keys()):
+                if key.startswith('_'):
+                    print('deleting', key)
+                    del v[key]
+
+        if self._skip_callable:
+            for key in list(v.keys()):
+                if callable(v[key]):
+                    del v[key]
+
+        for ig in self._ignore:
+            if ig in v:
+                del v[ig]
+
+        for key in list(v.keys()):
+            self._DL[key].append(v[key])
+
+        self.__dict__.update(self._DL)
+        self._len += 1
+
+
+    def __getitem__(self, key):
+        return self._DL[key]
+
+
+    def __len__(self):
+        return self._len
+
+
+    @property
+    def keys(self):
+        """ list of all keys"""
+        return list(self._DL.keys())
+
+
+    def to_array(self):
+        """
+        Convert all saved attributes from a list to np.array.
+
+        This may or may not work - every saved attribute must have the
+        same shape for every instance. i.e., if `K` changes shape due to `z`
+        changing shape then the call will raise an exception.
+
+        This can also happen if the default initialization in __init__ gives
+        the variable a different shape then it becomes after a predict/update
+        cycle.
+        """
+        for key in self.keys:
+            try:
+                self.__dict__[key] = np.array(self._DL[key])
+            except:
+                # get back to lists so we are in a valid state
+                self.__dict__.update(self._DL)
+
+                raise ValueError("could not convert {} into np.array".format(key))
+
 
 def runge_kutta4(y, x, dx, f):
     """computes 4th order Runge-Kutta for dy/dx.
@@ -112,3 +268,22 @@ def pprint(label, arr, **kwargs):
     """
 
     print(pretty_str(label, arr), **kwargs)
+
+
+def reshape_z(z, dim_z, ndim):
+    """ ensure z is a (dim_z, 1) shaped vector"""
+
+    z = np.atleast_2d(z)
+    if z.shape[1] == dim_z:
+        z = z.T
+
+    if z.shape != (dim_z, 1):
+        raise ValueError('z must be convertible to shape ({}, 1)'.format(dim_z))
+
+    if ndim == 1:
+        z = z[:, 0]
+
+    if ndim == 0:
+        z = z[0, 0]
+
+    return z