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

From: pbristow_at_[hidden]
Date: 2007-09-16 06:34:02

Author: pbristow
Date: 2007-09-16 06:34:01 EDT (Sun, 16 Sep 2007)
New Revision: 39314
URL: http://svn.boost.org/trac/boost/changeset/39314

Log:
Updates for find scale & location
Removed:
   sandbox/math_toolkit/libs/math/doc/distributions/distribution_construction_example.qbk
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/dist_algorithms.qbk |    75 ++++++++++++++++++++++++++++++++++++++- 
   sandbox/math_toolkit/libs/math/doc/dist_reference.qbk  |     3 +                                       
   sandbox/math_toolkit/libs/math/doc/dist_tutorial.qbk   |     4 +-                                      
   sandbox/math_toolkit/libs/math/doc/math.qbk            |     7 +--                                     
   4 files changed, 81 insertions(+), 8 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/dist_algorithms.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/dist_algorithms.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/dist_algorithms.qbk	2007-09-16 06:34:01 EDT (Sun, 16 Sep 2007)
@@ -1,7 +1,78 @@
-[section: dist_algorithms Distribution Algorithms]
+[section:dist_algorithms Distribution Algorithms]
 
 [h4 Finding the Location and Scale for Normal and similar distributions]
 
+Two functions aid finding location and scale of random variable z
+to give probability p (given a scale or location).
+Only applies to distributions like normal, lognormal, extreme value, Cauchy, (and symmetrical triangular),
+that have scale and location properties.
 
+These functions are useful to predict the mean and/or standard deviation that will be needed to meet a specified minimum weight or maximum dose.
 
-[endsect] [/section: dist_algorithms dist_algorithms]
+Complement versions are also provided, both with explicit and implicit (default) policy.
+
+  using boost::math::policies::policy; // May be needed by users defining their own policies.
+  using boost::math::complement; // Will be needed by users who want to use complements.
+
+[h4 find_location function]
+
+``#include <boost/math/distributions/find_location.hpp>``
+
+ namespace boost{ namespace math{
+
+ template <class Dist, class ``__Policy``> // explicit error handling policy
+   typename Dist::value_type find_location( // For example, normal mean.
+   typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+   // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+   typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+   typename Dist::value_type scale, // scale parameter, for example, normal standard deviation.
+   const ``__Policy``& pol);
+
+ template <class Dist>  // with default policy.
+   typename Dist::value_type find_location( // For example, normal mean.
+   typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+   // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+   typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+   typename Dist::value_type scale); // scale parameter, for example, normal standard deviation.
+
+   }} // namespaces
+
+[h4 find_scale function]
+
+``#include <boost/math/distributions/find_scale.hpp>``
+
+ namespace boost{ namespace math{ 
+
+ template <class Dist, class ``__Policy``>
+   typename Dist::value_type find_scale( // For example, normal mean.
+   typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+   // For example, a nominal minimum acceptable weight z, so that p * 100 % are > z
+   typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+   typename Dist::value_type location, // location parameter, for example, normal distribution mean.
+   const ``__Policy``& pol);
+
+  template <class Dist> // with default policy.
+    typename Dist::value_type find_scale( // For example, normal mean.
+    typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+    // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+    typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+    typename Dist::value_type location) // location parameter, for example, normal distribution mean.
+ }} // namespaces
+    
+All argument must be finite, otherwise __domain_error is called.
+
+Probability arguments must be [0, 1], otherwise __domain_error is called.
+
+If the choice of arguments would give a negative scale, __domain_error is called, unless the policy is to ignore, when the negative (impossible) value of scale is returned.    
+    
+[link math_toolkit.dist.stat_tut.weg.find_eg Find Mean and standard deviation examples]
+gives simple examples of use of both find_scale and find_location, and a longer example finding means and standard deviations of normally distributed weights to meet a specification.
+
+[endsect] [/section:dist_algorithms dist_algorithms]
+
+[/ dist_algorithms.qbk
+  Copyright 2007 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/dist_reference.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/dist_reference.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/dist_reference.qbk	2007-09-16 06:34:01 EDT (Sun, 16 Sep 2007)
@@ -26,8 +26,11 @@
 
 [endsect][/section:dists Distributions]
 
+[include dist_algorithms.qbk]
+
 [endsect][/section:dist_ref Statistical Distributions and Functions Reference]
 
+
 [section:future Extras/Future Directions]
 
 [h4 Adding Additional Location and Scale Parameters] 

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-09-16 06:34:01 EDT (Sun, 16 Sep 2007)
@@ -357,7 +357,7 @@
 [endsect] [/section:overview Overview]
 
 [section:weg Worked Examples]
-[include distributions/distribution_construction_example.qbk]
+[include distributions/distribution_construction.qbk]
 [include distributions/students_t_examples.qbk]
 [include distributions/chi_squared_examples.qbk]
 [include distributions/f_dist_example.qbk]
@@ -365,8 +365,8 @@
 [include distributions/negative_binomial_example.qbk]
 [include distributions/normal_example.qbk]
 [include distributions/error_handling_example.qbk]
+[include distributions/find_location_and_scale.qbk]
 [include distributions/nag_library.qbk]
-
 [endsect] [/section:weg Worked Examples]
 
 [include background.qbk]

Deleted: sandbox/math_toolkit/libs/math/doc/distributions/distribution_construction_example.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/distribution_construction_example.qbk	2007-09-16 06:34:01 EDT (Sun, 16 Sep 2007)
+++ (empty file)
@@ -1,9 +0,0 @@
-[section:distribution_construction_example Distribution Construction Example]
-
-See [@../../example/distribution_construction.cpp distribution_construction.cpp] for full source code.
-
-[import ../../example/distribution_construction.cpp]
-[distribution_construction1]
-[distribution_construction2]
-
-[endsect] [/section:distribution_construction_example Distribution Construction Example]

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-09-16 06:34:01 EDT (Sun, 16 Sep 2007)
@@ -251,8 +251,8 @@
 [link math_toolkit.policy.pol_ref.discrete_quant_ref reference docs] 
 describe how to change the rounding policy
 for these distributions.
-]
-]
+] [/ caution]
+] [/ template discrete_quantile_warning]
 
 [section:main_overview Overview]
 
@@ -272,12 +272,11 @@
 [performance_overview]
 [endsect]
 
-[endsect][/section:main_overview Overview]
+[endsect] [/section:main_overview Overview]
 
 [section:dist Statistical Distributions and Functions]
 [include dist_tutorial.qbk]
 [include dist_reference.qbk]
-[include dist_algorithms.qbk]
 [endsect] [/section:dist Statistical Distributions and Functions]
 
 [section:special Special Functions]