Chris@16: //  Copyright John Maddock 2006.
Chris@16: //  Use, modification and distribution are subject to the
Chris@16: //  Boost Software License, Version 1.0. (See accompanying file
Chris@16: //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Chris@16: 
Chris@16: #ifndef BOOST_STATS_DERIVED_HPP
Chris@16: #define BOOST_STATS_DERIVED_HPP
Chris@16: 
Chris@16: // This file implements various common properties of distributions
Chris@16: // that can be implemented in terms of other properties:
Chris@16: // variance OR standard deviation (see note below),
Chris@16: // hazard, cumulative hazard (chf), coefficient_of_variation.
Chris@16: //
Chris@16: // Note that while both variance and standard_deviation are provided
Chris@16: // here, each distribution MUST SPECIALIZE AT LEAST ONE OF THESE
Chris@16: // otherwise these two versions will just call each other over and over
Chris@16: // until stack space runs out ...
Chris@16: 
Chris@16: // Of course there may be more efficient means of implementing these
Chris@16: // that are specific to a particular distribution, but these generic
Chris@16: // versions give these properties "for free" with most distributions.
Chris@16: //
Chris@16: // In order to make use of this header, it must be included AT THE END
Chris@16: // of the distribution header, AFTER the distribution and its core
Chris@16: // property accessors have been defined: this is so that compilers
Chris@16: // that implement 2-phase lookup and early-type-checking of templates
Chris@16: // can find the definitions refered to herein.
Chris@16: //
Chris@16: 
Chris@16: #include <boost/type_traits/is_same.hpp>
Chris@16: #include <boost/static_assert.hpp>
Chris@16: 
Chris@16: #ifdef BOOST_MSVC
Chris@16: # pragma warning(push)
Chris@16: # pragma warning(disable: 4723) // potential divide by 0
Chris@16: // Suppressing spurious warning in coefficient_of_variation
Chris@16: #endif
Chris@16: 
Chris@16: namespace boost{ namespace math{
Chris@16: 
Chris@16: template <class Distribution>
Chris@16: typename Distribution::value_type variance(const Distribution& dist);
Chris@16: 
Chris@16: template <class Distribution>
Chris@16: inline typename Distribution::value_type standard_deviation(const Distribution& dist)
Chris@16: {
Chris@16:    BOOST_MATH_STD_USING  // ADL of sqrt.
Chris@16:    return sqrt(variance(dist));
Chris@16: }
Chris@16: 
Chris@16: template <class Distribution>
Chris@16: inline typename Distribution::value_type variance(const Distribution& dist)
Chris@16: {
Chris@16:    typename Distribution::value_type result = standard_deviation(dist);
Chris@16:    return result * result;
Chris@16: }
Chris@16: 
Chris@16: template <class Distribution, class RealType>
Chris@16: inline typename Distribution::value_type hazard(const Distribution& dist, const RealType& x)
Chris@16: { // hazard function
Chris@16:   // http://www.itl.nist.gov/div898/handbook/eda/section3/eda362.htm#HAZ
Chris@16:    typedef typename Distribution::value_type value_type;
Chris@16:    typedef typename Distribution::policy_type policy_type;
Chris@16:    value_type p = cdf(complement(dist, x));
Chris@16:    value_type d = pdf(dist, x);
Chris@16:    if(d > p * tools::max_value<value_type>())
Chris@16:       return policies::raise_overflow_error<value_type>(
Chris@16:       "boost::math::hazard(const Distribution&, %1%)", 0, policy_type());
Chris@16:    if(d == 0)
Chris@16:    {
Chris@16:       // This protects against 0/0, but is it the right thing to do?
Chris@16:       return 0;
Chris@16:    }
Chris@16:    return d / p;
Chris@16: }
Chris@16: 
Chris@16: template <class Distribution, class RealType>
Chris@16: inline typename Distribution::value_type chf(const Distribution& dist, const RealType& x)
Chris@16: { // cumulative hazard function.
Chris@16:   // http://www.itl.nist.gov/div898/handbook/eda/section3/eda362.htm#HAZ
Chris@16:    BOOST_MATH_STD_USING
Chris@16:    return -log(cdf(complement(dist, x)));
Chris@16: }
Chris@16: 
Chris@16: template <class Distribution>
Chris@16: inline typename Distribution::value_type coefficient_of_variation(const Distribution& dist)
Chris@16: {
Chris@16:    typedef typename Distribution::value_type value_type;
Chris@16:    typedef typename Distribution::policy_type policy_type;
Chris@16: 
Chris@16:    using std::abs;
Chris@16: 
Chris@16:    value_type m = mean(dist);
Chris@16:    value_type d = standard_deviation(dist);
Chris@16:    if((abs(m) < 1) && (d > abs(m) * tools::max_value<value_type>()))
Chris@16:    { // Checks too that m is not zero,
Chris@16:       return policies::raise_overflow_error<value_type>("boost::math::coefficient_of_variation(const Distribution&, %1%)", 0, policy_type());
Chris@16:    }
Chris@16:    return d / m; // so MSVC warning on zerodivide is spurious, and suppressed.
Chris@16: }
Chris@16: //
Chris@16: // Next follow overloads of some of the standard accessors with mixed
Chris@16: // argument types. We just use a typecast to forward on to the "real"
Chris@16: // implementation with all arguments of the same type:
Chris@16: //
Chris@16: template <class Distribution, class RealType>
Chris@16: inline typename Distribution::value_type pdf(const Distribution& dist, const RealType& x)
Chris@16: {
Chris@16:    typedef typename Distribution::value_type value_type;
Chris@16:    return pdf(dist, static_cast<value_type>(x));
Chris@16: }
Chris@16: template <class Distribution, class RealType>
Chris@16: inline typename Distribution::value_type cdf(const Distribution& dist, const RealType& x)
Chris@16: {
Chris@16:    typedef typename Distribution::value_type value_type;
Chris@16:    return cdf(dist, static_cast<value_type>(x));
Chris@16: }
Chris@16: template <class Distribution, class RealType>
Chris@16: inline typename Distribution::value_type quantile(const Distribution& dist, const RealType& x)
Chris@16: {
Chris@16:    typedef typename Distribution::value_type value_type;
Chris@16:    return quantile(dist, static_cast<value_type>(x));
Chris@16: }
Chris@16: /*
Chris@16: template <class Distribution, class RealType>
Chris@16: inline typename Distribution::value_type chf(const Distribution& dist, const RealType& x)
Chris@16: {
Chris@16:    typedef typename Distribution::value_type value_type;
Chris@16:    return chf(dist, static_cast<value_type>(x));
Chris@16: }
Chris@16: */
Chris@16: template <class Distribution, class RealType>
Chris@16: inline typename Distribution::value_type cdf(const complemented2_type<Distribution, RealType>& c)
Chris@16: {
Chris@16:    typedef typename Distribution::value_type value_type;
Chris@16:    return cdf(complement(c.dist, static_cast<value_type>(c.param)));
Chris@16: }
Chris@16: 
Chris@16: template <class Distribution, class RealType>
Chris@16: inline typename Distribution::value_type quantile(const complemented2_type<Distribution, RealType>& c)
Chris@16: {
Chris@16:    typedef typename Distribution::value_type value_type;
Chris@16:    return quantile(complement(c.dist, static_cast<value_type>(c.param)));
Chris@16: }
Chris@16: 
Chris@16: template <class Dist>
Chris@16: inline typename Dist::value_type median(const Dist& d)
Chris@16: { // median - default definition for those distributions for which a
Chris@16:   // simple closed form is not known,
Chris@16:   // and for which a domain_error and/or NaN generating function is NOT defined.
Chris@16:   typedef typename Dist::value_type value_type;
Chris@16:   return quantile(d, static_cast<value_type>(0.5f));
Chris@16: }
Chris@16: 
Chris@16: } // namespace math
Chris@16: } // namespace boost
Chris@16: 
Chris@16: 
Chris@16: #ifdef BOOST_MSVC
Chris@16: # pragma warning(pop)
Chris@16: #endif
Chris@16: 
Chris@16: #endif // BOOST_STATS_DERIVED_HPP