Chris@16: //  Copyright John Maddock 2006, 2007.
Chris@16: //  Copyright Paul A. Bristow 2006, 2007.
Chris@16: 
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_NORMAL_HPP
Chris@16: #define BOOST_STATS_NORMAL_HPP
Chris@16: 
Chris@16: // http://en.wikipedia.org/wiki/Normal_distribution
Chris@16: // http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm
Chris@16: // Also:
Chris@16: // Weisstein, Eric W. "Normal Distribution."
Chris@16: // From MathWorld--A Wolfram Web Resource.
Chris@16: // http://mathworld.wolfram.com/NormalDistribution.html
Chris@16: 
Chris@16: #include <boost/math/distributions/fwd.hpp>
Chris@16: #include <boost/math/special_functions/erf.hpp> // for erf/erfc.
Chris@16: #include <boost/math/distributions/complement.hpp>
Chris@16: #include <boost/math/distributions/detail/common_error_handling.hpp>
Chris@16: 
Chris@16: #include <utility>
Chris@16: 
Chris@16: namespace boost{ namespace math{
Chris@16: 
Chris@16: template <class RealType = double, class Policy = policies::policy<> >
Chris@16: class normal_distribution
Chris@16: {
Chris@16: public:
Chris@16:    typedef RealType value_type;
Chris@16:    typedef Policy policy_type;
Chris@16: 
Chris@16:    normal_distribution(RealType l_mean = 0, RealType sd = 1)
Chris@16:       : m_mean(l_mean), m_sd(sd)
Chris@16:    { // Default is a 'standard' normal distribution N01.
Chris@16:      static const char* function = "boost::math::normal_distribution<%1%>::normal_distribution";
Chris@16: 
Chris@16:      RealType result;
Chris@16:      detail::check_scale(function, sd, &result, Policy());
Chris@16:      detail::check_location(function, l_mean, &result, Policy());
Chris@16:    }
Chris@16: 
Chris@16:    RealType mean()const
Chris@16:    { // alias for location.
Chris@16:       return m_mean;
Chris@16:    }
Chris@16: 
Chris@16:    RealType standard_deviation()const
Chris@16:    { // alias for scale.
Chris@16:       return m_sd;
Chris@16:    }
Chris@16: 
Chris@16:    // Synonyms, provided to allow generic use of find_location and find_scale.
Chris@16:    RealType location()const
Chris@16:    { // location.
Chris@16:       return m_mean;
Chris@16:    }
Chris@16:    RealType scale()const
Chris@16:    { // scale.
Chris@16:       return m_sd;
Chris@16:    }
Chris@16: 
Chris@16: private:
Chris@16:    //
Chris@16:    // Data members:
Chris@16:    //
Chris@16:    RealType m_mean;  // distribution mean or location.
Chris@16:    RealType m_sd;    // distribution standard deviation or scale.
Chris@16: }; // class normal_distribution
Chris@16: 
Chris@16: typedef normal_distribution<double> normal;
Chris@16: 
Chris@101: #ifdef BOOST_MSVC
Chris@101: #pragma warning(push)
Chris@101: #pragma warning(disable:4127)
Chris@101: #endif
Chris@101: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline const std::pair<RealType, RealType> range(const normal_distribution<RealType, Policy>& /*dist*/)
Chris@16: { // Range of permissible values for random variable x.
Chris@16:   if (std::numeric_limits<RealType>::has_infinity)
Chris@16:   { 
Chris@16:      return std::pair<RealType, RealType>(-std::numeric_limits<RealType>::infinity(), std::numeric_limits<RealType>::infinity()); // - to + infinity.
Chris@16:   }
Chris@16:   else
Chris@16:   { // Can only use max_value.
Chris@16:     using boost::math::tools::max_value;
Chris@16:     return std::pair<RealType, RealType>(-max_value<RealType>(), max_value<RealType>()); // - to + max value.
Chris@16:   }
Chris@16: }
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline const std::pair<RealType, RealType> support(const normal_distribution<RealType, Policy>& /*dist*/)
Chris@101: { // This is range values for random variable x where cdf rises from 0 to 1, and outside it, the pdf is zero.
Chris@16:   if (std::numeric_limits<RealType>::has_infinity)
Chris@16:   { 
Chris@16:      return std::pair<RealType, RealType>(-std::numeric_limits<RealType>::infinity(), std::numeric_limits<RealType>::infinity()); // - to + infinity.
Chris@16:   }
Chris@16:   else
Chris@16:   { // Can only use max_value.
Chris@16:    using boost::math::tools::max_value;
Chris@16:    return std::pair<RealType, RealType>(-max_value<RealType>(),  max_value<RealType>()); // - to + max value.
Chris@16:   }
Chris@16: }
Chris@16: 
Chris@101: #ifdef BOOST_MSVC
Chris@101: #pragma warning(pop)
Chris@101: #endif
Chris@101: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType pdf(const normal_distribution<RealType, Policy>& dist, const RealType& x)
Chris@16: {
Chris@16:    BOOST_MATH_STD_USING  // for ADL of std functions
Chris@16: 
Chris@16:    RealType sd = dist.standard_deviation();
Chris@16:    RealType mean = dist.mean();
Chris@16: 
Chris@16:    static const char* function = "boost::math::pdf(const normal_distribution<%1%>&, %1%)";
Chris@16: 
Chris@16:    RealType result = 0;
Chris@16:    if(false == detail::check_scale(function, sd, &result, Policy()))
Chris@16:    {
Chris@16:       return result;
Chris@16:    }
Chris@16:    if(false == detail::check_location(function, mean, &result, Policy()))
Chris@16:    {
Chris@16:       return result;
Chris@16:    }
Chris@16:    if((boost::math::isinf)(x))
Chris@16:    {
Chris@16:      return 0; // pdf + and - infinity is zero.
Chris@16:    }
Chris@16:    // Below produces MSVC 4127 warnings, so the above used instead.
Chris@16:    //if(std::numeric_limits<RealType>::has_infinity && abs(x) == std::numeric_limits<RealType>::infinity())
Chris@16:    //{ // pdf + and - infinity is zero.
Chris@16:    //  return 0;
Chris@16:    //}
Chris@16:    if(false == detail::check_x(function, x, &result, Policy()))
Chris@16:    {
Chris@16:       return result;
Chris@16:    }
Chris@16: 
Chris@16:    RealType exponent = x - mean;
Chris@16:    exponent *= -exponent;
Chris@16:    exponent /= 2 * sd * sd;
Chris@16: 
Chris@16:    result = exp(exponent);
Chris@16:    result /= sd * sqrt(2 * constants::pi<RealType>());
Chris@16: 
Chris@16:    return result;
Chris@16: } // pdf
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType cdf(const normal_distribution<RealType, Policy>& dist, const RealType& x)
Chris@16: {
Chris@16:    BOOST_MATH_STD_USING  // for ADL of std functions
Chris@16: 
Chris@16:    RealType sd = dist.standard_deviation();
Chris@16:    RealType mean = dist.mean();
Chris@16:    static const char* function = "boost::math::cdf(const normal_distribution<%1%>&, %1%)";
Chris@16:    RealType result = 0;
Chris@16:    if(false == detail::check_scale(function, sd, &result, Policy()))
Chris@16:    {
Chris@16:       return result;
Chris@16:    }
Chris@16:    if(false == detail::check_location(function, mean, &result, Policy()))
Chris@16:    {
Chris@16:       return result;
Chris@16:    }
Chris@16:    if((boost::math::isinf)(x))
Chris@16:    {
Chris@16:      if(x < 0) return 0; // -infinity
Chris@16:      return 1; // + infinity
Chris@16:    }
Chris@16:    // These produce MSVC 4127 warnings, so the above used instead.
Chris@16:    //if(std::numeric_limits<RealType>::has_infinity && x == std::numeric_limits<RealType>::infinity())
Chris@16:    //{ // cdf +infinity is unity.
Chris@16:    //  return 1;
Chris@16:    //}
Chris@16:    //if(std::numeric_limits<RealType>::has_infinity && x == -std::numeric_limits<RealType>::infinity())
Chris@16:    //{ // cdf -infinity is zero.
Chris@16:    //  return 0;
Chris@16:    //}
Chris@16:    if(false == detail::check_x(function, x, &result, Policy()))
Chris@16:    {
Chris@16:      return result;
Chris@16:    }
Chris@16:    RealType diff = (x - mean) / (sd * constants::root_two<RealType>());
Chris@16:    result = boost::math::erfc(-diff, Policy()) / 2;
Chris@16:    return result;
Chris@16: } // cdf
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType quantile(const normal_distribution<RealType, Policy>& dist, const RealType& p)
Chris@16: {
Chris@16:    BOOST_MATH_STD_USING  // for ADL of std functions
Chris@16: 
Chris@16:    RealType sd = dist.standard_deviation();
Chris@16:    RealType mean = dist.mean();
Chris@16:    static const char* function = "boost::math::quantile(const normal_distribution<%1%>&, %1%)";
Chris@16: 
Chris@16:    RealType result = 0;
Chris@16:    if(false == detail::check_scale(function, sd, &result, Policy()))
Chris@16:       return result;
Chris@16:    if(false == detail::check_location(function, mean, &result, Policy()))
Chris@16:       return result;
Chris@16:    if(false == detail::check_probability(function, p, &result, Policy()))
Chris@16:       return result;
Chris@16: 
Chris@16:    result= boost::math::erfc_inv(2 * p, Policy());
Chris@16:    result = -result;
Chris@16:    result *= sd * constants::root_two<RealType>();
Chris@16:    result += mean;
Chris@16:    return result;
Chris@16: } // quantile
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType cdf(const complemented2_type<normal_distribution<RealType, Policy>, RealType>& c)
Chris@16: {
Chris@16:    BOOST_MATH_STD_USING  // for ADL of std functions
Chris@16: 
Chris@16:    RealType sd = c.dist.standard_deviation();
Chris@16:    RealType mean = c.dist.mean();
Chris@16:    RealType x = c.param;
Chris@16:    static const char* function = "boost::math::cdf(const complement(normal_distribution<%1%>&), %1%)";
Chris@16: 
Chris@16:    RealType result = 0;
Chris@16:    if(false == detail::check_scale(function, sd, &result, Policy()))
Chris@16:       return result;
Chris@16:    if(false == detail::check_location(function, mean, &result, Policy()))
Chris@16:       return result;
Chris@16:    if((boost::math::isinf)(x))
Chris@16:    {
Chris@16:      if(x < 0) return 1; // cdf complement -infinity is unity.
Chris@16:      return 0; // cdf complement +infinity is zero
Chris@16:    }
Chris@16:    // These produce MSVC 4127 warnings, so the above used instead.
Chris@16:    //if(std::numeric_limits<RealType>::has_infinity && x == std::numeric_limits<RealType>::infinity())
Chris@16:    //{ // cdf complement +infinity is zero.
Chris@16:    //  return 0;
Chris@16:    //}
Chris@16:    //if(std::numeric_limits<RealType>::has_infinity && x == -std::numeric_limits<RealType>::infinity())
Chris@16:    //{ // cdf complement -infinity is unity.
Chris@16:    //  return 1;
Chris@16:    //}
Chris@16:    if(false == detail::check_x(function, x, &result, Policy()))
Chris@16:       return result;
Chris@16: 
Chris@16:    RealType diff = (x - mean) / (sd * constants::root_two<RealType>());
Chris@16:    result = boost::math::erfc(diff, Policy()) / 2;
Chris@16:    return result;
Chris@16: } // cdf complement
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType quantile(const complemented2_type<normal_distribution<RealType, Policy>, RealType>& c)
Chris@16: {
Chris@16:    BOOST_MATH_STD_USING  // for ADL of std functions
Chris@16: 
Chris@16:    RealType sd = c.dist.standard_deviation();
Chris@16:    RealType mean = c.dist.mean();
Chris@16:    static const char* function = "boost::math::quantile(const complement(normal_distribution<%1%>&), %1%)";
Chris@16:    RealType result = 0;
Chris@16:    if(false == detail::check_scale(function, sd, &result, Policy()))
Chris@16:       return result;
Chris@16:    if(false == detail::check_location(function, mean, &result, Policy()))
Chris@16:       return result;
Chris@16:    RealType q = c.param;
Chris@16:    if(false == detail::check_probability(function, q, &result, Policy()))
Chris@16:       return result;
Chris@16:    result = boost::math::erfc_inv(2 * q, Policy());
Chris@16:    result *= sd * constants::root_two<RealType>();
Chris@16:    result += mean;
Chris@16:    return result;
Chris@16: } // quantile
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType mean(const normal_distribution<RealType, Policy>& dist)
Chris@16: {
Chris@16:    return dist.mean();
Chris@16: }
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType standard_deviation(const normal_distribution<RealType, Policy>& dist)
Chris@16: {
Chris@16:    return dist.standard_deviation();
Chris@16: }
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType mode(const normal_distribution<RealType, Policy>& dist)
Chris@16: {
Chris@16:    return dist.mean();
Chris@16: }
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType median(const normal_distribution<RealType, Policy>& dist)
Chris@16: {
Chris@16:    return dist.mean();
Chris@16: }
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType skewness(const normal_distribution<RealType, Policy>& /*dist*/)
Chris@16: {
Chris@16:    return 0;
Chris@16: }
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType kurtosis(const normal_distribution<RealType, Policy>& /*dist*/)
Chris@16: {
Chris@16:    return 3;
Chris@16: }
Chris@16: 
Chris@16: template <class RealType, class Policy>
Chris@16: inline RealType kurtosis_excess(const normal_distribution<RealType, Policy>& /*dist*/)
Chris@16: {
Chris@16:    return 0;
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_STATS_NORMAL_HPP
Chris@16: 
Chris@16: