boost/random/student_t_distribution.hpp

   1 /* boost random/student_t_distribution.hpp header file
   2  *
   3  * Copyright Steven Watanabe 2011
   4  * Distributed under the Boost Software License, Version 1.0. (See
   5  * accompanying file LICENSE_1_0.txt or copy at
   6  * http://www.boost.org/LICENSE_1_0.txt)
   7  *
   8  * See http://www.boost.org for most recent version including documentation.
   9  *
  10  * $Id: student_t_distribution.hpp 71018 2011-04-05 21:27:52Z steven_watanabe $
  11  */
  12
  13 #ifndef BOOST_RANDOM_STUDENT_T_DISTRIBUTION_HPP
  14 #define BOOST_RANDOM_STUDENT_T_DISTRIBUTION_HPP
  15
  16 #include <boost/config/no_tr1/cmath.hpp>
  17 #include <iosfwd>
  18 #include <boost/config.hpp>
  19 #include <boost/limits.hpp>
  20 #include <boost/random/detail/operators.hpp>
  21 #include <boost/random/chi_squared_distribution.hpp>
  22 #include <boost/random/normal_distribution.hpp>
  23
  24 namespace boost {
  25 namespace random {
  26
  27 /**
  28  * The Student t distribution is a real valued distribution with one
  29  * parameter n, the number of degrees of freedom.
  30  *
  31  * It has \f$\displaystyle p(x) =
  32  *   \frac{1}{\sqrt{n\pi}}
  33  *   \frac{\Gamma((n+1)/2)}{\Gamma(n/2)}
  34  *   \left(1+\frac{x^2}{n}\right)^{-(n+1)/2}
  35  * \f$.
  36  */
  37 template<class RealType = double>
  38 class student_t_distribution {
  39 public:
  40     typedef RealType result_type;
  41     typedef RealType input_type;
  42
  43     class param_type {
  44     public:
  45         typedef student_t_distribution distribution_type;
  46
  47         /**
  48          * Constructs a @c param_type with "n" degrees of freedom.
  49          *
  50          * Requires: n > 0
  51          */
  52         explicit param_type(RealType n_arg = RealType(1.0))
  53           : _n(n_arg)
  54         {}
  55
  56         /** Returns the number of degrees of freedom of the distribution. */
  57         RealType n() const { return _n; }
  58
  59         /** Writes a @c param_type to a @c std::ostream. */
  60         BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
  61         { os << parm._n; return os; }
  62
  63         /** Reads a @c param_type from a @c std::istream. */
  64         BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
  65         { is >> parm._n; return is; }
  66
  67         /** Returns true if the two sets of parameters are the same. */
  68         BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
  69         { return lhs._n == rhs._n; }
  70
  71         /** Returns true if the two sets of parameters are the different. */
  72         BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
  73
  74     private:
  75         RealType _n;
  76     };
  77
  78     /**
  79      * Constructs an @c student_t_distribution with "n" degrees of freedom.
  80      *
  81      * Requires: n > 0
  82      */
  83     explicit student_t_distribution(RealType n_arg = RealType(1.0))
  84       : _normal(), _chi_squared(n_arg)
  85     {}
  86     /** Constructs an @c student_t_distribution from its parameters. */
  87     explicit student_t_distribution(const param_type& parm)
  88       : _normal(), _chi_squared(parm.n())
  89     {}
  90
  91     /**
  92      * Returns a random variate distributed according to the
  93      * Student t distribution.
  94      */
  95     template<class URNG>
  96     RealType operator()(URNG& urng)
  97     {
  98         using std::sqrt;
  99         return _normal(urng) / sqrt(_chi_squared(urng) / n());
 100     }
 101
 102     /**
 103      * Returns a random variate distributed accordint to the Student
 104      * t distribution with parameters specified by @c param.
 105      */
 106     template<class URNG>
 107     RealType operator()(URNG& urng, const param_type& parm) const
 108     {
 109         return student_t_distribution(parm)(urng);
 110     }
 111
 112     /** Returns the number of degrees of freedom. */
 113     RealType n() const { return _chi_squared.n(); }
 114
 115     /** Returns the smallest value that the distribution can produce. */
 116     RealType min BOOST_PREVENT_MACRO_SUBSTITUTION () const
 117     { return -std::numeric_limits<RealType>::infinity(); }
 118     /** Returns the largest value that the distribution can produce. */
 119     RealType max BOOST_PREVENT_MACRO_SUBSTITUTION () const
 120     { return std::numeric_limits<RealType>::infinity(); }
 121
 122     /** Returns the parameters of the distribution. */
 123     param_type param() const { return param_type(n()); }
 124     /** Sets the parameters of the distribution. */
 125     void param(const param_type& parm)
 126     {
 127         typedef chi_squared_distribution<RealType> chi_squared_type;
 128         typename chi_squared_type::param_type chi_squared_param(parm.n());
 129         _chi_squared.param(chi_squared_param);
 130     }
 131
 132     /**
 133      * Effects: Subsequent uses of the distribution do not depend
 134      * on values produced by any engine prior to invoking reset.
 135      */
 136     void reset()
 137     {
 138         _normal.reset();
 139         _chi_squared.reset();
 140     }
 141
 142     /** Writes a @c student_t_distribution to a @c std::ostream. */
 143     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, student_t_distribution, td)
 144     {
 145         os << td.param();
 146         return os;
 147     }
 148
 149     /** Reads a @c student_t_distribution from a @c std::istream. */
 150     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, student_t_distribution, td)
 151     {
 152         param_type parm;
 153         if(is >> parm) {
 154             td.param(parm);
 155         }
 156         return is;
 157     }
 158
 159     /**
 160      * Returns true if the two instances of @c student_t_distribution will
 161      * return identical sequences of values given equal generators.
 162      */
 163     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(student_t_distribution, lhs, rhs)
 164     { return lhs._normal == rhs._normal && lhs._chi_squared == rhs._chi_squared; }
 165
 166     /**
 167      * Returns true if the two instances of @c student_t_distribution will
 168      * return different sequences of values given equal generators.
 169      */
 170     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(student_t_distribution)
 171
 172 private:
 173     normal_distribution<RealType> _normal;
 174     chi_squared_distribution<RealType> _chi_squared;
 175 };
 176
 177 } // namespace random
 178 } // namespace boost
 179
 180 #endif // BOOST_RANDOM_STUDENT_T_DISTRIBUTION_HPP