From: john_at_[hidden]
Date: 2007-08-14 06:45:41
Author: johnmaddock
Date: 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
New Revision: 38650
URL: http://svn.boost.org/trac/boost/changeset/38650
Log:
Fixed a few typos.
Added more information and links to discrete-distribution-quantiles tutorial.
Added more quickbook mark-up to example/distribution_construction.cpp to (hopefully) aid readability.
Text files modified:
sandbox/math_toolkit/libs/math/doc/background.qbk | 22 ++++++
sandbox/math_toolkit/libs/math/doc/dist_tutorial.qbk | 39 +++++++---
sandbox/math_toolkit/libs/math/doc/distributions/binomial.qbk | 1
sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial.qbk | 4
sandbox/math_toolkit/libs/math/doc/distributions/poisson.qbk | 2
sandbox/math_toolkit/libs/math/doc/math.qbk | 29 ++++++++
sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk | 24 +++++
sandbox/math_toolkit/libs/math/example/distribution_construction.cpp | 143 ++++++++++++++++++++++++++-------------
8 files changed, 199 insertions(+), 65 deletions(-)
Modified: sandbox/math_toolkit/libs/math/doc/background.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/background.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/background.qbk 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
@@ -51,6 +51,28 @@
parameters: the underlying special functions contain optimizations for
integer-valued arguments when applicable.
+[caution
+The quantile function of a discrete distribution will by
+default return an integer result that has been
+/rounded outwards/. That is to say lower quantiles (where the probability is
+less than 0.5) are rounded downward, and upper quantiles (where the probability
+is greater than 0.5) are rounded upwards. This behaviour
+ensures that if an X% quantile is requested, then /at least/ the requested
+coverage will be present in the central region, and /no more than/
+the requested coverage will be present in the tails.
+
+This behaviour can be changed so that the quantile functions are rounded
+differently, or even return a real-valued result using
+[link math_toolkit.policy.pol_overview Policies]. It is strongly
+recommended that you read the tutorial
+[link math_toolkit.policy.pol_tutorial.understand_dis_quant
+Understanding Quantiles of Discrete Distributions] before
+using the quantile function on a discrete distribution. The
+[link math_toolkit.policy.pol_ref.discrete_quant_ref reference docs]
+describe how to change the rounding policy
+for these distributions.
+]
+
[endsect]
Modified: sandbox/math_toolkit/libs/math/doc/dist_tutorial.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/dist_tutorial.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/dist_tutorial.qbk 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
@@ -31,7 +31,10 @@
Each kind of distribution in this library is a class type.
-[link math_toolkit.policy Policies] provide fine-grained control of their behaviour.]
+[link math_toolkit.policy Policies] provide fine-grained control
+of the behaviour of these classes, allowing the user to customise
+behaviour such as how errors are handled, or how the quantiles
+of discrete distribtions behave.
[tip If you are familiar with statistics libraries using functions,
and 'Distributions as Objects' seem alien, see
@@ -189,19 +192,29 @@
or `ceil` functions on the random variate prior to calling the distribution
function.
-TODO: this still needs rewriting, we don't return a real value any more but an integer result!
+The quantile functions for these distributions are hard to specify
+in a manner that will satisfy everyone all of the time. The default
+behaviour is to return an integer result, that has been rounded
+/outwards/: that is to say, lower quantiles - where the probablity
+is less than 0.5 are rounded down, while upper quantiles - where
+the probability is greater than 0.5 - are rounded up. This behaviour
+ensures that if an X% quantile is requested, then /at least/ the requested
+coverage will be present in the central region, and /no more than/
+the requested coverage will be present in the tails.
+
+This behaviour can be changed so that the quantile functions are rounded
+differently, or return a real-valued result using
+[link math_toolkit.policy.pol_overview Policies]. It is strongly
+recommended that you read the tutorial
+[link math_toolkit.policy.pol_tutorial.understand_dis_quant
+Understanding Quantiles of Discrete Distributions] before
+using the quantile function on a discrete distribtion. The
+[link math_toolkit.policy.pol_ref.discrete_quant_ref reference docs]
+describe how to change the rounding policy
+for these distributions.
-Likewise the `quantile` function will return a real value: users should use
-either the `floor` or `ceil` functions to convert the result to the nearest
-integer. However, whether it makes more sense to take the floor or the
-ceiling of the result, depends both on the distribution, and the particular
-use case. So some common sense needs to be applied as well!
-
-[link math_toolkit.policy.pol_overview Policies] provide a specific method of controlling
-the behaviour of any or all the discrete distributions using
-[link math_toolkit.policy.pol_ref.discrete_quant_ref policies].
-
-For similar reasons continuous distributions with parameters like "degrees of freedom"
+For similar reasons continuous distributions with parameters like
+"degrees of freedom"
that might appear to be integral, are treated as real values
(and are promoted from integer to floating-point if necessary).
In this case however, there are a small number of situations where non-integral
Modified: sandbox/math_toolkit/libs/math/doc/distributions/binomial.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/binomial.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/binomial.qbk 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
@@ -83,6 +83,7 @@
[$../graphs/binomial_pdf_2.png]
+[discrete_quantile_warning Binomial]
[h4 Member Functions]
Modified: sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial.qbk 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
@@ -93,7 +93,8 @@
The Poisson distribution is a generalization of the Pascal distribution,
where the success parameter r is an integer: to obtain the Pascal
distribution you must ensure that an integer value is provided for r,
-and take integer values (floor or ceiling) from functions like quantile that return successes.
+and take integer values (floor or ceiling) from functions that return
+a number of successes.
For large values of r (successes), the negative binomial distribution
converges to the Poisson distribution.
@@ -107,6 +108,7 @@
poisson([lambda]) = lim [sub r [rarr] [infin]] [space] negative_binomial(r, r / ([lambda] + r)))
+[discrete_quantile_warning Negative Binomial]
[h4 Member Functions]
Modified: sandbox/math_toolkit/libs/math/doc/distributions/poisson.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/poisson.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/poisson.qbk 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
@@ -43,6 +43,8 @@
[$../graphs/poisson.png]
+[discrete_quantile_warning Poisson]
+
[h4 Member Functions]
poisson_distribution(RealType mean = 1);
Modified: sandbox/math_toolkit/libs/math/doc/math.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/math.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/math.qbk 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
@@ -208,6 +208,35 @@
what level of precision to use etc. Refer to the
[link math_toolkit.policy policy documentation for more details].]
+[template discrete_quantile_warning[NAME]
+[caution
+The [NAME] distribution is a discrete distribution: internally
+functions like the `cdf` and `pdf` are treated "as if" they are continuous
+functions, but in reality the results returned from these functions
+only have meaning if an integer value is provided for the random variate
+argument.
+
+The quantile function will by default return an integer result that has been
+/rounded outwards/. That is to say lower quantiles (where the probability is
+less than 0.5) are rounded downward, and upper quantiles (where the probability
+is greater than 0.5) are rounded upwards. This behaviour
+ensures that if an X% quantile is requested, then /at least/ the requested
+coverage will be present in the central region, and /no more than/
+the requested coverage will be present in the tails.
+
+This behaviour can be changed so that the quantile functions are rounded
+differently, or even return a real-valued result using
+[link math_toolkit.policy.pol_overview Policies]. It is strongly
+recommended that you read the tutorial
+[link math_toolkit.policy.pol_tutorial.understand_dis_quant
+Understanding Quantiles of Discrete Distributions] before
+using the quantile function on the [NAME] distribution. The
+[link math_toolkit.policy.pol_ref.discrete_quant_ref reference docs]
+describe how to change the rounding policy
+for these distributions.
+]
+]
+
[section:intro About the Math Toolkit]
This library is divided into three interconnected parts:
Modified: sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
@@ -50,9 +50,27 @@
more precision than double.]]
[[Precision of Approximation Used][By default uses an approximation that
will result in the lowest level of error for the type of the result.]]
-[[Behaviour of Discrete Quantiles][Returns an integer result that is rounded
- down for lower quantiles and rounded up for upper quantiles by default
- but see - __math_discrete on other policies.]]
+[[Behaviour of Discrete Quantiles]
+ [
+ The quantile function will by default return an integer result that has been
+ /rounded outwards/. That is to say lower quantiles (where the probability is
+ less than 0.5) are rounded downward, and upper quantiles (where the probability
+ is greater than 0.5) are rounded upwards. This behaviour
+ ensures that if an X% quantile is requested, then /at least/ the requested
+ coverage will be present in the central region, and /no more than/
+ the requested coverage will be present in the tails.
+
+This behaviour can be changed so that the quantile functions are rounded
+ differently, or even return a real-valued result using
+ [link math_toolkit.policy.pol_overview Policies]. It is strongly
+ recommended that you read the tutorial
+ [link math_toolkit.policy.pol_tutorial.understand_dis_quant
+ Understanding Quantiles of Discrete Distributions] before
+ using the quantile function on a discrete distribution. The
+ [link math_toolkit.policy.pol_ref.discrete_quant_ref reference docs]
+ describe how to change the rounding policy
+ for these distributions.
+]]
]
What's more, if you define your own policy type, then it automatically
Modified: sandbox/math_toolkit/libs/math/example/distribution_construction.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/distribution_construction.cpp (original)
+++ sandbox/math_toolkit/libs/math/example/distribution_construction.cpp 2007-08-14 06:45:40 EDT (Tue, 14 Aug 2007)
@@ -44,58 +44,100 @@
int main()
{
- // First, a negative binomial distribution with 8 successes
- // and a success fraction 0.25, 25% or 1 in 4, is constructed like this:
+ /*`
+ First, a negative binomial distribution with 8 successes
+ and a success fraction 0.25, 25% or 1 in 4, is constructed like this:
+ */
boost::math::negative_binomial_distribution<double> mydist0(8., 0.25);
- // But this is inconveniently long, so by writing
+ /*`
+ But this is inconveniently long, so by writing
+ */
using namespace boost::math;
- // or
+ /*`
+ or
+ */
using boost::math::negative_binomial_distribution;
- // we can reduce typing.
+ /*`
+ we can reduce typing.
- // Since the vast majority of applications use double,
- // the RealType default is chosen to be double, so we can also write:
+ Since the vast majority of applications use double,
+ the RealType default is chosen to be double, so we can also write:
+ */
negative_binomial_distribution<> mydist9(8., 0.25); // Uses default RealType = double.
- // But the name "negative_binomial_distribution" is still inconveniently long,
- // so for most distributions, a typedef is provided, for example:
- // typedef negative_binomial_distribution<double> negative_binomial; // Reserved name of type double.
- // (Unless a clash would occur with the name of a function, for example gamma & beta)
- // So, after a using statement,
+ /*`
+ But the name "negative_binomial_distribution" is still inconveniently long,
+ so for most distributions, a conveniance typedef is provided, for example:
+
+ typedef negative_binomial_distribution<double> negative_binomial; // Reserved name of type double.
+
+ [caution
+ This convenience typedef is /not/ provided if a clash would occur
+ with the name of a function: currently only "beta" and "gamma"
+ fall into this category.
+ ]
+
+ So, after a using statement,
+ */
+
using boost::math::negative_binomial;
- // we have a convenient reference to negative_binomial_distribution<double> thus:
- negative_binomial mydist(8., 0.25); //
+
+ /*`
+ we have a convenient reference to negative_binomial_distribution<double> thus:
+ */
+ negative_binomial mydist(8., 0.25);
- // Some more examples using the provided convenience typedef:
+ /*`
+ Some more examples using the provided convenience typedef:
+ */
negative_binomial mydist10(5., 0.4); // Both arguments double.
- // And automatic conversion takes place, so you can use integers and floats:
+ /*`
+ And automatic conversion takes place, so you can use integers and floats:
+ */
negative_binomial mydist11(5, 0.4); // Using provided typedef double, int and double arguments.
- // This is probably the most common usage.
+ /*`
+ This is probably the most common usage.
+ */
negative_binomial mydist12(5., 0.4F); // Double and float arguments.
negative_binomial mydist13(5, 1); // Both arguments integer.
- // Similarly for most other distributions like the binomial.
+ /*`
+ Similarly for most other distributions like the binomial.
+ */
binomial mybinomial(1, 0.5); // is more concise than
binomial_distribution<> mybinomd1(1, 0.5);
- // For cases when the typdef distribution name would clash with a math special function
- // (for example: beta and gamma)
- // the typedef is deliberately not provided, and the longer version(s) must be used.
- // For example:
- using boost::math::beta;
- // NOT beta mybetad0(1, 0.5); because beta is a math FUNCTION!
- // error C2146: syntax error : missing ';' before identifier 'mybetad0'
- // warning C4551: function call missing argument list
- // error C3861: 'mybetad0': identifier not found
- // Instead use:
+ /*`
+ For cases when the typdef distribution name would clash with a math special function
+ (currently only beta and gamma)
+ the typedef is deliberately not provided, and the longer version of the name
+ must be used. For example do not use:
+
+ using boost::math::beta;
+ beta mybetad0(1, 0.5); // Error beta is a math FUNCTION!
+
+ Which produces the error messages:
+
+ [pre
+ error C2146: syntax error : missing ';' before identifier 'mybetad0'
+ warning C4551: function call missing argument list
+ error C3861: 'mybetad0': identifier not found
+ ]
+
+ Instead you should use:
+ */
using boost::math::beta_distribution;
beta_distribution<> mybetad1(1, 0.5);
- // or for the gamm distribution:
+ /*`
+ or for the gamma distribution:
+ */
gamma_distribution<> mygammad1(1, 0.5);
- // We can, of course, still provide the type explicitly thus:
+ /*`
+ We can, of course, still provide the type explicitly thus:
+ */
negative_binomial_distribution<double> mydist1(8., 0.25); // Explicit double.
negative_binomial_distribution<float> mydist2(8., 0.25); // Explicit float, double arguments -> float.
negative_binomial_distribution<float> mydist3(8, 0.25); // Explicit float, integer & double arguments -> float.
@@ -103,24 +145,29 @@
negative_binomial_distribution<float> mydist5(8, 1); // Explicit integer, integer arguments -> float.
negative_binomial_distribution<double> mydist6(8., 0.25); // Explicit double.
negative_binomial_distribution<long double> mydist7(8., 0.25); // Explicit long double.
- // And if you have your own RealType called MyFPType,
- // for example NTL quad_float (128-bit floating-point), then:
- // negative_binomial_distribution<MyFPType> mydist6(8, 1); // Integer arguments -> MyFPType.
-
- /*`
- Default arguments to distribution constructors.
- */
- // Note that default constructor arguments are only provided for some distributions.
- // So if you wrongly assume a default argument you will get an error message, for example:
- // negative_binomial_distribution<> mydist8;
- // error C2512 no appropriate default constructor available.
-
- // No default constructors are provided for the negative binomial,
- // because it is difficult to chose any sensible default values for this distribution.
- // For other distributions, like the normal distribution,
- // it is obviously very useful to provide 'standard'
- // defaults for the mean and standard deviation thus:
- // normal_distribution(RealType mean = 0, RealType sd = 1)
+ /*`
+ And if you have your own RealType called MyFPType,
+ for example NTL RR (an arbitrary precision type), then we can write:
+
+ negative_binomial_distribution<MyFPType> mydist6(8, 1); // Integer arguments -> MyFPType.
+
+ [heading Default arguments to distribution constructors.]
+
+ Note that default constructor arguments are only provided for some distributions.
+ So if you wrongly assume a default argument you will get an error message, for example:
+
+ negative_binomial_distribution<> mydist8;
+
+ [pre error C2512 no appropriate default constructor available.]
+
+ No default constructors are provided for the negative binomial,
+ because it is difficult to chose any sensible default values for this distribution.
+ For other distributions, like the normal distribution,
+ it is obviously very useful to provide 'standard'
+ defaults for the mean and standard deviation thus:
+
+ normal_distribution(RealType mean = 0, RealType sd = 1);
+ */
return 0;
} // int main()