libs/math/doc/distributions/dist_algorithms.qbk

   1 [section:dist_algorithms Distribution Algorithms]
   2
   3 [h4 Finding the Location and Scale for Normal and similar distributions]
   4
   5 Two functions aid finding location and scale of random variable z
   6 to give probability p (given a scale or location).
   7 Only applies to distributions like normal, lognormal, extreme value, Cauchy, (and symmetrical triangular),
   8 that have scale and location properties.
   9
  10 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.
  11
  12 Complement versions are also provided, both with explicit and implicit (default) policy.
  13
  14   using boost::math::policies::policy; // May be needed by users defining their own policies.
  15   using boost::math::complement; // Will be needed by users who want to use complements.
  16
  17 [h4 find_location function]
  18
  19 ``#include <boost/math/distributions/find_location.hpp>``
  20
  21  namespace boost{ namespace math{
  22
  23  template <class Dist, class ``__Policy``> // explicit error handling policy
  24    typename Dist::value_type find_location( // For example, normal mean.
  25    typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
  26    // For example, a nominal minimum acceptable z, so that p * 100 % are > z
  27    typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
  28    typename Dist::value_type scale, // scale parameter, for example, normal standard deviation.
  29    const ``__Policy``& pol);
  30
  31  template <class Dist>  // with default policy.
  32    typename Dist::value_type find_location( // For example, normal mean.
  33    typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
  34    // For example, a nominal minimum acceptable z, so that p * 100 % are > z
  35    typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
  36    typename Dist::value_type scale); // scale parameter, for example, normal standard deviation.
  37
  38    }} // namespaces
  39
  40 [h4 find_scale function]
  41
  42 ``#include <boost/math/distributions/find_scale.hpp>``
  43
  44  namespace boost{ namespace math{
  45
  46  template <class Dist, class ``__Policy``>
  47    typename Dist::value_type find_scale( // For example, normal mean.
  48    typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
  49    // For example, a nominal minimum acceptable weight z, so that p * 100 % are > z
  50    typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
  51    typename Dist::value_type location, // location parameter, for example, normal distribution mean.
  52    const ``__Policy``& pol);
  53
  54   template <class Dist> // with default policy.
  55     typename Dist::value_type find_scale( // For example, normal mean.
  56     typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
  57     // For example, a nominal minimum acceptable z, so that p * 100 % are > z
  58     typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
  59     typename Dist::value_type location) // location parameter, for example, normal distribution mean.
  60  }} // namespaces
  61
  62 All argument must be finite, otherwise __domain_error is called.
  63
  64 Probability arguments must be [0, 1], otherwise __domain_error is called.
  65
  66 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.
  67
  68 [link math_toolkit.stat_tut.weg.find_eg Find Mean and standard deviation examples]
  69 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.
  70
  71 [endsect] [/section:dist_algorithms dist_algorithms]
  72
  73 [/ dist_algorithms.qbk
  74   Copyright 2007 John Maddock and Paul A. Bristow.
  75   Distributed under the Boost Software License, Version 1.0.
  76   (See accompanying file LICENSE_1_0.txt or copy at
  77   http://www.boost.org/LICENSE_1_0.txt).
  78 ]