Logo ROOT   6.12/07
Reference Guide
QuantFuncMathCore.h
Go to the documentation of this file.
1 // @(#)root/mathcore:$Id$
2 // Authors: L. Moneta, A. Zsenei 08/2005
3 
4 
5 // Authors: Andras Zsenei & Lorenzo Moneta 08/2005
6 
7 
8 /**********************************************************************
9  * *
10  * Copyright (c) 2005 , LCG ROOT MathLib Team *
11  * *
12  * *
13  **********************************************************************/
14 
15 
16 #ifndef ROOT_Math_QuantFuncMathCore
17 #define ROOT_Math_QuantFuncMathCore
18 
19 
20 namespace ROOT {
21 namespace Math {
22 
23 
24 
25  /** @defgroup QuantFunc Quantile Functions
26  * @ingroup StatFunc
27  *
28  * Inverse functions of the cumulative distribution functions
29  * and the inverse of the complement of the cumulative distribution functions
30  * for various distributions.
31  * The functions with the extension <em>_quantile</em> calculate the
32  * inverse of the <em>_cdf</em> function, the
33  * lower tail integral of the probability density function
34  * \f$D^{-1}(z)\f$ where
35  *
36  * \f[ D(x) = \int_{-\infty}^{x} p(x') dx' \f]
37  *
38  * while those with the <em>_quantile_c</em> extension calculate the
39  * inverse of the <em>_cdf_c</em> functions, the upper tail integral of the probability
40  * density function \f$D^{-1}(z) \f$ where
41  *
42  * \f[ D(x) = \int_{x}^{+\infty} p(x') dx' \f]
43  *
44  * These functions are defined in the header file <em>Math/ProbFunc.h<em> or in the global one
45  * including all statistical functions <em>Math/DistFunc.h<em>
46  *
47  *
48  * <strong>NOTE:</strong> In the old releases (< 5.14) the <em>_quantile</em> functions were called
49  * <em>_quant_inv</em> and the <em>_quantile_c</em> functions were called
50  * <em>_prob_inv</em>.
51  * These names are currently kept for backward compatibility, but
52  * their usage is deprecated.
53  *
54  */
55 
56  /** @name Quantile Functions from MathCore
57  * The implementation is provided in MathCore and for the majority of the function comes from
58  * <A HREF="http://www.netlib.org/cephes">Cephes</A>.
59 
60  */
61 
62  //@{
63 
64 
65 
66  /**
67 
68  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
69  function of the upper tail of the beta distribution
70  (#beta_cdf_c).
71  It is implemented using the function incbi from <A HREF="http://www.netlib.org/cephes">Cephes</A>.
72 
73 
74  @ingroup QuantFunc
75 
76  */
77  double beta_quantile(double x, double a, double b);
78 
79  /**
80 
81  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
82  function of the lower tail of the beta distribution
83  (#beta_cdf).
84  It is implemented using
85  the function incbi from <A HREF="http://www.netlib.org/cephes">Cephes</A>.
86 
87  @ingroup QuantFunc
88 
89  */
90  double beta_quantile_c(double x, double a, double b);
91 
92 
93 
94  /**
95 
96  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
97  function of the upper tail of the Cauchy distribution (#cauchy_cdf_c)
98  which is also called Lorentzian distribution. For
99  detailed description see
100  <A HREF="http://mathworld.wolfram.com/CauchyDistribution.html">
101  Mathworld</A>.
102 
103  @ingroup QuantFunc
104 
105  */
106 
107  double cauchy_quantile_c(double z, double b);
108 
109 
110 
111 
112  /**
113 
114  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
115  function of the lower tail of the Cauchy distribution (#cauchy_cdf)
116  which is also called Breit-Wigner or Lorentzian distribution. For
117  detailed description see
118  <A HREF="http://mathworld.wolfram.com/CauchyDistribution.html">
119  Mathworld</A>. The implementation used is that of
120  <A HREF="http://www.gnu.org/software/gsl/manual/gsl-ref_19.html#SEC294">GSL</A>.
121 
122  @ingroup QuantFunc
123 
124  */
125 
126  double cauchy_quantile(double z, double b);
127 
128 
129 
130 
131  /**
132 
133  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
134  function of the upper tail of the Breit-Wigner distribution (#breitwigner_cdf_c)
135  which is similar to the Cauchy distribution. For
136  detailed description see
137  <A HREF="http://mathworld.wolfram.com/CauchyDistribution.html">
138  Mathworld</A>. It is evaluated using the same implementation of
139  #cauchy_quantile_c.
140 
141  @ingroup QuantFunc
142 
143  */
144 
145  inline double breitwigner_quantile_c(double z, double gamma) {
146  return cauchy_quantile_c(z, gamma/2.0);
147  }
148 
149 
150 
151 
152  /**
153 
154  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
155  function of the lower tail of the Breit_Wigner distribution (#breitwigner_cdf)
156  which is similar to the Cauchy distribution. For
157  detailed description see
158  <A HREF="http://mathworld.wolfram.com/CauchyDistribution.html">
159  Mathworld</A>. It is evaluated using the same implementation of
160  #cauchy_quantile.
161 
162 
163  @ingroup QuantFunc
164 
165  */
166 
167  inline double breitwigner_quantile(double z, double gamma) {
168  return cauchy_quantile(z, gamma/2.0);
169  }
170 
171 
172 
173 
174 
175 
176  /**
177 
178  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
179  function of the upper tail of the \f$\chi^2\f$ distribution
180  with \f$r\f$ degrees of freedom (#chisquared_cdf_c). For detailed description see
181  <A HREF="http://mathworld.wolfram.com/Chi-SquaredDistribution.html">
182  Mathworld</A>. It is implemented using the inverse of the incomplete complement gamma function, using
183  the function igami from <A HREF="http://www.netlib.org/cephes">Cephes</A>.
184 
185  @ingroup QuantFunc
186 
187  */
188 
189  double chisquared_quantile_c(double z, double r);
190 
191 
192 
193  /**
194 
195  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
196  function of the lower tail of the \f$\chi^2\f$ distribution
197  with \f$r\f$ degrees of freedom (#chisquared_cdf). For detailed description see
198  <A HREF="http://mathworld.wolfram.com/Chi-SquaredDistribution.html">
199  Mathworld</A>.
200  It is implemented using chisquared_quantile_c, therefore is not very precise for small z.
201  It is recommended to use the MathMore function (ROOT::MathMore::chisquared_quantile )implemented using GSL
202 
203  @ingroup QuantFunc
204 
205  */
206 
207  double chisquared_quantile(double z, double r);
208 
209 
210 
211  /**
212 
213  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
214  function of the upper tail of the exponential distribution
215  (#exponential_cdf_c). For detailed description see
216  <A HREF="http://mathworld.wolfram.com/ExponentialDistribution.html">
217  Mathworld</A>.
218 
219  @ingroup QuantFunc
220 
221  */
222 
223  double exponential_quantile_c(double z, double lambda);
224 
225 
226 
227 
228  /**
229 
230  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
231  function of the lower tail of the exponential distribution
232  (#exponential_cdf). For detailed description see
233  <A HREF="http://mathworld.wolfram.com/ExponentialDistribution.html">
234  Mathworld</A>.
235 
236  @ingroup QuantFunc
237 
238  */
239 
240  double exponential_quantile(double z, double lambda);
241 
242 
243 
244  /**
245 
246  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
247  function of the lower tail of the f distribution
248  (#fdistribution_cdf). For detailed description see
249  <A HREF="http://mathworld.wolfram.com/F-Distribution.html">
250  Mathworld</A>.
251  It is implemented using the inverse of the incomplete beta function,
252  function incbi from <A HREF="http://www.netlib.org/cephes">Cephes</A>.
253 
254  @ingroup QuantFunc
255 
256  */
257  double fdistribution_quantile(double z, double n, double m);
258 
259  /**
260 
261  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
262  function of the upper tail of the f distribution
263  (#fdistribution_cdf_c). For detailed description see
264  <A HREF="http://mathworld.wolfram.com/F-Distribution.html">
265  Mathworld</A>.
266  It is implemented using the inverse of the incomplete beta function,
267  function incbi from <A HREF="http://www.netlib.org/cephes">Cephes</A>.
268 
269  @ingroup QuantFunc
270  */
271 
272  double fdistribution_quantile_c(double z, double n, double m);
273 
274 
275  /**
276 
277  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
278  function of the upper tail of the gamma distribution
279  (#gamma_cdf_c). For detailed description see
280  <A HREF="http://mathworld.wolfram.com/GammaDistribution.html">
281  Mathworld</A>. The implementation used is that of
282  <A HREF="http://www.gnu.org/software/gsl/manual/gsl-ref_19.html#SEC300">GSL</A>.
283  It is implemented using the function igami taken
284  from <A HREF="http://www.netlib.org/cephes">Cephes</A>.
285 
286  @ingroup QuantFunc
287 
288  */
289 
290  double gamma_quantile_c(double z, double alpha, double theta);
291 
292 
293 
294 
295  /**
296 
297  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
298  function of the lower tail of the gamma distribution
299  (#gamma_cdf). For detailed description see
300  <A HREF="http://mathworld.wolfram.com/GammaDistribution.html">
301  Mathworld</A>.
302  It is implemented using chisquared_quantile_c, therefore is not very precise for small z.
303  For this special cases it is recommended to use the MathMore function ROOT::MathMore::gamma_quantile
304  implemented using GSL
305 
306 
307  @ingroup QuantFunc
308 
309  */
310 
311  double gamma_quantile(double z, double alpha, double theta);
312 
313 
314 
315  /**
316 
317  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
318  function of the upper tail of the normal (Gaussian) distribution
319  (#gaussian_cdf_c). For detailed description see
320  <A HREF="http://mathworld.wolfram.com/NormalDistribution.html">
321  Mathworld</A>. It can also be evaluated using #normal_quantile_c which will
322  call the same implementation.
323 
324  @ingroup QuantFunc
325 
326  */
327 
328  double gaussian_quantile_c(double z, double sigma);
329 
330 
331 
332 
333  /**
334 
335  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
336  function of the lower tail of the normal (Gaussian) distribution
337  (#gaussian_cdf). For detailed description see
338  <A HREF="http://mathworld.wolfram.com/NormalDistribution.html">
339  Mathworld</A>. It can also be evaluated using #normal_quantile which will
340  call the same implementation.
341  It is implemented using the function ROOT::Math::Cephes::ndtri taken from
342  <A HREF="http://www.netlib.org/cephes">Cephes</A>.
343 
344  @ingroup QuantFunc
345 
346  */
347 
348  double gaussian_quantile(double z, double sigma);
349 
350 
351 
352 
353  /**
354 
355  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
356  function of the upper tail of the lognormal distribution
357  (#lognormal_cdf_c). For detailed description see
358  <A HREF="http://mathworld.wolfram.com/LogNormalDistribution.html">
359  Mathworld</A>. The implementation used is that of
360  <A HREF="http://www.gnu.org/software/gsl/manual/gsl-ref_19.html#SEC302">GSL</A>.
361 
362  @ingroup QuantFunc
363 
364  */
365 
366  double lognormal_quantile_c(double x, double m, double s);
367 
368 
369 
370 
371  /**
372 
373  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
374  function of the lower tail of the lognormal distribution
375  (#lognormal_cdf). For detailed description see
376  <A HREF="http://mathworld.wolfram.com/LogNormalDistribution.html">
377  Mathworld</A>. The implementation used is that of
378  <A HREF="http://www.gnu.org/software/gsl/manual/gsl-ref_19.html#SEC302">GSL</A>.
379 
380  @ingroup QuantFunc
381 
382  */
383 
384  double lognormal_quantile(double x, double m, double s);
385 
386 
387 
388 
389  /**
390 
391  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
392  function of the upper tail of the normal (Gaussian) distribution
393  (#normal_cdf_c). For detailed description see
394  <A HREF="http://mathworld.wolfram.com/NormalDistribution.html">
395  Mathworld</A>. It can also be evaluated using #gaussian_quantile_c which will
396  call the same implementation.
397  It is implemented using the function ROOT::Math::Cephes::ndtri taken from
398  <A HREF="http://www.netlib.org/cephes">Cephes</A>.
399 
400  @ingroup QuantFunc
401 
402  */
403 
404  double normal_quantile_c(double z, double sigma);
405  /// alternative name for same function
406  inline double gaussian_quantile_c(double z, double sigma) {
407  return normal_quantile_c(z,sigma);
408  }
409 
410 
411 
412 
413  /**
414 
415  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
416  function of the lower tail of the normal (Gaussian) distribution
417  (#normal_cdf). For detailed description see
418  <A HREF="http://mathworld.wolfram.com/NormalDistribution.html">
419  Mathworld</A>. It can also be evaluated using #gaussian_quantile which will
420  call the same implementation.
421  It is implemented using the function ROOT::Math::Cephes::ndtri taken from
422  <A HREF="http://www.netlib.org/cephes">Cephes</A>.
423 
424 
425  @ingroup QuantFunc
426 
427  */
428 
429  double normal_quantile(double z, double sigma);
430  /// alternative name for same function
431  inline double gaussian_quantile(double z, double sigma) {
432  return normal_quantile(z,sigma);
433  }
434 
435 
436 
437 #ifdef LATER // t quantiles are still in MathMore
438 
439  /**
440 
441  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
442  function of the upper tail of Student's t-distribution
443  (#tdistribution_cdf_c). For detailed description see
444  <A HREF="http://mathworld.wolfram.com/Studentst-Distribution.html">
445  Mathworld</A>. The implementation used is that of
446  <A HREF="http://www.gnu.org/software/gsl/manual/gsl-ref_19.html#SEC305">GSL</A>.
447 
448  @ingroup QuantFunc
449 
450  */
451 
452  double tdistribution_quantile_c(double z, double r);
453 
454 
455 
456 
457  /**
458 
459  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
460  function of the lower tail of Student's t-distribution
461  (#tdistribution_cdf). For detailed description see
462  <A HREF="http://mathworld.wolfram.com/Studentst-Distribution.html">
463  Mathworld</A>. The implementation used is that of
464  <A HREF="http://www.gnu.org/software/gsl/manual/gsl-ref_19.html#SEC305">GSL</A>.
465 
466  @ingroup QuantFunc
467 
468  */
469 
470  double tdistribution_quantile(double z, double r);
471 
472 #endif
473 
474 
475  /**
476 
477  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
478  function of the upper tail of the uniform (flat) distribution
479  (#uniform_cdf_c). For detailed description see
480  <A HREF="http://mathworld.wolfram.com/UniformDistribution.html">
481  Mathworld</A>.
482 
483  @ingroup QuantFunc
484 
485  */
486 
487  double uniform_quantile_c(double z, double a, double b);
488 
489 
490 
491 
492  /**
493 
494  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
495  function of the lower tail of the uniform (flat) distribution
496  (#uniform_cdf). For detailed description see
497  <A HREF="http://mathworld.wolfram.com/UniformDistribution.html">
498  Mathworld</A>.
499 
500  @ingroup QuantFunc
501 
502  */
503 
504  double uniform_quantile(double z, double a, double b);
505 
506 
507 
508 
509  /**
510 
511  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
512  function of the lower tail of the Landau distribution
513  (#landau_cdf).
514 
515  For detailed description see
516  K.S. K&ouml;lbig and B. Schorr, A program package for the Landau distribution,
517  <A HREF="http://dx.doi.org/10.1016/0010-4655(84)90085-7">Computer Phys. Comm. 31 (1984) 97-111</A>
518  <A HREF="http://dx.doi.org/10.1016/j.cpc.2008.03.002">[Erratum-ibid. 178 (2008) 972]</A>.
519  The same algorithms as in
520  <A HREF="https://cern-tex.web.cern.ch/cern-tex/shortwrupsdir/g110/top.html">
521  CERNLIB</A> (RANLAN) is used.
522 
523  @param z The argument \f$z\f$
524  @param xi The width parameter \f$\xi\f$
525 
526  @ingroup QuantFunc
527 
528  */
529 
530  double landau_quantile(double z, double xi = 1);
531 
532 
533  /**
534 
535  Inverse (\f$D^{-1}(z)\f$) of the cumulative distribution
536  function of the upper tail of the landau distribution
537  (#landau_cdf_c).
538  Implemented using #landau_quantile
539 
540  @param z The argument \f$z\f$
541  @param xi The width parameter \f$\xi\f$
542 
543  @ingroup QuantFunc
544 
545  */
546 
547  double landau_quantile_c(double z, double xi = 1);
548 
549 
550 #ifdef HAVE_OLD_STAT_FUNC
551 
552  //@}
553  /** @name Backward compatible functions */
554 
555 
556  inline double breitwigner_prob_inv(double x, double gamma) {
557  return breitwigner_quantile_c(x,gamma);
558  }
559  inline double breitwigner_quant_inv(double x, double gamma) {
560  return breitwigner_quantile(x,gamma);
561  }
562 
563  inline double cauchy_prob_inv(double x, double b) {
564  return cauchy_quantile_c(x,b);
565  }
566  inline double cauchy_quant_inv(double x, double b) {
567  return cauchy_quantile (x,b);
568  }
569 
570  inline double exponential_prob_inv(double x, double lambda) {
571  return exponential_quantile_c(x, lambda );
572  }
573  inline double exponential_quant_inv(double x, double lambda) {
574  return exponential_quantile (x, lambda );
575  }
576 
577  inline double gaussian_prob_inv(double x, double sigma) {
578  return gaussian_quantile_c( x, sigma );
579  }
580  inline double gaussian_quant_inv(double x, double sigma) {
581  return gaussian_quantile ( x, sigma );
582  }
583 
584  inline double lognormal_prob_inv(double x, double m, double s) {
585  return lognormal_quantile_c( x, m, s );
586  }
587  inline double lognormal_quant_inv(double x, double m, double s) {
588  return lognormal_quantile ( x, m, s );
589  }
590 
591  inline double normal_prob_inv(double x, double sigma) {
592  return normal_quantile_c( x, sigma );
593  }
594  inline double normal_quant_inv(double x, double sigma) {
595  return normal_quantile ( x, sigma );
596  }
597 
598  inline double uniform_prob_inv(double x, double a, double b) {
599  return uniform_quantile_c( x, a, b );
600  }
601  inline double uniform_quant_inv(double x, double a, double b) {
602  return uniform_quantile ( x, a, b );
603  }
604 
605  inline double chisquared_prob_inv(double x, double r) {
606  return chisquared_quantile_c(x, r );
607  }
608 
609  inline double gamma_prob_inv(double x, double alpha, double theta) {
610  return gamma_quantile_c (x, alpha, theta );
611  }
612 
613 
614 #endif
615 
616 
617 } // namespace Math
618 } // namespace ROOT
619 
620 
621 
622 #endif // ROOT_Math_QuantFuncMathCore
double normal_quantile(double z, double sigma)
Inverse ( ) of the cumulative distribution function of the lower tail of the normal (Gaussian) distri...
auto * m
Definition: textangle.C:8
Namespace for new ROOT classes and functions.
Definition: StringConv.hxx:21
double normal_quantile_c(double z, double sigma)
Inverse ( ) of the cumulative distribution function of the upper tail of the normal (Gaussian) distri...
double cauchy_quantile(double z, double b)
Inverse ( ) of the cumulative distribution function of the lower tail of the Cauchy distribution (cau...
double uniform_quantile(double z, double a, double b)
Inverse ( ) of the cumulative distribution function of the lower tail of the uniform (flat) distribut...
double gamma_quantile_c(double z, double alpha, double theta)
Inverse ( ) of the cumulative distribution function of the upper tail of the gamma distribution (gamm...
double landau_quantile_c(double z, double xi=1)
Inverse ( ) of the cumulative distribution function of the upper tail of the landau distribution (lan...
Double_t x[n]
Definition: legend1.C:17
double breitwigner_quantile_c(double z, double gamma)
Inverse ( ) of the cumulative distribution function of the upper tail of the Breit-Wigner distributio...
double chisquared_quantile_c(double z, double r)
Inverse ( ) of the cumulative distribution function of the upper tail of the distribution with degr...
double exponential_quantile_c(double z, double lambda)
Inverse ( ) of the cumulative distribution function of the upper tail of the exponential distribution...
double breitwigner_quantile(double z, double gamma)
Inverse ( ) of the cumulative distribution function of the lower tail of the Breit_Wigner distributio...
const Double_t sigma
double cauchy_quantile_c(double z, double b)
Inverse ( ) of the cumulative distribution function of the upper tail of the Cauchy distribution (cau...
double uniform_quantile_c(double z, double a, double b)
Inverse ( ) of the cumulative distribution function of the upper tail of the uniform (flat) distribut...
double gamma(double x)
ROOT::R::TRInterface & r
Definition: Object.C:4
auto * a
Definition: textangle.C:12
double beta_quantile_c(double x, double a, double b)
Inverse ( ) of the cumulative distribution function of the lower tail of the beta distribution (beta_...
static constexpr double s
double tdistribution_quantile(double z, double r)
Inverse ( ) of the cumulative distribution function of the lower tail of Student&#39;s t-distribution (td...
Namespace for new Math classes and functions.
double fdistribution_quantile(double z, double n, double m)
Inverse ( ) of the cumulative distribution function of the lower tail of the f distribution (fdistrib...
double fdistribution_quantile_c(double z, double n, double m)
Inverse ( ) of the cumulative distribution function of the upper tail of the f distribution (fdistrib...
you should not use this method at all Int_t Int_t z
Definition: TRolke.cxx:630
double lognormal_quantile_c(double x, double m, double s)
Inverse ( ) of the cumulative distribution function of the upper tail of the lognormal distribution (...
double landau_quantile(double z, double xi=1)
Inverse ( ) of the cumulative distribution function of the lower tail of the Landau distribution (lan...
double gaussian_quantile(double z, double sigma)
Inverse ( ) of the cumulative distribution function of the lower tail of the normal (Gaussian) distri...
you should not use this method at all Int_t Int_t Double_t Double_t Double_t Int_t Double_t Double_t Double_t Double_t b
Definition: TRolke.cxx:630
double gaussian_quantile_c(double z, double sigma)
Inverse ( ) of the cumulative distribution function of the upper tail of the normal (Gaussian) distri...
double lognormal_quantile(double x, double m, double s)
Inverse ( ) of the cumulative distribution function of the lower tail of the lognormal distribution (...
double gamma_quantile(double z, double alpha, double theta)
Inverse ( ) of the cumulative distribution function of the lower tail of the gamma distribution (gamm...
const Int_t n
Definition: legend1.C:16
double exponential_quantile(double z, double lambda)
Inverse ( ) of the cumulative distribution function of the lower tail of the exponential distribution...
double chisquared_quantile(double z, double r)
Inverse ( ) of the cumulative distribution function of the lower tail of the distribution with degr...
double tdistribution_quantile_c(double z, double r)
Inverse ( ) of the cumulative distribution function of the upper tail of Student&#39;s t-distribution (td...
double beta_quantile(double x, double a, double b)
Inverse ( ) of the cumulative distribution function of the upper tail of the beta distribution (beta_...