FractionalBrownianMotionModel

(Source code, png)

../../_images/openturns-FractionalBrownianMotionModel-1.png
class FractionalBrownianMotionModel(*args)

Multivariate fractional Brownian motion covariance function.

Available constructors:

FractionalBrownianMotionModel()

FractionalBrownianMotionModel(scale, amplitude, exponent)

FractionalBrownianMotionModel(scale, amplitude, exponent, eta, rho)

Parameters:
scalepositive float

Correlation scale between two locations.

amplitudesequence of positive floats

Standard deviations of the model \vect{\sigma}\in \Rset^d.

exponentsequence of float, 0<exponent_i<1

Hurst exponents of the model, ie homogeneity degrees of the self-similarity property.

etaSquareMatrix

Disymmetry matrix. This matrix expresses the antisymmetric part of the dependence between the components of the model. It is antisymmetric, only its strictly lower part is addressed.

rhoCorrelationMatrix

Correlation matrix. This matrix expresses the symmetric part of the dependence between the components of the model.

See also

CovarianceModel

Notes

The multivariate fractional Brownian motion model is a nonstationary covariance function of input dimension 1 defined by:

\begin{align*}
  \forall s, t\in \Rset, &\\
  C_{i,j}(s, t)=&\dfrac{\sigma_i\sigma_j}{2}\left\{\rho_{i,j}\left(\left|\dfrac{s}{\theta}\right|^{H_{ij}}+\left|\dfrac{t}{\theta}\right|^{H_{ij}}-\left|\dfrac{t-s}{\theta}\right|^{H_{ij}}\right)-\eta_{i,j}(H_{ij}-1)\left(\sgn(s)\left|\dfrac{s}{\theta}\right|^{H_{ij}}-\sgn(t)\left|\dfrac{t}{\theta}\right|^{H_{ij}}+\sgn(t-s)\left|\dfrac{t-s}{\theta}\right|^{H_{ij}}\right)\right\}
\end{align*}

for H_{ij}=H_i+H_j\neq 1 and:

\forall s, t\in \Rset, C_{i,j}(s, t)=&\dfrac{\sigma_i\sigma_j}{2}\left\{\rho_{i,j}\left(\left|\dfrac{s}{\theta}\right|+\left|\dfrac{t}{\theta}\right|-\left|\dfrac{t-s}{\theta}\right|\right)-\dfrac{\eta_{i,j}}{\theta}\left(s\log|s|-t\log|t|+(t-s)\log|t-s|\right)\right\}

for H_i + H_j=1, where H_i is the Hurst exponent of the i-th component and \sigma_i its amplitude. Note that the scale coefficient simplifies in the antisymmetric part when H_{ij}=1. The compatibility conditions between the vector of exponents, the correlation matrix and the disymmetry matrix are quite evolved, see [amblard2012].

Examples

Create a standard fractional Brownian motion covariance, corresponding to the univariate standard Brownian motion:

>>> import openturns as ot
>>> covModel = ot.FractionalBrownianMotionModel()
>>> s = 0.1
>>> t = 0.2
>>> print(covModel(s, t))
[[ 0.223607 ]]

Create an univariate fractional Brownian motion covariance:

>>> covModel2 = ot.FractionalBrownianMotionModel(0.5, 1.5, 0.25)

Create a multivariate fractional Brownian motion covariance:

>>> covModel3 = ot.FractionalBrownianMotionModel(0.5, [1.5, 1.0], [0.25, 0.6], ot.SquareMatrix([[0.0, 0.2], [-0.2, 0.0]]), ot.CorrelationMatrix([[1.0, 0.5], [0.5, 1.0]]))

Methods

__call__(*args)

Evaluate the covariance function.

computeAsScalar(*args)

Compute the covariance function for scalar model.

computeCrossCovariance(*args)

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

getEta()

Eta accessor.

getExponent()

Exponent accessor.

getFullParameter()

Get the full parameters of the covariance function.

getFullParameterDescription()

Get the description full parameters of the covariance function.

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.

getRho()

Rho accessor.

getScale()

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

getShadowedId()

Accessor to the object's shadowed id.

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.

setExponentEtaRho(exponent, eta, rho)

Multivariate parameters accessor.

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

computeCrossCovariance 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

Container of the cross covariance

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

getEta()

Eta accessor.

Returns:
eta2-d sequence of floats

Disymmetry matrix. This matrix express the antisymmetric part of the dependence between the components of the model. It is antisymmetric, only its strictly lower part is addressed.

getExponent()

Exponent accessor.

Returns:
exponentseqence of float, H_i\in(0,1)

Define the Hurst exponents of the components.

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.

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

getRho()

Rho accessor.

Returns:
rho2-d sequence of floats

Correlation matrix. This matrix express the symmetric part of the dependence between the components of the model.

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.

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.

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

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.

setExponentEtaRho(exponent, eta, rho)

Multivariate parameters accessor.

Parameters:
exponentsequence of float, H_i\in(0,1)

Define the Hurst exponents of the components.

eta2-d sequence of floats

Disymmetry matrix. This matrix express the antisymmetric part of the dependence between the components of the model. It is antisymmetric, only its strictly lower part is addressed.

rho2-d sequence of floats

Correlation matrix. This matrix express the symmetric part of the dependence between the components of the model.

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.