statespace_models package

Submodules

statespace_models.estimators module

class statespace_models.estimators.kalman(kf_type, data, transition_matrix=None, observation_matrix=None, measurement_noise=None, initial_state=None, initial_state_covariance=None, process_covariance=None, n_em_iterations=10, window_std_estimate=5, ncpu=1, use_threads=False)

Bases: object

Provides an interface for various types of kalman filters.

Parameters:

kf_type (str) –

  • ‘kf’ : standard kalman filter

  • ’skf’ : smoothed standard kalman filter

  • ’ukf’ : unscented kalman filter

  • ’akf’ : adaptive kalman filter

n_em_iterations: int, optional

‘kf’ type uses the EM algorithm to optimize the transition and observation matrices. This option sets the number of allowable iterations.

get_estimate()

See https://en.wikipedia.org/wiki/Kalman_filter for more information on how Kalman Filters work.

Parameters:

  • kf_type (str) – kf, skf, akf, ukf

  • data (np.array) –

  • transition_matrix (np.array, optional) – If not present, identity matrix is used. The default is None.

  • observation_matrix (np.array, optional) – If not present, identity matrix is used. The default is None.

  • measurement_noise (np.array, optional) – If not present, TwinStat will utilize a rolling variance calculation to estimate each individual variable setting the diagnols of the matrix. The default is None.

  • initial_state (np.array, optional) – If not present TwinStat will use the first data points in the provided data. The default is None.

  • initial_state_covariance (np.array, optional) – If not present, identity matrix is used. The default is None.

  • process_covariance (np.array, optional) – If not present, the measurement covariance matrix is used. The default is None.

  • n_em_iterations (int, optional) – When using akf, the EM algorithm will use this many iterations. The default is 10.

  • window_std_estimate (int, optional) – When estimating the measurment noise, TwinStat will using this many lags in the rolling variance estimation. The default is 5.

  • ncpu (int, optional) – UKF will use ncpu for sigma point evaluation. The default is 1.

Return type:

None.

state_func(x)

A user is expected to provide their own state transition function for UKF, otherwise the default is the identity matrix.

Return type:

array

Parameters:

x (np.array) – Input vector

Return type:

Predicted next hidden variable value

obs_func(x)

A user is expected to provide their own observation function for UKF, otherwise the default is the identity matrix.

Return type:

array

Parameters:

x (np.array) – Input vector

Return type:

Predicted next hidden variable value

get_estimate(Y)

Use the kalman filter type to estimate the 0:n estimations of the hidden statespace variable for the provided data.

Return type:

array

Parameters:

data (np.array) –

Returns:

  • filtered_state_means (np.array)

  • filtered_state_covariances (np.array)

class statespace_models.estimators.HiddenVarModel(**kwargs)

Bases: StateSpaceModel

Definition of the hidden variable model to be used in the particle filtering.

This object currently assumes both a gaussian hidden markov variables and a guassian measurment error.

Also assumes a unity observation/transition function.

Users can instantiate this object and alter various parts based on their application. Use the customized object with the ‘statespace_model’ model input.

Parameters:

  • sigmaX (float, optional) –

  • sigmaY (float, optional) –

default_params = {'sigmaX': 0.5, 'sigmaY': 0.5}
PX0()

Define the function that initializes the particle filter

f(x)

Define the transition function

PX(t, xp)

Define the sampling distribution of the transition function

PY(t, xp, x)

Define the observation sampling distribution

class statespace_models.estimators.particle_filter(y=None, sigmaX=None, sigmaY=None, n_particles=500, statespace_model=None, window_std_estimate=5)

Bases: object

Provides an interface for sequential monte carlo particle filtering of time series signals. Relying on the “particles” package.

Default model:

X = X(n-1) + N(0,sigmaX)
Y = X + N(0,sigmaY)

While the assumed model is gaussian variability, user can provide their own statespace model by extending the particles StateSpaceModel object. See the default _HiddenVarModel object as an example for setup.

Full package options can be found here:

Parameters:

  • y (np.array, optional) – required if no values are provided for sigmaX and sigmaY

  • sigmaX (float, optional,) – Assumed gaussian noise of the hidden variable. If user provides no value, a moving average with window of ‘window_std_estimate’ of the standard deviation will be used. Note that this variable will control the level of smoothing relative to the sigmaY value. The smaller sigmaX is relative to sigmaY, the greater the smoothing.

  • sigmaY (float, optional,) – Assumed gaussian noise of the measurement variable. If user provides no value, a moving average with window of ‘window_std_estimate’ of the standard deviation will be used.

  • n_particles (float, optional) – Number of particles to use in monte carlo sampling.

  • statespace_model (object, optional) –

  • window_std_estimate (int, optional, default = 5) – Window size used when estimating the mesurement variability.

get_estimate(data)

Use the SIR particle filter to estimate the 0:n predictions of the provided data.

Return type:

array

Parameters:

data (np.array) –

Returns:

  • means (np.array)

  • variances (np.array)

Module contents