{smcl}
{* 31 aug 2004}{...}
{hline}
help for {hi:genbinomial}
{hline}

{title:Generate random deviates from the binomial distribution}

{p 8 14}{cmd:genbinomial} {it:newvar} 
	[{cmd:if} {it:exp}] [{cmd:in} {it:range}]{cmd:,}
	{{cmd:p(}{it:#}|{it:varname}{cmd:)} |
	{cmdab:m:u(}{it:#}|{it:varname}{cmd:)} | 
	{cmdab:xb:eta(}{it:varname}{cmd:)}} [ 
        {{cmd:n(}{it:#}|{it:varname}{cmd:)} |
	{cmdab:d:enominator(}{it:#}|{it:varname}{cmd:)}}
	{cmdab:l:ink(}{it:linkname}{cmd:)}
	]

{p 4 4 2}where {it:linkname} is one of

{p 8 8 2}{cmdab:i:dentity} | {cmd:log} | {cmdab:l:ogit} | {cmdab:p:robit} |
{cmdab:c:loglog} | {cmdab:logl:og} | {cmd:logc}

{title:Description}

{p}{cmd:genbinomial} generates data {it:newvar} which are random draws
from a binomial distribution with a given number of trials and success
probability.

{title:Options}

{p 0 4}{cmd:p(}{it:#}|{it:varname}{cmd:)} specifies the success probability
as either a constant {it:#} or (when the probability of success varies 
from observation to observation) {it:varname}.

{p 0 4}{cmd:mu(}{it:#}|{it:varname}{cmd:)} is a synonym for {cmd:p()}.

{p 0 4}{cmd:xbeta(}{it:varname}{cmd:)} specifies the linear 
predictor in a binomial regression model.  That is, rather than specify
the success probability {cmd:p()} directly, you can specify a linear 
predictor variable and a link function (see option {cmd:link()} below), and
{cmd:genbinomial} will generate binomial deviates with success probability
equal to the inverse link of the linear predictor.  Thus, {cmd:xbeta()} 
is useful if you wish to compare various {help glm} links with simulated 
data.

{p 4 4}You must specify either {cmd:p()}/{cmd:mu()} or {cmd:xbeta()}.

{p 0 4}{cmd:n(}{it:#}|{it:varname}{cmd:)} specifies the number of Bernoulli
trials, either as a constant {it:#} or {it:varname} when n varies from 
observation to observation.  By default, n is equal to 1.

{p 0 4}{cmd:denominator(}{it:#}|{it:varname}{cmd:)} is a synonym for {cmd:n()}.

{p 0 4}{cmd:link(}{it:linkname}{cmd:)} is for use with {cmd:xbeta()}, and 
specifies the link function to be applied to the linear predictor.  By default,
(when you specify {cmd:xbeta()}) the (inverse) logit link is applied to 
the linear predictor, thus making the generated response appropriate for 
{help glm} with {cmd:family(binomial {it:n})} and {cmd:link(logit)}.  The
other available links are listed in the above syntax diagram, and are 
consistent with those found in {help glm}.

{p 4 4}{cmd:link()} is not allowed when you specify either {cmd:mu()} or 
{cmd:p()}.

{title:Examples}

{p 4 8 2}{inp:. genbinomial b, p(0.4)}{p_end}

{p 4 8 2}{inp:. genbinomial b, p(0.4) n(500)}{p_end}

{p 4 8 2}{inp:. genbinomial b, p(p_var) n(n_var)}{p_end}

{p 4 8 2}{inp:. gen x1 = invnorm(uniform())}{p_end}
{p 4 8 2}{inp:. gen x2 = invnorm(uniform())}{p_end}
{p 4 8 2}{inp:. gen xb = -1 + 0.5*x1 + 1.5*x2}{p_end}
{p 4 8 2}{inp:. genbinomial y, xbeta(xb) n(50)}{p_end}
{p 4 8 2}{inp:. glm y x1 x2, fam(bin 50)}{p_end}

{p 4 8 2}{inp:. genbinomial y_c, xbeta(xb) n(n_var) link(cloglog)}{p_end}
{p 4 8 2}{inp:. glm y_c x1 x2, fam(bin n_var) link(cloglog)}{p_end}

{title:Replication}

{p}For technical reasons having to do with plugins, {cmd:genbinomial} uses
Stata's older random number generator.  As a result, those wishing to 
replicate previous random draws should {cmd:set seed0} {it:#} rather than 
{cmd:set seed} {it:#}.  See {help version:help version} for more details.

{title:Acknowledgement}

{p}{cmd:genbinomial} is an extension of {cmd:rndbinx}, by Hilbe et al., STB-41.
{cmd:genbinomial} is somewhat faster than {cmd:rndbinx} since the binomial
generation algorithm is implemented as a plugin.