{smcl}
{* 2007-02-27}{...}
{cmd:help ovbd} {right:Version 1.0 2007-02-27}
{hline}

{title:Title}

    {hi:ovbd}


{title:Generate correlated random binomial variables}


{title:Syntax}

{p 8 17 2}
{cmd:ovbd}
[{it:{help newvarlist}}]
{cmd:,} {cmdab:m:eans(}{it:name}{cmd:)} {cmdab:c:orr(}{it:name}{cmd:)} {cmd:n(#)} [{it:options}] {cmd:clear}

{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Main}
{synopt:{opth m:eans(name)}}row vector of mean values (proportions){p_end}
{synopt:{opth c:orr(name)}}correlation coefficient matrix{p_end}
{synopt:{opt n(#)}}# of observations to be generated{p_end}
{synopt:{opt clear}}mandatory reminder that the dataset will be overwritten

{syntab :Options}
{synopt:{opth st:ub(string)}}stub for new variable names{p_end}
{synopt :{opt seed(#)}}seed for random-number generator{p_end}
{synopt:{opt v:erbose}}verbose root-finder output{p_end}
{synoptline}
{p2colreset}{...}


{title:Description}

{pstd}
{cmd:ovbd} generates correlated random binomial variables using the algorithm of Ahn and 
Chen (1995) as described by Gregori, Di Consiglio and Carmeci (1995).


{title:Options}

{dlgtab:Main}


{phang}
{cmd:means} the name of a row vector containing the desired proportions in the variables
containing the resulting correlated random binomial variables;
proportions the row vector must be in the same order as the the corresponding variables in 
{it:{help newvarlist}}, if used.

{phang}
{cmd:corr} the name of a symmetric matrix containing the desired correlation coefficients.

{phang}
{opt n} an integer specifying the desired number of observations.

{phang}
{opt stub} stub for new variable names if {it:{help newvarlist}} is not specified.  
At least one of {it:{opt stub()}} or {it:{help newvarlist}} must be specified.  If 
{it:{help newvarlist}} is specified, then {it:{opt stub()}} is ignored.

{phang}
{opt seed} seed for random number generator; a seed value of zero is ignored.

{phang}
{opt verbose} requests diplay of output from {cmd:ridder}, which is called by {cmd:ovbd}; 
primarily for diagnostic purposes when Ridder's method fails.

{phang}
{cmd:clear} not optional; the user's acknowledgment the dataset will be 
cleared, as will any global macro {it:S_1} that the user has defined.  Despite this forced 
option, none of the {it:{help newvarlist}} may be present in the dataset.  ({opt clear} 
might become truly optional in a later version of {cmd:ovbd}.)

{title:Remarks}

{pstd}
{cmd:ovbd} follows the algorithm of Ahn and Chen (1995), and is roughly modeled after the 
implementation described by Gregori, Di Consiglio and Carmeci (1995), from whose Fortran-77 
subroutine the Stata command's name derives.

{pstd}
{cmd:ovbd} calls {cmd:ridder}, which, in turn, calls the Stata function {cmd:binormal()}, in 
order to find the bivariate normal correlation coefficients that will give rise to the desired 
correlations between the end-result pairs of binomial variables.  Finding this correlation 
coefficient for each pair is not guaranteed to be successful; {opt verbose} will show the 
pair (matrix elements) where the root-finding exercise fails first.  This might aid in finding a 
more judicious construction of the mean vector and correlation matrix to feed to {cmd:ovbd}.

{pstd}
The command also calls {cmd:drawnorm} in order to generate the correlated normal variables 
used in creating the corresponding correlated binomial variables.  The option to use {it:{help newvarlist}} 
follows the convention of the latter, and allows greater flexibility in naming the new variables, 
but the use of {it:stub()} might be more convenient for workaday use.


{title:References}

{pstd}
H. Ahn and J. J. Chen, Generation of overdispersed and underdispersed binomial 
variables. {it:Journal of Computational and Graphical Statistics} {bf:4}:55{c 150}64, 1995.

{pstd}
D. Gregori, L. Di Consiglio and G. Carmeci, A Fortran77 routine for overdispersed binary 
data generation. Presented at the {it:1st Conference of the Biometric Society, Italian Region} June 16 and 17, 1995.
http://lib.stat.cmu.edu/general/corbin


{title:Examples}

{phang}{cmd:. ovbd a b c, means(A) corr(B) n(250) clear}

{phang}{cmd:. ovbd , st(response_) means(A) corr(B) n(200) seed(12345) clear}


{title:Author}

{pstd}
Joseph Coveney
jcoveney@bigplanet.com


{title:Also see}

{psee}
Manual:  {bf:[D] drawnorm}, {bf:[P] matrix}

{psee}
Online:  {helpb ridder}, {helpb drawnorm}, {helpb matrix}, {helpb nbreg}, 
{helpb rnd} (if installed), {helpb ebb} (if installed)