Generate Multivariate Normal Data \( \mathbf{X} \sim \mathcal{N}_{k} \left( \boldsymbol{\mu}, \boldsymbol{\Sigma} \right) %(\#eq:dist-X-mvn) \)

Generates an \(n \times k\) multivariate data matrix or a list of \(n \times k\) multivariate data matrices of length R from the multivariate normal distribution $$ \mathbf{X} \sim \mathcal{N}_{k} \left( \boldsymbol{\mu}, \boldsymbol{\Sigma} \right) . %(\#eq:dist-X-mvn) $$ This function is a wrapper around MASS::mvrnorm().

mvn(
  n,
  mu = NULL,
  Sigma,
  tol = 1e-06,
  empirical = FALSE,
  df = FALSE,
  varnames = NULL,
  R = NULL,
  par = FALSE,
  ncores = NULL,
  mc = TRUE,
  lb = FALSE,
  cl_eval = FALSE,
  cl_export = FALSE,
  cl_expr,
  cl_vars
)

Arguments

n	Integer. Sample size.
mu	Numeric vector. Location parameter mean vector \(\boldsymbol{\mu}\) of length \(k\).
Sigma	Numeric matrix. \(k \times k\) variance-covariance matrix \(\boldsymbol{\Sigma}\).
tol	Numeric. Tolerance (relative to largest variance) for numerical lack of positive-definiteness in Sigma.
empirical	Logical. If TRUE, mu and Sigma specify the empirical, not population. mean and covariance matrix.
df	Logical. If TRUE, the function returns a data frame. If FALSE, the function returns a matrix.
varnames	Character string. Optional column names with the same length as mu.
R	Integer. Number of Monte Carlo replications. If R is not provided, the function produces a single random data set. If R is an integer greater than 1, (e.g., R = 10), the function produces multiple random data sets stored in each element of a list of length R. par and all succeeding arguments are only relevant when R > 1.
par	Logical. If TRUE, use multiple cores. If FALSE, use lapply().
ncores	Integer. Number of cores to use if par = TRUE. If unspecified, defaults to detectCores() - 1.
mc	Logical. If TRUE, use parallel::mclapply(). If FALSE, use parallel::parLapply() or parallel::parLapplyLB(). Ignored if par = FALSE.
lb	Logical. If TRUE use parallel::parLapplyLB(). If FALSE, use parallel::parLapply(). Ignored if par = FALSE and mc = TRUE.
cl_eval	Logical. Execute parallel::clusterEvalQ() using cl_expr. Ignored if mc = TRUE.
cl_export	Logical. Execute parallel::clusterExport() using cl_vars. Ignored if mc = TRUE.
cl_expr	Expression. Expression passed to parallel::clusterEvalQ() Ignored if mc = TRUE.
cl_vars	Character vector. Names of objects to pass to parallel::clusterExport() Ignored if mc = TRUE.

Value

If R = NULL or R = 1, returns an \(n \times k\) multivariate normal data matrix or data frame . If R is an integer greater than 1, (e.g., R = 10) returns a list of length R of \(n \times k\) multivariate normal data matrix or data frame.

Details

The multivariate normal distribution has two parameters, namely the \(k \times 1\) mean vector mu \(\left( \boldsymbol{\mu} \right)\) and the \(k \times k\) variance-covariance matrix Sigma \(\left( \boldsymbol{\Sigma} \right)\). If mu is not provided, it is set to a vector of zeroes with the appropriate length.

Options for explicit parallelism are provided when R > 1 especially when R is large. See par and suceeding arguments.

References

Venables, W. N., Ripley, B. D., & Venables, W. N. (2002). Modern applied statistics with S. New York, N.Y: Springer.

Wikipedia: Multivariate normal distribution

See also

jeksterslabRdist::mvnpdf(), jeksterslabRdist::mvnll(), and jeksterslabRdist::mvn2ll(), for more information on the multivariate normal distribution.

Other multivariate data functions: mvnramsigma2(), mvnram()

Examples

mu <- c(100, 100, 100)
Sigma <- matrix(
  data = c(225, 112.50, 56.25, 112.5, 225, 112.5, 56.25, 112.50, 225),
  ncol = 3
)
X <- mvn(n = 100, mu = mu, Sigma = Sigma)
Xstar <- mvn(n = 100, mu = mu, Sigma = Sigma, R = 100)
str(Xstar, list.len = 6)
#> List of 100
#>  $ : num [1:100, 1:3] 73.5 107.9 83.4 105.4 100.1 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 87.1 95.7 102.3 118.8 90.1 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 109.1 109.7 104 112.8 84.6 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 89.9 76.6 122.5 129.7 90.8 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 122.1 90.9 94.7 132.6 92.8 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 101.7 109.7 107 80.4 96.9 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>   [list output truncated]