Chris@16: // boost\math\distributions\bernoulli.hpp
Chris@16: 
Chris@16: // Copyright John Maddock 2006.
Chris@16: // Copyright Paul A. Bristow 2007.
Chris@16: 
Chris@16: // Use, modification and distribution are subject to the
Chris@16: // Boost Software License, Version 1.0.
Chris@16: // (See accompanying file LICENSE_1_0.txt
Chris@16: // or copy at http://www.boost.org/LICENSE_1_0.txt)
Chris@16: 
Chris@16: // http://en.wikipedia.org/wiki/bernoulli_distribution
Chris@16: // http://mathworld.wolfram.com/BernoulliDistribution.html
Chris@16: 
Chris@16: // bernoulli distribution is the discrete probability distribution of
Chris@16: // the number (k) of successes, in a single Bernoulli trials.
Chris@16: // It is a version of the binomial distribution when n = 1.
Chris@16: 
Chris@16: // But note that the bernoulli distribution
Chris@16: // (like others including the poisson, binomial & negative binomial)
Chris@16: // is strictly defined as a discrete function: only integral values of k are envisaged.
Chris@16: // However because of the method of calculation using a continuous gamma function,
Chris@16: // it is convenient to treat it as if a continous function,
Chris@16: // and permit non-integral values of k.
Chris@16: // To enforce the strict mathematical model, users should use floor or ceil functions
Chris@16: // on k outside this function to ensure that k is integral.
Chris@16: 
Chris@16: #ifndef BOOST_MATH_SPECIAL_BERNOULLI_HPP
Chris@16: #define BOOST_MATH_SPECIAL_BERNOULLI_HPP
Chris@16: 
Chris@16: #include <boost/math/distributions/fwd.hpp>
Chris@16: #include <boost/math/tools/config.hpp>
Chris@16: #include <boost/math/distributions/complement.hpp> // complements
Chris@16: #include <boost/math/distributions/detail/common_error_handling.hpp> // error checks
Chris@16: #include <boost/math/special_functions/fpclassify.hpp> // isnan.
Chris@16: 
Chris@16: #include <utility>
Chris@16: 
Chris@16: namespace boost
Chris@16: {
Chris@16:   namespace math
Chris@16:   {
Chris@16:     namespace bernoulli_detail
Chris@16:     {
Chris@16:       // Common error checking routines for bernoulli distribution functions:
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_success_fraction(const char* function, const RealType& p, RealType* result, const Policy& /* pol */)
Chris@16:       {
Chris@16:         if(!(boost::math::isfinite)(p) || (p < 0) || (p > 1))
Chris@16:         {
Chris@16:           *result = policies::raise_domain_error<RealType>(
Chris@16:             function,
Chris@16:             "Success fraction argument is %1%, but must be >= 0 and <= 1 !", p, Policy());
Chris@16:           return false;
Chris@16:         }
Chris@16:         return true;
Chris@16:       }
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_dist(const char* function, const RealType& p, RealType* result, const Policy& /* pol */, const mpl::true_&)
Chris@16:       {
Chris@16:         return check_success_fraction(function, p, result, Policy());
Chris@16:       }
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_dist(const char* , const RealType& , RealType* , const Policy& /* pol */, const mpl::false_&)
Chris@16:       {
Chris@16:          return true;
Chris@16:       }
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_dist(const char* function, const RealType& p, RealType* result, const Policy& /* pol */)
Chris@16:       {
Chris@16:          return check_dist(function, p, result, Policy(), typename policies::constructor_error_check<Policy>::type());
Chris@16:       }
Chris@16: 
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_dist_and_k(const char* function, const RealType& p, RealType k, RealType* result, const Policy& pol)
Chris@16:       {
Chris@16:         if(check_dist(function, p, result, Policy(), typename policies::method_error_check<Policy>::type()) == false)
Chris@16:         {
Chris@16:           return false;
Chris@16:         }
Chris@16:         if(!(boost::math::isfinite)(k) || !((k == 0) || (k == 1)))
Chris@16:         {
Chris@16:           *result = policies::raise_domain_error<RealType>(
Chris@16:             function,
Chris@16:             "Number of successes argument is %1%, but must be 0 or 1 !", k, pol);
Chris@16:           return false;
Chris@16:         }
Chris@16:        return true;
Chris@16:       }
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_dist_and_prob(const char* function, RealType p, RealType prob, RealType* result, const Policy& /* pol */)
Chris@16:       {
Chris@16:         if(check_dist(function, p, result, Policy(), typename policies::method_error_check<Policy>::type()) && detail::check_probability(function, prob, result, Policy()) == false)
Chris@16:         {
Chris@16:           return false;
Chris@16:         }
Chris@16:         return true;
Chris@16:       }
Chris@16:     } // namespace bernoulli_detail
Chris@16: 
Chris@16: 
Chris@16:     template <class RealType = double, class Policy = policies::policy<> >
Chris@16:     class bernoulli_distribution
Chris@16:     {
Chris@16:     public:
Chris@16:       typedef RealType value_type;
Chris@16:       typedef Policy policy_type;
Chris@16: 
Chris@16:       bernoulli_distribution(RealType p = 0.5) : m_p(p)
Chris@16:       { // Default probability = half suits 'fair' coin tossing
Chris@16:         // where probability of heads == probability of tails.
Chris@16:         RealType result; // of checks.
Chris@16:         bernoulli_detail::check_dist(
Chris@16:            "boost::math::bernoulli_distribution<%1%>::bernoulli_distribution",
Chris@16:           m_p,
Chris@16:           &result, Policy());
Chris@16:       } // bernoulli_distribution constructor.
Chris@16: 
Chris@16:       RealType success_fraction() const
Chris@16:       { // Probability.
Chris@16:         return m_p;
Chris@16:       }
Chris@16: 
Chris@16:     private:
Chris@16:       RealType m_p; // success_fraction
Chris@16:     }; // template <class RealType> class bernoulli_distribution
Chris@16: 
Chris@16:     typedef bernoulli_distribution<double> bernoulli;
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline const std::pair<RealType, RealType> range(const bernoulli_distribution<RealType, Policy>& /* dist */)
Chris@16:     { // Range of permissible values for random variable k = {0, 1}.
Chris@16:       using boost::math::tools::max_value;
Chris@16:       return std::pair<RealType, RealType>(static_cast<RealType>(0), static_cast<RealType>(1));
Chris@16:     }
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline const std::pair<RealType, RealType> support(const bernoulli_distribution<RealType, Policy>& /* dist */)
Chris@16:     { // Range of supported values for random variable k = {0, 1}.
Chris@16:       // This is range where cdf rises from 0 to 1, and outside it, the pdf is zero.
Chris@16:       return std::pair<RealType, RealType>(static_cast<RealType>(0), static_cast<RealType>(1));
Chris@16:     }
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType mean(const bernoulli_distribution<RealType, Policy>& dist)
Chris@16:     { // Mean of bernoulli distribution = p (n = 1).
Chris@16:       return dist.success_fraction();
Chris@16:     } // mean
Chris@16: 
Chris@16:     // Rely on dereived_accessors quantile(half)
Chris@16:     //template <class RealType>
Chris@16:     //inline RealType median(const bernoulli_distribution<RealType, Policy>& dist)
Chris@16:     //{ // Median of bernoulli distribution is not defined.
Chris@16:     //  return tools::domain_error<RealType>(BOOST_CURRENT_FUNCTION, "Median is not implemented, result is %1%!", std::numeric_limits<RealType>::quiet_NaN());
Chris@16:     //} // median
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType variance(const bernoulli_distribution<RealType, Policy>& dist)
Chris@16:     { // Variance of bernoulli distribution =p * q.
Chris@16:       return  dist.success_fraction() * (1 - dist.success_fraction());
Chris@16:     } // variance
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     RealType pdf(const bernoulli_distribution<RealType, Policy>& dist, const RealType& k)
Chris@16:     { // Probability Density/Mass Function.
Chris@16:       BOOST_FPU_EXCEPTION_GUARD
Chris@16:       // Error check:
Chris@16:       RealType result = 0; // of checks.
Chris@16:       if(false == bernoulli_detail::check_dist_and_k(
Chris@16:         "boost::math::pdf(bernoulli_distribution<%1%>, %1%)",
Chris@16:         dist.success_fraction(), // 0 to 1
Chris@16:         k, // 0 or 1
Chris@16:         &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16:       // Assume k is integral.
Chris@16:       if (k == 0)
Chris@16:       {
Chris@16:         return 1 - dist.success_fraction(); // 1 - p
Chris@16:       }
Chris@16:       else  // k == 1
Chris@16:       {
Chris@16:         return dist.success_fraction(); // p
Chris@16:       }
Chris@16:     } // pdf
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType cdf(const bernoulli_distribution<RealType, Policy>& dist, const RealType& k)
Chris@16:     { // Cumulative Distribution Function Bernoulli.
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       // Error check:
Chris@16:       RealType result = 0;
Chris@16:       if(false == bernoulli_detail::check_dist_and_k(
Chris@16:         "boost::math::cdf(bernoulli_distribution<%1%>, %1%)",
Chris@16:         p,
Chris@16:         k,
Chris@16:         &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16:       if (k == 0)
Chris@16:       {
Chris@16:         return 1 - p;
Chris@16:       }
Chris@16:       else
Chris@16:       { // k == 1
Chris@16:         return 1;
Chris@16:       }
Chris@16:     } // bernoulli cdf
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType cdf(const complemented2_type<bernoulli_distribution<RealType, Policy>, RealType>& c)
Chris@16:     { // Complemented Cumulative Distribution Function bernoulli.
Chris@16:       RealType const& k = c.param;
Chris@16:       bernoulli_distribution<RealType, Policy> const& dist = c.dist;
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       // Error checks:
Chris@16:       RealType result = 0;
Chris@16:       if(false == bernoulli_detail::check_dist_and_k(
Chris@16:         "boost::math::cdf(bernoulli_distribution<%1%>, %1%)",
Chris@16:         p,
Chris@16:         k,
Chris@16:         &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16:       if (k == 0)
Chris@16:       {
Chris@16:         return p;
Chris@16:       }
Chris@16:       else
Chris@16:       { // k == 1
Chris@16:         return 0;
Chris@16:       }
Chris@16:     } // bernoulli cdf complement
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType quantile(const bernoulli_distribution<RealType, Policy>& dist, const RealType& p)
Chris@16:     { // Quantile or Percent Point Bernoulli function.
Chris@16:       // Return the number of expected successes k either 0 or 1.
Chris@16:       // for a given probability p.
Chris@16: 
Chris@16:       RealType result = 0; // of error checks:
Chris@16:       if(false == bernoulli_detail::check_dist_and_prob(
Chris@16:         "boost::math::quantile(bernoulli_distribution<%1%>, %1%)",
Chris@16:         dist.success_fraction(),
Chris@16:         p,
Chris@16:         &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16:       if (p <= (1 - dist.success_fraction()))
Chris@16:       { // p <= pdf(dist, 0) == cdf(dist, 0)
Chris@16:         return 0;
Chris@16:       }
Chris@16:       else
Chris@16:       {
Chris@16:         return 1;
Chris@16:       }
Chris@16:     } // quantile
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType quantile(const complemented2_type<bernoulli_distribution<RealType, Policy>, RealType>& c)
Chris@16:     { // Quantile or Percent Point bernoulli function.
Chris@16:       // Return the number of expected successes k for a given
Chris@16:       // complement of the probability q.
Chris@16:       //
Chris@16:       // Error checks:
Chris@16:       RealType q = c.param;
Chris@16:       const bernoulli_distribution<RealType, Policy>& dist = c.dist;
Chris@16:       RealType result = 0;
Chris@16:       if(false == bernoulli_detail::check_dist_and_prob(
Chris@16:         "boost::math::quantile(bernoulli_distribution<%1%>, %1%)",
Chris@16:         dist.success_fraction(),
Chris@16:         q,
Chris@16:         &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16: 
Chris@16:       if (q <= 1 - dist.success_fraction())
Chris@16:       { // // q <= cdf(complement(dist, 0)) == pdf(dist, 0)
Chris@16:         return 1;
Chris@16:       }
Chris@16:       else
Chris@16:       {
Chris@16:         return 0;
Chris@16:       }
Chris@16:     } // quantile complemented.
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType mode(const bernoulli_distribution<RealType, Policy>& dist)
Chris@16:     {
Chris@16:       return static_cast<RealType>((dist.success_fraction() <= 0.5) ? 0 : 1); // p = 0.5 can be 0 or 1
Chris@16:     }
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType skewness(const bernoulli_distribution<RealType, Policy>& dist)
Chris@16:     {
Chris@16:       BOOST_MATH_STD_USING; // Aid ADL for sqrt.
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       return (1 - 2 * p) / sqrt(p * (1 - p));
Chris@16:     }
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType kurtosis_excess(const bernoulli_distribution<RealType, Policy>& dist)
Chris@16:     {
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       // Note Wolfram says this is kurtosis in text, but gamma2 is the kurtosis excess,
Chris@16:       // and Wikipedia also says this is the kurtosis excess formula.
Chris@16:       // return (6 * p * p - 6 * p + 1) / (p * (1 - p));
Chris@16:       // But Wolfram kurtosis article gives this simpler formula for kurtosis excess:
Chris@16:       return 1 / (1 - p) + 1/p -6;
Chris@16:     }
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType kurtosis(const bernoulli_distribution<RealType, Policy>& dist)
Chris@16:     {
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       return 1 / (1 - p) + 1/p -6 + 3;
Chris@16:       // Simpler than:
Chris@16:       // return (6 * p * p - 6 * p + 1) / (p * (1 - p)) + 3;
Chris@16:     }
Chris@16: 
Chris@16:   } // namespace math
Chris@16: } // namespace boost
Chris@16: 
Chris@16: // This include must be at the end, *after* the accessors
Chris@16: // for this distribution have been defined, in order to
Chris@16: // keep compilers that support two-phase lookup happy.
Chris@16: #include <boost/math/distributions/detail/derived_accessors.hpp>
Chris@16: 
Chris@16: #endif // BOOST_MATH_SPECIAL_BERNOULLI_HPP
Chris@16: 
Chris@16: 
Chris@16: