help mata mm_rbinomial()
-------------------------------------------------------------------------------

Title

    mm_rbinomial() -- Generate binomial distributed random numbers

-------------------------------------------------------------------------------
  Note: An official rbinomial() function was introduced in Stata 10.1 (see
  help [M-5] runiform()). Official rbinomial() is much faster than
  mm_rbinomial().
-------------------------------------------------------------------------------


Syntax

        real matrix mm_rbinomial(n, p)

        real matrix mm_cebinomial(n, k, p)

    where

        n:  real matrix n
        k:  real matrix k
        p:  real matrix p


Description

    mm_rbinomial() returns a random draw from the binomial distribution where
    n is the number of trials and p is the success probability.

    When n and p are not scalar, mm_rbinomial() returns element-by-element
    results. n and p are required to be r-conformable (see help [M-6]
    glossary).

    If you are serious about generating random numbers, you should first set
    the random number seed; see help generate or help for [M-5] uniform().

    mm_cebinomial() returns the expected value of a binomial distributed
    random variable conditional on the variable being equal to k or larger.
    That is, mm_cebinomial() returns

        E(X|X>=k)

    where

        X ~ B(n, p)

    and n is the number of trials and p is the success probability.

    When n, k, and p are not scalar, mm_cebinomial() returns
    element-by-element results. n, k, and p are required to be r-conformable
    (see help [M-6] glossary).


Remarks

    mm_rbinomial(): If n<50 or p>.03, the random numbers are generated using
    the rejection technique. If n>=50 and p>=.03, the geometric distribution
    technique is applied (see Evans et al. 2000).

    mm_cebinomial(): The expectation of X ~ B(n, p) conditional on X>=k may
    be written as

        E(X|X>=k) = k + [ P(X>=k+1) + ... + P(X=n) ] / P(X>=k)

    where P(X>=k) is the probability of k or more successes, which is
    computed as Binomial(n, k, p) (see [M-5] normal()).


Conformability

    Both functions require arguments be r-conformable (see help [M-6]
    glossary). Returned is a matrix of max(argument rows) rows and
    max(argument columns) columns containing element-by-element calculated
    results.


Diagnostics

    Missing value is returned if arguments are out of range (p>1, p<0, n<=0,
    k<0, or k>n) or contain missing value or if n and k are non-integer.


Source code

    mm_rbinomial.mata, mm_cebinomial.mata


References

    Evans, M., N. Hastings, B. Peacock (2000): Statistical Distributions.
        Third Edition. New York: Wiley.


Author

    Ben Jann, ETH Zurich, jann@soz.gess.ethz.ch


Also see

    Online:  help for [M-5] normal(), moremata