xSJpearson: Simulate joint given marginals, Pearson correlations and...

In SimJoint: Simulate Joint Distribution

Simulate joint given marginals, Pearson correlations and uncorrelated support matrix.

Description

Users specify the uncorrelated random source instead of using a permuted X to left-multiply the correlation matrix decomposition. See the package vignette for more details.

Usage

xSJpearson(
  X,
  cor,
  noise,
  stochasticStepDomain = as.numeric(c(0, 1)),
  errorType = "meanSquare",
  seed = 123L,
  maxCore = 7L,
  convergenceTail = 8L,
  iterLimit = 100000L,
  verbose = TRUE
  )

Arguments

X	An N x K numeric matrix of K marginal distributions (samples). Columns are sorted.
cor	A K x K correlation matrix. The matrix should be positive semi-definite.
noise	An N x K arbitrary numeric matrix where columns are (more or less) uncorrelated. Exact zero correlations are unnecessary.
stochasticStepDomain	A numeric vector of size 2. Range of the stochastic step ratio for correcting the correlation matrix in each iteration. Default [0, 1]. See the package vignette for more details.
errorType	Cost function for convergence test. "meanRela": average absolute relative error between elements of the target correlation matrix and the correlation matrix approximated in each iteration. "maxRela": maximal absolute relative error. "meanSquare": mean squared error. Default.
seed	An integer or an integer vector of size 4. A single integer seeds a pcg64 generator the usual way. An integer vector of size 4 supplies all the bits for a pcg64 object.
maxCore	An integer. Maximal threads to invoke. Default 7. Better be no greater than the total number of virtual cores on machine.
convergenceTail	An integer. If the last convergenceTail iterations resulted in equal cost function values, return. Default 8.
iterLimit	An integer. The maximal number of iterations. Default 100000.
verbose	A boolean value. TRUE prints progress.

Details

Algorithms are detailed in the package vignette.

Value

A list of size 2.

X	A numeric matrix of size N x K, the simulated joint distribution.
cor	Pearson correlation matrix of X.

Examples

# =============================================================================
# Use the same example from <https://cran.r-project.org/web/packages/
#                            SimMultiCorrData/vignettes/workflow.html>.
# =============================================================================
set.seed(123)
N = 10000L # Sample size.
K = 10L # 10 marginals.
# Sample from 3 PDFs, 2 nonparametric PMFs, 5 parametric PMFs:
marginals = cbind(
  rnorm(N), rchisq(N, 4), rbeta(N, 4, 2),
  SimJoint::LHSpmf(data.frame(val = 1:3, P = c(0.3, 0.45, 0.25)), N,
         seed = sample(1e6L, 1)),
  SimJoint::LHSpmf(data.frame(val = 1:4, P = c(0.2, 0.3, 0.4, 0.1)), N,
         seed = sample(1e6L, 1)),
  rpois(N, 1), rpois(N, 5), rpois(N, 10),
  rnbinom(N, 3, 0.2), rnbinom(N, 6, 0.8))
# The seeding for `LHSpmf()` is unhealthy, but OK for small examples.


marginals = apply(marginals, 2, function(x) sort(x))


# Create the target correlation matrix `Rey`:
set.seed(11)
Rey <- diag(1, nrow = K)
for (i in 1:nrow(Rey)) {
  for (j in 1:ncol(Rey)) {
    if (i > j) Rey[i, j] <- runif(1, 0.2, 0.7)
    Rey[j, i] <- Rey[i, j]
  }
}


system.time({result = SimJoint::xSJpearson(
  X = marginals, cor = Rey, noise = matrix(runif(N * K), ncol = K),
  errorType = "meanSquare", seed = 456, maxCore = 1,
  convergenceTail = 8, verbose = TRUE)})


summary(as.numeric(round(cor(result$X) - Rey, 6)))

SimJoint documentation built on May 29, 2024, 12:05 p.m.