1 /* boost random/negative_binomial_distribution.hpp header file
3 * Copyright Steven Watanabe 2010
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)
8 * See http://www.boost.org for most recent version including documentation.
13 #ifndef BOOST_RANDOM_NEGATIVE_BINOMIAL_DISTRIBUTION_HPP_INCLUDED
14 #define BOOST_RANDOM_NEGATIVE_BINOMIAL_DISTRIBUTION_HPP_INCLUDED
18 #include <boost/limits.hpp>
19 #include <boost/random/detail/config.hpp>
20 #include <boost/random/gamma_distribution.hpp>
21 #include <boost/random/poisson_distribution.hpp>
27 * The negative binomial distribution is an integer valued
28 * distribution with two parameters, @c k and @c p. The
29 * distribution produces non-negative values.
31 * The distribution function is
32 * \f$\displaystyle P(i) = {k+i-1\choose i}p^k(1-p)^i\f$.
34 * This implementation uses a gamma-poisson mixture.
36 template<class IntType = int, class RealType = double>
37 class negative_binomial_distribution {
39 typedef IntType result_type;
40 typedef RealType input_type;
44 typedef negative_binomial_distribution distribution_type;
46 * Construct a param_type object. @c k and @c p
47 * are the parameters of the distribution.
49 * Requires: k >=0 && 0 <= p <= 1
51 explicit param_type(IntType k_arg = 1, RealType p_arg = RealType (0.5))
52 : _k(k_arg), _p(p_arg)
54 /** Returns the @c k parameter of the distribution. */
55 IntType k() const { return _k; }
56 /** Returns the @c p parameter of the distribution. */
57 RealType p() const { return _p; }
58 #ifndef BOOST_RANDOM_NO_STREAM_OPERATORS
59 /** Writes the parameters of the distribution to a @c std::ostream. */
60 template<class CharT, class Traits>
61 friend std::basic_ostream<CharT,Traits>&
62 operator<<(std::basic_ostream<CharT,Traits>& os,
63 const param_type& parm)
65 os << parm._p << " " << parm._k;
69 /** Reads the parameters of the distribution from a @c std::istream. */
70 template<class CharT, class Traits>
71 friend std::basic_istream<CharT,Traits>&
72 operator>>(std::basic_istream<CharT,Traits>& is, param_type& parm)
74 is >> parm._p >> std::ws >> parm._k;
78 /** Returns true if the parameters have the same values. */
79 friend bool operator==(const param_type& lhs, const param_type& rhs)
81 return lhs._k == rhs._k && lhs._p == rhs._p;
83 /** Returns true if the parameters have different values. */
84 friend bool operator!=(const param_type& lhs, const param_type& rhs)
94 * Construct a @c negative_binomial_distribution object. @c k and @c p
95 * are the parameters of the distribution.
97 * Requires: k >=0 && 0 <= p <= 1
99 explicit negative_binomial_distribution(IntType k_arg = 1,
100 RealType p_arg = RealType(0.5))
101 : _k(k_arg), _p(p_arg)
105 * Construct an @c negative_binomial_distribution object from the
108 explicit negative_binomial_distribution(const param_type& parm)
109 : _k(parm.k()), _p(parm.p())
113 * Returns a random variate distributed according to the
114 * negative binomial distribution.
117 IntType operator()(URNG& urng) const
119 gamma_distribution<RealType> gamma(_k, (1-_p)/_p);
120 poisson_distribution<IntType, RealType> poisson(gamma(urng));
121 return poisson(urng);
125 * Returns a random variate distributed according to the negative
126 * binomial distribution with parameters specified by @c param.
129 IntType operator()(URNG& urng, const param_type& parm) const
131 return negative_binomial_distribution(parm)(urng);
134 /** Returns the @c k parameter of the distribution. */
135 IntType k() const { return _k; }
136 /** Returns the @c p parameter of the distribution. */
137 RealType p() const { return _p; }
139 /** Returns the smallest value that the distribution can produce. */
140 IntType min BOOST_PREVENT_MACRO_SUBSTITUTION() const { return 0; }
141 /** Returns the largest value that the distribution can produce. */
142 IntType max BOOST_PREVENT_MACRO_SUBSTITUTION() const
143 { return (std::numeric_limits<IntType>::max)(); }
145 /** Returns the parameters of the distribution. */
146 param_type param() const { return param_type(_k, _p); }
147 /** Sets parameters of the distribution. */
148 void param(const param_type& parm)
155 * Effects: Subsequent uses of the distribution do not depend
156 * on values produced by any engine prior to invoking reset.
160 #ifndef BOOST_RANDOM_NO_STREAM_OPERATORS
161 /** Writes the parameters of the distribution to a @c std::ostream. */
162 template<class CharT, class Traits>
163 friend std::basic_ostream<CharT,Traits>&
164 operator<<(std::basic_ostream<CharT,Traits>& os,
165 const negative_binomial_distribution& bd)
171 /** Reads the parameters of the distribution from a @c std::istream. */
172 template<class CharT, class Traits>
173 friend std::basic_istream<CharT,Traits>&
174 operator>>(std::basic_istream<CharT,Traits>& is,
175 negative_binomial_distribution& bd)
182 /** Returns true if the two distributions will produce the same
183 sequence of values, given equal generators. */
184 friend bool operator==(const negative_binomial_distribution& lhs,
185 const negative_binomial_distribution& rhs)
187 return lhs._k == rhs._k && lhs._p == rhs._p;
189 /** Returns true if the two distributions could produce different
190 sequences of values, given equal generators. */
191 friend bool operator!=(const negative_binomial_distribution& lhs,
192 const negative_binomial_distribution& rhs)
194 return !(lhs == rhs);
199 /// @cond \show_private
201 template<class CharT, class Traits>
202 void read(std::basic_istream<CharT, Traits>& is) {