Boost logo

Boost-Commit :

From: pbristow_at_[hidden]
Date: 2007-06-26 09:40:12


Author: pbristow
Date: 2007-06-26 09:40:09 EDT (Tue, 26 Jun 2007)
New Revision: 7168
URL: http://svn.boost.org/trac/boost/changeset/7168

Log:
Dealing with statisticians nits

Text files modified:
   sandbox/math_toolkit/libs/math/doc/dist_tutorial.qbk | 32 +++++++++++++-------------
   sandbox/math_toolkit/libs/math/doc/distributions/students_t_examples.qbk | 49 +++++++++++++++++++++++++++------------
   sandbox/math_toolkit/libs/math/doc/html/boostbook.css | 23 ++++++++++++++++--
   sandbox/math_toolkit/libs/math/doc/math.qbk | 21 ++++++++++------
   sandbox/math_toolkit/libs/math/doc/test_HTML4_symbols.qbk | 5 +--
   5 files changed, 85 insertions(+), 45 deletions(-)

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-06-26 09:40:09 EDT (Tue, 26 Jun 2007)
@@ -112,10 +112,20 @@
 The distributions in the random number library are typically much faster,
 but much less accurate than those in this library. This reflects the
 differing uses of the two libraries: if you want to conduct statistical
-tests, then you will need the reliable computation of this library, where
-as random numbers are ['random]: so accuracy is not a concern, where
+tests, then you will need the reliable computation of this library,
+whereas random numbers are ['random]: so accuracy is not a concern, where
 as speed most certainly is.
-]
+] [/tip Random numbers that approximate Quantiles of Distributions]
+
+For example, the binomial distribution has two parameters:
+n (the number of trials) and p (the probability of success on one trial).
+
+The `binomial_distribution` constructor therefore has two parameters:
+
+`binomial_distribution(RealType n, RealType p);`
+
+For this distribution the random variate is k: the number of successes observed.
+The probability density\/mass function (pdf) is therefore written as ['f(k; n, p)].
 
 [tip
 
@@ -127,17 +137,7 @@
 by placing a semi-colon (or sometimes vertical bar)
 after the random variate (whose value you 'choose'),
 to separate the variate from the parameter(s) that defines the shape of the distribution.
-]
-
-For example, the binomial distribution has two parameters:
-n (the number of trials) and p (the probability of success on one trial).
-
-The `binomial_distribution` constructor therefore has two parameters:
-
-`binomial_distribution(RealType n, RealType p);`
-
-For this distribution the random variate is k: the number of successes observed.
-The probability density\/mass function (pdf) is therefore written as ['f(k; n, p)].
+] [/tip Random Variates and Distribution Parameters]
 
 As noted above the non-member function `pdf` has one parameter for the distribution object,
 and a second for the random variate. So taking our binomial distribution
@@ -152,8 +152,8 @@
 Non-mathematicians might say it means the 'interesting' smallest range
 of random variate x that has the cdf going from zero to unity.
 Outside are uninteresting zones where the pdf is zero, and the cdf zero or unity.
-Mathematically, the random variate may take an (+ or -) infinite value,
-but this implementation limits it to finite values from the `max` to `min` for the `RealType`.
+Mathematically, the functions may make sense with an (+ or -) infinite value,
+but this implementation limits random variates to finite values from the `max` to `min` for the `RealType`.
 (See [link math_toolkit.backgrounders.implementation.handling_of_floating_point_infinity
 Handling of Floating-Point Infinity] for rationale).
 

Modified: sandbox/math_toolkit/libs/math/doc/distributions/students_t_examples.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/students_t_examples.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/students_t_examples.qbk 2007-06-26 09:40:09 EDT (Tue, 26 Jun 2007)
@@ -8,8 +8,8 @@
 P% sure contains the true mean". (On a technical point, note that
 the interval either contains the true mean or it does not: the
 meaning of the confidence level is subtly
-different from this colloquialism. More background information can be found
-[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm on the NIST site]).
+different from this colloquialism. More background information can be found on the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm NIST site]).
 
 The formula for the interval can be expressed as:
 
@@ -20,7 +20,7 @@
 ['t[sub ([alpha]/2,N-1)]] is the upper critical value of the Students-t
 distribution with /N-1/ degrees of freedom.
 
-[Note
+[note
 The quantity [alpha][space] is the maximum acceptable risk of falsely rejecting
 the null-hypothesis. The smaller the value of [alpha] the greater the
 strength of the test.
@@ -30,9 +30,16 @@
 to a 95% confidence level. Refer to
 [@http://www.itl.nist.gov/div898/handbook/prc/section1/prc14.htm
 "What are confidence intervals?"] in __handbook for more information.
+] [/ Note]
+
+[note
+The usual assumptions of
+[@http://en.wikipedia.org/wiki/Independent_and_identically-distributed_random_variables independent and identically distributed (i.i.d.)]
+variables and [@http://en.wikipedia.org/wiki/Normal_distribution normal distribution]
+of course apply here, as they do in other examples.]
 ]
 
-From the formula it should be clear that:
+From the formula, it should be clear that:
 
 * The width of the confidence interval decreases as the sample size increases.
 * The width increases as the standard deviation increases.
@@ -198,7 +205,18 @@
 [@../../example/students_t_single_sample.cpp students_t_single_sample.cpp].
 
 We'll begin by defining a procedure to determine which of the
-possible hypothesis are accepted or rejected at a given significance level:
+possible hypothesis are rejected or not-rejected
+at a given significance level:
+
+[note
+Non-statisticians might say 'not-rejected' means 'accepted',
+(often of the null-hypothesis) implying, wrongly, that there really *IS* no difference,
+but statisticans eschew this to avoid implying that there is positive evidence of 'no difference'.
+'Not-rejected' here means there is *no evidence* of difference, but there still might well be a difference.
+For example, see [@http://en.wikipedia.org/wiki/Argument_from_ignorance argument from ignorance] and
+[@http://www.bmj.com/cgi/content/full/311/7003/485 Absence of evidence does not constitute evidence of absence.]
+] [/ note]
+
 
    // Needed includes:
    #include <boost/math/distributions/students_t.hpp>
@@ -299,9 +317,9 @@
    Results for Alternative Hypothesis and alpha = 0.0500'''
 
    Alternative Hypothesis Conclusion
- Mean != 5.000 ACCEPTED
+ Mean != 5.000 NOT REJECTED
    Mean < 5.000 REJECTED
- Mean > 5.000 ACCEPTED
+ Mean > 5.000 NOT REJECTED
 ]
 
 You will note the line that says the probability that the difference is
@@ -310,7 +328,7 @@
 probability is smaller than the smallest representable double precision number,
 hence the appearance of a zero here. Whatever its "true" value is, we know it
 must be extraordinarily small, so the alternative hypothesis - that there is
-a difference in means - is accepted.
+a difference in means - is not rejected.
 
 For comparison the next example data output is taken from
 ['P.K.Hou, O. W. Lau & M.C. Wong, Analyst (1983) vol. 108, p 64.
@@ -368,12 +386,13 @@
 
 Alternative Hypothesis Conclusion
 Mean != 38.900 REJECTED
-Mean < 38.900 ACCEPTED
+Mean < 38.900 NOT REJECTED
 Mean > 38.900 REJECTED
 ]
 
-In this case we really have a borderline result, and more data should
-be collected.
+In this case, we really have a borderline result,
+and more data (and/or more accurate data),
+is needed for a more convincing conclusion.
 
 [endsect]
 
@@ -638,8 +657,8 @@
    Results for Alternative Hypothesis and alpha = 0.0500'''
 
    Alternative Hypothesis Conclusion
- Sample 1 Mean != Sample 2 Mean ACCEPTED
- Sample 1 Mean < Sample 2 Mean ACCEPTED
+ Sample 1 Mean != Sample 2 Mean NOT REJECTED
+ Sample 1 Mean < Sample 2 Mean NOT REJECTED
    Sample 1 Mean > Sample 2 Mean REJECTED
 ]
 
@@ -714,8 +733,8 @@
    Results for Alternative Hypothesis and alpha = 0.0500'''
 
    Alternative Hypothesis Conclusion
- Sample 1 Mean != Sample 2 Mean ACCEPTED
- Sample 1 Mean < Sample 2 Mean ACCEPTED
+ Sample 1 Mean != Sample 2 Mean NOT REJECTED
+ Sample 1 Mean < Sample 2 Mean NOT REJECTED
    Sample 1 Mean > Sample 2 Mean REJECTED
 ]
 

Modified: sandbox/math_toolkit/libs/math/doc/html/boostbook.css
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/html/boostbook.css (original)
+++ sandbox/math_toolkit/libs/math/doc/html/boostbook.css 2007-06-26 09:40:09 EDT (Tue, 26 Jun 2007)
@@ -5,6 +5,8 @@
     Use, modification and distribution is subject to the Boost Software
     License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
     http://www.boost.org/LICENSE_1_0.txt)
+
+ New syntax color Paul A. Bristow 8 Jun 2007
 =============================================================================*/
 
 /*=============================================================================
@@ -361,8 +363,23 @@
             color: #000000;
         }
     
- /* Syntax Highlighting */
- .keyword { color: #0000AA; }
+ /* New Syntax Highlighting
+ using Recognized color keyword names, for example:
+ http://www.w3.org/TR/SVG/types.html see section 4.2
+ */
+ .keyword { color: blue; }
+ .identifier { color: black; }
+ .special { color: magenta; }
+ .preprocessor { color: blueviolet; }
+ .char { color: teal; }
+ .comment { color: green; }
+ .string { color: teal; }
+ .number { color: red; }
+ .white_bkd { background-color: white; }
+ .dk_grey_bkd { background-color: dimgray; }
+
+ /* Original Syntax Highlighting
+ .keyword { color: blue; }
         .identifier { color: #000000; }
         .special { color: #707070; }
         .preprocessor { color: #402080; }
@@ -372,7 +389,7 @@
         .number { color: teal; }
         .white_bkd { background-color: #FFFFFF; }
         .dk_grey_bkd { background-color: #999999; }
-
+ */
     /* Copyright, Legal Notice */
         .copyright
         {

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-06-26 09:40:09 EDT (Tue, 26 Jun 2007)
@@ -1,6 +1,6 @@
 [article Math Toolkit
- [quickbook 1.3]
- [copyright 2006 John Maddock, Paul A. Bristow, Hubert Holin and Xiaogang Zhang]
+ [quickbook 1.4]
+ [copyright 2006-2007 John Maddock, Paul A. Bristow, Hubert Holin and Xiaogang Zhang]
     [purpose Various Special Functions, Statistical Distributions, and Numerical Tools]
     [license
         Distributed under the Boost Software License, Version 1.0.
@@ -12,7 +12,8 @@
     [/last-revision $Date$]
 ]
 
-[include HTML4_symbols.qbk]
+[include HTML4_symbols.qbk] [/ just for testing]
+[include Latin1_symbols.qbk] [/ just for testing]
 
 [def __effects [*Effects: ]]
 [def __formula [*Formula: ]]
@@ -215,14 +216,16 @@
 
 Provides a small number of high quality
 [@http://en.wikipedia.org/wiki/Special_functions special functions],
-initially these are be concentrated on functions used in statistical applications.
+initially these were concentrated on functions used in statistical applications
+but now also include some recently standardised in C99 & C++.
 
 The function families currently implemented are the gamma, beta & erf functions
 along with the incomplete gamma and beta functions (four variants
 of each) and all the possible inverses of these, plus digamma and various
-special power and logarithmic functions. Future additions will focus on
-those new math functions added in the C++ Technical Report on Standard Library
-Extensions.
+special power and logarithmic functions. Additions now include
+most new math functions added in the
+[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf C++ Technical Report on Standard Library
+Extensions].
 
 All the implementations
 are fully generic and support the use of arbitrary "real-number" types,
@@ -367,7 +370,9 @@
 [include issues.qbk]
 [include credits.qbk]
 [/include test_HTML4_symbols.qbk]
-[endsect][/section:status Status and Roadmap]
+[/include test_Latin1_symbols.qbk]
+
+[endsect][/section:status Status and Roadmap]
 
 [/ math.qbk
   Copyright 2006 John Maddock and Paul A. Bristow.

Modified: sandbox/math_toolkit/libs/math/doc/test_HTML4_symbols.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/test_HTML4_symbols.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/test_HTML4_symbols.qbk 2007-06-26 09:40:09 EDT (Tue, 26 Jun 2007)
@@ -1,4 +1,4 @@
-[section:test test HTML4 symbols]
+[section:test_HTML_4_Symbols test HTML4 symbols]
 [/ Examples of using all the Greek and Math symbols defined in HTML4_symbols.qbk]
 [/ See http://www.htmlhelp.com/reference/html40/entities/symbols.html]
 
@@ -132,10 +132,9 @@
 [hearts],
 [diams],
 
-
 [endsect]
 
-[/ testsymbols.qbk
+[/ test_MTML4_symbols.qbk
   Copyright 2006 John Maddock and Paul A. Bristow.
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk