diff --git a/doc/sf_and_dist/dist_reference.qbk b/doc/sf_and_dist/dist_reference.qbk index 62f6cb362..623dbf65f 100644 --- a/doc/sf_and_dist/dist_reference.qbk +++ b/doc/sf_and_dist/dist_reference.qbk @@ -17,6 +17,7 @@ [include distributions/negative_binomial.qbk] [include distributions/nc_beta.qbk] [include distributions/nc_chi_squared.qbk] +[include distributions/nc_f.qbk] [include distributions/normal.qbk] [include distributions/pareto.qbk] [include distributions/poisson.qbk] diff --git a/doc/sf_and_dist/distributions/nc_beta.qbk b/doc/sf_and_dist/distributions/nc_beta.qbk index 50920fdb0..5a8c9e644 100644 --- a/doc/sf_and_dist/distributions/nc_beta.qbk +++ b/doc/sf_and_dist/distributions/nc_beta.qbk @@ -80,10 +80,10 @@ Returns the parameter /lambda/ from which this object was constructed. Most of the [link math_toolkit.dist.dist_ref.nmp usual non-member accessor functions] are supported: __cdf, __pdf, __quantile, -__hazard, __chf, __range and __support. +__median, __mode, __hazard, __chf, __range and __support. However, the following are not currently implemented: -__mean, __median, __mode, __variance, __sd, __skewness, +__mean, __variance, __sd, __skewness, __kurtosis and __kurtosis_excess. The domain of the random variable is \[0, 1\]. diff --git a/doc/sf_and_dist/distributions/nc_f.qbk b/doc/sf_and_dist/distributions/nc_f.qbk new file mode 100644 index 000000000..137a5eb9a --- /dev/null +++ b/doc/sf_and_dist/distributions/nc_f.qbk @@ -0,0 +1,188 @@ +[section:nc_f_dist Non Central F Distribution] + +``#include `` + + namespace boost{ namespace math{ + + template + class non_central_f_distribution; + + typedef non_central_f_distribution<> non_central_f; + + template + class non_central_f_distribution + { + public: + typedef RealType value_type; + typedef Policy policy_type; + + // Constructor: + non_central_f_distribution(RealType v1, RealType v2, RealType lambda); + + // Accessor to parameters: + RealType degrees_of_freedom1()const; + RealType degrees_of_freedom2()const; + + // Accessor to non centrality parameter: + 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]. +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], +and Y is a central [chi][super 2] random variable with /v2/ degrees of freedom. + +This gives the following PDF: + +[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 + +[equation nc_f_ref2] + +The following graph illustrates how the distribution changes +for different values of [lambda]: + +[$../graphs/nc_f_pdf.png] + +[h4 Member Functions] + + non_central_f_distribution(RealType v1, RealType v2, RealType lambda); + +Constructs a non-central beta distribution with parameters /v1/ and /v2/ +and non-centrality parameter /lambda/. + +Requires v1 > 0, v2 > 0 and lambda >= 0, otherwise calls __domain_error. + + RealType degrees_of_freedom1()const; + +Returns the parameter /v1/ from which this object was constructed. + + RealType degrees_of_freedom2()const; + +Returns the parameter /v2/ from which this object was constructed. + + RealType non_centrality()const; + +Returns the parameter /lambda/ from which this object was constructed. + +[h4 Non-member Accessors] + +All the [link math_toolkit.dist.dist_ref.nmp usual non-member accessor functions] +that are generic to all distributions are supported: __usual_accessors. + +The domain of the random variable is \[0, +[infin]\]. + +[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. + +[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. + +[h4 Implementation] + +In the following table /v1/ and /v2/ are the first and second +degrees of freedom parameters of the distribution, [lambda] +is the non-centrality parameter, +/x/ is the random variate, /p/ is the probability, and /q = 1-p/. + +[table +[[Function][Implementation Notes]] +[[pdf][Implemented in terms of the non-central beta PDF using the relation: + +f(x;v1,v2;[lambda]) = (v1\/v2) / ((1+y)*(1+y)) * g(y\/(1+y);v1\/2,v2\/2;[lambda]) + +where g(x; a, b; [lambda]) is the non central beta PDF, and: + +y = x * v1 \/ v2 +]] +[[cdf][Using the relation: + +p = B[sub y](v1\/2, v2\/2; [lambda]) + +where B[sub x](a, b; [lambda]) is the non-central beta distribution CDF and + +y = x * v1 \/ v2 + +]] + +[[cdf complement][Using the relation: + +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 + +y = x * v1 \/ v2 + +]] +[[quantile][Using the relation: + +x = (bx \/ (1-bx)) * (v1 \/ v2) + +where + +bx = Q[sub p][super -1](v1\/2, v2\/2; [lambda]) + +and + +Q[sub p][super -1](v1\/2, v2\/2; [lambda]) + +is the non-central beta quantile. + +]] +[[quantile + +from the complement][ +Using the relation: + +x = (bx \/ (1-bx)) * (v1 \/ v2) + +where + +bx = QC[sub q][super -1](v1\/2, v2\/2; [lambda]) + +and + +QC[sub q][super -1](v1\/2, v2\/2; [lambda]) + +is the non-central 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 + Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.] ]] +[[skewness][Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html + Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.], + and to the [@http://reference.wolfram.com/mathematica/ref/NoncentralFRatioDistribution.html + Mathematica documentation] ]] +[[kurtosis and kurtosis excess] + [Refer to, [@http://mathworld.wolfram.com/NoncentralF-Distribution.html + Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram Web Resource.], + and to the [@http://reference.wolfram.com/mathematica/ref/NoncentralFRatioDistribution.html + Mathematica documentation] ]] +] + +[endsect][/section:nc_beta_dist] + +[/ nc_beta.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 + http://www.boost.org/LICENSE_1_0.txt). +] + diff --git a/doc/sf_and_dist/equations/generate.sh b/doc/sf_and_dist/equations/generate.sh index a8f497cc5..be6e7b9fc 100755 --- a/doc/sf_and_dist/equations/generate.sh +++ b/doc/sf_and_dist/equations/generate.sh @@ -14,7 +14,7 @@ for mmlfile in $*; do pngfile=$(basename $svgfile .svg).png tempfile=temp.mml # strip html wrappers put in by MathCast: - cat $svgfile | tr -d "\r\n" | sed -e 's/.*\(]*>.*<\/math>\).*/\1/' > $tempfile + cat $mmlfile | tr -d "\r\n" | sed -e 's/.*\(]*>.*<\/math>\).*/\1/' > $tempfile echo Generating $svgfile $python $math2svg $tempfile > $svgfile @@ -24,3 +24,4 @@ for mmlfile in $*; do done + diff --git a/doc/sf_and_dist/equations/nc_f_ref1.mml b/doc/sf_and_dist/equations/nc_f_ref1.mml new file mode 100644 index 000000000..1fd749e84 --- /dev/null +++ b/doc/sf_and_dist/equations/nc_f_ref1.mml @@ -0,0 +1,314 @@ + +]> + +nc_f_ref1 + + + + + + f + + + x + ; + + ν + 1 + + , + + ν + 2 + + ; + λ + + + + = + + + e + + + − + + λ + 2 + + + + + + + + λ + + ν + 1 + + x + + + + + 2 + + + + ν + 2 + + + + + ν + 1 + + x + + + + + + + + + + + ν + 1 + + + + + + + ν + 1 + + + 2 + + + + + + + ν + 2 + + + + + + + ν + 2 + + + 2 + + + + + x + + + + + ν + 1 + + + 2 + + − + 1 + + + + + + + ν + 2 + + + + + ν + 1 + + x + + + + − + + + + + ν + 1 + + + + + ν + 2 + + + + 2 + + + + + + Γ + + + + 1 + 2 + + + ν + 1 + + + + Γ + + + 1 + + + + 1 + 2 + + + ν + 2 + + + + + L + + + + + ν + 2 + + + 2 + + + + + + + ν + 1 + + + 2 + + − + 1 + + + + + − + + + λ + + ν + 1 + + x + + + 2 + + + + ν + 2 + + + + + ν + 1 + + x + + + + + + + + + B + + + + 1 + 2 + + + + ν + 1 + + + , + + 1 + 2 + + + + ν + 2 + + + + + Γ + + + + 1 + 2 + + + + + + ν + 1 + + + + + + + ν + 2 + + + + + + + + + + + + diff --git a/doc/sf_and_dist/equations/nc_f_ref1.png b/doc/sf_and_dist/equations/nc_f_ref1.png new file mode 100644 index 000000000..114f31d59 Binary files /dev/null and b/doc/sf_and_dist/equations/nc_f_ref1.png differ diff --git a/doc/sf_and_dist/equations/nc_f_ref1.svg b/doc/sf_and_dist/equations/nc_f_ref1.svg new file mode 100644 index 000000000..c08ee1c3e --- /dev/null +++ b/doc/sf_and_dist/equations/nc_f_ref1.svg @@ -0,0 +1,2 @@ + +f(x;ν1,ν2;λ)=e−λ2+(λν1x)(2(ν2+ν1x))ν1ν12ν2ν22xν12−1(ν2+ν1x)−(ν1+ν2)2Γ(12ν1)Γ(1+12ν2)Lν22ν12−1(−λν1x2(ν2+ν1x))B(12ν1,12ν2)Γ(12(ν1+ν2)) \ No newline at end of file diff --git a/doc/sf_and_dist/equations/nc_f_ref2.mml b/doc/sf_and_dist/equations/nc_f_ref2.mml new file mode 100644 index 000000000..b470fd619 --- /dev/null +++ b/doc/sf_and_dist/equations/nc_f_ref2.mml @@ -0,0 +1,202 @@ + +]> + +nc_f_ref2 + + + + + + f + + + x + ; + + ν + 1 + + , + + ν + 2 + + ; + λ + + + + = + + + ∑ + + k + = + 0 + + ∞ + + + + + e + + − + + λ + 2 + + + + + + + + λ + 2 + + + + k + + + + B + + + + + + ν + 2 + + + 2, + + + + + ν + 1 + + + 2 + + + + k + + + k + ! + + + + + + + + + ν + 1 + + + + + ν + 2 + + + + + + + + + + ν + 1 + + + 2 + + + + k + + + + + + + + + ν + 2 + + + + + + ν + 2 + + + + + + + ν + 1 + + + x + + + + + + + + + + ν + 1 + + + + + + + ν + 2 + + + + 2 + + + + k + + + + x + + + + + ν + 1 + + + 2 + + + + k + − + 1 + + + + + + diff --git a/doc/sf_and_dist/equations/nc_f_ref2.png b/doc/sf_and_dist/equations/nc_f_ref2.png new file mode 100644 index 000000000..b7d6721cd Binary files /dev/null and b/doc/sf_and_dist/equations/nc_f_ref2.png differ diff --git a/doc/sf_and_dist/equations/nc_f_ref2.svg b/doc/sf_and_dist/equations/nc_f_ref2.svg new file mode 100644 index 000000000..9b26cf08c --- /dev/null +++ b/doc/sf_and_dist/equations/nc_f_ref2.svg @@ -0,0 +1,2 @@ + +f(x;ν1,ν2;λ)=∑k=0∞e−λ2(λ2)kB(ν22,ν12+k)k!(ν1ν2)ν12+k(ν2ν2+ν1x)ν1+ν22+kxν12+k−1 \ No newline at end of file