1%feature("docstring") OT::ANCOVA
2"ANalysis of COVAriance method (ANCOVA).
3
4Refer to :ref:`sensitivity_ancova`.
5
6Available constructor:
7    ANCOVA(*functionalChaosResult, correlatedInput*)
8
9Parameters
10----------
11functionalChaosResult : :class:`~openturns.FunctionalChaosResult`
12    Functional chaos result approximating the model response with
13    uncorrelated inputs.
14correlatedInput : 2-d sequence of float
15    Correlated inputs used to compute the real values of the output.
16    Its dimension must be equal to the number of inputs of the model.
17
18Notes
19-----
20ANCOVA, a variance-based method described in [caniou2012]_, is a generalization
21of the ANOVA (ANalysis Of VAriance) decomposition for models with correlated
22input parameters.
23
24Let us consider a model :math:`Y = h(\vect{X})` without making any hypothesis
25on the dependence structure of :math:`\vect{X} = \{X^1, \ldots, X^{n_X} \}`, a
26n_X-dimensional random vector. The covariance decomposition requires a functional
27decomposition of the model. Thus the model response :math:`Y` is expanded as a
28sum of functions of increasing dimension as follows:
29
30.. math::
31    :label: model
32
33    h(\vect{X}) = h_0 + \sum_{u\subseteq\{1,\dots,n_X\}} h_u(X_u)
34
35:math:`h_0` is the mean of :math:`Y`. Each function :math:`h_u` represents,
36for any non empty set :math:`u\subseteq\{1, \dots, n_X\}`, the combined
37contribution of the variables :math:`X_u` to :math:`Y`.
38
39Using the properties of the covariance, the variance of :math:`Y` can be
40decomposed into a variance part and a covariance part as follows:
41
42.. math::
43
44    Var[Y]&= Cov\left[h_0 + \sum_{u\subseteq\{1,\dots,n_X\}} h_u(X_u), h_0 + \sum_{u\subseteq\{1,\dots,n_X\}} h_u(X_u)\right] \\
45          &= \sum_{u\subseteq\{1,\dots,n_X\}} \left[Var[h_u(X_u)] + Cov[h_u(X_u), \sum_{v\subseteq\{1,\dots,n_X\}, v\cap u=\varnothing} h_v(X_v)]\right]
46
47This variance formula enables to define each total part of variance of
48:math:`Y` due to :math:`X_u`, :math:`S_u`, as the sum of a *physical*
49(or *uncorrelated*) part and a *correlated* part such as:
50
51.. math::
52
53    S_u = \frac{Cov[Y, h_u(X_u)]} {Var[Y]} = S_u^U + S_u^C
54
55where :math:`S_u^U` is the uncorrelated part of variance of Y due to :math:`X_u`:
56
57.. math::
58
59    S_u^U = \frac{Var[h_u(X_u)]} {Var[Y]}
60
61and :math:`S_u^C` is the contribution of the correlation of :math:`X_u` with the
62other parameters:
63
64.. math::
65
66    S_u^C = \frac{Cov\left[h_u(X_u), \displaystyle \sum_{v\subseteq\{1,\dots,n_X\}, v\cap u=\varnothing} h_v(X_v)\right]}
67                 {Var[Y]}
68
69As the computational cost of the indices with the numerical model :math:`h`
70can be very high, [caniou2012]_ suggests to approximate the model response with
71a polynomial chaos expansion:
72
73.. math::
74
75    Y \simeq \hat{h} = \sum_{j=0}^{P-1} \alpha_j \Psi_j(x)
76
77However, for the sake of computational simplicity, the latter is constructed
78considering *independent* components :math:`\{X^1,\dots,X^{n_X}\}`. Thus the
79chaos basis is not orthogonal with respect to the correlated inputs under
80consideration, and it is only used as a metamodel to generate approximated
81evaluations of the model response and its summands :eq:`model`.
82
83The next step consists in identifying the component functions. For instance, for
84:math:`u = \{1\}`:
85
86.. math::
87
88    h_1(X_1) = \sum_{\alpha | \alpha_1 \neq 0, \alpha_{i \neq 1} = 0} y_{\alpha} \Psi_{\alpha}(\vect{X})
89
90where :math:`\alpha` is a set of degrees associated to the :math:`n_X` univariate
91polynomial :math:`\psi_i^{\alpha_i}(X_i)`.
92
93Then the model response :math:`Y` is evaluated using a sample
94:math:`X=\{x_k, k=1,\dots,N\}` of the correlated joint distribution. Finally,
95the several indices are computed using the model response and its component
96functions that have been identified on the polynomial chaos.
97
98Examples
99--------
100>>> import openturns as ot
101>>> ot.RandomGenerator.SetSeed(0)
102>>> # Model and distribution definition
103>>> model = ot.SymbolicFunction(['X1','X2'], ['4.*X1 + 5.*X2'])
104>>> distribution = ot.ComposedDistribution([ot.Normal()] * 2)
105>>> S = ot.CorrelationMatrix(2)
106>>> S[1, 0] = 0.3
107>>> R = ot.NormalCopula().GetCorrelationFromSpearmanCorrelation(S)
108>>> CorrelatedInputDistribution = ot.ComposedDistribution([ot.Normal()] * 2, ot.NormalCopula(R))
109>>> sample = CorrelatedInputDistribution.getSample(200)
110>>> # Functional chaos computation
111>>> productBasis = ot.OrthogonalProductPolynomialFactory([ot.HermiteFactory()] * 2, ot.LinearEnumerateFunction(2))
112>>> adaptiveStrategy = ot.FixedStrategy(productBasis, 15)
113>>> projectionStrategy = ot.LeastSquaresStrategy(ot.MonteCarloExperiment(100))
114>>> algo = ot.FunctionalChaosAlgorithm(model, distribution, adaptiveStrategy, projectionStrategy)
115>>> algo.run()
116>>> ancovaResult = ot.ANCOVA(algo.getResult(), sample)
117>>> indices = ancovaResult.getIndices()
118>>> print(indices)
119[0.408398,0.591602]
120>>> uncorrelatedIndices = ancovaResult.getUncorrelatedIndices()
121>>> print(uncorrelatedIndices)
122[0.284905,0.468108]
123>>> # Get indices measuring the correlated effects
124>>> print(indices - uncorrelatedIndices)
125[0.123494,0.123494]"
126
127// ---------------------------------------------------------------------
128
129%feature("docstring") OT::ANCOVA::getUncorrelatedIndices
130"Accessor to the ANCOVA indices measuring uncorrelated effects.
131
132Parameters
133----------
134marginalIndex : int, :math:`0 \leq i < n`, optional
135    Index of the model's marginal used to estimate the indices.
136    By default, marginalIndex is equal to 0.
137
138Returns
139-------
140indices : :class:`~openturns.Point`
141    List of the ANCOVA indices measuring uncorrelated effects of the inputs.
142    The effects of the correlation are represented by the indices resulting
143    from the subtraction of the :meth:`getIndices` and
144    :meth:`getUncorrelatedIndices` lists."
145
146// ---------------------------------------------------------------------
147
148%feature("docstring") OT::ANCOVA::getIndices
149"Accessor to the ANCOVA indices.
150
151Parameters
152----------
153marginalIndex : int, :math:`0 \leq i < n`, optional
154    Index of the model's marginal used to estimate the indices.
155    By default, marginalIndex is equal to 0.
156
157Returns
158-------
159indices : :class:`~openturns.Point`
160    List of the ANCOVA indices measuring the contribution of the
161    input variables to the variance of the model. These indices are made up
162    of a *physical* part and a *correlated* part. The first one is obtained
163    thanks to :meth:`getUncorrelatedIndices`.
164    The effects of the correlation are represented by the indices resulting
165    from the subtraction of the :meth:`getIndices` and
166    :meth:`getUncorrelatedIndices` lists."
167