Python doc and SWIG interface.

lib/src/Uncertainty/Algorithm/MetaModel/FunctionalChaos/openturns/FunctionalChaosValidation.hxx

@@ -21,8 +21,8 @@
 #ifndef OPENTURNS_FUNCTIONALCHAOSVALIDATION_HXX
 #define OPENTURNS_FUNCTIONALCHAOSVALIDATION_HXX
 
+#include "openturns/Sample.hxx"
 #include "openturns/FunctionalChaosResult.hxx"
-#include "openturns/GridLayout.hxx"
 #include "openturns/MetaModelValidation.hxx"
 
 BEGIN_NAMESPACE_OPENTURNS

lib/src/Uncertainty/Algorithm/MetaModel/LinearModel/openturns/LinearModelValidation.hxx

@@ -21,11 +21,7 @@
 #ifndef OPENTURNS_LINEARMODELVALIDATION_HXX
 #define OPENTURNS_LINEARMODELVALIDATION_HXX
 
-#include "openturns/PersistentObject.hxx"
 #include "openturns/Sample.hxx"
-#include "openturns/Description.hxx"
-#include "openturns/TestResult.hxx"
-#include "openturns/Graph.hxx"
 #include "openturns/LinearModelResult.hxx"
 #include "openturns/MetaModelValidation.hxx"
 

python/doc/user_manual/response_surface/functional_chaos_expansion.rst

@@ -75,6 +75,7 @@ Results
     FunctionalChaosRandomVector
     FunctionalChaosResult
     FunctionalChaosSobolIndices
+    FunctionalChaosValidation
 
 Functional chaos on fields
 ==========================

python/doc/user_manual/response_surface/lm.rst

@@ -23,3 +23,4 @@ Post-processing
     :template: class.rst_t
 
     LinearModelAnalysis
+    LinearModelValidation

python/src/CMakeLists.txt

@@ -874,6 +874,7 @@ ot_add_python_module(metamodel metamodel_module.i
                       LinearModelStepwiseAlgorithm.i LinearModelStepwiseAlgorithm_doc.i.in
                       LinearModelAlgorithm.i LinearModelAlgorithm_doc.i.in
                       LinearModelAnalysis.i LinearModelAnalysis_doc.i.in
+                      LinearModelValidation.i LinearModelValidation_doc.i.in
                       RandomVector.i RandomVector_doc.i.in
                       PythonEvaluation.cxx
                       PythonGradient.cxx
@@ -888,6 +889,7 @@ ot_add_python_module(metamodel metamodel_module.i
                       UnionEvent.i UnionEvent_doc.i.in
                       FunctionalChaosRandomVector.i FunctionalChaosRandomVector_doc.i.in
                       FunctionalChaosSobolIndices.i FunctionalChaosSobolIndices_doc.i.in
+                      FunctionalChaosValidation.i FunctionalChaosValidation_doc.i.in
                       KrigingRandomVector.i KrigingRandomVector_doc.i.in
                       UncertaintyMetaModelTemplateDefs.i
                    )

python/src/FunctionalChaosValidation.i

@@ -4,7 +4,7 @@
 #include "openturns/FunctionalChaosValidation.hxx"
 %}
 
-%include FunctionalChaosValidation.i
+%include FunctionalChaosValidation_doc.i
 
 %include openturns/FunctionalChaosValidation.hxx
 

python/src/FunctionalChaosValidation_doc.i.in

@@ -0,0 +1,59 @@
+%feature("docstring") OT::FunctionalChaosValidation
+"Validate a functional chaos metamodel.
+
+Available constructors:
+    FunctionalChaosValidation(*functionalChaosResult*)
+
+Parameters
+----------
+    result : :class:`~openturns.FunctionalChaosResult`
+    A functional chaos result resulting from a polynomial chaos expansion.
+
+See also
+--------
+FunctionalChaosAlgorithm, FunctionalChaosResult
+
+Notes
+-----
+A `FunctionalChaosValidation` object is used for the validation of a functional chaos expansion.
+This can be done only if the coefficients of the expansion are estimated
+using least squares regression: if the expansion is computed from integration,
+then an exception is produced.
+
+Examples
+--------
+Create a polynomial chaos for the Ishigami function:
+
+>>> import openturns as ot
+>>> from math import pi
+>>> from openturns.usecases import ishigami_function
+>>> im = ishigami_function.IshigamiModel()
+>>> distributionList = [ot.Uniform(-pi, pi)] * 3
+>>> distribution = ot.ComposedDistribution(distributionList)
+>>> N = 500 
+>>> inputTrain = im.distributionX.getSample(N)
+>>> outputTrain = im.model(inputTrain)
+>>> multivariateBasis = ot.OrthogonalProductPolynomialFactory([im.X1, im.X2, im.X3])
+>>> selectionAlgorithm = ot.LeastSquaresMetaModelSelectionFactory()
+>>> projectionStrategy = ot.LeastSquaresStrategy(
+>>>     inputTrain, outputTrain, selectionAlgorithm
+>>> )
+>>> totalDegree = 8
+>>> enumerateFunction = multivariateBasis.getEnumerateFunction()
+>>> basisSize = enumerateFunction.getStrataCumulatedCardinal(totalDegree)
+>>> adaptiveStrategy = ot.FixedStrategy(multivariateBasis, basisSize)
+>>> chaosalgo = ot.FunctionalChaosAlgorithm(
+>>>     inputTrain, outputTrain, im.distributionX, adaptiveStrategy, projectionStrategy
+>>> )
+>>> chaosalgo.run()
+>>> result = chaosalgo.getResult()
+
+Validate the polynomial chaos expansion.
+
+>>> validation = ot.FunctionalChaosValidation(result, ot.FunctionalChaosValidation.LEAVEONEOUT)
+>>> r2Score = validation.computeR2Score()
+>>> print('R2 = ', r2Score[0])
+R2 =  0.8...
+
+>>> # Draw the validation graph
+>>> graph = validation.drawValidation()"

python/src/LinearModelValidation.i

@@ -4,7 +4,7 @@
 #include "openturns/LinearModelValidation.hxx"
 %}
 
-%include LinearModelValidation.i
+%include LinearModelValidation_doc.i
 
 %include openturns/LinearModelValidation.hxx
 

python/src/LinearModelValidation_doc.i.in

@@ -0,0 +1,43 @@
+%feature("docstring") OT::LinearModelValidation
+"Validate a linear regression metamodel.
+
+Available constructors:
+    LinearModelValidation(*linearModelResult*)
+
+Parameters
+----------
+    result : :class:`~openturns.LinearModelResult`
+    A linear model result resulting from linear least squares regression.
+
+See also
+--------
+LinearModelResult
+
+Notes
+-----
+A `LinearModelValidation` object is used for the validation of a linear model.
+
+Examples
+--------
+Create a linear model.
+
+>>> import openturns as ot
+>>> distribution = ot.Normal()
+>>> func = ot.SymbolicFunction(['x1','x2', 'x3'], ['x1 + x2 + sin(x2 * 2 * pi_) / 5 + 1e-3 * x3^2'])
+>>> dimension = 3
+>>> distribution = ot.ComposedDistribution([ot.Normal()] * dimension)
+>>> input_sample = distribution.getSample(20)
+>>> output_sample = func(input_sample)
+>>> algo = ot.LinearModelAlgorithm(input_sample, output_sample)
+>>> algo.run()
+>>> result = algo.getResult()
+
+Validated the linear model.
+
+>>> validation = ot.LinearModelValidation(result, ot.LinearModelValidation.LEAVEONEOUT)
+>>> r2Score = validation.computeR2Score()
+>>> print('R2 = ', r2Score[0])
+R2 =  0.98...
+
+>>> # Draw the validation graph
+>>> graph = validation.drawValidation()"

python/src/MetaModelValidation_doc.i.in

@@ -1,8 +1,5 @@
 %feature("docstring") OT::MetaModelValidation
-"Base class to score a metamodel and perform validations.
-
-Refer to :ref:`cross_validation`.
-
+"Score a metamodel and perform validation.
 
 Available constructors:
     MetaModelValidation(*inputValidationSample, outputValidationSample, metaModel*)
@@ -26,9 +23,9 @@ A `MetaModelValidation` object is used for the validation of a metamodel.
 For that purpose, a dataset independent of the learning step, is used to score the surrogate model.
 Its main functionalities are :
 
-- To compute the coefficient of determination :math:`R^2`
-- To get the residual sample and its non parametric distribution
-- To draw a validation graph presenting the metamodel predictions against
+- compute the coefficient of determination :math:`R^2` ;
+- get the residual sample and its non parametric distribution ;
+- draw a validation graph presenting the metamodel predictions against
   the model observations.
 
 More details on this topic are presented in :ref:`cross_validation`.
@@ -106,20 +103,20 @@ where :math:`Y = g(\bdX)` is the output of the physical model :math:`g`,
 mean squared error of the metamodel:
 
 .. math::
-    \operatorname{MSE}(\tilde{g}) = \Expect{\left[g(\bdX) - \tilde{g}(\bdX) \right]^2}.
+    \operatorname{MSE}(\tilde{g}) = \Expect{\left(g(\bdX) - \tilde{g}(\bdX) \right)^2}.
 
 The sample :math:`R^2` is:
 
 .. math::
     \hat{R}^2 = 1 - \frac{\frac{1}{n} \sum_{j=1}^{n} \left(y^{(j)} - \tilde{g}\left(\bdx^{(j)}\right)\right)^2}{\hat{\sigma}^2_Y}
 
 where :math:`n \in \Nset` is the sample size, :math:`\tilde{g}` is the metamodel,
-:math:`\{\bdx^{(j)} \in \Rset^{n_X}\}_{j = 1, ..., n}` is the input experimental design,
-:math:`\{y^{(j)} \in \Rset\}_{j = 1, ..., n}` is the output of the model and
+:math:`\left\{\bdx^{(j)} \in \Rset^{n_X}\right\}_{j = 1, ..., n}` is the input experimental design,
+:math:`\left\{y^{(j)} \in \Rset\right\}_{j = 1, ..., n}` is the output of the model and
 :math:`\hat{\sigma}^2_Y` is the sample variance of the output:
 
 .. math::
-    \hat{\sigma}^2_Y = \frac{1}{n - 1} \sum_{j=1}^{n} (y^{(j)} - \overline{y})^2
+    \hat{\sigma}^2_Y = \frac{1}{n - 1} \sum_{j=1}^{n} \left(y^{(j)} - \overline{y}\right)^2
 
 where :math:`\overline{y}` is the output sample mean:
 
@@ -185,6 +182,12 @@ graph : :class:`~openturns.GridLayout`
 
 Notes
 -----
+The plot presents the metamodel predictions depending on the model observations. 
+If the points are close to the diagonal line of the plot, then the 
+metamodel validation is satisfactory. 
+Points which are far away from the diagonal represents outputs 
+for which the metamodel is not accurate.
+
 If the output is multi-dimensional, the graph has 1 row and :math:`n_y \in \Nset`
 columns, where :math:`n_y` is the output dimension."
 

python/src/metamodel_module.i

@@ -59,13 +59,15 @@
 %include FunctionalChaosResult.i
 %include FunctionalChaosAlgorithm.i
 %include FunctionalChaosSobolIndices.i
+%include FunctionalChaosValidation.i
 %include MetaModelValidation.i
 %include GeneralLinearModelResult.i
 %include GeneralLinearModelAlgorithm.i
 %include KrigingAlgorithm.i
 %include LinearModelStepwiseAlgorithm.i
 %include LinearModelAlgorithm.i
 %include LinearModelAnalysis.i
+%include LinearModelValidation.i
 
 /* Uncertainty/Model */
 %include RandomVector.i