[Boost-commit] svn:boost r38650 - in sandbox/math_toolkit/libs/math: doc doc/distributions example

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()