1%feature("docstring") OT::CompositeDistribution
2"Composite distribution.
3
4Helper class for defining the push-forward distribution of a given univariate
5distribution by a given scalar function.
6
7Available constructors:
8    CompositeDistribution(*g=Function('x', 'x'), distX=Uniform(0.0,1.0)*)
9
10    CompositeDistribution(*g, distX, a, v*)
11
12Parameters
13----------
14g : :class:`~openturns.Function`, :math:`\Rset \rightarrow \Rset`
15distX : :class:`~openturns.Distribution`, univariate
16a : sequence of float of dimension :math:`N+1`, :math:`a[0]=\inf \supp{distX}`, :math:`a[N]=\sup \supp{distX}`
17    The bounds of the intervals on which :math:`g` is monotone, sorted in
18    ascending order.
19v : sequence of float of dimension :math:`N+1`,
20    The values taken by :math:`g` on each bound: :math:`v[k]=g(a[k])`.
21
22Returns
23-------
24distY : :class:`~openturns.Distribution`, univariate
25    :math:`distY` is the push-forward distribution of :math:`distX` by :math:`g`.
26
27
28Notes
29-----
30We note :math:`X` a scalar random variable which distribution is :math:`distX`,
31which probability density function is :math:`f_X`.
32
33Then :math:`distY` is the distribution of the scalar random variable
34:math:`Y=g(X)`, which probability density function :math:`f_Y` is defined as:
35
36.. math::
37
38    \displaystyle f_Y(y) = \sum_{k =0}^{k=N} \frac{f_X (g^{-1}(y))}{|g'\circ g^{-1}(y)|}1_{y \in g^{-1}([a_k, a_{k+1}))}
39
40with :math:`a_0=\inf \supp{f_X}`, :math:`a_N=\sup \supp{f_X}` and
41:math:`(a_1, \dots, a_N)` such that :math:`g` is monotone over
42:math:`[a_k, a_{k+1})` for :math:`0 \leq k \leq N`.
43
44Its first moments are obtained by numerical integration.
45
46Examples
47--------
48Create a distribution:
49
50>>> import openturns as ot
51>>> g = ot.SymbolicFunction(['x'], ['sin(x) + cos(x)'])
52>>> distY = ot.CompositeDistribution(g, ot.Normal(1.0, 0.5))
53
54>>> g = ot.SymbolicFunction(['x'], ['abs(x)'])
55>>> a = [-1.0, 0.0, 2.0]
56>>> v = [1.0, 0.0, 2.0]
57>>> distZ = ot.CompositeDistribution(g, ot.Uniform(-1.0, 2.0), a, v)
58
59>>> distX = ot.Normal(0.0, 1.0)
60>>> a0 = distX.getRange().getLowerBound()
61>>> aN = distX.getRange().getUpperBound()
62>>> a = [a0[0], 0.0, 0.0, aN[0]]
63>>> g = ot.SymbolicFunction(['x'], ['1.0/x'])
64>>> v = [g(a0)[0], -ot.SpecFunc.MaxScalar, ot.SpecFunc.MaxScalar, g(aN)[0]]
65>>> distT = ot.CompositeDistribution(g, distX, a, v)
66
67
68Draw a sample:
69
70>>> sample = distT.getSample(5)"
71
72// ---------------------------------------------------------------------
73
74%feature("docstring") OT::CompositeDistribution::getFunction
75"Accessor to the function.
76
77Returns
78-------
79g :  :class:`~openturns.Function`, :math:`\Rset \rightarrow \Rset`
80    the function :math:`g`."
81
82// ---------------------------------------------------------------------
83
84%feature("docstring") OT::CompositeDistribution::getAntecedent
85"Accessor to the antecedent distribution.
86
87Returns
88-------
89distX : :class:`~openturns.Distribution`, univariate
90    Antecedent distribution :math:`distX`."
91
92// ---------------------------------------------------------------------
93
94%feature("docstring") OT::CompositeDistribution::setFunction
95"Fix the function through wich the distribution is push-forwarded.
96
97Parameters
98----------
99g :  :class:`~openturns.Function`, :math:`\Rset \rightarrow \Rset`
100    the function :math:`g`."
101// ---------------------------------------------------------------------
102
103%feature("docstring") OT::CompositeDistribution::setAntecedent
104"Fix the antecedent distribution which is push-forwarded.
105
106Parameters
107----------
108distX : :class:`~openturns.Distribution`, univariate
109   Distribution of the antecedent :math:`distX`."
110