ObtainMultBinaryDist: Generating a multivariate Bernoulli joint-distribution

In mipfp: Multidimensional Iterative Proportional Fitting and Alternative Models

Description

This function applies the IPFP procedure to obtain a joint distribution of K multivariate binary (Bernoulli) variables X_1, ..., X_K.

It requires as input the odds ratio or alternatively the correlation as a measure of association between all the binary variables and a vector of marginal probabilities.

This function is useful when one wants to simulate and draw from a multivariate binary distribution when only first order (marginal probabilities) and second order moments (correlation or odds ratio) are available.

Usage

ObtainMultBinaryDist(odds = NULL, corr = NULL, marg.probs, ...)

Arguments

odds	A K x K matrix where the i-th row and the j-th column represents the Odds ratio between variables i and j. Must be provided if corr is not.
corr	A K x K matrix where the i-th row and the j-th column represents the correlation between variables i and j. Must be provided if odds is not.
marg.probs	A vector with K elements of marginal probabilities where the i-th entry refers to P(X_i = 1).
...	Additional arguments that can be passed to the Ipfp function such as tol, iter, print and compute.cov.

Value

A list whose elements are mainly determined by the Ipfp function.

joint.proba	The resulting multivariate joint-probabilities (from Ipfp).
stp.crit	The final value of the Ipfp stopping criterion.
conv	Boolean indicating whether the Ipfp algorithm converged to a solution.
check.margins	A list returning, for each margin, the absolute maximum deviation between the desired and generated margin. Ideally the elements should approximate 0 (from Ipfp).
label	The names of the variables.

Note

It is important to note that either the odds ratio defined in odds or the correlations described in corr must be provided.

Author(s)

Thomas Suesse

Maintainer: Johan Barthelemy <[e-mail]>.

References

Lee, A.J. (1993). Generating Random Binary Deviates Having Fixed Marginal Distributions and Specified Degrees of Association The American Statistician 47 (3): 209-215.

Qaqish, B. F., Zink, R. C., and Preisser, J. S. (2012). Orthogonalized residuals for estimation of marginally specified association parameters in multivariate binary data. Scandinavian Journal of Statistics 39, 515-527.

See Also

Ipfp for the function used to estimate the distribution; RMultBinary to simulate the estimated joint-distribution; Corr2Odds and Odds2Corr to convert odds ratio to correlation and conversely.

Examples

# initial odds ratios from Qaqish et al. (2012)
or <- matrix(c(Inf, 0.281, 2.214, 2.214, 
               0.281, Inf, 2.214, 2.214,
               2.214, 2.214, Inf, 2.185,
               2.214, 2.214, 2.185, Inf), nrow = 4, ncol = 4, byrow = TRUE)
rownames(or) <- colnames(or) <- c("Parent1", "Parent2", "Sibling1", "Sibling2")

# hypothetical marginal probabilities
p <- c(0.2, 0.4, 0.6, 0.8)

# estimating the joint-distribution
p.joint <- ObtainMultBinaryDist(odds = or, corr = NULL, marg.probs = p)
print(p.joint$joint.proba)

# obtain identical solution when providing correlation
corr <- Odds2Corr(odds = or, marg.probs = p)$corr
p.joint.alt <- ObtainMultBinaryDist(corr = corr, marg.probs = p)

# checking if the results are truly identicals
diff <- sum(abs(p.joint.alt$joint.proba - p.joint$joint.proba))
cat('Sum of the absolute deviations: ', diff, '\n')

Example output

Loading required package: cmm
Loading required package: Rsolnp
Loading required package: numDeriv
Warning message:
In Ipfp(seed = seed, target.list = target.list, target.data = target.data,  :
  Missing values allowed in the target margins.
             Computation of the covariance matrices set to FALSE!
, , 1, 1

           [,1]      [,2]
[1,] 0.03103957 0.1030999
[2,] 0.22256798 0.1539331

, , 2, 1

            [,1]       [,2]
[1,] 0.004620486 0.03846173
[2,] 0.090103251 0.15617398

, , 1, 2

           [,1]       [,2]
[1,] 0.00164749 0.01254437
[2,] 0.02907328 0.04609431

, , 2, 2

             [,1]        [,2]
[1,] 0.0004275708 0.008158924
[2,] 0.0205203665 0.081533688

Warning message:
In Ipfp(seed = seed, target.list = target.list, target.data = target.data,  :
  Missing values allowed in the target margins.
             Computation of the covariance matrices set to FALSE!
Sum of the absolute deviations:  0 

mipfp documentation built on May 2, 2019, 6:01 a.m.