|
|
Boost-Commit : |
From: pbristow_at_[hidden]
Date: 2008-02-07 13:47:08
Author: pbristow
Date: 2008-02-07 13:47:08 EST (Thu, 07 Feb 2008)
New Revision: 43161
URL: http://svn.boost.org/trac/boost/changeset/43161
Log:
Editorial work on non-central distribs
Text files modified:
sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_beta.qbk | 59 +++++++++++++++++----------------
sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_chi_squared.qbk | 70 +++++++++++++++++++++------------------
sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_f.qbk | 43 ++++++++++++------------
3 files changed, 91 insertions(+), 81 deletions(-)
Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_beta.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_beta.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_beta.qbk 2008-02-07 13:47:08 EST (Thu, 07 Feb 2008)
@@ -1,4 +1,4 @@
-[section:nc_beta_dist Non Central Beta Distribution]
+[section:nc_beta_dist Noncentral Beta Distribution]
``#include <boost/math/distributions/non_central_beta.hpp>``
@@ -20,30 +20,31 @@
// Constructor:
non_central_beta_distribution(RealType alpha, RealType beta, RealType lambda);
- // Accessor to parameters:
+ // Accessor to shape parameters:
RealType alpha()const;
RealType beta()const;
- // Accessor to non centrality parameter:
+ // Accessor to non-centrality parameter lambda:
RealType non_centrality()const;
};
}} // namespaces
-The non-central beta distribution is a generalization of the
-beta distribution. It is defined as the ratio
+The noncentral beta distribution is a generalization of the __beta_distrib.
+
+It is defined as the ratio
X = [chi][sub m][super 2]([lambda]) \/ ([chi][sub m][super 2]([lambda])
+ [chi][sub n][super 2])
-where [chi][sub m][super 2]([lambda]) is a non-central [chi][super 2]
+where [chi][sub m][super 2]([lambda]) is a noncentral [chi][super 2]
random variable with /m/ degrees of freedom, and [chi][sub n][super 2]
is a central [chi][super 2] random variable with /n/ degrees of freedom.
This gives a PDF that can be expressed as a Poisson mixture
-of beta distribution PDF's:
+of beta distribution PDFs:
[equation nc_beta_ref1]
-where P(i;[lambda]\/2) is the discrete poisson probablity at /i/, with mean
+where P(i;[lambda]\/2) is the discrete Poisson probablity at /i/, with mean
[lambda]\/2, and I[sub x][super ']([alpha], [beta]) is the derivative of
the incomplete beta function. This leads to the usual form of the CDF
as:
@@ -59,7 +60,7 @@
non_central_beta_distribution(RealType a, RealType b, RealType lambda);
-Constructs a non-central beta distribution with parameters /a/ and /b/
+Constructs a noncentral beta distribution with shape parameters /a/ and /b/
and non-centrality parameter /lambda/.
Requires a > 0, b > 0 and lambda >= 0, otherwise calls __domain_error.
@@ -90,17 +91,18 @@
[h4 Accuracy]
-The following table shows the peak errors (in units of epsilon)
+The following table shows the peak errors
+(in units of [@http://en.wikipedia.org/wiki/Machine_epsilon epsilon])
found on various platforms with various floating point types.
-No comparison to the R-2.5.1 Math library, or to the FORTRAN
-implementations of AS226 or AS310 are given since these appear
-to only guarentee absolute error: this would causes our test harness
+No comparison to the [@http://www.r-project.org/ R-2.5.1 Math library],
+or to the FORTRAN implementations of AS226 or AS310 are given since these appear
+to only guarantee absolute error: this would causes our test harness
to assign an /"infinite"/ error to these libraries for some of our
test values when measuring /relative error/.
-Unless otherwise specified any floating point type that is narrower
+Unless otherwise specified any floating-point type that is narrower
than the one shown will have __zero_error.
-[table Errors In CDF of the Non Central Beta
+[table Errors In CDF of the Noncentral Beta
[[Significand Size] [Platform and Compiler] [[alpha], [beta],[lambda] < 200] [[alpha],[beta],[lambda] > 200]]
[[53] [Win32, Visual C++ 8] [Peak=620 Mean=22] [Peak=8670 Mean=1040]]
[[64] [RedHat Linux IA32, gcc-4.1.1] [Peak=825 Mean=50] [Peak=2.5x10[super 4] Mean=4000]]
@@ -116,7 +118,8 @@
[h4 Tests]
There are two sets of test data used to verify this implementation:
-firstly we can compare with a few sample values generated by the R library.
+firstly we can compare with a few sample values generated by the
+[@http://www.r-project.org/ R library].
Secondly, we have tables of test data, computed with this
implementation and using interval arithmetic - this data should
be accurate to at least 50 decimal digits - and is the used for
@@ -124,24 +127,24 @@
[h4 Implementation]
-The CDF and it's complement are evaluated as follows:
+The CDF and its complement are evaluated as follows:
First we determine which of the two values (the CDF or its
complement) is likely to be the smaller, the crossover point
-is taken to be the mean of the distribution, for which we use the
+is taken to be the mean of the distribution: for this we use the
approximation due to: R. Chattamvelli and R. Shanmugam,
"Algorithm AS 310: Computing the Non-Central Beta Distribution Function",
Applied Statistics, Vol. 46, No. 1. (1997), pp. 146-156.
[equation nc_beta_ref3]
-Then either the CDF or it's complement is computed using the
+Then either the CDF or its complement is computed using the
relations:
[equation nc_beta_ref4]
The summation is performed by starting at i = [lambda]/2, and then recursing
-in both directions, using the usual recurrence relations for the poisson
+in both directions, using the usual recurrence relations for the Poisson
PDF and incomplete beta functions. This is the "Method 2" described
by:
@@ -152,7 +155,7 @@
multiple correlation coefficient",
Computational Statistics & Data Analysis 43 (2003) 249-267.
-Specific applications of the above formulae to the non-central
+Specific applications of the above formulae to the noncentral
beta distribution can be found in:
Russell V. Lenth,
@@ -176,7 +179,7 @@
The American Statistician, Vol. 49, No. 2. (May, 1995), pp. 231-234.
Of these, the Posten reference provides the most complete overview,
-and includes the modification of starting iteration at [lambda]/2.
+and includes the modification starting iteration at [lambda]/2.
The main difference between this implementation and the above
references is the direct computation of the complement when most
@@ -190,17 +193,17 @@
[equation nc_beta_ref1]
Quantiles are computed using a specially modified version of
-[link math_toolkit.toolkit.internals1.roots2 bracket_and_solve_root]
-and starting the search for the root at the mean of the distribution
-(a Cornish-Fisher type expansion was also tried, but while this gets
-quite close to the root in many cases, when it's wrong it tends to
+[link math_toolkit.toolkit.internals1.roots2 bracket_and_solve_root],
+starting the search for the root at the mean of the distribution.
+(A Cornish-Fisher type expansion was also tried, but while this gets
+quite close to the root in many cases, when it is wrong it tends to
introduce quite pathological behaviour: more investigation in this
-area is probably warrented).
+area is probably warranted).
[endsect][/section:nc_beta_dist]
[/ nc_beta.qbk
- Copyright 2006 John Maddock and Paul A. Bristow.
+ Copyright 2008 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
http://www.boost.org/LICENSE_1_0.txt).
Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_chi_squared.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_chi_squared.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_chi_squared.qbk 2008-02-07 13:47:08 EST (Thu, 07 Feb 2008)
@@ -1,4 +1,4 @@
-[section:nc_chi_squared_dist Non Central Chi Squared Distribution]
+[section:nc_chi_squared_dist Noncentral Chi-Squared Distribution]
``#include <boost/math/distributions/non_central_chi_squared.hpp>``
@@ -10,7 +10,7 @@
typedef non_central_chi_squared_distribution<> non_central_chi_squared;
- template <class RealType, class ``__Policy``>
+ template <class RealType, class ``__Policy``>bja
class non_central_chi_squared_distribution
{
public:
@@ -20,10 +20,10 @@
// Constructor:
non_central_chi_squared_distribution(RealType v, RealType lambda);
- // Accessor to degrees of freedom parameter:
+ // Accessor to degrees of freedom parameter v:
RealType degrees_of_freedom()const;
- // Accessor to non centrality parameter:
+ // Accessor to non centrality parameter lambda:
RealType non_centrality()const;
// Parameter finders:
@@ -38,28 +38,29 @@
}} // namespaces
-The non-central chi-square distribution is a generalization of the
-chi-square distribution. If X[sub i] are [nu] independent, normally
+The noncentral chi-squared distribution is a generalization of the
+__chi_squared_distrib. If X[sub i] are [nu] independent, normally
distributed random variables with means [mu][sub i] and variances
[sigma][sub i][super 2], then the random variable
[equation nc_chi_squ_ref1]
-is distributed according to the non-central chi-square distribution.
-The non central chi-square distribution has two parameters:
+is distributed according to the noncentral chi-squared distribution.
+
+The noncentral chi-squared distribution has two parameters:
[nu] which specifies the number of degrees of freedom
(i.e. the number of X[sub i]), and [lambda] which is related to the
mean of the random variables X[sub i] by:
[equation nc_chi_squ_ref2]
-Note that some references define [lambda] as one half of the above sum.
+(Note that some references define [lambda] as one half of the above sum).
This leads to a PDF of:
[equation nc_chi_squ_ref3]
-where ['f(x;k)] is the central chi squared distribution PDF, and
+where ['f(x;k)] is the central chi-squared distribution PDF, and
['I[sub v](x)] is a modified Bessel function of the first kind.
The following graph illustrates how the distribution changes
@@ -95,11 +96,13 @@
When called with argument `boost::math::complement(lambda, x, q)`
this function returns the number of degrees of freedom /v/ such that:
+
`cdf(complement(non_central_chi_squared<RealType, Policy>(v, lambda), x)) == q`.
static RealType find_non_centrality(RealType v, RealType x, RealType p);
This function returns the non centrality parameter /lambda/ such that:
+
`cdf(non_central_chi_squared<RealType, Policy>(v, lambda), x) == p`
template <class A, class B, class C>
@@ -107,6 +110,7 @@
When called with argument `boost::math::complement(v, x, q)`
this function returns the non centrality parameter /lambda/ such that:
+
`cdf(complement(non_central_chi_squared<RealType, Policy>(v, lambda), x)) == q`.
[h4 Non-member Accessors]
@@ -120,17 +124,18 @@
There is a
[link math_toolkit.dist.stat_tut.weg.nccs_eg worked example]
-for the Non central Chi Squared distribution.
+for the noncentral chi-squared distribution.
[h4 Accuracy]
-The following table shows the peak errors (in units of epsilon)
-found on various platforms with various floating point types,
-along with comparisons to the R-2.5.1 Math library.
-Unless otherwise specified any floating point type that is narrower
+The following table shows the peak errors
+(in units of [@http://en.wikipedia.org/wiki/Machine_epsilon epsilon])
+found on various platforms with various floating-point types,
+along with comparisons to the [@http://www.r-project.org/ R-2.5.1 Math library].
+Unless otherwise specified, any floating-point type that is narrower
than the one shown will have __zero_error.
-[table Errors In CDF of the Non Central Chi Squared
+[table Errors In CDF of the Noncentral Chi-Squared
[[Significand Size] [Platform and Compiler] [[nu],[lambda] < 200] [[nu],[lambda] > 200]]
[[53] [Win32, Visual C++ 8] [Peak=50 Mean=9.9
@@ -168,10 +173,10 @@
[h4 Implementation]
-The CDF and it's complement are evaluated as follows:
+The CDF and its complement are evaluated as follows:
First we determine which of the two values (the CDF or its
-complement) is likely to be the smaller, for this we can use the
+complement) is likely to be the smaller: for this we can use the
relation due to Temme (see "Asymptotic and Numerical Aspects of the
Noncentral Chi-Square Distribution", N. M. Temme, Computers Math. Applic.
Vol 25, No. 5, 55-63, 1993) that:
@@ -181,10 +186,10 @@
and so compute the CDF when the random variable is less than
[nu]+[lambda], and its complement when the random variable is
greater than [nu]+[lambda]. If necessary the computed result
-is then subtracted from 1 to give the desired result (the CDF or it's
+is then subtracted from 1 to give the desired result (the CDF or its
complement).
-For small values of the non centrality parameter the CDF is computed
+For small values of the non centrality parameter, the CDF is computed
using the method of Ding (see "Algorithm AS 275: Computing the Non-Central
#2 Distribution Function", Cherng G. Ding, Applied Statistics, Vol. 41,
No. 2. (1992), pp. 478-482). This uses the following series representation:
@@ -194,12 +199,12 @@
which requires just one call to __gamma_p_derivative with the subsequent
terms being computed by recursion as shown above.
-For larger values of the non centrality parameter, Ding's method can take
-an unreasonable number of terms before convergence is achieved. Further more
+For larger values of the non-centrality parameter, Ding's method can take
+an unreasonable number of terms before convergence is achieved. Furthermore,
the largest term is not the first term, so in extreme cases the first term may
be zero, leading to a zero result, even though the true value may be non-zero.
-Therefore when the non centrality parameter is greater than 200 the method due
+Therefore, when the non-centrality parameter is greater than 200, the method due
to Krishnamoorthy (see "Computing discrete mixtures of continuous distributions:
noncentral chisquare, noncentral t and the distribution of the
square of the sample multiple correlation coefficient",
@@ -212,9 +217,9 @@
Where P[sub a](x) is the incomplete gamma function.
-The method starts at the [lambda]'th term, which is where the Poisson weighting
+The method starts at the [lambda]th term, which is where the Poisson weighting
function achieves its maximum value, although this is not necessarily
-the largest overall term. Subsequent terms are calculate via the normal
+the largest overall term. Subsequent terms are calculates via the normal
recurrence relations for the incomplete gamma function, and iteration proceeds
both forwards and backwards until sufficient precision has been achieved. It
should be noted that recurrence in the forwards direction of P[sub a](x) is
@@ -238,24 +243,25 @@
[equation nc_chi_squ_ref3]
Note that this formula fails for large values of the non-centrality
-parameter, unfortunately there appears to be no other alternative at
+parameter: unfortunately there appears to be no other alternative at
this time.
The quantile functions are computed by numeric inversion of the CDF.
-There is no closed form for the mode of the non-central chi squared
-distribution, it is computed numerically by finding the maximum
-of the PDF. Likewise the median is computed numerically via
+There is no [@http://en.wikipedia.org/wiki/Closed_form closed form]
+for the mode of the noncentral chi-squared
+distribution: it is computed numerically by finding the maximum
+of the PDF. Likewise, the median is computed numerically via
the quantile.
-The remaining non member functions use the following formulas:
+The remaining non-member functions use the following formulas:
[equation nc_chi_squ_ref7]
-[endsect][/section:nc_chi_squared_dist]
+[endsect] [/section:nc_chi_squared_dist]
[/ nc_chi_squared.qbk
- Copyright 2006 John Maddock and Paul A. Bristow.
+ Copyright 2008 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
http://www.boost.org/LICENSE_1_0.txt).
Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_f.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_f.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/distributions/nc_f.qbk 2008-02-07 13:47:08 EST (Thu, 07 Feb 2008)
@@ -1,4 +1,4 @@
-[section:nc_f_dist Non Central F Distribution]
+[section:nc_f_dist Noncentral F Distribution]
``#include <boost/math/distributions/non_central_f.hpp>``
@@ -20,24 +20,23 @@
// Constructor:
non_central_f_distribution(RealType v1, RealType v2, RealType lambda);
- // Accessor to parameters:
+ // Accessor to degrees_of_freedom parameters v1 & v2:
RealType degrees_of_freedom1()const;
RealType degrees_of_freedom2()const;
- // Accessor to non centrality parameter:
+ // Accessor to non-centrality parameter lambda:
RealType non_centrality()const;
};
}} // namespaces
-The non-central F distribution is a generalization of the
-[link math_toolkit.dist.dist_ref.dists.f_dist Fisher F distribution].
+The noncentral F distribution is a generalization of the __F_distrib.
It is defined as the ratio
F = (X/v1) / (Y/v2)
-where X is a non-central [chi][super 2]
-random variable with /v1/ degrees of freedom and non centrality parameter [lambda],
+where X is a noncentral [chi][super 2]
+random variable with /v1/ degrees of freedom and non-centrality parameter [lambda],
and Y is a central [chi][super 2] random variable with /v2/ degrees of freedom.
This gives the following PDF:
@@ -45,7 +44,7 @@
[equation nc_f_ref1]
where L[sub a][super b](c) is a generalised Laguerre polynomial and B(a,b) is the
-beta function, or
+__beta function, or
[equation nc_f_ref2]
@@ -73,7 +72,7 @@
RealType non_centrality()const;
-Returns the parameter /lambda/ from which this object was constructed.
+Returns the non-centrality parameter /lambda/ from which this object was constructed.
[h4 Non-member Accessors]
@@ -84,15 +83,17 @@
[h4 Accuracy]
-This distribution is implemented in terms of the
-[link math_toolkit.dist.dist_ref.dists.nc_beta_dist non-central beta distribution]:
-refer to that distribution for accuracy data.
+This distribution is implemented in terms of the
+__non_central_beta_distrib
+ [link math_toolkit.dist.dist_ref.dists.nc_beta_dist noncentral beta distribution]
+:refer to that distribution for accuracy data.
[h4 Tests]
Since this distribution is implemented by adapting another distribution,
-the tests consist of basic sanity checks computed by the R statistical
-package and the pbeta and dbeta functions.
+the tests consist of basic sanity checks computed by the
+[@http://www.r-project.org/ R-2.5.1 Math library statistical
+package] and its pbeta and dbeta functions.
[h4 Implementation]
@@ -115,7 +116,7 @@
p = B[sub y](v1\/2, v2\/2; [lambda])
-where B[sub x](a, b; [lambda]) is the non-central beta distribution CDF and
+where B[sub x](a, b; [lambda]) is the noncentral beta distribution CDF and
y = x * v1 \/ v2
@@ -126,7 +127,7 @@
q = 1 - B[sub y](v1\/2, v2\/2; [lambda])
where 1 - B[sub x](a, b; [lambda]) is the complement of the
-non-central beta distribution CDF and
+noncentral beta distribution CDF and
y = x * v1 \/ v2
@@ -143,7 +144,7 @@
Q[sub p][super -1](v1\/2, v2\/2; [lambda])
-is the non-central beta quantile.
+is the noncentral beta quantile.
]]
[[quantile
@@ -161,7 +162,7 @@
QC[sub q][super -1](v1\/2, v2\/2; [lambda])
-is the non-central beta quantile from the complement.]]
+is the noncentral beta quantile from the complement.]]
[[mean][v2 * (v1 + l) \/ (v1 * (v2 - 2))]]
[[mode][By numeric maximalisation of the PDF.]]
[[variance][Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html
@@ -177,10 +178,10 @@
Mathematica documentation] ]]
]
-[endsect][/section:nc_beta_dist]
+[endsect] [/section:nc_f_dist]
-[/ nc_beta.qbk
- Copyright 2006 John Maddock and Paul A. Bristow.
+[/ nc_f.qbk
+ Copyright 2008 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
http://www.boost.org/LICENSE_1_0.txt).
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