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

From: john_at_[hidden]
Date: 2007-08-23 13:46:52

Author: johnmaddock
Date: 2007-08-23 13:46:50 EDT (Thu, 23 Aug 2007)
New Revision: 38865
URL: http://svn.boost.org/trac/boost/changeset/38865

Log:
Some typo fixes, changes layout to prevent overflow of code blocks, plus some editorial changes to try and make the descriptions/layout as clear as possible.
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/distributions/binomial_coinflip_example.qbk |     4 ++                                      
   sandbox/math_toolkit/libs/math/doc/distributions/binomial_example.qbk          |     4 ++                                      
   sandbox/math_toolkit/libs/math/example/binomial_coinflip_example.cpp           |    56 +++++++++++++++++++++++++++------------ 
   sandbox/math_toolkit/libs/math/example/distribution_construction.cpp           |    45 ++++++++++++++++++++++++-------         
   4 files changed, 78 insertions(+), 31 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/distributions/binomial_coinflip_example.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/binomial_coinflip_example.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/binomial_coinflip_example.qbk	2007-08-23 13:46:50 EDT (Thu, 23 Aug 2007)
@@ -4,6 +4,8 @@
 [binomial_coinflip_example1]
 
 See [@../../example/binomial_coinflip_example.cpp binomial_coinflip_example.cpp]
-for full source code and output.
+for full source code the program output looks like this:
+
+[binomial_coinflip_example_output]
 
 [endsect] [/section:binomial_coinflip_example_example Binomial Coin-Flipping example]

Modified: sandbox/math_toolkit/libs/math/doc/distributions/binomial_example.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/binomial_example.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/binomial_example.qbk	2007-08-23 13:46:50 EDT (Thu, 23 Aug 2007)
@@ -8,7 +8,9 @@
 [binomial_coinflip_example1]
 
 See [@../../example/binomial_coinflip_example.cpp binomial_coinflip_example.cpp]
-for full source code and output.
+for full source code, the program output looks like this:
+
+[binomial_coinflip_example_output]
 
 [endsect] [/section:binomial_quiz_example_example Binomial Quiz example]
 

Modified: sandbox/math_toolkit/libs/math/example/binomial_coinflip_example.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/binomial_coinflip_example.cpp	(original)
+++ sandbox/math_toolkit/libs/math/example/binomial_coinflip_example.cpp	2007-08-23 13:46:50 EDT (Thu, 23 Aug 2007)
@@ -55,15 +55,19 @@
 {
   cout << "Using Binomial distribution to predict how many heads and tails." << endl;
   try
-  { // (See note with the catch block about why a try'n'catch is a good idea).
+  { 
 /*`
-First, construct a binomial distribution with parameters success_fraction 1/2, and how many flips.
+See note [link binomial_coinflip_example_catch_block
+with the catch block] about why a try and catch block is always a good idea.
+
+First, construct a binomial distribution with parameters success_fraction 
+1/2, and how many flips.
 */
     const double success_fraction = 0.5; // = 50% = 1/2 for a 'fair' coin.
     int flips = 10; 
     binomial flip(flips, success_fraction);
 
-    cout.precision(4); // Might be able to calculate an appropriate precision from how many flips?
+    cout.precision(4);
 /*`
  Then some examples of using Binomial moments (and echoing the parameters).
 */
@@ -79,7 +83,7 @@
     // if success_fraction is exactly one half,
     // for example, when flipping 'fair' coins.
     cout << "Skewness if success_fraction is " << flip.success_fraction()
-      << " is " << skewness(flip) << endl; // Expect zero for a 'fair' coin.
+      << " is " << skewness(flip) << endl << endl; // Expect zero for a 'fair' coin.
 /*`
 Now we show a variety of predictions on the probability of heads:
 */
@@ -87,7 +91,7 @@
     cout << "Probability of getting no heads is " << pdf(flip, 0) << endl;
     cout << "Probability of getting at least one head is " << 1. - pdf(flip, 0) << endl;
 /*`
-But this last complement may be inaccurate, so better to use either of
+When we want to calculate the probabilty for a range or values we can sum the PDF's:
 */
     cout << "Probability of getting 0 or 1 heads is "
       << pdf(flip, 0) + pdf(flip, 1) << endl; // sum of exactly == probabilities
@@ -105,6 +109,11 @@
 */
     cout << "Probability of getting 9 or 10 heads is " << cdf(complement(flip, 8)) << endl;
 /*`
+Since the subtraction may involve 
+[@http://docs.sun.com/source/806-3568/ncg_goldberg.html cancellation error], 
+where as `cdf(complement(flip, 8))`
+does not use such a subtraction internally, and so does not exhibit the problem.
+
 To get the probability for a range of heads, we can either add the pdfs for each number of heads
 */
     cout << "Probability of between 4 and 6 heads (4 or 5 or 6) is "
@@ -132,7 +141,7 @@
     for (int successes = 0; successes <= flips; successes++) 
     { // Say success means getting a head (or equally success means getting a tail).
       double probability = pdf(flip, successes);
-      cout << setw(2) << successes << "     " << left << setw(10) 
+      cout << left << setw(2) << successes << "     " << setw(10) 
         << probability << " or 1 in " << 1. / probability
         << ", or " << probability * 100. << "%" << endl;
     } // for i
@@ -153,11 +162,17 @@
 */
   }
   catch(const std::exception& e)
-  { // Always useful to include try & catch blocks because
-    // default policies are to throw exceptions on arguments that cause
-    // errors like underflow, overflow. 
-    // Lacking try & catch blocks, the program will abort without a message below,
-    // which may give some helpful clues as to the cause of the exception.
+  {
+    /*` 
+    [#binomial_coinflip_example_catch_block]
+    It is always essential to include try & catch blocks because
+    default policies are to throw exceptions on arguments that 
+    are out of domain or cause errors like numeric-overflow.
+
+    Lacking try & catch blocks, the program will abort, whereas the
+    message below from the thrown exception will give some helpful 
+    clues as to the cause of the problem.
+    */
     std::cout <<
       "\n""Message from thrown exception was:\n   " << e.what() << std::endl;
   }
@@ -165,10 +180,12 @@
   return 0;
 } // int main()
 
-/*
+// Output:
 
-Output:
+//[binomial_coinflip_example_output
+/*`
 
+[pre
 Using Binomial distribution to predict how many heads and tails.
 From 10 one can expect to get on average 5 heads (or tails).
 Mode is 5
@@ -176,7 +193,8 @@
 So about 2/3 will lie within 1 standard deviation and get between 4 and 6 correct.
 Skewness is 0
 Skewness if success_fraction is 0.5 is 0
-For 10 coin flips: 
+
+For 10 coin flips:
 Probability of getting no heads is 0.0009766
 Probability of getting at least one head is 0.999
 Probability of getting 0 or 1 heads is 0.01074
@@ -184,11 +202,12 @@
 Probability of getting 9 or 10 heads is 0.01074
 Probability of getting 9 or 10 heads is 0.01074
 Probability of getting 9 or 10 heads is 0.01074
-Probability of between 4 and 6 heads (4 or 5 or 6) is 0.6563
+Probability of between 4 and 6 heads (4 or 5 or 6) is 0.6562
 Probability of between 4 and 6 heads (4 or 5 or 6) is 0.6563
 Probability of between 3 and 7 heads (3, 4, 5, 6 or 7) is 0.8906
+
 Probability of getting exactly (==) heads
- 0     0.0009766  or 1 in 1024, or 0.09766%
+0      0.0009766  or 1 in 1024, or 0.09766%
 1      0.009766   or 1 in 102.4, or 0.9766%
 2      0.04395    or 1 in 22.76, or 4.395%
 3      0.1172     or 1 in 8.533, or 11.72%
@@ -199,6 +218,7 @@
 8      0.04395    or 1 in 22.76, or 4.395%
 9      0.009766   or 1 in 102.4, or 0.9766%
 10     0.0009766  or 1 in 1024, or 0.09766%
+
 Probability of getting upto (<=) heads
 0         0.0009766  or 1 in 1024, or 0.09766%
 1         0.01074    or 1 in 93.09, or 1.074%
@@ -211,6 +231,6 @@
 8         0.9893     or 1 in 1.011, or 98.93%
 9         0.999      or 1 in 1.001, or 99.9%
 10        1          or 1 in 1, or 100%
-
+]
 */
-
+//][/binomial_coinflip_example_output]

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-23 13:46:50 EDT (Thu, 23 Aug 2007)
@@ -61,8 +61,9 @@
   /*`
   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 will be using double precision,
+  the template argument to the distribution (RealType) defaults
+  to type double, so we can also write:
   */
 
   negative_binomial_distribution<> mydist9(8., 0.25); // Uses default RealType = double.
@@ -85,12 +86,12 @@
   using boost::math::negative_binomial;
   
   /*`
-  we have a convenient reference to negative_binomial_distribution<double> thus:
+  we have a convenient typedef to `negative_binomial_distribution<double>`:
   */
   negative_binomial mydist(8., 0.25);
 
   /*`
-  Some more examples using the provided convenience typedef:
+  Some more examples using the convenience typedef:
   */
   negative_binomial mydist10(5., 0.4); // Both arguments double.
   /*`
@@ -138,13 +139,28 @@
   /*`
   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.
-  negative_binomial_distribution<float>  mydist4(8.F, 0.25F); // Explicit float, float arguments, no conversion.
-  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.
+  
+  // Explicit double precision:
+  negative_binomial_distribution<double>        mydist1(8., 0.25); 
+
+  // Explicit float precision, double arguments are truncated to float:
+  negative_binomial_distribution<float>         mydist2(8., 0.25);
+
+  // Explicit float precision, integer & double arguments converted to float.
+  negative_binomial_distribution<float>         mydist3(8, 0.25); 
+
+  // Explicit float precision, float arguments, so no conversion:
+  negative_binomial_distribution<float>         mydist4(8.F, 0.25F); 
+
+  // Explicit float precision, integer arguments promoted to float.
+  negative_binomial_distribution<float>         mydist5(8, 1); 
+
+  // Explicit double precision:
+  negative_binomial_distribution<double>        mydist6(8., 0.25); 
+
+  // Explicit long double precision:
+  negative_binomial_distribution<long double>   mydist7(8., 0.25); 
+
   /*`
   And if you have your own RealType called MyFPType,
   for example NTL RR (an arbitrary precision type), then we can write:
@@ -167,7 +183,14 @@
   defaults for the mean and standard deviation thus:
   
       normal_distribution(RealType mean = 0, RealType sd = 1);
+
+  So in this case we can write:
   */
+  using boost::math::normal;
+  
+  normal norm1;       // Standard normal distribution.
+  normal norm2(2);    // Mean = 2, std deviation = 1.
+  normal norm3(2, 3); // Mean = 2, std deviation = 3.
 
   return 0;
 }  // int main()