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

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) $$ The model-implied matrices used to generate data is derived from the Reticular Action Model (RAM) Matrices.

mvnram(
  n,
  mu = NULL,
  M = NULL,
  A,
  S,
  F,
  I,
  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\).
M	Numeric vector. Mean structure. Vector of means and intercepts.
A	\(\mathbf{A}\) matrix. Asymmetric paths (single-headed arrows), such as regression coefficients and factor loadings.
S	\(\mathbf{S}\) matrix. Symmetric paths (double-headed arrows), such as variances and covariances.
F	\(\mathbf{F}\) matrix. Filter matrix used to select the observed variables.
I	\(\mathbf{I}\) matrix. Identity matrix.
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)\).

The mean vector mu can be supplied directly using the mu argument. It can also be derived using M. Note that the argument mu takes precedence over M. If mu is not provided, it is computed using M with the jeksterslabRsem::ram_mutheta() function. If both mu and M are not provided, mu is set to a vector of zeroes with the appropriate length.

The variance-covariance matrix Sigma is derived from the RAM matrices A, S, F, and I.

mu and Sigma are then used by the mvn() function to generate multivariate normal data.

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

References

McArdle, J. J. (2013). The development of the RAM rules for latent variable structural equation modeling. In A. Maydeu-Olivares & J. J. McArdle (Eds.), Contemporary Psychometrics: A festschrift for Roderick P. McDonald (pp. 225--273). Lawrence Erlbaum Associates.

McArdle, J. J., & McDonald, R. P. (1984). Some algebraic properties of the Reticular Action Model for moment structures. British Journal of Mathematical and Statistical Psychology, 37 (2), 234--251.

See also

jeksterslabRsem::ram_Sigmatheta(), and jeksterslabRsem::ram_mutheta() for more information on the Reticular Action Model (RAM) and mvn() for multivariate normal data generation.

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

Examples

mu <- c(100, 100, 100)
A <- matrix(
  data = c(0, sqrt(0.26), 0, 0, 0, sqrt(0.26), 0, 0, 0),
  ncol = 3
)
S <- diag(c(225, 166.5, 116.5))
F <- I <- diag(3)
X <- mvnram(n = 100, mu = mu, A = A, S = S, F = F, I = I)
Xstar <- mvnram(n = 100, mu = mu, A = A, S = S, F = F, I = I, R = 100)
str(Xstar, list.len = 6)
#> List of 100
#>  $ : num [1:100, 1:3] 129 106 125 110 105 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 117.5 99.9 85.4 90.7 97.4 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 109.2 92.8 62.4 94.4 100.9 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 98.4 72.2 68.9 84.8 90.2 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 104 104 103 101 108 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>  $ : num [1:100, 1:3] 106.9 111.9 92.4 116.2 88.4 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>   [list output truncated]