*! version 2.0.0 2024-07-07

Title

ovbd -- Generate correlated random binomial variables

ovbdc -- Called by ovbd; may be called directly

ovbdr -- Called by ovbd; may be called directly

Syntax

ovbd [varlist],
means(name)
corr(name)
[options]

ovbdc ,
means(name)
corr(name)
[options]

ovbdr newvarlist,
z(name)
a(name)

Main
means(name) Stata matrix containing vector of proportions

corr(name) Stata matrix containing correlation structure

n(#) generate # observations; default is current number*

stub(string) stub for new variable names*

clear replace the current dataset*

Options
verbose allows notification when matrix is not positive definite

seed(#) seed for random-number generator*

iterate(#) maximum iterations for root finder

tolerance(#) tolerance for root finder

Options marked with an asterisk are available only for ovbd.

means() and corr() are not optional for ovbd or ovbdc.

ovbdr has no options; newvarlist, z() and a() are not optional.

Description

ovbd generates correlated random binomial variables. The
correlation matrix fed to ovbd may contain negative or positive
coefficients, allowing for simulation of underdispersion as well as
overdispersion.

Options

Main

means(name) name of a Stata matrix that is a vector of the desired
proportions in the generated variables. It is not optional.

corr(name) name of a Stata matrix of the desired correlation structure of
the generated variables. It is not optional.

n(#) specifies the number of observations to be generated.

stub(string) stub for new variable names if varlist is not
specified. At least one of stub() or varlist must be
specified.

clear specifies that the dataset in memory be replaced, even though the
current dataset has not been saved on disk.

Options

verbose requests diplay of a message whenever the transformed correlation
matrix is not positive definite.

seed(#) specifies the initial value of the random-number seed used in
generating the random binomial variables. The default is the current
random-number seed. Specifying seed() is the same as typing
set seed # before issuing the ovbd command.

iterate(#) perform maximum of # iterations for root finder; default is
30; this should never need to be changed.

tolerance(#) tolerance for declaring convergence by the root finder;
default is 1e-10; this should never need to be changed.

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 command's name derives.

ovbd calls ovbdc 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 where the desired correlation coefficient is not zero is
accomplished by an iterative root-finding algorithm (Ridders), and will not be
successful if the root is not bracketed by the parameter space, which in
practice here is ±[0.001, 0.999]. ovbdc will automatically report all
pairs (matrix elements) where the root-finding algorithm fails. This is
intended to aid the user in determining a more judicious construction of the
mean vector and correlation matrix to feed to ovbd.

Upon completion, ovbdc returns the transformed correlation matrix and
transformed means (proportions) vector to ovbd, which then forwards them
along with the variable list to ovbdr in order to generate the correlated
binomial variables. The option to use varlist with ovbd (which
must be a newvarlist if any variable name in the list already exists in
the dataset and the clear option is not also specified) allows greater
flexibility in naming the generated variables, but the use of stub()
might be more convenient for workaday use.

ovbdc and ovbdr may be directly invoked by the user. Calling the
two commands directly will be more efficient in the typical simulation use case
in that the iterative root finding of each element that is involved in creation
of the transformed correlation matrix need be undertaken just once by
ovbdc, and the transformed proportions vector and transformed correlation
matrix that are returned by it can be fed to ovbdr repeatedly by the
simulation program.

Examples

Generate 250 observations (response1, response2);
response1 with proportion 0.6,
response2 with proportion 0.4
and correlation 0.5

. matrix input M = (0.6, 0.4)

. matrix input C = (1 0.5 \ 0.5 1)

. ovbd response1 response2, means(M) corr(C) n(250)

Equivalently,

. matrix input M = (0.6, 0.4)

. matrix input C = (1 0.5 \ 0.5 1)

. ovbd , means(M) corr(C) stub(response) n(250)

Invoking ovbdc and ovbdr directly

. matrix input M = (0.6, 0.4)

. matrix input C = (1 0.5 \ 0.5 1)

. ovbdc , means(M) corr(C)

. matrix define Z = r(Z)

. matrix define A = r(A)

. drop _all

. set obs 250

. ovbdr response1 response2, z(Z) a(A)

Author

Joseph Coveney
https://www.statalist.org/forums/member/159-joseph-coveney

Stored results

ovbd and ovbdc store the following in r():

Matrices

r(A) upper-triangular Cholesky factor (if positive definite) or
analogous factor by spectral decomposition (otherwise) of transformed
orrelation matrix

r(Z) transformed means (proportions) vector

Neither ovbd nor ovbdc clears r() and when invoked will
overwrite only the two matrices above if present.

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

W. H. Press, S. A. Teukolsky, W. T. Vetterling, B. P. Flannery, Numerical
Recipes in Fortran 77: The Art of Scientific Computing. Second Edition.
pp. 351–52. Cambridge University Press, 1992.