Kalman

class paleokalmag.Kalman

Bases: object

A (somewhat) abstract Kalman-filter class, that can be used as a boilerplate.

Attributes Summary

cov	The posterior covariance of the model.
cov_inf	The stationary state covariance matrix.
evaluated	Wether the model has been evaluated.
knots	The knot points of the filter, i.e. at which points the posterior mean and covariance are stored.
mean	The posterior mean of the model.
prior_cov	The a priori covariance matrix.
prior_mean	The a priori mean vector.
smoothed	Wether the model has been smoothed.

Methods Summary

F(delta_t)	Return the forward operator for a given delta_t.
backward([quiet])	Smooth the posterior model in-place.
correct(mean, cov, data[, est])	Perform a Kalman-filter correction step for the given data.
forward(data[, t_start, delta_t, t_end, ...])	Run the Kalman-filter (forward step).
predict(mean, cov, delta_t)	Perform a Kalman-filter prediction step of length delta_t.
sample([n_samps, quiet])	Returns an ensemble of n_samps samples from the posterior.
sample_prior(ts[, n_samps, quiet])	Returns an ensemble of n_samps samples from the prior.
smooth(z_k1d1, C_k1d1, z_kd, C_kd, delta_t)	Perform a smoothing step of length delta_t.
update_F(delta_t)	Update the forward operator for a new delta_t.

Attributes Documentation

cov

The posterior covariance of the model. This is a big array, containing one covariance matrix for each knot of the algorithm.

Type:

array

cov_inf

The stationary state covariance matrix.

Type:

tensor

evaluated

Wether the model has been evaluated.

Type:

bool

knots

The knot points of the filter, i.e. at which points the posterior mean and covariance are stored.

Type:

array

mean

The posterior mean of the model. This is a big array, containing one mean vector for each knot of the algorithm.

Type:

array

prior_cov

The a priori covariance matrix.

Type:

tensor

prior_mean

The a priori mean vector.

Type:

tensor

smoothed

Wether the model has been smoothed.

Type:

bool

Methods Documentation

F(delta_t)

Return the forward operator for a given delta_t.

Parameters:

delta_t (float) – The temporal increment in years.

Returns:

The forward operator as a matrix.

Return type:

tensor

backward(quiet=True)

Smooth the posterior model in-place. This will re-introduce cross- correlations. Can only be used after the model has been evaluated via a call to forward.

Parameters:

quiet (bool, optional) – If False, show progress using tqdm.

abstract correct(mean, cov, data, est=False)

Perform a Kalman-filter correction step for the given data.

Parameters:

• mean (tensor) – The initial mean vector in uT.

• cov (tensor) – The initial covariance in (uT)^2.

• data (Data) – Data for the correction step.

• est (bool, optional.) – If true, calculate the marginal likelihood along the way and return it together with the corrected mean and covariance. Default is False.

Returns:

• tensor – The corrected mean.

• tensor – The corrected covariance.

forward(data, t_start=None, delta_t=None, t_end=None, output_every=1, mean=None, cov=None, quiet=True)

Run the Kalman-filter (forward step). This is, predict and correct until no more data is available. The posterior mean and covariance will be update in-place and are available after a call to this function.

Parameters:

• data (ChunkedData or DataFrame or str) – The data. If ChunkedData is passed, the following three kwargs will be ignored. If Dataframe or str is passed, ChunkedData will be constructed from those kwargs.

• t_start (float, optional.) – If a DataFrame or str is passed to data, this argument gives the initial time for the Kalman-filter in yrs. Otherwise it will be inferred from the ChunkedData. Default is None.

• delta_t (float, optional.) – If a DataFrame or str is passed to data, this argument gives the time increment for the Kalman-filter in yrs. Otherwise it will be inferred from the ChunkedData. Default is None.

• t_end (float, optional.) – If a DataFrame or str is passed to data, this argument gives the final time for the Kalman-filter in yrs. Otherwise it will be inferred from the ChunkedData. Default is None.

• output_every (int, optional) – The model will be stored every (delta_t*output_every)-years. Increase this to get a more rough model, which saves memory. Default is 1.

• mean (tensor, optional) – The initial mean vector. This can be used to “glue” the model to an existing one.

• cov (tensor, optional) – The initial covariance matrix. This can be used to “glue” the model to an existing one.

• quiet (bool, optional) – If False, show progress using tqdm.

predict(mean, cov, delta_t)

Perform a Kalman-filter prediction step of length delta_t.

Parameters:

• mean (array) – The initial mean vector in uT.

• cov (array) – The initial covariance in (uT)^2.

• delta_t (float) – The temporal increment in years.

Returns:

• array – The predicted mean.

• array – The predicted covariance.

sample(n_samps=10, quiet=True)

Returns an ensemble of n_samps samples from the posterior. The model will be smoothed along the way. Has to be run on a model that is not yet smoothed.

Parameters:

• n_samps (int, optional) – The number of samples

• quiet (bool, optional) – If False, show progress using tqdm.

Returns:

ens – An array storing the ensemble along the first dimension, i.e. each element ens[i] is a sample from the posterior.

Return type:

array

sample_prior(ts, n_samps=10, quiet=True)

Returns an ensemble of n_samps samples from the prior.

Parameters:

• ts (array or tensor) – The knot points at which the prior samples are evaluated

• n_samps (int, optional) – The number of samples

• quiet (bool, optional) – If False, show progress using tqdm.

Returns:

ens – An array storing the ensemble along the first dimension, i.e. each element ens[i] is a sample from the posterior.

Return type:

array

smooth(z_k1d1, C_k1d1, z_kd, C_kd, delta_t)

Perform a smoothing step of length delta_t.

Parameters:

• z_k1d1 (tensor) – The mean to be smoothed.

• C_k1d1 (tensor) – The covariance to be smoothed.

• z_kd (tensor) – The smoothed previous-step mean.

• C_kd (tensor) – The smoothed previous-step covariance.

• delta_t (float) – The temporal increment in years.

Returns:

• tensor – The smoothed mean.

• tensor – The smoothed covariance.

abstract update_F(delta_t)

Update the forward operator for a new delta_t.

Parameters:

delta_t (float) – The temporal increment in years.

Returns:

The forward operator as a matrix.

Return type:

tensor