TensorizedCovarianceModel¶

(Source code, svg)

class TensorizedCovarianceModel(*args)¶

Multivariate covariance function defined as a tensorization of covariance models.

Parameters:

collsequence of CovarianceModel: Collection of covariance models $(C_k)_{1 \leq k \leq K}$ of dimension $d_k$ .

Methods

`activateAmplitude`(isAmplitudeActive)	Activate/deactivate the amplitude parameter(s).
`activateNuggetFactor`(isNuggetFactorActive)	Activate/deactivate the nugget factor.
`activateScale`(isScaleActive)	Activate/deactivate the scale parameter(s).
`computeAsScalar`(*args)	Compute the covariance function for scalar model.
`computeCrossCovariance`(*args)	Compute the covariance function on a given mesh.
`discretize`(*args)	Discretize the covariance function on a given mesh.
`discretizeAndFactorize`(*args)	Discretize and factorize the covariance function on a given mesh.
`discretizeAndFactorizeHMatrix`(*args)	Discretize and factorize the covariance function on a given mesh.
`discretizeHMatrix`(*args)	Discretize the covariance function on a given mesh using HMatrix result.
`discretizeRow`(vertices, p)	(TODO)
`draw`(*args)	Draw a specific component of the covariance model with input dimension 1.
`getActiveParameter`()	Accessor to the active parameter set.
`getAmplitude`()	Get the amplitude parameter $\vect{\sigma}$ of the covariance function.
`getClassName`()	Accessor to the object's name.
`getCollection`()	Covariance model collection accessor.
`getFullParameter`()	Get the full parameters of the covariance function.
`getFullParameterDescription`()	Get the description full parameters of the covariance function.
`getInputDimension`()	Get the input dimension $n$ of the covariance function.
`getMarginal`(index)	Get the ith marginal of the model.
`getName`()	Accessor to the object's name.
`getNuggetFactor`()	Accessor to the nugget factor.
`getOutputCorrelation`()	Get the spatial correlation matrix $\mat{R}$ of the covariance function.
`getOutputDimension`()	Get the dimension $d$ of the covariance function.
`getParameter`()	Get the parameters of the covariance function.
`getParameterDescription`()	Get the description of the covariance function parameters.
`getScale`()	Get the scale parameter $\vect{\theta}$ of the covariance function.
`hasName`()	Test if the object is named.
`isDiagonal`()	Test whether the model is diagonal or not.
`isParallel`()	Accessor to the parallel flag.
`isStationary`()	Test whether the model is stationary or not.
`parameterGradient`(s, t)	Compute the gradient according to the parameters.
`partialGradient`(s, t)	Compute the gradient of the covariance function.
`setActiveParameter`(active)	Accessor to the active parameter set.
`setAmplitude`(amplitude)	Set the amplitude parameter $\vect{\sigma}$ of the covariance function.
`setFullParameter`(parameter)	Set the full parameters of the covariance function.
`setName`(name)	Accessor to the object's name.
`setNuggetFactor`(nuggetFactor)	Set the nugget factor for the variance of the observation error.
`setOutputCorrelation`(correlation)	Set the spatial correlation matrix $\mat{R}$ of the covariance function.
`setParameter`(parameter)	Set the parameters of the covariance function.
`setScale`(scale)	Set the scale parameter $\vect{\theta}$ of the covariance function.

Notes

The tensorized covariance model defines a multivariate covariance model of dimension $d\geq 1$ from the tensorization of a given collection of covariance models. This allows one to create a higher dimension covariance model by combining models of smaller dimensions. The dimension of each model in the collection does not necessarily have to be equal to 1. The input dimension of each covariance model in the collection must be the same.

We consider the stochastic process $X: \Omega \times\cD \mapsto \Rset^d$ , where $\omega \in \Omega$ is an event, $\cD$ is a domain of $\Rset^n$ .

Its covariance function $C : \cD \times \cD \rightarrow \cS_d^+(\Rset)$ is defined from the collection of covariance functions $C_k: \cD \times \cD \mapsto \cS_{d_k}^+(\Rset)$ where $d_1+\dots+d_k=d$ , as follows:

$C(\vect{s}, \vect{t}) = \left( \begin{array}{cccc} C_1(\vect{s}, \vect{t}) & 0 & \dots & 0 \\ 0 & C_2(\vect{s}, \vect{t}) & 0 & \\ \dots & \dots & \ddots & \dots \\ 0 & \dots & \dots & C_K(\vect{s}, \vect{t}) \end{array} \right)$

The amplitude of the covariance function is $\Tr{\sigma} =(\Tr{\sigma}_{1}, \dots, \Tr{\sigma}_{K})$ and each model $C_k$ is parameterized by its scale $\vect{\theta}_k \in \Rset^n$ .

The method $setScale(\vect{\theta})$ updates the scale the following way. Let $\vect{\theta}_k^0=(\theta_{k,1}^0,\hdots,\theta_{k,n}^0)$ be the initial scale of the covariance model $C_k$ . After the update, $C_k$ has the scale $\vect{\theta}_k=\left(\theta_1\rho_{k,1}^0,\hdots,\theta_n\rho_{k,n}^0\right)$ where $\rho_{k,j}^0=\dfrac{\theta^0_{k,j}}{\theta^0_{1,j}}$ .

Examples

Create a tensorized covariance function from the tensorization of an absolute exponential function, a squared exponential function and an exponential function:

>>> import openturns as ot
>>> inputDimension = 2

Create the each covariance models:

>>> myCov1 = ot.AbsoluteExponential([3.0] * inputDimension)
>>> myCov2 = ot.SquaredExponential([2.0] * inputDimension)

Define the scale of the tensorized model:

>>> scale = [0.3, 0.8]

Create the tensorized model:

>>> covarianceModel = ot.TensorizedCovarianceModel([myCov1, myCov2], scale)

Fix the same scale to each model:

>>> covarianceModel.setScale([1.0] * inputDimension)

__init__(*args)¶

activateAmplitude(isAmplitudeActive)¶

Activate/deactivate the amplitude parameter(s).

In the context of Kriging, defines whether amplitude parameters should be tuned.

Parameters:

isAmplitudeActivebool: If True, the amplitude parameters are all tuned. If False, none of them is tuned.

activateNuggetFactor(isNuggetFactorActive)¶

Activate/deactivate the nugget factor.

In the context of Kriging, defines whether the nugget factor should be tuned.

Parameters:

isNuggetFactorActivebool: If True (resp. False), the nugget factor is (resp. is not) tuned.

activateScale(isScaleActive)¶

Activate/deactivate the scale parameter(s).

In the context of Kriging, defines whether scale parameters should be tuned.

Parameters:

isScaleActivebool: If True, the scale parameters are all tuned. If False, none of them is tuned.

computeAsScalar(*args)¶

Compute the covariance function for scalar model.

Available usages:

computeAsScalar(s, t)

computeAsScalar(tau)

Parameters:

s, tfloats (if $n=1$ ) or sequences of floats (any $n$ ): Multivariate index $(\vect{s}, \vect{t}) \in \cD \times \cD$
taufloat (if $n=1$ ) or sequence of floats (any $n$ ): Multivariate index $\vect{\tau} \in \cD$

Returns:

covariancefloat: Covariance.

Notes

The method makes sense only if the dimension of the process is $d=1$ . It evaluates $C(\vect{s}, \vect{t})$ .

In the second usage, the covariance model must be stationary. Then we note $C^{stat}(\vect{\tau})$ for $C(\vect{s}, \vect{s}+\vect{\tau})$ as this quantity does not depend on $\vect{s}$ .

computeCrossCovariance(*args)¶

Compute the covariance function on a given mesh.

Parameters:

firstVerticesSample or Point: Container of the first discretization vertices
secondVerticesSample or Point: Container of the second discretization vertices

Returns:

MatrixMatrix: Cross covariance matrix

Notes

This method computes a cross-covariance matrix. The cross-covariance is the evaluation of the covariance model on both firstVertices and secondVertices.

If firstVertices contains $n_1$ points and secondVertices contains $n_2$ points, the method returns an $n_1 d \times n_2 d$ matrix ( $d$ being the output dimension).

To make things easier, let us focus on the $d=1$ case. Let $\vect{x}_0, \dots, \vect{x}_{n_1-1}$ be the points of firstVertices and let $\vect{y}_0, \dots, \vect{y}_{n_2-1}$ be the points of secondVertices. The result is the $n_1 \times n_2$ matrix $\mat{M}$ such that for any nonnegative integers $i < n_1$ and $j < n_2$ , $\mat{M}_{i,j} = \mathcal{C}(\vect{x}_i, \vect{y}_j)$ .

discretize(*args)¶

Discretize the covariance function on a given mesh.

Parameters:

whereMesh or RegularGrid or Sample: Container of the discretization vertices

Returns:

covarianceMatrixCovarianceMatrix: Covariance matrix $\in \cS_{nd}^+(\Rset)$ (if the process is of dimension $d$ )

Notes

This method makes a discretization of the model on the given Mesh, RegularGrid or Sample composed of the vertices $(\vect{t}_1, \dots, \vect{t}_{N-1})$ and returns the covariance matrix:

$\mat{C}_{1,\dots,k} = \left( \begin{array}{cccc} C(\vect{t}_1, \vect{t}_1) &C(\vect{t}_1, \vect{t}_2) & \dots & C(\vect{t}_1, \vect{t}_{k}) \\ \dots & C(\vect{t}_2, \vect{t}_2) & \dots & C(\vect{t}_2, \vect{t}_{k}) \\ \dots & \dots & \dots & \dots \\ \dots & \dots & \dots & C(\vect{t}_{k}, \vect{t}_{k}) \end{array} \right)$

discretizeAndFactorize(*args)¶

Discretize and factorize the covariance function on a given mesh.

Parameters:

whereMesh or RegularGrid or Sample: Container of the discretization vertices

Returns:

CholeskyMatrixTriangularMatrix: Cholesky factor of the covariance matrix $\in \cM_{nd\times nd}(\Rset)$ (if the process is of dimension $d$ )

Notes

This method makes a discretization of the model on the given Mesh, RegularGrid or Sample composed of the vertices $(\vect{t}_1, \dots, \vect{t}_{N-1})$ thanks to the discretize() method and returns its Cholesky factor.

discretizeAndFactorizeHMatrix(*args)¶

Discretize and factorize the covariance function on a given mesh.

This uses HMatrix.

Parameters:

whereMesh or RegularGrid or Sample: Container of the discretization vertices
hmatParamHMatrixParameters: Parameter values for the HMatrix

Returns:

HMatrixHMatrix: Cholesk matrix $\in \cS_{nd}^+(\Rset)$ (if the process is of dimension $d$ ), stored in hierarchical format (H-Matrix)

Notes

This method is similar to the discretizeAndFactorize() method. This method requires that requires that OpenTURNS has been compiled with the hmat library. The method is helpful for very large parameters (Mesh, grid, Sample) because it compresses data.

discretizeHMatrix(*args)¶

Discretize the covariance function on a given mesh using HMatrix result.

Parameters:

whereMesh or RegularGrid or Sample: Container of the discretization vertices
hmatParamHMatrixParameters: Parameter values for the HMatrix

Returns:

HMatrixHMatrix: Covariance matrix $\in\cS_{nd}^+(\Rset)$ (if the process is of dimension $d$ ), stored in hierarchical format (H-Matrix)

Notes

This method is similar to the discretize() method. This method requires that OpenTURNS has been compiled with the hmat library. The method is helpful for very large parameters (Mesh, grid, Sample) because it compresses data.

discretizeRow(vertices, p)¶: (TODO)

draw(*args)¶

Draw a specific component of the covariance model with input dimension 1.

Parameters:

rowIndexint, $0 \leq rowIndex < dimension$: The row index of the component to draw. Default value is 0.
columnIndex: int, :math:`0 leq columnIndex < dimension`: The column index of the component to draw. Default value is 0.
tMinfloat: The lower bound of the range over which the model is plotted. Default value is CovarianceModel-DefaultTMin in ResourceMap.
tMaxfloat: The upper bound of the range over which the model is plotted. Default value is CovarianceModel-DefaultTMax in ResourceMap.
pointNumberint, $pointNumber \geq 2$: The discretization of the range $[tMin,tMax]$ over which the model is plotted. Default value is CovarianceModel-DefaultPointNumber in class:~openturns.ResourceMap.
asStationarybool: Flag to tell if the model has to be plotted as a stationary model, ie as a function of the lag $\tau=t-s$ if equals to True, or as a non-stationary model, ie as a function of $(s,t)$ if equals to False. Default value is True.
correlationFlagbool: Flag to tell if the model has to be plotted as a correlation function if equals to True or as a covariance function if equals to False. Default value is False.

Returns:

graphGraph: A graph containing a unique curve if asStationary=True and if the model is actually a stationary model, or containing the iso-values of the model if asStationary=False or if the model is nonstationary.

getActiveParameter()¶

Accessor to the active parameter set.

In the context of kriging, it allows one to choose which hyperparameters are tuned.

Returns:

activeIndices: Indices of the active parameters.

getAmplitude()¶

Get the amplitude parameter $\vect{\sigma}$ of the covariance function.

Returns:

amplitudePoint: The amplitude parameter $\vect{\sigma} \in \Rset^d$ of the covariance function.

getClassName()¶

Accessor to the object’s name.

Returns:

class_namestr: The object class name (object.__class__.__name__).

getCollection()¶

Covariance model collection accessor.

Returns:

collsequence of CovarianceModel: Collection of covariance models $(C_k)_{1 \leq k \leq K}$ of dimension $d_k$ .

getFullParameter()¶

Get the full parameters of the covariance function.

Returns:

parameterPoint: List the full parameter of the covariance function i.e. scale parameter $\vect{\theta} \in \Rset^n$ , the the amplitude parameter $\vect{\sigma} \in \Rset^d$ , the Spatial correlation parameter $\mat{R} \in \cS_d^+([-1,1])$ ; and potential other parameter depending on the model;

getFullParameterDescription()¶

Get the description full parameters of the covariance function.

Returns:

descriptionDescription: Description of the full parameter of the covariance function.

getInputDimension()¶

Get the input dimension $n$ of the covariance function.

Returns:

inputDimensionint: Spatial dimension $n$ of the covariance function.

getMarginal(index)¶

Get the ith marginal of the model.

Returns:

marginalint or sequence of int: index of marginal of the model.

getName()¶

Accessor to the object’s name.

Returns:

namestr: The name of the object.

getNuggetFactor()¶

Accessor to the nugget factor.

This parameter allows smooth predictions from noisy data. The nugget is added to the diagonal of the assumed training covariance (thanks to discretize) and acts as a Tikhonov regularization in the problem.

Returns:

nuggetFactorfloat: Nugget factor used to model the observation error variance.

getOutputCorrelation()¶

Get the spatial correlation matrix $\mat{R}$ of the covariance function.

Returns:

spatialCorrelationCorrelationMatrix: Correlation matrix $\mat{R} \in \cS_d^+(\Rset)$ .

getOutputDimension()¶

Get the dimension $d$ of the covariance function.

Returns:

dint: Dimension $d$ such that $C : \cD \times \cD \mapsto \cS_d^+(\Rset).$ This is the dimension of the process $X$ .

getParameter()¶

Get the parameters of the covariance function.

Returns:

parametersPoint: List of the scale parameter $\vect{\theta} \in \Rset^n$ and the amplitude parameter $\vect{\sigma} \in \Rset^d$ of the covariance function.

The other specific parameters are not included.

getParameterDescription()¶

Get the description of the covariance function parameters.

Returns:

descriptionParamDescription: Description of the components of the parameters obtained with the getParameter method..

getScale()¶

Get the scale parameter $\vect{\theta}$ of the covariance function.

Returns:

scalePoint: The scale parameter $\vect{\theta} \in \Rset^n$ used in the covariance function.

hasName()¶

Test if the object is named.

Returns:

hasNamebool: True if the name is not empty.

isDiagonal()¶

Test whether the model is diagonal or not.

Returns:

isDiagonalbool: True if the model is diagonal.

isParallel()¶

Accessor to the parallel flag.

Returns:

isParallelbool: Whether the object is considered thread-safe.

isStationary()¶

Test whether the model is stationary or not.

Returns:

isStationarybool: True if the model is stationary.

Notes

The covariance function $C$ is stationary when it is invariant by translation:

$\forall(\vect{s},\vect{t},\vect{h}) \in \cD \times \cD, & \, \quad C(\vect{s}, \vect{s}+\vect{h}) = C(\vect{t}, \vect{t}+\vect{h})$

We note $C^{stat}(\vect{\tau})$ for $C(\vect{s}, \vect{s}+\vect{\tau})$ .

parameterGradient(s, t)¶

Compute the gradient according to the parameters.

Parameters:

s, tsequences of float: Multivariate index $(\vect{s}, \vect{t}) \in \cD \times \cD$ .

Returns:

gradientMatrix: Gradient of the function according to the parameters.

partialGradient(s, t)¶

Compute the gradient of the covariance function.

Parameters:

s, tfloats or sequences of float: Multivariate index $(\vect{s}, \vect{t}) \in \cD \times \cD$ .

Returns:

gradientMatrix: Gradient of the covariance function.

setActiveParameter(active)¶

Accessor to the active parameter set.

This method defines which hyperparameters are tuned.

Parameters:

activesequence of int: Indices of the active parameters.

Notes

In order to get the position of a parameter known by its name, we have to first call the method getFullParameterDescription() and then call the method find as shown in the following example.

Examples

For example, we create a MaternModel covariance model. By default, only the scale and the amplitude parameters are active and will be estimated. We want to add the estimation of the $\nu$ parameter.

>>> import openturns as ot
>>> covModel = ot.MaternModel()

We get the default active parameters description: we can see that the $\nu$ parameter is not included in the list.

>>> covModel.getParameterDescription()
[scale_0,amplitude_0]

We now get the active parameters. The parameter $\nu$ is not in the list.

>>> active = covModel.getActiveParameter()
>>> print(active)
[0,2]

We want to search the index associated to the parameter $\nu$ in the full list of the parameters indices.

>>> activeDesc = covModel.getFullParameterDescription()
>>> print(activeDesc)
[scale_0,nuggetFactor,amplitude_0,nu]
>>> index = activeDesc.find('nu')
>>> print(index)
3

Now, we add the index of $\nu$ in the initial list of active parameters. We sort the active indices by increasing order. Then we update the list of the active parameters.

>>> active = covModel.getActiveParameter()
>>> active.add(index)
>>> covModel.setActiveParameter(sorted(active))

Check that the parameter $\nu$ is in the active parameters list!

>>> covModel.getActiveParameter()
[0,2,3]

>>> covModel.getFullParameterDescription()
[scale_0,nuggetFactor,amplitude_0,nu]

setAmplitude(amplitude)¶

Set the amplitude parameter $\vect{\sigma}$ of the covariance function.

Parameters:

amplitudePoint: The amplitude parameter $\vect{\sigma} \in \Rset^d$ to be used in the covariance function. Its size must be equal to the dimension of the covariance function.

setFullParameter(parameter)¶

Set the full parameters of the covariance function.

Parameters:

parameterPoint

List the full parameter of the covariance function i.e. scale parameter $\vect{\theta} \in \Rset^n$ , the the amplitude parameter $\vect{\sigma} \in \Rset^d$ , the Spatial correlation parameter $\mat{R} \in \cS_d^+([-1,1])$ ; and potential other parameter depending on the model;

Must be at least of dimension $n+\frac{d(d+1)}{2}$ .

setName(name)¶

Accessor to the object’s name.

Parameters:

namestr: The name of the object.

setNuggetFactor(nuggetFactor)¶

Set the nugget factor for the variance of the observation error.

Acts on the discretized covariance matrix.

Parameters:

nuggetFactorfloat: nugget factor to be used to model the variance of the observation error.

setOutputCorrelation(correlation)¶

Set the spatial correlation matrix $\mat{R}$ of the covariance function.

Parameters:

spatialCorrelationCorrelationMatrix: Correlation matrix $\mat{R} \in \cS_d^+([-1,1])$ .

setParameter(parameter)¶

Set the parameters of the covariance function.

Parameters:

parametersPoint

List of the scale parameter $\vect{\theta} \in \Rset^n$ and the amplitude parameter $\vect{\sigma} \in \Rset^d$ of the covariance function.

Must be of dimension $n+d$ .

setScale(scale)¶

Set the scale parameter $\vect{\theta}$ of the covariance function.

Parameters:

scalePoint: The scale parameter $\vect{\theta} \in \Rset^n$ to be used in the covariance function. Its size must be equal to the input dimension of the covariance function.

Examples using the class¶

Example of multi output Gaussian Process Regression on the fire satellite model

OpenTURNS

An Open source initiative for the Treatment of Uncertainties, Risks'N Statistics

Table of Contents

Previous topic

Next topic

This Page

TensorizedCovarianceModel¶

Examples using the class¶