BoxCoxTransform

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

../../_images/BoxCoxTransform.png
class BoxCoxTransform(*args)

BoxCox transformation.

Available constructors:

BoxCoxTransform(lambdaVect, shiftVect = [0])

BoxCoxTransform(lambda, shift=0)

Parameters:

lambdaVect : sequence of float

The (\lambda_1, \dots, \lambda_d) parameter.

shiftVect : sequence of float

The (\alpha_1, \dots, \alpha_d) parameter.

Default is (\alpha_1, \dots, \alpha_d)=(0, \dots, 0).

lambda : float

The \lambda parameter in the univariate case.

shift : float

The \alpha parameter in the univariate case.

Default is \alpha = 0.

Notes

The Box Cox transformation h_{\vect{\lambda}, \vect{\alpha}}: \Rset^d \rightarrow \Rset^d writes for each component h_{\lambda_i, \alpha_i}: \Rset \rightarrow \Rset:

h_{\lambda_i, \alpha_i} (x)= 
\left\{
\begin{array}{ll}
\dfrac{(x+\alpha_i)^{\lambda_i}-1}{\lambda} & \lambda_i \neq 0 \\
\log(x+\alpha_i)                        & \lambda_i = 0
\end{array}
\right.

for all x+\alpha_i >0.

The inverse Box Cox transformation writes:

\begin{array}{lcl}
  h_{\lambda_i, \alpha_i}^{-1}(y) & = &
  \left\{
  \begin{array}{ll}
\displaystyle (\lambda_i y + 1)^{\frac{1}{\lambda_i}} - \alpha_i & \lambda_i \neq 0 \\
\displaystyle \exp(y) - \alpha_i                         & \lambda_i = 0
  \end{array}
  \right.
\end{array}

Examples

Create a Box Cox tranformation:

>>> import openturns as ot
>>> myLambda = 0.1
>>> myBoxCox = ot.BoxCoxTransform(myLambda)

Estimate a transformation from a sample:

>>> mySample = ot.Exponential(2).getSample(100)
>>> myModelTransform = ot.BoxCoxFactory().build(mySample)

Apply ot to the sample:

>>> myNormalSample = myModelTransform(mySample)
>>> hist = ot.HistogramFactory().build(myNormalSample)
>>> graph = hist.drawPDF()

Apply it to a field:

>>> myIndices= ot.Indices([10,5])
>>> myMesher=ot.IntervalMesher(myIndices)
>>> myInterval = ot.Interval([0.0, 0.0], [2.0, 1.0])
>>> myMesh=myMesher.build(myInterval)
>>> amplitude=[1.0]
>>> scale=[0.2, 0.2]
>>> myCovModel=ot.ExponentialModel(scale, amplitude)
>>> myXproc=ot.TemporalNormalProcess(myCovModel, myMesh)
>>> g = ot.NumericalMathFunction(['x1'],  ['exp(x1)'])
>>> myDynTransform = ot.SpatialFunction(g, 2)
>>> myXtProcess = ot.CompositeProcess(myDynTransform, myXproc)
>>> myField = myXtProcess.getRealization()
>>> myModelTransform = ot.BoxCoxFactory().build(myField)
>>> myStabilizedField = myModelTransform(myField)
>>> marginal = ot.HistogramFactory().build(myStabilizedField.getValues())
>>> graph2 = marginal.drawPDF()

Methods

GetValidConstants() Return the list of valid constants.
GetValidFunctions() Return the list of valid functions.
GetValidOperators() Return the list of valid operators.
__call__(*args)
addCacheContent(inSample, outSample) Add input numerical points and associated output to the cache.
clearCache() Empty the content of the cache.
clearHistory() Empty the content of the history.
disableCache() Disable the cache mechanism.
disableHistory() Disable the history mechanism.
draw(*args) Draw the output of function as a Graph.
enableCache() Enable the cache mechanism.
enableHistory() Enable the history mechanism.
getCacheHits() Accessor to the number of computations saved thanks to the cache mecanism.
getCacheInput() Accessor to all the input numerical points stored in the cache mecanism.
getCacheOutput() Accessor to all the output numerical points stored in the cache mecanism.
getCallsNumber() Accessor to the number of times the function has been called.
getClassName() Accessor to the object’s name.
getDescription() Accessor to the description of the inputs and outputs.
getEvaluation() Accessor to the evaluation function.
getEvaluationCallsNumber() Accessor to the number of times the function has been called.
getGradient() Accessor to the gradient function.
getGradientCallsNumber() Accessor to the number of times the gradient of the function has been called.
getHessian() Accessor to the hessian function.
getHessianCallsNumber() Accessor to the number of times the hessian of the function has been called.
getHistoryInput() Accessor to the history of the input values.
getHistoryOutput() Accessor to the history of the output values.
getId() Accessor to the object’s id.
getImplementation(*args) Accessor to the underlying implementation.
getInputDescription() Accessor to the description of the inputs.
getInputDimension() Accessor to the number of the inputs.
getInputParameterHistory() Accessor to the history of the input parameter values.
getInputPointHistory() Accessor to the history of the input point values.
getInverse() Accessor to the inverse Box Cox transformation.
getLambda() Accessor to the \vect{\lambda} parameter.
getMarginal(*args) Accessor to marginal.
getName() Accessor to the object’s name.
getOutputDescription() Accessor to the description of the outputs.
getOutputDimension() Accessor to the number of the outputs.
getParameter() Accessor to the parameter values.
getParameterDescription() Accessor to the parameter description.
getParameterDimension() Accessor to the dimension of the parameter.
getShift() Accessor to the \vect{\alpha} parameter.
gradient(*args) Return the Jacobian transposed matrix of the function at a point.
hessian(*args) Return the hessian of the function at a point.
isCacheEnabled() Test whether the cache mechanism is enabled or not.
isHistoryEnabled() Test whether the history mechanism is enabled or not.
parameterGradient(*args) Accessor to the gradient against the parameter.
setDescription(description) Accessor to the description of the inputs and outputs.
setEvaluation(evaluation) Accessor to the evaluation function.
setGradient(gradient) Accessor to the gradient function.
setHessian(hessian) Accessor to the hessian function.
setName(name) Accessor to the object’s name.
setParameter(parameter) Accessor to the parameter values.
setParameterDescription(description) Accessor to the parameter description.
__init__(*args)
GetValidConstants()

Return the list of valid constants.

Returns:

list_constants : Description

List of the constants we can use within OpenTURNS.

Examples

>>> import openturns as ot
>>> print(ot.NumericalMathFunction.GetValidConstants()[0])
_e -> Euler's constant (2.71828...)
GetValidFunctions()

Return the list of valid functions.

Returns:

list_functions : Description

List of the functions we can use within OpenTURNS.

Examples

>>> import openturns as ot
>>> print(ot.NumericalMathFunction.GetValidFunctions()[0])
sin(arg) -> sine function
GetValidOperators()

Return the list of valid operators.

Returns:

list_operators : Description

List of the operators we can use within OpenTURNS.

Examples

>>> import openturns as ot
>>> print(ot.NumericalMathFunction.GetValidOperators()[0])
= -> assignement, can only be applied to variable names (priority -1)
addCacheContent(inSample, outSample)

Add input numerical points and associated output to the cache.

Parameters:

input_sample : 2-d sequence of float

Input numerical points to be added to the cache.

output_sample : 2-d sequence of float

Output numerical points associated with the input_sample to be added to the cache.

clearCache()

Empty the content of the cache.

clearHistory()

Empty the content of the history.

disableCache()

Disable the cache mechanism.

disableHistory()

Disable the history mechanism.

draw(*args)

Draw the output of function as a Graph.

Available usages:

draw(inputMarg, outputMarg, CP, xiMin, xiMax, ptNb)

draw(firstInputMarg, secondInputMarg, outputMarg, CP, xiMin_xjMin, xiMax_xjMax, ptNbs)

draw(xiMin, xiMax, ptNb)

draw(xiMin_xjMin, xiMax_xjMax, ptNbs)

Parameters:

outputMarg, inputMarg : int, outputMarg, inputMarg \geq 0

outputMarg is the index of the marginal to draw as a function of the marginal with index inputMarg.

firstInputMarg, secondInputMarg : int, firstInputMarg, secondInputMarg \geq 0

In the 2D case, the marginal outputMarg is drawn as a function of the two marginals with indexes firstInputMarg and secondInputMarg.

CP : sequence of float

Central point.

xiMin, xiMax : float

Define the interval where the curve is plotted.

xiMin_xjMin, xiMax_xjMax : sequence of float of dimension 2.

In the 2D case, define the intervals where the curves are plotted.

ptNb : int ptNb > 0 or list of ints of dimension 2 ptNb_k > 0, k=1,2

The number of points to draw the curves.

Notes

We note f: \Rset^n \rightarrow \Rset^p where \vect{x} = (x_1, \dots, x_n) and f(\vect{x}) = (f_1(\vect{x}), \dots,f_p(\vect{x})), with n\geq 1 and p\geq 1.

  • In the first usage:

Draws graph of the given 1D outputMarg marginal f_k: \Rset^n \rightarrow \Rset as a function of the given 1D inputMarg marginal with respect to the variation of x_i in the interval [x_i^{min}, x_i^{max}], when all the other components of \vect{x} are fixed to the corresponding ones of the central point CP. Then OpenTURNS draws the graph: t\in [x_i^{min}, x_i^{max}] \mapsto f_k(CP_1, \dots, CP_{i-1}, t,  CP_{i+1} \dots, CP_n).

  • In the second usage:

Draws the iso-curves of the given outputMarg marginal f_k as a function of the given 2D firstInputMarg and secondInputMarg marginals with respect to the variation of (x_i, x_j) in the interval [x_i^{min}, x_i^{max}] \times [x_j^{min}, x_j^{max}], when all the other components of \vect{x} are fixed to the corresponding ones of the central point CP. Then OpenTURNS draws the graph: (t,u) \in [x_i^{min}, x_i^{max}] \times [x_j^{min}, x_j^{max}] \mapsto f_k(CP_1, \dots, CP_{i-1}, t, CP_{i+1}, \dots, CP_{j-1}, u,  CP_{j+1} \dots, CP_n).

  • In the third usage:

The same as the first usage but only for function f: \Rset \rightarrow \Rset.

  • In the fourth usage:

The same as the second usage but only for function f: \Rset^2 \rightarrow \Rset.

Examples

>>> import openturns as ot
>>> from openturns.viewer import View
>>> f = ot.NumericalMathFunction('x', 'sin(2*_pi*x)*exp(-x^2/2)', 'y')
>>> graph = f.draw(-1.2, 1.2, 100)
>>> View(graph).show()
enableCache()

Enable the cache mechanism.

enableHistory()

Enable the history mechanism.

getCacheHits()

Accessor to the number of computations saved thanks to the cache mecanism.

Returns:

cacheHits : int

Integer that counts the number of computations saved thanks to the cache mecanism.

getCacheInput()

Accessor to all the input numerical points stored in the cache mecanism.

Returns:

cacheInput : NumericalSample

All the input numerical points stored in the cache mecanism.

getCacheOutput()

Accessor to all the output numerical points stored in the cache mecanism.

Returns:

cacheInput : NumericalSample

All the output numerical points stored in the cache mecanism.

getCallsNumber()

Accessor to the number of times the function has been called.

Returns:

calls_number : int

Integer that counts the number of times the function has been called since its creation.

getClassName()

Accessor to the object’s name.

Returns:

class_name : str

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

getDescription()

Accessor to the description of the inputs and outputs.

Returns:

description : Description

Description of the inputs and the outputs.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getDescription())
[x1,x2,y]
getEvaluation()

Accessor to the evaluation function.

Returns:

function : NumericalMathEvaluationImplementation

The evaluation function.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getEvaluation())
[x1,x2]->[2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6]
getEvaluationCallsNumber()

Accessor to the number of times the function has been called.

Returns:

evaluation_calls_number : int

Integer that counts the number of times the function has been called since its creation.

getGradient()

Accessor to the gradient function.

Returns:

gradient : NumericalMathGradientImplementation

The gradient function.

getGradientCallsNumber()

Accessor to the number of times the gradient of the function has been called.

Returns:

gradient_calls_number : int

Integer that counts the number of times the gradient of the NumericalMathFunction has been called since its creation. Note that if the gradient is implemented by a finite difference method, the gradient calls number is equal to 0 and the different calls are counted in the evaluation calls number.

getHessian()

Accessor to the hessian function.

Returns:

hessian : NumericalMathHessianImplementation

The hessian function.

getHessianCallsNumber()

Accessor to the number of times the hessian of the function has been called.

Returns:

hessian_calls_number : int

Integer that counts the number of times the hessian of the NumericalMathFunction has been called since its creation. Note that if the hessian is implemented by a finite difference method, the hessian calls number is equal to 0 and the different calls are counted in the evaluation calls number.

getHistoryInput()

Accessor to the history of the input values.

Returns:

input_history : NumericalSample

All the input numerical points stored in the history mecanism.

getHistoryOutput()

Accessor to the history of the output values.

Returns:

output_history : NumericalSample

All the output numerical points stored in the history mecanism.

getId()

Accessor to the object’s id.

Returns:

id : int

Internal unique identifier.

getImplementation(*args)

Accessor to the underlying implementation.

Returns:

impl : Implementation

The implementation class.

getInputDescription()

Accessor to the description of the inputs.

Returns:

description : Description

Description of the inputs.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getInputDescription())
[x1,x2]
getInputDimension()

Accessor to the number of the inputs.

Returns:

number_inputs : int

Number of inputs.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getInputDimension())
2
getInputParameterHistory()

Accessor to the history of the input parameter values.

Returns:

history : NumericalSample

All the input parameters stored in the history mecanism.

getInputPointHistory()

Accessor to the history of the input point values.

Returns:

history : NumericalSample

All the input points stored in the history mecanism.

getInverse()

Accessor to the inverse Box Cox transformation.

Returns:

myInverseBoxCox : InverseBoxCoxTransform

The inverse Box Cox transformation.

getLambda()

Accessor to the \vect{\lambda} parameter.

Returns:

myLambda : NumericalPoint

The \vect{\lambda} parameter.

getMarginal(*args)

Accessor to marginal.

Parameters:

indices : int or list of ints

Set of indices for which the marginal is extracted.

Returns:

marginal : NumericalMathFunction

Function corresponding to either f_i or (f_i)_{i \in indices}, with f:\Rset^n \rightarrow \Rset^p and f=(f_0 , \dots, f_{p-1}).

getName()

Accessor to the object’s name.

Returns:

name : str

The name of the object.

getOutputDescription()

Accessor to the description of the outputs.

Returns:

description : Description

Description of the outputs.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getOutputDescription())
[y]
getOutputDimension()

Accessor to the number of the outputs.

Returns:

number_outputs : int

Number of outputs.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getOutputDimension())
1
getParameter()

Accessor to the parameter values.

Returns:

parameter : NumericalPoint

The parameter values.

getParameterDescription()

Accessor to the parameter description.

Returns:

parameter : Description

The parameter description.

getParameterDimension()

Accessor to the dimension of the parameter.

Returns:

parameterDimension : int

Dimension of the parameter.

getShift()

Accessor to the \vect{\alpha} parameter.

Returns:

myLambda : NumericalPoint

The \vect{\Lambda} parameter.

gradient(*args)

Return the Jacobian transposed matrix of the function at a point.

Parameters:

point : sequence of float

Point where the Jacobian transposed matrix is calculated.

Returns:

gradient : Matrix

The Jacobian transposed matrix of the function at point.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y','z'],
...                ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6','x1 + x2'])
>>> print(f.gradient([3.14, 4]))
[[ 13.5345   1       ]
 [  4.00001  1       ]]
hessian(*args)

Return the hessian of the function at a point.

Parameters:

point : sequence of float

Point where the hessian of the function is calculated.

Returns:

hessian : SymmetricTensor

Hessian of the function at point.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y','z'],
...                ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6','x1 + x2'])
>>> print(f.hessian([3.14, 4]))
sheet #0
[[ 20          -0.00637061 ]
 [ -0.00637061  0          ]]
sheet #1
[[  0           0          ]
 [  0           0          ]]
isCacheEnabled()

Test whether the cache mechanism is enabled or not.

Returns:

isCacheEnabled : bool

Flag telling whether the cache mechanism is enabled. It is disabled by default.

isHistoryEnabled()

Test whether the history mechanism is enabled or not.

Returns:

isHistoryEnabled : bool

Flag telling whether the history mechanism is enabled. It is disabled by default.

parameterGradient(*args)

Accessor to the gradient against the parameter.

Returns:

gradient : Matrix

The gradient.

setDescription(description)

Accessor to the description of the inputs and outputs.

Parameters:

description : sequence of str

Description of the inputs and the outputs.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getDescription())
[x1,x2,y]
>>> f.setDescription(['a','b','y'])
>>> print(f.getDescription())
[a,b,y]
setEvaluation(evaluation)

Accessor to the evaluation function.

Parameters:

function : NumericalMathEvaluationImplementation

The evaluation function.

setGradient(gradient)

Accessor to the gradient function.

Parameters:

gradient_function : NumericalMathGradientImplementation

The gradient function.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> f.setGradient(ot.CenteredFiniteDifferenceGradient(
...  ot.ResourceMap.GetAsNumericalScalar('CenteredFiniteDifferenceGradient-DefaultEpsilon'),
...  f.getEvaluation()))
setHessian(hessian)

Accessor to the hessian function.

Parameters:

hessian_function : NumericalMathHessianImplementation

The hessian function.

Examples

>>> import openturns as ot
>>> f = ot.NumericalMathFunction(['x1', 'x2'], ['y'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> f.setHessian(ot.CenteredFiniteDifferenceHessian(
...  ot.ResourceMap.GetAsNumericalScalar('CenteredFiniteDifferenceHessian-DefaultEpsilon'),
...  f.getEvaluation()))
setName(name)

Accessor to the object’s name.

Parameters:

name : str

The name of the object.

setParameter(parameter)

Accessor to the parameter values.

Parameters:

parameter : sequence of float

The parameter values.

setParameterDescription(description)

Accessor to the parameter description.

Parameters:

parameter : Description

The parameter description.