help ovbd                                                Version 1.0 2007-02-27
-------------------------------------------------------------------------------

Title

ovbd

Generate correlated random binomial variables

Syntax

ovbd [newvarlist] , means(name) corr(name) n(#) [options] clear

options Description ------------------------------------------------------------------------- Main means(name) row vector of mean values (proportions) corr(name) correlation coefficient matrix n(#) # of observations to be generated clear mandatory reminder that the dataset will be overwritten

Options stub(string) stub for new variable names seed(#) seed for random-number generator verbose verbose root-finder output -------------------------------------------------------------------------

Description

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

Options

+------+ ----+ Main +-------------------------------------------------------------

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 newvarlist, if used.

corr the name of a symmetric matrix containing the desired correlation coefficients.

n an integer specifying the desired number of observations.

stub stub for new variable names if newvarlist is not specified. At least one of stub() or newvarlist must be specified. If newvarlist is specified, then stub() is ignored.

seed seed for random number generator; a seed value of zero is ignored.

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

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

Remarks

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.

ovbd calls ridder, which, in turn, calls the Stata function 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; 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 ovbd.

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

References

H. Ahn and J. J. Chen, Generation of overdispersed and underdispersed binomial variables. Journal of Computational and Graphical Statistics 4:5564, 1995.

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

Examples

. ovbd a b c, means(A) corr(B) n(250) clear

. ovbd , st(response_) means(A) corr(B) n(200) seed(12345) clear

Author

Joseph Coveney jcoveney@bigplanet.com

Also see

Manual: [D] drawnorm, [P] matrix

Online: ridder, drawnorm, matrix, nbreg, rnd (if installed), ebb (if