boost/random/student_t_distribution.hpp

0001 /* boost random/student_t_distribution.hpp header file
0002  *
0003  * Copyright Steven Watanabe 2011
0004  * Distributed under the Boost Software License, Version 1.0. (See
0005  * accompanying file LICENSE_1_0.txt or copy at
0006  * http://www.boost.org/LICENSE_1_0.txt)
0007  *
0008  * See http://www.boost.org for most recent version including documentation.
0009  *
0010  * $Id$
0011  */
0012
0013 #ifndef BOOST_RANDOM_STUDENT_T_DISTRIBUTION_HPP
0014 #define BOOST_RANDOM_STUDENT_T_DISTRIBUTION_HPP
0015
0016 #include <boost/config/no_tr1/cmath.hpp>
0017 #include <iosfwd>
0018 #include <boost/config.hpp>
0019 #include <boost/limits.hpp>
0020 #include <boost/random/detail/operators.hpp>
0021 #include <boost/random/chi_squared_distribution.hpp>
0022 #include <boost/random/normal_distribution.hpp>
0023
0024 namespace boost {
0025 namespace random {
0026
0027 /**
0028  * The Student t distribution is a real valued distribution with one
0029  * parameter n, the number of degrees of freedom.
0030  *
0031  * It has \f$\displaystyle p(x) =
0032  *   \frac{1}{\sqrt{n\pi}}
0033  *   \frac{\Gamma((n+1)/2)}{\Gamma(n/2)}
0034  *   \left(1+\frac{x^2}{n}\right)^{-(n+1)/2}
0035  * \f$.
0036  */
0037 template<class RealType = double>
0038 class student_t_distribution {
0039 public:
0040     typedef RealType result_type;
0041     typedef RealType input_type;
0042
0043     class param_type {
0044     public:
0045         typedef student_t_distribution distribution_type;
0046
0047         /**
0048          * Constructs a @c param_type with "n" degrees of freedom.
0049          *
0050          * Requires: n > 0
0051          */
0052         explicit param_type(RealType n_arg = RealType(1.0))
0053           : _n(n_arg)
0054         {}
0055
0056         /** Returns the number of degrees of freedom of the distribution. */
0057         RealType n() const { return _n; }
0058
0059         /** Writes a @c param_type to a @c std::ostream. */
0060         BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
0061         { os << parm._n; return os; }
0062
0063         /** Reads a @c param_type from a @c std::istream. */
0064         BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
0065         { is >> parm._n; return is; }
0066
0067         /** Returns true if the two sets of parameters are the same. */
0068         BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
0069         { return lhs._n == rhs._n; }
0070
0071         /** Returns true if the two sets of parameters are the different. */
0072         BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
0073
0074     private:
0075         RealType _n;
0076     };
0077
0078     /**
0079      * Constructs an @c student_t_distribution with "n" degrees of freedom.
0080      *
0081      * Requires: n > 0
0082      */
0083     explicit student_t_distribution(RealType n_arg = RealType(1.0))
0084       : _normal(), _chi_squared(n_arg)
0085     {}
0086     /** Constructs an @c student_t_distribution from its parameters. */
0087     explicit student_t_distribution(const param_type& parm)
0088       : _normal(), _chi_squared(parm.n())
0089     {}
0090
0091     /**
0092      * Returns a random variate distributed according to the
0093      * Student t distribution.
0094      */
0095     template<class URNG>
0096     RealType operator()(URNG& urng)
0097     {
0098         using std::sqrt;
0099         return _normal(urng) / sqrt(_chi_squared(urng) / n());
0100     }
0101
0102     /**
0103      * Returns a random variate distributed accordint to the Student
0104      * t distribution with parameters specified by @c param.
0105      */
0106     template<class URNG>
0107     RealType operator()(URNG& urng, const param_type& parm) const
0108     {
0109         return student_t_distribution(parm)(urng);
0110     }
0111
0112     /** Returns the number of degrees of freedom. */
0113     RealType n() const { return _chi_squared.n(); }
0114
0115     /** Returns the smallest value that the distribution can produce. */
0116     RealType min BOOST_PREVENT_MACRO_SUBSTITUTION () const
0117     { return -std::numeric_limits<RealType>::infinity(); }
0118     /** Returns the largest value that the distribution can produce. */
0119     RealType max BOOST_PREVENT_MACRO_SUBSTITUTION () const
0120     { return std::numeric_limits<RealType>::infinity(); }
0121
0122     /** Returns the parameters of the distribution. */
0123     param_type param() const { return param_type(n()); }
0124     /** Sets the parameters of the distribution. */
0125     void param(const param_type& parm)
0126     {
0127         typedef chi_squared_distribution<RealType> chi_squared_type;
0128         typename chi_squared_type::param_type chi_squared_param(parm.n());
0129         _chi_squared.param(chi_squared_param);
0130     }
0131
0132     /**
0133      * Effects: Subsequent uses of the distribution do not depend
0134      * on values produced by any engine prior to invoking reset.
0135      */
0136     void reset()
0137     {
0138         _normal.reset();
0139         _chi_squared.reset();
0140     }
0141
0142     /** Writes a @c student_t_distribution to a @c std::ostream. */
0143     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, student_t_distribution, td)
0144     {
0145         os << td.param();
0146         return os;
0147     }
0148
0149     /** Reads a @c student_t_distribution from a @c std::istream. */
0150     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, student_t_distribution, td)
0151     {
0152         param_type parm;
0153         if(is >> parm) {
0154             td.param(parm);
0155         }
0156         return is;
0157     }
0158
0159     /**
0160      * Returns true if the two instances of @c student_t_distribution will
0161      * return identical sequences of values given equal generators.
0162      */
0163     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(student_t_distribution, lhs, rhs)
0164     { return lhs._normal == rhs._normal && lhs._chi_squared == rhs._chi_squared; }
0165
0166     /**
0167      * Returns true if the two instances of @c student_t_distribution will
0168      * return different sequences of values given equal generators.
0169      */
0170     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(student_t_distribution)
0171
0172 private:
0173     normal_distribution<RealType> _normal;
0174     chi_squared_distribution<RealType> _chi_squared;
0175 };
0176
0177 } // namespace random
0178 } // namespace boost
0179
0180 #endif // BOOST_RANDOM_STUDENT_T_DISTRIBUTION_HPP