Modules

class tfilterspy.base_estimator.BaseEstimator(name=None)

Bases: object

Base class for all estimators in the TFilterPy package. Provides common functionality such as parameter handling and validation.

get_params(deep=True)

Get parameters of the estimator.

Parameters:

deep (bool) – If True, retrieves parameters of nested objects.

Returns:

A dictionary of parameter names mapped to their values.

Return type:

dict

set_params(**params)

Set parameters of the estimator.

Parameters:

**params – Arbitrary keyword arguments of parameters to set.

Returns:

Returns the instance itself.

Return type:

self

static to_dask_array(numpy_array, chunk_size=None)

Convert a NumPy array to a Dask array with specified chunking. If chunk_size is None, use Dask’s automatic chunking.

Parameters:

• numpy_array (np.ndarray) – Input array.

• chunk_size (int or tuple, optional) – Desired chunk size.

Returns:

Dask array version of numpy_array.

Return type:

da.Array

validate_matrices(matrices)

Validate that matrices have consistent shapes.

Parameters:

matrices (dict) – A dictionary of matrix names and their values.

Raises:

ValueError – If the matrices are inconsistent.

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

class tfilterspy.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, chunk_size: int = 64, 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 tfilterspy.state_estimation.DaskNonLinearKalmanFilter(estimation_strategy: str = 'residual_analysis')

Bases: ParameterEstimator

class tfilterspy.state_estimation.DaskParticleFilter(state_transition, observation_model, process_noise_cov, observation_noise_cov, initial_state, num_particles=1000, use_dask=True, estimation_strategy='residual_analysis')

Bases: ParameterEstimator

A multivariate, scalable particle filter using Dask. Inherits parameter estimation methods from ParameterEstimator.

estimate_state()

Step 5: State Estimation. Compute the state estimate as the weighted average of particles.

predict()

Step 2: Prediction. Propagate each particle using the state transition model plus Gaussian process noise.

resample()

Step 4: Resampling. Multinomial resampling to refocus on high-probability particles.

run_filter(measurements)

This method is required for parameter estimation routines. It should run the filter over a sequence of measurements and return both the state estimates and the residuals.

Parameters:

measurements (da.Array) – Array of measurements over time, shape (n_timesteps, n_obs).

Returns:

Filtered state estimates, shape (n_timesteps, n_state). residuals (da.Array): Residuals (measurement - predicted_measurement), same shape as measurements.

Return type:

state_estimates (da.Array)

For this simple example, we run the filter sequentially over the measurements.

step(measurement)

Step 6: Iteration. Run one full filter cycle: predict, update, resample, and state estimation.

Parameters:

measurement (np.ndarray) – The observed measurement.

Returns:

The estimated state.

Return type:

np.ndarray

update(measurement)

Step 3: Measurement Update. Update particle weights based on the likelihood of the observed measurement.

Parameters:

measurement (np.ndarray) – The observed measurement.