RankMCovarianceModel¶

(Source code, png, hires.png, pdf)

class RankMCovarianceModel(*args)¶

Covariance function of finite rank.

Available constructors:

RankMCovarianceModel(inputDimension)

RankMCovarianceModel(variance, basis)

RankMCovarianceModel(covariance, basis)

Parameters

variancesequence of float: The marginal variances of the coefficients of the basis.
covarianceCovarianceMatrix: The covariance of the coefficients of the basis.

Notes

Let $X$ be a stochastic process defined by:

$X(\omega,\vect{t})=\sum_{i=1}^M\xi_i(\omega)\phi_i(\vect{t}), \quad \forall \omega \in \Omega, \vect{t} \in \cD$

where $(\xi_1,\dots,\xi_M)$ is a random vector of dimension $M$ and $(\phi_i)_{i=1,\dots,M}$ are the $M$ first elements of a given basis.

Its covariance function, a rank-M covariance function, is given by:

$C(\vect{s}, \vect{t}) = \sum_{i=1}^M \sum_{j=1}^M \Sigma_{ij}\phi_i(\vect{s})\Tr{\phi_j(\vect{t})}, \quad \forall (\vect{s}, \vect{t}) \in \cD$

where $\mat{\Sigma}$ is the covariance matrix of $(\xi_1,\dots,\xi_M)$ .

When $\mat{\Sigma}$ is diagonal, it reduces to:

$C(\vect{s}, \vect{t}) = \sum_{i=1}^M \sigma_i^2\phi_i(\vect{s})\Tr{\phi_i(\vect{t})}, \quad \forall (\vect{s}, \vect{t}) \in \cD$

where $\sigma_i^2$ is the variance of $\xi_i$ .

The name rank-M is here to recall that the discretization of such a model will always lead to a covariance matrix of rank at most $M$ .

Examples

>>> import openturns as ot
>>> variance = [1.0, 2.0]
>>> basis = ot.LinearBasisFactory().build()
>>> myCovarianceModel = ot.RankMCovarianceModel(variance, basis)
>>> covariance = ot.CovarianceMatrix(2, [1.0, 0.5, 0.5, 2.0])
>>> covarianceModel = ot.RankMCovarianceModel(covariance, basis)

Methods

`__call__`(*args)	Evaluate the covariance function.
`computeAsScalar`(s, t)	Compute the covariance function for scalar model.
`computeStandardRepresentative`(s, t)	Compute the standard representative function of the covariance model.
`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.
`getBasis`()	Accessor to the Basis.
`getClassName`()	Accessor to the object’s name.
`getCovariance`()	Covariance accessor.
`getFullParameter`()	Get the full parameters of the covariance function.
`getFullParameterDescription`()	Get the description full parameters of the covariance function.
`getFunctions`()	Function collection accessor.
`getId`()	Accessor to the object’s id.
`getInputDimension`()	Get the input dimension $n$ of the covariance function.
`getMarginal`(*args)	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.
`getShadowedId`()	Accessor to the object’s shadowed id.
`getVariance`()	Variance accessor.
`getVisibility`()	Accessor to the object’s visibility state.
`hasName`()	Test if the object is named.
`hasVisibleName`()	Test if the object has a distinguishable name.
`isDiagonal`()	Test whether the model is diagonal or not.
`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.
`setShadowedId`(id)	Accessor to the object’s shadowed id.
`setVisibility`(visible)	Accessor to the object’s visibility state.

__init__(*args)¶: Initialize self. See help(type(self)) for accurate signature.

computeAsScalar(s, t)¶

Compute the covariance function for scalar model.

Available usages:

computeAsScalar(s, t)

computeAsScalar(tau)

Parameters

s, tsequences of float: Multivariate index $(\vect{s}, \vect{t}) \in \cD \times \cD$
tausequence of float: 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}$ .

computeStandardRepresentative(s, t)¶

Compute the standard representative function of the covariance model.

Available usages:

computeStandardRepresentative(s, t)

computeStandardRepresentative(tau)

Parameters

s, tsequences of float: Multivariate index $(\vect{s}, \vect{t}) \in \cD \times \cD$
taufloat or sequence of float: Multivariate index $\vect{\tau} \in \cD$

Returns

rhofloat: Correlation model $\rho$

Notes

It evaluates the scalar function $\rho\left(\dfrac{\vect{s}}{\theta}, \dfrac{\vect{t}}{\theta}\right)$ or $\rho\left(\dfrac{\vect{\tau}}{\theta}\right)$ if the model is stationary.

discretize(*args)¶

Discretize the covariance function on a given mesh.

Parameters

meshOrGridMesh or RegularGrid: Mesh or time grid of size $N$ associated with the process.

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 meshOrGrid 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

meshOrGridMesh or RegularGrid: Mesh or time grid of size $N$ associated with the process.

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 meshOrGrid 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

meshOrGridMesh or RegularGrid: Mesh or time grid of size $N$ associated with the process.
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 si similar to the discretizeAndFactorize method. This method requires that OpenTURNS has been compiled with the hmat library. The method is helpfull for very large parameters (Mesh, grid, Sample) as its compress data.

discretizeHMatrix(*args)¶

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

Parameters

meshOrGridMesh or RegularGrid: Mesh or time grid of size $N$ associated with the process.
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 si similar to the discretize method. This method requires that OpenTURNS has been compiled with the hmat library. The method is helpfull for very large parameters (Mesh, grid, Sample) as its compress 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.

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.

getBasis()¶

Accessor to the Basis.

Returns

basisBasis: Basis to which the functions $(\phi_i)_{i=1,\dots,M}$ belong.

getClassName()¶

Accessor to the object’s name.

Returns

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

getCovariance()¶

Covariance accessor.

Returns

covarianceCovarianceMatrix: Covariance matrix of $(\xi_1,\dots,\xi_M)$ . Its dimension is zero if the coefficients are uncorrelated, in which case the marginal variances are given by getVariance().

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.

getFunctions()¶

Function collection accessor.

Returns

functionsFunctionCollection: The collection of functions $(\phi_i)_{i=1,\dots,M}$ defining the covariance model.

getId()¶

Accessor to the object’s id.

Returns

idint: Internal unique identifier.

getInputDimension()¶

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

Returns

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

getMarginal(*args)¶

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.

getShadowedId()¶

Accessor to the object’s shadowed id.

Returns

idint: Internal unique identifier.

getVariance()¶

Variance accessor.

Returns

variancePoint: Vector of marginal variances of $(\xi_1,\dots,\xi_M)$ . Its dimension is zero if the coefficients are correlated, in which case the covariance matrix is given by getCovariance().

getVisibility()¶

Accessor to the object’s visibility state.

Returns

visiblebool: Visibility flag.

hasName()¶

Test if the object is named.

Returns

hasNamebool: True if the name is not empty.

hasVisibleName()¶

Test if the object has a distinguishable name.

Returns

hasVisibleNamebool: True if the name is not empty and not the default one.

isDiagonal()¶

Test whether the model is diagonal or not.

Returns

isDiagonalbool: True if the model is diagonal.

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.

Parameters

activesequence of int: Indices of the active parameters.

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.

setShadowedId(id)¶

Accessor to the object’s shadowed id.

Parameters

idint: Internal unique identifier.

setVisibility(visible)¶

Accessor to the object’s visibility state.

Parameters

visiblebool: Visibility flag.

OpenTURNS

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

Previous topic

Next topic

This Page

RankMCovarianceModel¶