boost/random/fisher_f_distribution.hpp

0001 /* boost random/fisher_f_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_FISHER_F_DISTRIBUTION_HPP
0014 #define BOOST_RANDOM_FISHER_F_DISTRIBUTION_HPP
0015
0016 #include <iosfwd>
0017 #include <istream>
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
0023 namespace boost {
0024 namespace random {
0025
0026 /**
0027  * The Fisher F distribution is a real valued distribution with two
0028  * parameters m and n.
0029  *
0030  * It has \f$\displaystyle p(x) =
0031  *   \frac{\Gamma((m+n)/2)}{\Gamma(m/2)\Gamma(n/2)}
0032  *   \left(\frac{m}{n}\right)^{m/2}
0033  *   x^{(m/2)-1} \left(1+\frac{mx}{n}\right)^{-(m+n)/2}
0034  * \f$.
0035  */
0036 template<class RealType = double>
0037 class fisher_f_distribution {
0038 public:
0039     typedef RealType result_type;
0040     typedef RealType input_type;
0041
0042     class param_type {
0043     public:
0044         typedef fisher_f_distribution distribution_type;
0045
0046         /**
0047          * Constructs a @c param_type from the "m" and "n" parameters
0048          * of the distribution.
0049          *
0050          * Requires: m > 0 and n > 0
0051          */
0052         explicit param_type(RealType m_arg = RealType(1.0),
0053                             RealType n_arg = RealType(1.0))
0054           : _m(m_arg), _n(n_arg)
0055         {}
0056
0057         /** Returns the "m" parameter of the distribtuion. */
0058         RealType m() const { return _m; }
0059         /** Returns the "n" parameter of the distribution. */
0060         RealType n() const { return _n; }
0061
0062         /** Writes a @c param_type to a @c std::ostream. */
0063         BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
0064         { os << parm._m << ' ' << parm._n; return os; }
0065
0066         /** Reads a @c param_type from a @c std::istream. */
0067         BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
0068         { is >> parm._m >> std::ws >> parm._n; return is; }
0069
0070         /** Returns true if the two sets of parameters are the same. */
0071         BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
0072         { return lhs._m == rhs._m && lhs._n == rhs._n; }
0073
0074         /** Returns true if the two sets of parameters are the different. */
0075         BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
0076
0077     private:
0078         RealType _m;
0079         RealType _n;
0080     };
0081
0082     /**
0083      * Constructs a @c fisher_f_distribution from its "m" and "n" parameters.
0084      *
0085      * Requires: m > 0 and n > 0
0086      */
0087     explicit fisher_f_distribution(RealType m_arg = RealType(1.0),
0088                                    RealType n_arg = RealType(1.0))
0089       : _impl_m(m_arg), _impl_n(n_arg)
0090     {}
0091     /** Constructs an @c fisher_f_distribution from its parameters. */
0092     explicit fisher_f_distribution(const param_type& parm)
0093       : _impl_m(parm.m()), _impl_n(parm.n())
0094     {}
0095
0096     /**
0097      * Returns a random variate distributed according to the
0098      * F distribution.
0099      */
0100     template<class URNG>
0101     RealType operator()(URNG& urng)
0102     {
0103         return (_impl_m(urng) * n()) / (_impl_n(urng) * m());
0104     }
0105
0106     /**
0107      * Returns a random variate distributed according to the
0108      * F distribution with parameters specified by @c param.
0109      */
0110     template<class URNG>
0111     RealType operator()(URNG& urng, const param_type& parm) const
0112     {
0113         return fisher_f_distribution(parm)(urng);
0114     }
0115
0116     /** Returns the "m" parameter of the distribution. */
0117     RealType m() const { return _impl_m.n(); }
0118     /** Returns the "n" parameter of the distribution. */
0119     RealType n() const { return _impl_n.n(); }
0120
0121     /** Returns the smallest value that the distribution can produce. */
0122     RealType min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return 0; }
0123     /** Returns the largest value that the distribution can produce. */
0124     RealType max BOOST_PREVENT_MACRO_SUBSTITUTION () const
0125     { return std::numeric_limits<RealType>::infinity(); }
0126
0127     /** Returns the parameters of the distribution. */
0128     param_type param() const { return param_type(m(), n()); }
0129     /** Sets the parameters of the distribution. */
0130     void param(const param_type& parm)
0131     {
0132         typedef chi_squared_distribution<RealType> impl_type;
0133         typename impl_type::param_type m_param(parm.m());
0134         _impl_m.param(m_param);
0135         typename impl_type::param_type n_param(parm.n());
0136         _impl_n.param(n_param);
0137     }
0138
0139     /**
0140      * Effects: Subsequent uses of the distribution do not depend
0141      * on values produced by any engine prior to invoking reset.
0142      */
0143     void reset() { }
0144
0145     /** Writes an @c fisher_f_distribution to a @c std::ostream. */
0146     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, fisher_f_distribution, fd)
0147     {
0148         os << fd.param();
0149         return os;
0150     }
0151
0152     /** Reads an @c fisher_f_distribution from a @c std::istream. */
0153     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, fisher_f_distribution, fd)
0154     {
0155         param_type parm;
0156         if(is >> parm) {
0157             fd.param(parm);
0158         }
0159         return is;
0160     }
0161
0162     /**
0163      * Returns true if the two instances of @c fisher_f_distribution will
0164      * return identical sequences of values given equal generators.
0165      */
0166     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(fisher_f_distribution, lhs, rhs)
0167     { return lhs._impl_m == rhs._impl_m && lhs._impl_n == rhs._impl_n; }
0168
0169     /**
0170      * Returns true if the two instances of @c fisher_f_distribution will
0171      * return different sequences of values given equal generators.
0172      */
0173     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(fisher_f_distribution)
0174
0175 private:
0176     chi_squared_distribution<RealType> _impl_m;
0177     chi_squared_distribution<RealType> _impl_n;
0178 };
0179
0180 } // namespace random
0181 } // namespace boost
0182
0183 #endif // BOOST_RANDOM_EXTREME_VALUE_DISTRIBUTION_HPP