DOC: `copula`

[vincentarelbundock]

The documentation section on correlated random variables flags this functionality as "experimental."

One "understood" alternative to the approach proposed in that vignette is to use copulas. It turns out that the copula package works very well in combination with fabricatr. So I thought I'd leave an example here in case you want to include something like this in the documentation.

In this example, we generate three variables from a normal copula structure (many others are available, like Gumbel, Frank, Joe, Archimedean, etc.). The variables' margins are set to Poisson, Normal, and Beta, with defined parameters. The correlations are controlled.

library(copula)
library(fabricatr)

margins = list(
  "pois" = list(lambda = 2),
  "norm" = list(mean = 1),
  "beta" = list(shape1 = 0.5, shape2 = 0.5))

mvNN = mvdc(
  copula = normalCopula(c(0.5, 0.2, 0.7), dim = 3, dispstr = "un"),
  margins = names(margins),
  paramMargins = margins)

dat <- draw_multivariate(
  c(X_1, X_2, X_3) ~ rMvdc(n = 1e5, mvNN)
)

cor(dat)
#>           X_1       X_2       X_3
#> X_1 1.0000000 0.4776166 0.1791387
#> X_2 0.4776166 1.0000000 0.6640809
#> X_3 0.1791387 0.6640809 1.0000000

par(mfrow = c(1, 3))
with(dat, {
  hist(X_1)
  hist(X_2)
  hist(X_3)
})