Kalman Filter¶
- class darts.models.filtering.kalman_filter.KalmanFilter(dim_x=1, kf=None)[source]¶
Bases:
FilteringModel,ABCThis model implements a Kalman filter over a time series.
The key method is KalmanFilter.filter(). It considers the provided time series as containing (possibly noisy) observations z obtained from a (possibly noisy) linear dynamical system with hidden state x. The function filter(series) returns a new TimeSeries describing the distribution of the output z (without noise), as inferred by the Kalman filter from sequentially observing z from series, and the dynamics of the linear system of order dim_x.
This filter also supports missing values in the observation series, in which case the underlying Kalman filter will carry on using its mean estimate.
The method KalmanFilter.fit() is used to initialize the Kalman filter by estimating the state space model of a linear dynamical system and the covariance matrices of the process and measurement noise using the N4SID algorithm.
This implementation uses Kalman from the NFourSID package. More information can be found here: https://nfoursid.readthedocs.io/en/latest/source/kalman.html.
The dimensionality of the measurements z and optional control signal (covariates) u is automatically inferred upon calling filter().
- Parameters
dim_x (int) – Size of the Kalman filter state vector.
kf (nfoursid.kalman.Kalman) – Optionally, an instance of nfoursid.kalman.Kalman. If this is provided, the parameter dim_x is ignored. This instance will be copied for every call to filter(), so the state is not carried over from one time series to another across several calls to filter(). The dimensionalities of the filter must match those of the TimeSeries used when calling filter().
Methods
filter(series[, covariates, num_samples])Sequentially applies the Kalman filter on the provided series of observations.
fit(series[, covariates, num_block_rows])Initializes the Kalman filter using the N4SID algorithm.
- filter(series, covariates=None, num_samples=1)[source]¶
Sequentially applies the Kalman filter on the provided series of observations.
- Parameters
series (TimeSeries) – The series of outputs (observations) used to infer the underlying outputs according to the specified Kalman process. This must be a deterministic series (containing one sample).
covariates (Optional[TimeSeries]) – An optional series of inputs (control signal), necessary if the Kalman filter was initialized with covariates. This must be a deterministic series (containing one sample).
num_samples (int, default: 1) – The number of samples to generate from the inferred distribution of the output z. If this is set to 1, the output is a TimeSeries containing a single sample using the mean of the distribution.
- Returns
A (stochastic) TimeSeries of the inferred output z, of the same width as the input series.
- Return type
- fit(series, covariates=None, num_block_rows=None)[source]¶
Initializes the Kalman filter using the N4SID algorithm.
- Parameters
series (TimeSeries) – The series of outputs (observations) used to infer the underlying state space model. This must be a deterministic series (containing one sample).
covariates (Optional[TimeSeries]) – An optional series of inputs (control signal) that will also be used to infer the underlying state space model. This must be a deterministic series (containing one sample).
num_block_rows (Optional[int]) – The number of block rows to use in the block Hankel matrices used in the N4SID algorithm. See the documentation of nfoursid.nfoursid.NFourSID for more information. If not provided, the dimensionality of the state space model will be used, with a maximum of 10.
- Returns
Fitted Kalman filter.
- Return type
self