CoreFieldModel

class paleokalmag.CoreFieldModel(lmax, R, gamma, alpha_dip, tau_dip, alpha_wodip, tau_wodip, rho=0.0, slope=-1)[source]

Bases: Kalman

A Kalman-filter based model for the paleomagnetic core field. It represents an AR(2) process of Gauss coefficients and inherits from Kalman. The observation functional consists of the linearized directions and intensity. See also [Baerenzung2020].

Parameters:

  • lmax (int) – The maximal spherical harmonics degree of the model.

  • R (float) – The reference radius for the kernels.

  • gamma (float) – The a priori constant axial dipole mean in uT wrt. the Earth’s surface.

  • alpha_dip (float) – The a priori dipole variance in uT wrt. R.

  • tau_dip (float) – The a priori dipole correlation length in years.

  • alpha_wodip (float) – The a priori non-dipole variance in uT wrt. R.

  • tau_wodip (float) – The a priori non-dipole correlation length in years.

  • rho (float, optional) – The residual scaling in uT.

  • slope (float, optional) – The per-degree slope of the non-dipole temporal correlations. Default is -1.

References

[Baerenzung2020]

: Baerenzung, J., Holschneider, M. Wicht, J. Lesur, V. and Sanchez, S. “The Kalmag model as a candidate for IGRF-13”, Earth, Planets, Space, vol. 72, pp. 163, 2020.

Attributes Summary

cov_inf

The stationary state covariance matrix.

prior_mean

The a priori mean vector.

Methods Summary

H(data, poe[, ret_I])

calc_residuals(data[, t_start, delta_t, ...])

Run the Kalman-filter and calculate residuals along the backward pass.

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).

reject_outliers(data[, t_start, delta_t, ...])

Run the Kalman-filter and reject outliers along the backward pass.

save(fname)

Save the current model as a .npz file that can be read by loadCoreFieldModel.

update_F([delta_t])

Update the forward operator for a new delta_t.

Attributes Documentation

cov_inf[source]
prior_mean[source]

Methods Documentation

H(data, poe, ret_I=False)[source]
calc_residuals(data, t_start=None, delta_t=None, t_end=None, mean=None, cov=None, quiet=True)[source]

Run the Kalman-filter and calculate residuals along the backward pass. The posterior mean and covariance will be updated in-place and are available after a call to this function, i.e. the model will be evaluated and smoothed.

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.

  • 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.

Returns:

  • array – An array containing the standardized declination residuals.

  • array – An array containing the standardized inclination residuals.

  • array – An array containing the standardized intensity residuals.

correct(mean, cov, data, est=False)[source]

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, data_has_base=False, quiet=True)[source]

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.

  • data_has_base (bool, optional) – Whether the data chunks contain an attribute .base with the basis functions precomputed. This can be useful if multiple models are evaluated on the same dataset and especially for hyperparameter optimization.

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

reject_outliers(data, t_start=None, delta_t=None, t_end=None, mean=None, cov=None, r_outlier=0.2, quiet=True)[source]

Run the Kalman-filter and reject outliers along the backward pass. A naive Bayes classifier is used, to decide for every record whether it is more likeli to stem from a flat distribution (outlier) or from a normal distribution (data). The posterior mean and covariance will be updated in-place and are available after a call to this function, i.e. the model will be evaluated and smoothed.

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.

  • 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.

  • r_outlier (float, optional) – The a priori likelihood for a datum to be an outlier. This can be a rough estimate of the fraction of outliers in the data. Default is 0.2 (= 20%).

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

Returns:

An array containing UID, FID and data types (D, I or F) of the records that are found to be outliers. Additionally, the estimated model mean, model and data variance are provided for further analysis.

Return type:

array

save(fname)[source]

Save the current model as a .npz file that can be read by loadCoreFieldModel.

Parameters:

fname (str) – Where to save the model.

update_F(delta_t=50)[source]

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