models

This package provides tools to define covariance models. A few pre-defined covariance models are made available. To define your own covariance model, you need to inherit from CovarianceModel or CompoundCovarianceModel. In both cases, you need to define the _compute method, which will expect a lag array with shape (ndim, n1, ..., nk, 1) where ndim is the number of spatio-temporal dimensions, n1, ..., nk, can have any shape. The trailing 1 is not needed in calls to the model as it is automatically added by the inherited call method. More specifically, the trailing dimension is used to adress the case where the user sets each parameter to be array-valued rather than scalar. This allows parallel evaluation of the likelihood for several model parameters. This feature can be ignored by new users of the package.

Within the _compute method of a CompoundModel, when evaluating children models at lags, you should not use their call method but rather their _compute method (see e.g. SumModel).

For a univariate model, if we pass a lags array with shape (ndim, n1, ..., nk), we expect the covariance model to return an array with shape (n1, ..., nk).

For a bivariate model, we expect the covariance model to return an array with shape (n1, ..., nk, 2, 2).

`base`

`ModelParameter(*args, **kwargs)`

Bases: Parameter

Class used to represent a covariance model's parameter. When writing a new model, any parameter should be of this type. See for instance the models defined in the univariate module.

Attributes:

Name	Type	Description
`bounds`	`tuple[float, float]`	Range of possible parameter values. Used by the optimizers during inference.
`default`	`float`	Default value of the parameter.
`free`	`bool`	True if the parameter is free, i.e. can be modified. By default all parameters are free. However one can fix a model parameter using the fix_parameter method of ModelInterface. In particular, this is relevant for optimization: the optimizers will only work with the free parameters.

`free: bool` `property`

true is the model parameter is free, i.e. not readonly and not constant

`ModelInterface`

Bases: Parameterized

Class defining the general interface for covariance models.

`free_parameters` `property`

free parameters of the model - not deep

`n_free_parameters` `property`

number of free parameters of the model - not deep

`call(lags: xp.ndarray)` `abstractmethod`

Evaluate the covariance model at the passed lags.

Parameters:

Name	Type	Description	Default
`lags`	`ndarray`	array of lags. Shape (ndim, n1, ..., nk) where ndim is the number of spatial dimensions.	required

Returns:

Type Description

cov

covariances at the passed lags. The shape of cov will depend on scalar vs multivariate model whether vectorized models are used. This is summarized by the table below, where \(p\) denotes the number of variates of the random field (\(p=1\) for a scalar random field), and \(m\) denotes the number of models in the case of vectorized models.

cov shape	p=1	p > 1
single model	(n1, ..., nk)	(n1, ..., nk, p, p)
vectorized model	(n1, ... nk, m)	(n1, ..., nk, m, p, p)

`n_free_parameters_deep()`

number of free parameters, recursive

`update_free_parameters(param_values: xp.ndarray)` `abstractmethod`

Update free parameters of the model recursively from array values. Useful for numerical optimization.

`free_parameter_values_to_array_deep()` `abstractmethod`

provide the free parameter values. Useful to pass to the x0 parameter of a numerical optimizer

`free_parameter_bounds_to_list_deep()` `abstractmethod`

provide the free parameter bounds as a list. Useful to pass to bounds parameter of a numerical optimizer

`set_param_bounds(bounds: dict[str, tuple[float, float]])`

set parameter bounds according to dictionary of parameter_name: parameter_bounds

`_set_param_bounds(param_name, bounds)`

set parameter bounds for a single parameter. Checks that we make the bounds more restrictive

`link_param(param_name, other_param)`

link a parameter to another. The former becomes readonly, and therefore is not free anymore

`gradient(lags: xp.ndarray, params: list[ModelParameter]) -> xp.ndarray`

Compute the gradient of the model with respect to the passed parameters

Parameters:

Name	Type	Description	Default
`lags`	`ndarray`	array of lags. Shape (d, n1, ..., nk)	required
`params`	`list[ModelParameter]`	parameters for which we require the derivative	required

Returns:

Type Description

gradient

array of gradient w.r.t. parameters in params. The shape depends on scalar versus multivariate random field model and on unique versus vectorized model. This is summarized by the table below, where \(p\) denotes the number of variates of the random field (\(p=1\) for a scalar random field), and \(m\) denotes the number of models in the case of vectorized models. \(g\) denotes the number of parameters in params, those for which we request the gradient.

cov shape	p=1	p > 1
single model	(n1, ..., nk, g)	(n1, ..., nk, g, p, p)
vectorized model	Not tested	Not tested

`cov_mat_x1_x2(x1: xp.ndarray, x2: xp.ndarray = None) -> xp.ndarray`

Compute the covariance matrix between between points in x1 and points in x2.

Parameters:

Name	Type	Description	Default
`x1`	`ndarray`	shape (n1, d), first set of locations	required
`x2`	`ndarray`	shape (n2, d), second set of locations	`None`

Returns:

Type	Description
`covmat`	shape (n1, n2), covariance matrix

`predict(x_obs: xp.ndarray, y_obs: xp.ndarray, x_pred: xp.ndarray, return_variance: bool = False)`

Compute conditional mean at a set of locations x_pred given values y_obs observed at x_obs.

Parameters:

Name	Type	Description	Default
`x_obs`	`ndarray`	shape (n_obs, d), array of locations where observations are made	required
`y_obs`	`ndarray`	shape (n_obs, 1), observed values	required
`x_pred`	`ndarray`	shape (n_pred, d), array of locations where predicted values are requested	required

Returns:

Type	Description
`y_pred`	shape (n_pred, 1), array of predicted values

`CovarianceModel`

Bases: ModelInterface

Class to define low-level covariance modes (e.g. exponential, squared exponential).

`update_free_parameters(param_values: xp.ndarray)`

In the case of a simple model, we simply update the free parameters

`CompoundModel(children: list[ModelInterface], *args, **kwargs)`

Bases: ModelInterface

Class that permits to combine several covariance models to define a new covariance model. For instance, this allows to define a sum covariance model, or a space-time covariance model that uses a spatial component and a temporal component.

Parameters:

Name	Type	Description	Default
`children`	`list[ModelInterface]`	list of children covariance models	required

`SumModel(*args, **kwargs)`

Bases: CompoundModel

Implements a covariance model defined as the sum of two covariance models.

Examples:

>>> from debiased_spatial_whittle.models.univariate import SquaredExponentialModel, ExponentialModel
>>> model_1 = SquaredExponentialModel(rho=32)
>>> model_2 = ExponentialModel(rho=5)
>>> model = model_1 + model_2
>>> model.free_parameter_values_to_array_deep()
array([32.,  1.,  5.,  1.])
>>> model_1.rho = 30
>>> model.free_parameter_values_to_array_deep()
array([30.,  1.,  5.,  1.])

`_parameterized_repr_html(p, open)`

HTML representation for a Parameterized object

`univariate`

`ExponentialModel`

Bases: CovarianceModel

Implements the Exponential covariance model.

Attributes:

Name	Type	Description
`rho`	`ModelParameter`	length scale parameter
`sigma`	`ModelParameter`	amplitude parameter

Examples:

>>> model = ExponentialModel(rho=5, sigma=1.41)
>>> model(xp.array([[0., 1.], [0., 0.]]))
array([1.9881    , 1.62771861])
>>> model.rho = 3
>>> model.rho
3
>>> model.param.rho.bounds
(0, inf)
>>> model.free_parameters
['rho', 'sigma']
>>> model.fix_parameter("rho")
>>> model.free_parameters
['sigma']

`SquaredExponentialModel`

Bases: CovarianceModel

Implements the Squared Exponential covariance model, or Gaussian covariance model.

Attributes:

Name	Type	Description
`rho`	`ModelParameter`	length scale parameter
`sigma`	`ModelParameter`	amplitude parameter

Examples:

>>> model = SquaredExponentialModel(rho=5, sigma=1.41)
>>> model(xp.array([[0., 1.], [0., 0.]]))
array([1.9881    , 1.94873298])

`_gradient(lags: xp.ndarray)`

Provides the derivatives of the covariance model evaluated at the passed lags with respect to the model's parameters.

Examples:

>>> model = SquaredExponentialModel(rho=2, sigma=1.41)
>>> model.gradient(xp.array([[0, 0, 1, 1], [0, 1, 0, 1]]), [model.param.rho, model.param.sigma])
array([[0.        , 2.82      ],
       [0.21931151, 2.48864127],
       [0.21931151, 2.48864127],
       [0.38708346, 2.19621821]])

`Matern32Model(*args, **kwargs)`

Bases: CovarianceModel

Implements the Matern Covariance kernel with slope parameter 3/2.

Attributes:

Name	Type	Description
`rho`	`ModelParameter`	length scale parameter of the kernel
`sigma`	`ModelParameter`	amplitude parameter of the kernel

Examples:

>>> model = Matern32Model(rho=5, sigma=1)

`Matern52Model(*args, **kwargs)`

Bases: CovarianceModel

Implements the Matern Covariance kernel with slope parameter 5/2.

Attributes:

Name	Type	Description
`rho`	`ModelParameter`	length scale parameter of the kernel
`sigma`	`ModelParameter`	amplitude parameter of the kernel

Examples:

>>> model = Matern52Model(rho=10)
>>> model = Matern52Model(rho=10, sigma=0.9)

`RationalQuadraticModel(*args, **kwargs)`

Bases: CovarianceModel

Implements the Rational Quadratic Covariance Kernel.

Attributes:

Name	Type	Description
`rho`	`ModelParameter`	length scale parameter of the kernel
`alpha`	`ModelParameter`	alpha parameter of the kernel
`sigma`	`ModelParameter`	amplitude parameter of the kernel

Examples:

>>> model = RationalQuadraticModel(rho=20, alpha=1.5)

`NuggetModel(model, *args, **kwargs)`

Bases: CompoundModel

Allows to add a nugget to a base covariance model. The nugget parameter is between 0 and 1 and characterises the proportion of the variance due to the nugget. For instance, if the base model has variance 2, using a Nugget model on top with nugget parameter 0.1 will result in a model whose variance is still 2, but with a nugget of 0.2.

Properties

nugget: ModelParameter Proportion of variance explained by the nugget

Examples:

>>> model = SquaredExponentialModel(rho=12, sigma=1)
>>> model(xp.array([[0., 1., 2.]]))
array([1.        , 0.9965338 , 0.98620712])
>>> model = NuggetModel(model, nugget=0.1)
>>> model(xp.array([[0., 1., 2.]]))
array([1.        , 0.89688042, 0.88758641])

`AnisotropicModel(base_model: CovarianceModel, *args, **kwargs)`

Bases: CompoundModel

Allows to define an anisotropic model based on a base isotropic model via a scaling + rotation transform. Dimension 2.

Attributes:

Name	Type	Description
`base_model`	`ModelInterface`	Underlying covariance modelCovariance model
`eta`	`ModelParameter`	Scaling factor
`phi`	`ModelParameter`	Rotation angle

Examples:

>>> base_model = SquaredExponentialModel(rho=10)
>>> model = AnisotropicModel(base_model, eta=1.5, phi=xp.pi / 3)

`bivariate`

`BivariateUniformCorrelation(base_model: CovarianceModel, *args, **kwargs)`

Bases: CompoundModel

This class defines the simple case of a bivariate covariance model where a given univariate covariance model is used in parallel to a uniform correlation parameter.

Attributes:

Name	Type	Description
`base_model`	`CovarianceModel`	Base univariate covariance model
`r`	`Parameter`	Correlation parameter, float between -1 and 1
`f`	`Parameter`	Amplitude ratio, float, positive

Examples:

>>> from debiased_spatial_whittle.models.univariate import ExponentialModel
>>> base_model = ExponentialModel(rho=12.)
>>> bivariate_model = BivariateUniformCorrelation(base_model, r=0.3, f=2.)

`_compute(lags: xp.ndarray)`

Evaluates the covariance model at the passed lags. Since the model is bivariate, the returned array has two extra dimensions compared to the array lags, both of size two.

Parameters:

Name	Type	Description	Default
`lags`	`ndarray`	lag array with shape (ndim, m1, m2, ..., mk)	required

Returns:

Type	Description
`Covariance values with shape (m1, m2, ..., mk, 2, 2)`

`_gradient(x: xp.ndarray)`

Parameters:

Name	Type	Description	Default
`x`	`ndarray`	shape (ndim, m1, ..., mk)	required

Returns:

Type	Description
`gradient`	shape (m1, ..., mk, 2, 2, p + 2) where p is the number of parameters of the base model.

`spectral`

`SpectralModel`

Bases: CovarianceModel

Base class to define a covariance model from a spectral density function.

`spectral_density(frequencies: xp.ndarray) -> xp.ndarray` `abstractmethod`

Abstract method that must provide the spectral density function evaluated at the passed frequencies

Parameters:

Name	Type	Description	Default
`frequencies`	`ndarray`	shape (n1, ..., nk, d)	required

Returns:

Type	Description
`sdf`	shape (n1, ..., nk). Values of the spectral density function

`call(lags: xp.ndarray)`

Compute an approximation to the covariance function evaluated at the passed lags based on the spectral density function.

Currently, not implemented: we only provide an implementation in the case where the lags are those of a grid, cf method call_on_rectangular_grid.

Parameters:

Name	Type	Description	Default
`lags`	`ndarray`	shape (d, n1, n2, ..., nk)	required

Returns:

Type	Description
`cov`	shape (n1, ..., nk). Approximate values of the covariance function

`SpectralMatern(*args, **kwargs)`

Bases: SpectralModel

Implement a spectral domain version of the Matern, which is approximate but much more efficient than the spatial domain version for non half integer values of the slope parameter.

`spectral_density(frequencies: xp.ndarray) -> xp.ndarray`

Implements the spectral density of the Matern.

Parameters:

Name	Type	Description	Default
`frequencies`	`ndarray`	shape (n1, ..., nk, d).	required

models

base

ModelParameter(*args, **kwargs)

free: bool property

ModelInterface

free_parameters property

n_free_parameters property

__call__(lags: xp.ndarray) abstractmethod

n_free_parameters_deep()

update_free_parameters(param_values: xp.ndarray) abstractmethod

free_parameter_values_to_array_deep() abstractmethod

free_parameter_bounds_to_list_deep() abstractmethod

set_param_bounds(bounds: dict[str, tuple[float, float]])

_set_param_bounds(param_name, bounds)

link_param(param_name, other_param)

gradient(lags: xp.ndarray, params: list[ModelParameter]) -> xp.ndarray

cov_mat_x1_x2(x1: xp.ndarray, x2: xp.ndarray = None) -> xp.ndarray

predict(x_obs: xp.ndarray, y_obs: xp.ndarray, x_pred: xp.ndarray, return_variance: bool = False)

CovarianceModel

update_free_parameters(param_values: xp.ndarray)

CompoundModel(children: list[ModelInterface], *args, **kwargs)

SumModel(*args, **kwargs)

_parameterized_repr_html(p, open)

univariate

ExponentialModel

SquaredExponentialModel

_gradient(lags: xp.ndarray)

Matern32Model(*args, **kwargs)

Matern52Model(*args, **kwargs)

RationalQuadraticModel(*args, **kwargs)

NuggetModel(model, *args, **kwargs)

AnisotropicModel(base_model: CovarianceModel, *args, **kwargs)

bivariate

BivariateUniformCorrelation(base_model: CovarianceModel, *args, **kwargs)

_compute(lags: xp.ndarray)

_gradient(x: xp.ndarray)

spectral

SpectralModel

spectral_density(frequencies: xp.ndarray) -> xp.ndarray abstractmethod

__call__(lags: xp.ndarray)

SpectralMatern(*args, **kwargs)

spectral_density(frequencies: xp.ndarray) -> xp.ndarray

`base`

`ModelParameter(*args, **kwargs)`

`free: bool` `property`

`ModelInterface`

`free_parameters` `property`

`n_free_parameters` `property`

`call(lags: xp.ndarray)` `abstractmethod`

`n_free_parameters_deep()`

`update_free_parameters(param_values: xp.ndarray)` `abstractmethod`

`free_parameter_values_to_array_deep()` `abstractmethod`

`free_parameter_bounds_to_list_deep()` `abstractmethod`

`set_param_bounds(bounds: dict[str, tuple[float, float]])`

`_set_param_bounds(param_name, bounds)`

`link_param(param_name, other_param)`

`gradient(lags: xp.ndarray, params: list[ModelParameter]) -> xp.ndarray`

`cov_mat_x1_x2(x1: xp.ndarray, x2: xp.ndarray = None) -> xp.ndarray`

`predict(x_obs: xp.ndarray, y_obs: xp.ndarray, x_pred: xp.ndarray, return_variance: bool = False)`

`CovarianceModel`

`update_free_parameters(param_values: xp.ndarray)`

`CompoundModel(children: list[ModelInterface], *args, **kwargs)`

`SumModel(*args, **kwargs)`

`_parameterized_repr_html(p, open)`

`univariate`

`ExponentialModel`

`SquaredExponentialModel`

`_gradient(lags: xp.ndarray)`

`Matern32Model(*args, **kwargs)`

`Matern52Model(*args, **kwargs)`

`RationalQuadraticModel(*args, **kwargs)`

`NuggetModel(model, *args, **kwargs)`

`AnisotropicModel(base_model: CovarianceModel, *args, **kwargs)`

`bivariate`

`BivariateUniformCorrelation(base_model: CovarianceModel, *args, **kwargs)`

`_compute(lags: xp.ndarray)`

`_gradient(x: xp.ndarray)`

`spectral`

`SpectralModel`

`spectral_density(frequencies: xp.ndarray) -> xp.ndarray` `abstractmethod`

`call(lags: xp.ndarray)`

`SpectralMatern(*args, **kwargs)`

`spectral_density(frequencies: xp.ndarray) -> xp.ndarray`