libs/math/doc/distributions/triangular.qbk

   1 [section:triangular_dist Triangular Distribution]
   2
   3
   4 ``#include <boost/math/distributions/triangular.hpp>``
   5
   6    namespace boost{ namespace math{
   7     template <class RealType = double,
   8               class ``__Policy``   = ``__policy_class`` >
   9     class triangular_distribution;
  10
  11     typedef triangular_distribution<> triangular;
  12
  13     template <class RealType, class ``__Policy``>
  14     class triangular_distribution
  15     {
  16     public:
  17        typedef RealType value_type;
  18        typedef Policy   policy_type;
  19
  20        triangular_distribution(RealType lower = -1, RealType mode = 0) RealType upper = 1); // Constructor.
  21           : m_lower(lower), m_mode(mode), m_upper(upper) // Default is -1, 0, +1 symmetric triangular distribution.
  22        // Accessor functions.
  23        RealType lower()const;
  24        RealType mode()const;
  25        RealType upper()const;
  26     }; // class triangular_distribution
  27
  28    }} // namespaces
  29
  30 The [@http://en.wikipedia.org/wiki/Triangular_distribution triangular distribution]
  31 is a [@http://en.wikipedia.org/wiki/Continuous_distribution continuous]
  32 [@http://en.wikipedia.org/wiki/Probability_distribution probability distribution]
  33 with a lower limit a,
  34 [@http://en.wikipedia.org/wiki/Mode_%28statistics%29 mode c],
  35 and upper limit b.
  36
  37 The triangular distribution is often used where the distribution is only vaguely known,
  38 but, like the [@http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29 uniform distribution],
  39 upper and limits are 'known', but a 'best guess', the mode or center point, is also added.
  40 It has been recommended as a
  41 [@http://www.worldscibooks.com/mathematics/etextbook/5720/5720_chap1.pdf proxy for the beta distribution.]
  42 The distribution is used in business decision making and project planning.
  43
  44 The [@http://en.wikipedia.org/wiki/Triangular_distribution triangular distribution]
  45 is a distribution with the
  46 [@http://en.wikipedia.org/wiki/Probability_density_function probability density function]:
  47
  48 [expression f(x) = 2(x-a)/(b-a) (c-a) [sixemspace]  for a <= x <= c]
  49 [expression f(x) = 2(b-x)/(b-a) (b-c) [sixemspace] for c < x <= b]
  50
  51 Parameter ['a] (lower) can be any finite value.
  52 Parameter ['b] (upper) can be any finite value > a (lower).
  53 Parameter ['c] (mode) a <= c <= b.  This is the most probable value.
  54
  55 The [@http://en.wikipedia.org/wiki/Random_variate random variate] x must also be finite, and is supported lower <= x <= upper.
  56
  57 The triangular distribution may be appropriate when an assumption of a normal distribution
  58 is unjustified because uncertainty is caused by rounding and quantization from analog to digital conversion.
  59 Upper and lower limits are known, and the most probable value lies midway.
  60
  61 The distribution simplifies when the 'best guess' is either the lower or upper limit - a 90 degree angle triangle.
  62 The 001 triangular distribution which expresses an estimate that the lowest value is the most likely;
  63 for example, you believe that the next-day quoted delivery date is most likely
  64 (knowing that a quicker delivery is impossible - the postman only comes once a day),
  65 and that longer delays are decreasingly likely,
  66 and delivery is assumed to never take more than your upper limit.
  67
  68 The following graph illustrates how the
  69 [@http://en.wikipedia.org/wiki/Probability_density_function probability density function PDF]
  70 varies with the various parameters:
  71
  72 [graph triangular_pdf]
  73
  74 and cumulative distribution function
  75
  76 [graph triangular_cdf]
  77
  78 [h4 Member Functions]
  79
  80    triangular_distribution(RealType lower = 0, RealType mode = 0 RealType upper = 1);
  81
  82 Constructs a [@http://en.wikipedia.org/wiki/triangular_distribution triangular distribution]
  83 with lower  /lower/ (a) and upper /upper/ (b).
  84
  85 Requires that the /lower/, /mode/ and /upper/ parameters are all finite,
  86 otherwise calls __domain_error.
  87
  88 [warning These constructors are slightly different from the analogs provided by __Mathworld
  89 [@http://reference.wolfram.com/language/ref/TriangularDistribution.html Triangular distribution],
  90 where
  91
  92 [^TriangularDistribution\[{min, max}\]]  represents a [*symmetric] triangular statistical distribution giving values between min and max.[br]
  93 [^TriangularDistribution\[\]] represents a [*symmetric] triangular statistical distribution giving values between 0 and 1.[br]
  94 [^TriangularDistribution\[{min, max}, c\]] represents a triangular distribution with mode at c (usually [*asymmetric]).[br]
  95
  96 So, for example, to compute a variance using __WolframAlpha, use
  97 [^N\[variance\[TriangularDistribution{1, +2}\], 50\]]
  98 ]
  99
 100 The parameters of a distribution can be obtained using these member functions:
 101
 102    RealType lower()const;
 103
 104 Returns the ['lower] parameter of this distribution (default -1).
 105
 106    RealType mode()const;
 107
 108 Returns the ['mode] parameter of this distribution (default 0).
 109
 110    RealType upper()const;
 111
 112 Returns the ['upper] parameter of this distribution (default+1).
 113
 114 [h4 Non-member Accessors]
 115
 116 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] that are generic to all
 117 distributions are supported: __usual_accessors.
 118
 119 The domain of the random variable is \lower\ to \upper\,
 120 and the supported range is lower <= x <= upper.
 121
 122 [h4 Accuracy]
 123
 124 The triangular distribution is implemented with simple arithmetic operators and so should have errors within an epsilon or two,
 125 except quantiles with arguments nearing the extremes of zero and unity.
 126
 127 [h4 Implementation]
 128
 129 In the following table, a is the /lower/ parameter of the distribution,
 130 c is the /mode/ parameter,
 131 b is the /upper/ parameter,
 132 /x/ is the random variate, /p/ is the probability and /q = 1-p/.
 133
 134 [table
 135 [[Function][Implementation Notes]]
 136 [[pdf][Using the relation: pdf = 0 for x < mode, 2(x-a)\/(b-a)(c-a) else 2*(b-x)\/((b-a)(b-c))]]
 137 [[cdf][Using the relation: cdf = 0 for x < mode (x-a)[super 2]\/((b-a)(c-a)) else 1 - (b-x)[super 2]\/((b-a)(b-c))]]
 138 [[cdf complement][Using the relation: q = 1 - p ]]
 139 [[quantile][let p0 = (c-a)\/(b-a) the point of inflection on the cdf,
 140 then given probability p and q = 1-p:
 141
 142 x = sqrt((b-a)(c-a)p) + a ; for p < p0
 143
 144 x = c                     ; for p == p0
 145
 146 x = b - sqrt((b-a)(b-c)q) ; for p > p0
 147
 148 (See [@../../../../boost/math/distributions/triangular.hpp /boost/math/distributions/triangular.hpp] for details.)]]
 149 [[quantile from the complement][As quantile (See [@../../../../boost/math/distributions/triangular.hpp /boost/math/distributions/triangular.hpp] for details.)]]
 150 [[mean][(a + b + 3) \/ 3 ]]
 151 [[variance][(a[super 2]+b[super 2]+c[super 2] - ab - ac - bc)\/18]]
 152 [[mode][c]]
 153 [[skewness][(See [@../../../../boost/math/distributions/triangular.hpp /boost/math/distributions/triangular.hpp] for details). ]]
 154 [[kurtosis][12\/5]]
 155 [[kurtosis excess][-3\/5]]
 156 ]
 157
 158 Some 'known good' test values were obtained using __WolframAlpha.
 159
 160 [h4 References]
 161
 162 * [@http://en.wikipedia.org/wiki/Triangular_distribution Wikpedia triangular distribution]
 163 * [@http://mathworld.wolfram.com/TriangularDistribution.html Weisstein, Eric W. "Triangular Distribution." From MathWorld--A Wolfram Web Resource.]
 164 * Evans, M.; Hastings, N.; and Peacock, B. "Triangular Distribution." Ch. 40 in Statistical Distributions, 3rd ed. New York: Wiley, pp. 187-188, 2000, ISBN - 0471371246.
 165 * [@http://www.measurement.sk/2002/S1/Wimmer2.pdf Gejza Wimmer, Viktor Witkovsky and Tomas Duby,
 166 Measurement Science Review, Volume 2, Section 1, 2002, Proper Rounding Of The Measurement Results Under The Assumption Of Triangular Distribution.]
 167
 168 [endsect][/section:triangular_dist triangular]
 169
 170 [/
 171   Copyright 2006 John Maddock and Paul A. Bristow.
 172   Distributed under the Boost Software License, Version 1.0.
 173   (See accompanying file LICENSE_1_0.txt or copy at
 174   http://www.boost.org/LICENSE_1_0.txt).
 175 ]
 176