optimize_cor_mat: Find initial correlation matrix for NORTA from target correlation

Description

This function can be used to find a suitable correlation matrix to be used for simulating initial multivariate normal data in a NORTA based simulation design (see simdesign_norta).

Usage

optimize_cor_mat(
  cor_target,
  dist,
  ensure_cor_mat = TRUE,
  conv_norm_type = "O",
  return_diagnostics = FALSE,
  ...
)

Value

If return_diagnostics is FALSE, a correlation matrix to be used in the definition of a simdesign_norta object. If TRUE, then a list with two entries: cor_mat containing the correlation matrix, and convergence containing a list of objects returned by the individual optimisation problems from stats::uniroot.

Arguments

cor_target: Target correlation matrix.
dist: List of functions of marginal distributions for simulated variables. Must have the same length as the specified correlation matrix (cor_target), and the order of the entries must correspond to the variables in the correlation matrix. See simdesign_norta for details of the specification of the marginal distributions.
ensure_cor_mat: if TRUE, this function ensures that the optimized matrix is a proper correlation matrix by ensuring positive definitiness. If FALSE, the optimized matrix is returned as is.
conv_norm_type: Metric to be used to find closest positive definite matrix to optimal matrix, used if ensure_cor_mat is TRUE. Passed to Matrix::nearPD.
return_diagnostics: TRUE to return additional diagnostics of the optimization procedure, see below.
...: Additional parameters passed to optimize_cor_for_pair.

Details

This function first finds a suitable correlation matrix for the underlying multivariate normal data used in the NORTA procedure. It does so by solving k*(k-1) univariable optimisation problems (where k is the number of variables). In case the result is not a positive-definite matrix, the nearest positive-definite matrix is found according to the user specified metric using Matrix::nearPD. See e.g. Ghosh and Henderson (2003) for an overview of the procedure.

References