TFilterPy.state_estimation package

Submodules

TFilterPy.state_estimation.linear_filters module

class TFilterPy.state_estimation.linear_filters.DaskKalmanFilter(state_transition_matrix: ndarray | Array, observation_matrix: ndarray | Array, process_noise_cov: ndarray | Array, observation_noise_cov: ndarray | Array, initial_state: ndarray | Array, initial_covariance: ndarray | Array, estimation_strategy: str = 'residual_analysis')

Bases: ParameterEstimator

Dask-based implementation of a Kalman Filter that supports distributed computing for large datasets. This class extends the ParameterEstimator to estimate the process noise covariance (Q) and observation noise covariance (R) while applying Kalman Filtering on incoming measurements.

The Kalman Filter is a recursive algorithm that estimates the state of a linear dynamic system from noisy measurements. This implementation leverages Dask to scale computations across distributed systems.

Parameters:

• state_transition_matrix (np.ndarray or da.Array, shape (n_features, n_features)) – The state transition matrix (F) representing how the system evolves between states.

• observation_matrix (np.ndarray or da.Array, shape (n_observations, n_features)) – The observation matrix (H) that maps the true state space into the observed space.

• process_noise_cov (np.ndarray or da.Array, shape (n_features, n_features)) – Covariance matrix (Q) representing the process noise.

• observation_noise_cov (np.ndarray or da.Array, shape (n_observations, n_observations)) – Covariance matrix (R) representing the observation noise.

• initial_state (np.ndarray or da.Array, shape (n_features,)) – Initial state vector (x0) of the system.

• initial_covariance (np.ndarray or da.Array, shape (n_features, n_features)) – Initial state covariance matrix (P0), representing initial uncertainty in the state.

• estimation_strategy (str, optional, default="residual_analysis") – The strategy for estimating Q and R. Can be one of: - “residual_analysis” - “mle” - “cross_validation” - “adaptive_filtering”

Raises:

ValueError – If matrix dimensions do not conform to Kalman Filter requirements.

References

Welch, G., & Bishop, G. (1995). An Introduction to the Kalman Filter.

estimate_parameters(measurements: Array) → tuple

Estimate process (Q) and observation (R) noise covariances using the specified strategy.

Parameters:

measurements (da.Array, shape (n_timesteps, n_observations)) – Observed measurements over time.

Returns:

• Q (da.Array, shape (n_features, n_features)) – Estimated process noise covariance matrix.

• R (da.Array, shape (n_features, n_features)) – Estimated observation noise covariance matrix.

Notes

• This method calls the appropriate estimation strategy from the parent class.

• The available strategies include residual analysis, MLE, cross-validation, and adaptive filtering.

fit(X: ndarray | Array) → DaskKalmanFilter

Prepare the Kalman Filter by storing the measurements as a Dask array.

Parameters:

X (np.ndarray or da.Array, shape (n_timesteps, n_observations)) – Array of measurements over time.

Returns:

self – The fitted Kalman Filter instance.

Return type:

DaskKalmanFilter

Raises:

ValueError – If the input measurements are not 2-dimensional.

predict() → Array

Perform state estimation over all time steps using the Kalman Filter algorithm.

This method constructs a Dask computation graph to process the entire measurement sequence in parallel using delayed execution.

Returns:

state_estimates – The estimated state at each time step.

Return type:

da.Array, shape (n_timesteps, n_features)

Notes

• The Kalman Filter operates in two steps: prediction and update.

• Predictions are made using the state transition matrix F.

• Updates are performed using the observation matrix H and Kalman Gain K.

• This method leverages Dask to parallelize the filter process over multiple time steps.

run_filter(measurements: Array) → tuple

Apply the Kalman Filter on measurements to compute state estimates and residuals.

Parameters:

measurements (da.Array, shape (n_timesteps, n_observations)) – Observed measurements over time.

Returns:

• state_estimates (da.Array, shape (n_timesteps, n_features)) – Estimated states over the measurement timeline.

• residuals (da.Array, shape (n_timesteps, n_observations)) – Difference between observed and predicted measurements (innovations).

Notes

• This function is used by parameter estimation strategies to compute residuals.

• Residuals are used for adaptive filtering and cross-validation strategies.

TFilterPy.state_estimation.nonlinear_filters module

class TFilterPy.state_estimation.nonlinear_filters.DaskNonLinearKalmanFilter(estimation_strategy: str = 'residual_analysis')

Bases: ParameterEstimator

TFilterPy.state_estimation.particle_filters module

class TFilterPy.state_estimation.particle_filters.DaskParticleFilter(estimation_strategy: str = 'residual_analysis')

Bases: ParameterEstimator

Module contents

State Estimation submodule containing implementations for Kalman Filters, Nonlinear Filters, and Particle Filters.

class TFilterPy.state_estimation.DaskKalmanFilter(state_transition_matrix: ndarray | Array, observation_matrix: ndarray | Array, process_noise_cov: ndarray | Array, observation_noise_cov: ndarray | Array, initial_state: ndarray | Array, initial_covariance: ndarray | Array, estimation_strategy: str = 'residual_analysis')

Bases: ParameterEstimator

Dask-based implementation of a Kalman Filter that supports distributed computing for large datasets. This class extends the ParameterEstimator to estimate the process noise covariance (Q) and observation noise covariance (R) while applying Kalman Filtering on incoming measurements.

The Kalman Filter is a recursive algorithm that estimates the state of a linear dynamic system from noisy measurements. This implementation leverages Dask to scale computations across distributed systems.

Parameters:

• state_transition_matrix (np.ndarray or da.Array, shape (n_features, n_features)) – The state transition matrix (F) representing how the system evolves between states.

• observation_matrix (np.ndarray or da.Array, shape (n_observations, n_features)) – The observation matrix (H) that maps the true state space into the observed space.

• process_noise_cov (np.ndarray or da.Array, shape (n_features, n_features)) – Covariance matrix (Q) representing the process noise.

• observation_noise_cov (np.ndarray or da.Array, shape (n_observations, n_observations)) – Covariance matrix (R) representing the observation noise.

• initial_state (np.ndarray or da.Array, shape (n_features,)) – Initial state vector (x0) of the system.

• initial_covariance (np.ndarray or da.Array, shape (n_features, n_features)) – Initial state covariance matrix (P0), representing initial uncertainty in the state.

• estimation_strategy (str, optional, default="residual_analysis") – The strategy for estimating Q and R. Can be one of: - “residual_analysis” - “mle” - “cross_validation” - “adaptive_filtering”

Raises:

ValueError – If matrix dimensions do not conform to Kalman Filter requirements.

References

Welch, G., & Bishop, G. (1995). An Introduction to the Kalman Filter.

estimate_parameters(measurements: Array) → tuple

Estimate process (Q) and observation (R) noise covariances using the specified strategy.

Parameters:

measurements (da.Array, shape (n_timesteps, n_observations)) – Observed measurements over time.

Returns:

• Q (da.Array, shape (n_features, n_features)) – Estimated process noise covariance matrix.

• R (da.Array, shape (n_features, n_features)) – Estimated observation noise covariance matrix.

Notes

• This method calls the appropriate estimation strategy from the parent class.

• The available strategies include residual analysis, MLE, cross-validation, and adaptive filtering.

fit(X: ndarray | Array) → DaskKalmanFilter

Prepare the Kalman Filter by storing the measurements as a Dask array.

Parameters:

X (np.ndarray or da.Array, shape (n_timesteps, n_observations)) – Array of measurements over time.

Returns:

self – The fitted Kalman Filter instance.

Return type:

DaskKalmanFilter

Raises:

ValueError – If the input measurements are not 2-dimensional.

predict() → Array

Perform state estimation over all time steps using the Kalman Filter algorithm.

This method constructs a Dask computation graph to process the entire measurement sequence in parallel using delayed execution.

Returns:

state_estimates – The estimated state at each time step.

Return type:

da.Array, shape (n_timesteps, n_features)

Notes

• The Kalman Filter operates in two steps: prediction and update.

• Predictions are made using the state transition matrix F.

• Updates are performed using the observation matrix H and Kalman Gain K.

• This method leverages Dask to parallelize the filter process over multiple time steps.

run_filter(measurements: Array) → tuple

Apply the Kalman Filter on measurements to compute state estimates and residuals.

Parameters:

measurements (da.Array, shape (n_timesteps, n_observations)) – Observed measurements over time.

Returns:

• state_estimates (da.Array, shape (n_timesteps, n_features)) – Estimated states over the measurement timeline.

• residuals (da.Array, shape (n_timesteps, n_observations)) – Difference between observed and predicted measurements (innovations).

Notes

• This function is used by parameter estimation strategies to compute residuals.

• Residuals are used for adaptive filtering and cross-validation strategies.

class TFilterPy.state_estimation.DaskNonLinearKalmanFilter(estimation_strategy: str = 'residual_analysis')

Bases: ParameterEstimator

class TFilterPy.state_estimation.DaskParticleFilter(estimation_strategy: str = 'residual_analysis')

Bases: ParameterEstimator