libs/math/doc/sf_and_dist/background.qbk

   1 [section:variates Random Variates and Distribution Parameters]
   2
   3 [@http://en.wikipedia.org/wiki/Random_variate Random variates]
   4 and [@http://en.wikipedia.org/wiki/Parameter distribution parameters]
   5 are conventionally distinguished (for example in Wikipedia and Wolfram MathWorld
   6 by placing a semi-colon after the __random_variate (whose value you 'choose'),
   7 to separate the variate from the parameter(s) that defines the shape of the distribution.
   8
   9 For example, the binomial distribution has two parameters:
  10 n (the number of trials) and p (the probability of success on one trial).
  11 It also has the __random_variate /k/: the number of successes observed.
  12 This means the probability density\/mass function (pdf) is written as ['f(k; n, p)].
  13
  14 Translating this into code the `binomial_distribution` constructor
  15 therefore has two parameters:
  16
  17         binomial_distribution(RealType n, RealType p);
  18
  19 While the function `pdf` has one argument specifying the distribution type
  20 (which includes its parameters, if any),
  21 and a second argument for the __random_variate.  So taking our binomial distribution
  22 example, we would write:
  23
  24         pdf(binomial_distribution<RealType>(n, p), k);
  25
  26 [endsect]
  27
  28 [section:dist_params Discrete Probability Distributions]
  29
  30 Note that the [@http://en.wikipedia.org/wiki/Discrete_probability_distribution
  31 discrete distributions], including the binomial, negative binomial, Poisson & Bernoulli,
  32 are all mathematically defined as discrete functions:
  33 only integral values of the __random_variate are envisaged
  34 and the functions are only defined at these integral values.
  35 However because the method of calculation often uses continuous functions,
  36 it is convenient to treat them as if they were continuous functions,
  37 and permit non-integral values of their parameters.
  38
  39 To enforce a strict mathematical model,
  40 users may use floor or ceil functions on the __random_variate,
  41 prior to calling the distribution function, to enforce integral values.
  42
  43 For similar reasons, in continuous distributions, parameters like degrees of freedom
  44 that might appear to be integral, are treated as real values
  45 (and are promoted from integer to floating-point if necessary).
  46 In this case however, that there are a small number of situations where non-integral
  47 degrees of freedom do have a genuine meaning.
  48
  49 Generally speaking there is no loss of performance from allowing real-values
  50 parameters: the underlying special functions contain optimizations for
  51 integer-valued arguments when applicable.
  52
  53 [caution
  54 The quantile function of a discrete distribution will by
  55 default return an integer result that has been
  56 /rounded outwards/.  That is to say lower quantiles (where the probability is
  57 less than 0.5) are rounded downward, and upper quantiles (where the probability
  58 is greater than 0.5) are rounded upwards.  This behaviour
  59 ensures that if an X% quantile is requested, then /at least/ the requested
  60 coverage will be present in the central region, and /no more than/
  61 the requested coverage will be present in the tails.
  62
  63 This behaviour can be changed so that the quantile functions are rounded
  64 differently, or even return a real-valued result using
  65 [link math_toolkit.policy.pol_overview Policies].  It is strongly
  66 recommended that you read the tutorial
  67 [link math_toolkit.policy.pol_tutorial.understand_dis_quant
  68 Understanding Quantiles of Discrete Distributions] before
  69 using the quantile function on a discrete distribution.  The
  70 [link math_toolkit.policy.pol_ref.discrete_quant_ref reference docs]
  71 describe how to change the rounding policy
  72 for these distributions.
  73 ]
  74
  75 [endsect]
  76
  77 [/
  78   Copyright 2006 John Maddock and Paul A. Bristow.
  79   Distributed under the Boost Software License, Version 1.0.
  80   (See accompanying file LICENSE_1_0.txt or copy at
  81   http://www.boost.org/LICENSE_1_0.txt).
  82 ]
  83
  84