math/distributions/find_location.hpp

0001 //  Copyright John Maddock 2007.
0002 //  Copyright Paul A. Bristow 2007.
0003
0004 //  Use, modification and distribution are subject to the
0005 //  Boost Software License, Version 1.0. (See accompanying file
0006 //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0007
0008 #ifndef BOOST_STATS_FIND_LOCATION_HPP
0009 #define BOOST_STATS_FIND_LOCATION_HPP
0010
0011 #include <boost/math/distributions/fwd.hpp> // for all distribution signatures.
0012 #include <boost/math/distributions/complement.hpp>
0013 #include <boost/math/policies/policy.hpp>
0014 #include <boost/math/tools/traits.hpp>
0015 #include <boost/math/special_functions/fpclassify.hpp>
0016 #include <boost/math/policies/error_handling.hpp>
0017 // using boost::math::policies::policy;
0018 // using boost::math::complement; // will be needed by users who want complement,
0019 // but NOT placed here to avoid putting it in global scope.
0020
0021 namespace boost
0022 {
0023   namespace math
0024   {
0025   // Function to find location of random variable z
0026   // to give probability p (given scale)
0027   // Applies to normal, lognormal, extreme value, Cauchy, (and symmetrical triangular),
0028   // enforced by static_assert below.
0029
0030     template <class Dist, class Policy>
0031     inline
0032       typename Dist::value_type find_location( // For example, normal mean.
0033       typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
0034       // For example, a nominal minimum acceptable z, so that p * 100 % are > z
0035       typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
0036       typename Dist::value_type scale, // scale parameter, for example, normal standard deviation.
0037       const Policy& pol
0038       )
0039     {
0040       static_assert(::boost::math::tools::is_distribution<Dist>::value, "The provided distribution does not meet the conceptual requirements of a distribution.");
0041       static_assert(::boost::math::tools::is_scaled_distribution<Dist>::value, "The provided distribution does not meet the conceptual requirements of a scaled distribution.");
0042       static const char* function = "boost::math::find_location<Dist, Policy>&, %1%)";
0043
0044       if(!(boost::math::isfinite)(p) || (p < 0) || (p > 1))
0045       {
0046        return policies::raise_domain_error<typename Dist::value_type>(
0047            function, "Probability parameter was %1%, but must be >= 0 and <= 1!", p, pol);
0048       }
0049       if(!(boost::math::isfinite)(z))
0050       {
0051        return policies::raise_domain_error<typename Dist::value_type>(
0052            function, "z parameter was %1%, but must be finite!", z, pol);
0053       }
0054       if(!(boost::math::isfinite)(scale))
0055       {
0056        return policies::raise_domain_error<typename Dist::value_type>(
0057            function, "scale parameter was %1%, but must be finite!", scale, pol);
0058       }
0059
0060       //cout << "z " << z << ", p " << p << ",  quantile(Dist(), p) "
0061       //  << quantile(Dist(), p) << ", quan * scale " << quantile(Dist(), p) * scale << endl;
0062       return z - (quantile(Dist(), p) * scale);
0063     } // find_location
0064
0065     template <class Dist>
0066     inline // with default policy.
0067       typename Dist::value_type find_location( // For example, normal mean.
0068       typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
0069       // For example, a nominal minimum acceptable z, so that p * 100 % are > z
0070       typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
0071       typename Dist::value_type scale) // scale parameter, for example, normal standard deviation.
0072     { // Forward to find_location with default policy.
0073        return (find_location<Dist>(z, p, scale, policies::policy<>()));
0074     } // find_location
0075
0076     // So the user can start from the complement q = (1 - p) of the probability p,
0077     // for example, l = find_location<normal>(complement(z, q, sd));
0078
0079     template <class Dist, class Real1, class Real2, class Real3>
0080     inline typename Dist::value_type find_location( // Default policy.
0081       complemented3_type<Real1, Real2, Real3> const& c)
0082     {
0083       static const char* function = "boost::math::find_location<Dist, Policy>&, %1%)";
0084
0085       typename Dist::value_type p = c.param1;
0086       if(!(boost::math::isfinite)(p) || (p < 0) || (p > 1))
0087       {
0088        return policies::raise_domain_error<typename Dist::value_type>(
0089            function, "Probability parameter was %1%, but must be >= 0 and <= 1!", p, policies::policy<>());
0090       }
0091       typename Dist::value_type z = c.dist;
0092       if(!(boost::math::isfinite)(z))
0093       {
0094        return policies::raise_domain_error<typename Dist::value_type>(
0095            function, "z parameter was %1%, but must be finite!", z, policies::policy<>());
0096       }
0097       typename Dist::value_type scale = c.param2;
0098       if(!(boost::math::isfinite)(scale))
0099       {
0100        return policies::raise_domain_error<typename Dist::value_type>(
0101            function, "scale parameter was %1%, but must be finite!", scale, policies::policy<>());
0102       }
0103        // cout << "z " << c.dist << ", quantile (Dist(), " << c.param1 << ") * scale " << c.param2 << endl;
0104        return z - quantile(Dist(), p) * scale;
0105     } // find_location complement
0106
0107
0108     template <class Dist, class Real1, class Real2, class Real3, class Real4>
0109     inline typename Dist::value_type find_location( // Explicit policy.
0110       complemented4_type<Real1, Real2, Real3, Real4> const& c)
0111     {
0112       static const char* function = "boost::math::find_location<Dist, Policy>&, %1%)";
0113
0114       typename Dist::value_type p = c.param1;
0115       if(!(boost::math::isfinite)(p) || (p < 0) || (p > 1))
0116       {
0117        return policies::raise_domain_error<typename Dist::value_type>(
0118            function, "Probability parameter was %1%, but must be >= 0 and <= 1!", p, c.param3);
0119       }
0120       typename Dist::value_type z = c.dist;
0121       if(!(boost::math::isfinite)(z))
0122       {
0123        return policies::raise_domain_error<typename Dist::value_type>(
0124            function, "z parameter was %1%, but must be finite!", z, c.param3);
0125       }
0126       typename Dist::value_type scale = c.param2;
0127       if(!(boost::math::isfinite)(scale))
0128       {
0129        return policies::raise_domain_error<typename Dist::value_type>(
0130            function, "scale parameter was %1%, but must be finite!", scale, c.param3);
0131       }
0132        // cout << "z " << c.dist << ", quantile (Dist(), " << c.param1 << ") * scale " << c.param2 << endl;
0133        return z - quantile(Dist(), p) * scale;
0134     } // find_location complement
0135
0136   } // namespace boost
0137 } // namespace math
0138
0139 #endif // BOOST_STATS_FIND_LOCATION_HPP
0140