1%feature("docstring") OT::LogNormalFactory
2"Lognormal factory distribution.
3
4Available constructors:
5    LogNormalFactory()
6
7See also
8--------
9DistributionFactory, LogNormal
10
11Notes
12-----
13Several estimators to build a LogNormal distribution from a scalar sample
14are proposed.
15
16**Moments based estimator:**
17
18Lets denote:
19
20- :math:`\displaystyle \overline{x}_n = \frac{1}{n} \sum_{i=1}^n x_i` the empirical
21  mean of the sample,
22- :math:`\displaystyle s_n^2 = \frac{1}{n-1} \sum_{i=1}^n (x_i - \overline{x}_n)^2`
23  its empirical variance,
24- :math:`\displaystyle a_{3,n} = \sqrt{n} \frac{\sum_{i=1}^n (x_i - \overline{x}_n)^3}{ \left( \sum_{i=1}^n (x_i - \overline{x}_n)^2 \right)^{3/2}}`
25  its empirical skewness.
26
27We note :math:`\omega = e^{\sigma_l^2}`. The estimator :math:`\hat{\omega}_n` of
28:math:`\omega` is the positive root of the relation:
29
30.. math::
31    :label: omega_moment_relation
32
33    \omega^3 + 3 \omega^2 - (4 + a_{3,n}^2) = 0
34
35Then we estimate :math:`(\hat{\mu}_{ln}, \hat{\sigma}_{ln}, \hat{\gamma}_{n})`
36using:
37
38.. math::
39    :label: moment_estimator
40
41    \hat{\mu}_{ln} &= \log \hat{\beta}_{n} \\
42    \hat{\sigma}_{ln} &= \sqrt{ \log \hat{\omega}_{n} } \\
43    \hat{\gamma}_{ln} &= \overline{x}_n - \hat{\beta}_{n} \sqrt{ \hat{\omega}_{n} }
44
45where :math:`\displaystyle \hat{\beta}_{n} = \frac{s_n}{\hat{\omega}_{n} (\hat{\omega}_{n} - 1)}`.
46
47**Modified moments based estimator:**
48
49Using :math:`\overline{x}_n` and :math:`s_n^2` previously defined, the third
50equation is:
51
52.. math::
53    :label: expected_modified_moment
54
55    \Eset[ \log (X_{(1)} - \gamma)] = \log (x_{(1)} - \gamma)
56
57The quantity :math:`\displaystyle EZ_1 (n) = \frac{\Eset[ \log (X_{(1)} - \gamma)] - \mu_l}{\sigma_l}`
58is the mean of the first order statistics of a standard normal sample of size
59:math:`n`. We have:
60
61.. math::
62    :label: EZ1_equation
63
64    EZ_1(n) = \int_\Rset nz\phi(z) (1 - \Phi(z))^{n-1}\di{z}
65
66where :math:`\varphi` and :math:`\Phi` are the PDF and CDF of the standard
67normal distribution. The estimator :math:`\hat{\omega}_{n}` of :math:`\omega` is
68obtained as the solution of:
69
70.. math::
71    :label: omega_modified_moment_relation
72
73    \omega (\omega - 1) - \kappa_n \left[ \sqrt{\omega} - e^{EZ_1(n)\sqrt{\log \omega}} \right]^2 = 0
74
75where :math:`\displaystyle \kappa_n = \frac{s_n^2}{(\overline{x}_n - x_{(1)})^2}`.
76Then we have :math:`(\hat{\mu}_{ln}, \hat{\sigma}_{ln}, \hat{\gamma}_{n})` using
77the relations defined for the moments based estimator :eq:`moment_estimator`.
78
79**Local maximum likelihood estimator:**
80
81The following sums are defined:
82
83.. math::
84
85    S_0 &= \sum_{i=1}^n \frac{1}{x_i - \gamma} \\
86    S_1 &= \sum_{i=1}^n \log (x_i - \gamma) \\
87    S_2 &= \sum_{i=1}^n \log^2 (x_i - \gamma) \\
88    S_3 &= \sum_{i=1}^n \frac{\log (x_i - \gamma)}{x_i - \gamma}
89
90The Maximum Likelihood estimator of :math:`(\mu_{l}, \sigma_{l}, \gamma)` is
91defined by:
92
93.. math::
94    :label: ln_mll_estimator
95
96    \hat{\mu}_{l,n} &= \frac{S_1(\hat{\gamma})}{n} \\
97    \hat{\sigma}_{l,n}^2 &= \frac{S_2(\hat{\gamma})}{n} - \hat{\mu}_{l,n}^2
98
99Thus, :math:`\hat{\gamma}_n` satisfies the relation:
100
101.. math::
102    :label: ln_mll_relation
103
104    S_0 (\gamma) \left(S_2(\gamma) - S_1(\gamma) \left( 1 + \frac{S_1(\gamma)}{n} \right) \right) + n S_3(\gamma) = 0
105
106under the constraint :math:`\gamma \leq \min x_i`.
107
108**Least squares method estimator:**
109
110The parameter :math:`\gamma` is numerically optimized by non-linear least-squares:
111
112.. math::
113
114    \min{\gamma} \norm{\Phi^{-1}(\hat{F}_n(x_i)) - (a_1 \log(x_i - \gamma) + a_0)}_2^2
115
116where :math:`a_0, a_1` are computed from linear least-squares at each optimization evaluation.
117
118When :math:`\gamma` is known and the :math:`x_i` follow a Log-Normal distribution then
119we use linear least-squares to solve the relation:
120
121.. math::
122  :label: least_squares_estimator_lognormal
123
124    \Phi^{-1}(\hat{F}_n(x_i)) = a_1 \log(x_i - \gamma) + a_0
125
126And the remaining parameters are estimated with:
127
128.. math::
129
130    \hat{\sigma}_l &= \frac{1}{a_1}\\
131    \hat{\mu}_l &= -a_0 \hat{\sigma}_l
132
133Examples
134--------
135
136>>> import openturns as ot
137>>> ot.RandomGenerator.SetSeed(0)
138>>> sample = ot.LogNormal(1.5, 2.5, -1.5).getSample(1000)
139>>> estimated = ot.LogNormalFactory().build(sample)"
140
141// ---------------------------------------------------------------------
142
143%feature("docstring") OT::LogNormalFactory::build
144"Build the distribution.
145
146**Available usages**:
147
148    build()
149
150    build(*sample*)
151
152    build(*sample, method*)
153
154    build(*param*)
155
156Parameters
157----------
158sample : 2-d sequence of float, of dimension 1
159    The sample from which the distribution parameters are estimated.
160method : integer
161    An integer corresponding to a specific estimator method:
162
163    - 0 : Local likelihood maximum estimator
164    - 1 : Modified moment estimator
165    - 2 : Method of moment estimator
166    - 3 : Least squares method.
167
168param : Collection of :class:`~openturns.PointWithDescription`
169    A vector of parameters of the distribution.
170
171Returns
172-------
173dist : :class:`~openturns.Distribution`
174    The built distribution.
175
176Notes
177-----
178See the *buildAsLogNormal* method.
179"
180
181// ---------------------------------------------------------------------
182
183%feature("docstring") OT::LogNormalFactory::buildAsLogNormal
184"Build the distribution as a LogNormal type.
185
186**Available usages**:
187
188    buildAsLogNormal()
189
190    buildAsLogNormal(*sample*)
191
192    buildAsLogNormal(*sample, method*)
193
194    buildAsLogNormal(*param*)
195
196Parameters
197----------
198sample : 2-d sequence of float, of dimension 1
199    The sample from which the distribution parameters are estimated.
200method : integer
201    An integer ranges from 0 to 2 corresponding to a specific estimator method:
202    - 0 : Local likelihood maximum estimator (default)
203    - 1 : Modified moment estimator
204    - 2 : Method of moment estimator
205    - 3 : Least squares method.
206
207    The default value is from the :class:`~openturns.ResourceMap` key `LogNormalFactory-EstimationMethod`.
208param : Collection of :class:`~openturns.PointWithDescription`
209    A vector of parameters of the distribution.
210
211Returns
212-------
213dist : :class:`~openturns.LogNormal`
214    The built distribution.
215
216Notes
217-----
218In the first usage, the default :class:`~openturns.LogNormal` distribution is built.
219
220In the second usage, the parameters are evaluated according the following strategy:
221
222- It first uses the local likelihood maximum based estimator.
223- It uses the modified moments based estimator if the resolution of
224  :eq:`ln_mll_relation` is not possible.
225- It uses the moments based estimator, which are always defined, if
226  the resolution of :eq:`omega_modified_moment_relation` is not possible.
227
228In the third usage, the parameters of the :class:`~openturns.LogNormal` are estimated using the given method.
229
230In the fourth usage, a :class:`~openturns.LogNormal` distribution corresponding to the given parameters is built."
231
232// ---------------------------------------------------------------------
233
234%feature("docstring") OT::LogNormalFactory::buildMethodOfLocalLikelihoodMaximization
235"Build the distribution based on the local likelihood maximum estimator.
236
237Parameters
238----------
239sample : 2-d sequence of float, of dimension 1
240    The sample from which the distribution parameters are estimated.
241
242Returns
243-------
244dist : :class:`~openturns.LogNormal`
245    The built distribution."
246
247// ---------------------------------------------------------------------
248
249%feature("docstring") OT::LogNormalFactory::buildMethodOfModifiedMoments
250"Build the distribution based on the modified moments estimator.
251
252Parameters
253----------
254sample : 2-d sequence of float, of dimension 1
255    The sample from which the distribution parameters are estimated.
256
257Returns
258-------
259dist : :class:`~openturns.LogNormal`
260    The built distribution."
261
262// ---------------------------------------------------------------------
263
264%feature("docstring") OT::LogNormalFactory::buildMethodOfMoments
265"Build the distribution based on the method of moments estimator.
266
267Parameters
268----------
269sample : 2-d sequence of float, of dimension 1
270    The sample from which the distribution parameters are estimated.
271
272Returns
273-------
274dist : :class:`~openturns.LogNormal`
275    The built distribution."
276
277// ---------------------------------------------------------------------
278
279%feature("docstring") OT::LogNormalFactory::buildMethodOfLeastSquares
280"Build the distribution based on the least-squares estimator.
281
282Parameters
283----------
284sample : 2-d sequence of float, of dimension 1
285    The sample from which the distribution parameters are estimated.
286gamma : float, optional
287    The :math:`\gamma` parameter estimate
288
289Returns
290-------
291dist : :class:`~openturns.LogNormal`
292    The built distribution."
293