simulateVE: Simulate eigenvalue dispersion indices

In watanabe-j/eigvaldisp: Statistics of Eigenvalue Dispersion Indices

Simulate eigenvalue dispersion indices

Description

simulateVE() iteratively generates multivariate normal variates, from which eigenvalues, eigenvectors (optional, if nv > 0), and eigenvalue dispersion indices (both unstandardized V and standardized V_\mathrm{rel}) of sample covariance and correlation matrices are obtained. These are invisibly returned as a list.

rmvn() is a function to generate random multivariate normal variates

Usage

simulateVE(
  b = 100L,
  X,
  Sigma,
  cSigma = sqrtfun(Sigma),
  N = nrow(X),
  divisor = c("UB", "ML"),
  m = switch(divisor, UB = N - 1, ML = N),
  center = TRUE,
  scale. = FALSE,
  sub = seq_len(ncol(cSigma)),
  nv = 0,
  sqrt_method = "chol",
  drop_0 = FALSE,
  tol = .Machine$double.eps * 100
)

rmvn(
  N,
  p = 2L,
  s2 = 1,
  Sigma = s2 * diag(p),
  cSigma = sqrtfun(Sigma),
  mean = rep_len(0, p),
  sqrt_method = "chol"
)

Arguments

b	Number of iterations
X	(Optional) Data matrix; when Sigma and cSigma are missing, the sample covariance matrix from X is used as the population covariance matrix in simulations (parametric bootstrapping)
Sigma	Population covariance matrix, assumed validly constructed; by default a spherical covariance is used; ignored when cSigma is provided
cSigma	Cholesky factor of Sigma; this can be specified instead of Sigma. Potentially useful when multiple simulations are run for the same Sigma (although this will not substantially improve speed for a single call of simulateVE(Sigma = ...), where sqrtfun(Sigma) is called only once).
N	Sample size in each iteration or each run of rmvn()
divisor, m, nv, drop_0, tol, center, scale., sub	These arguments are passed to VE(). center and scale. are also used construct Sigma when X is provided.
sqrt_method	Method for matrix square root, which defines the internal function sqrtfun(). Choose one from the following: "chol" or "default" for chol(), "chol_piv" or "pivot" for chol_piv(), "chol_qr" or "qr" for chol_qr(), "matsqrt" or "sqrt" for matsqrt(). See sqrt_methods for details. Ignored when cSigma is provided.
p	Number of variables; ignored when Sigma or cSigma is provided
s2	Population variance used for the spherical condition; ignored when Sigma or cSigma is provided
mean	Population mean vector; default is a p vector of 0's

Details

When simulateVE() is called, either data (X), a covariance matrix (Sigma), or its Cholesky factor (cSigma) should be given. Specify the sample size N as well, unless X is provided.

simulateVE() does not actually calculate sample covariance/correlation matrices, but instead directly obtain eigenvalues and eigenvectors of these from singular value decomposition svd() of normal variates generated with rmvn().

In the output of simulateVE(), suffices *v and *r denote covariance and correlation matrices, respectively.

Value

simulateVE() invisiblly returns a list containing the following:

$VES

Eigenvalue variance of covariance matrix V(\mathbf{S}) (b vector)

$VRS

Relative eigenvalue variance of covariance matrix V_{\mathrm{rel}}(\mathbf{S}) (b vector)

$LS

Eigenvalues of covariance matrix (p * b matrix)

$VER

Eigenvalue variance of correlation matrix V(\mathbf{R}) (b vector)

$VRR

Relative eigenvalue variance of correlation matrix V_{\mathrm{rel}}(\mathbf{R}) (b vector)

$LR

Eigenvalues of correlation matrix (p * b matrix)

(the following elements are appended only when nv > 0)

$US

Eigenvectors of covariance matrix (p * nv * b array)

$UR

Eigenvectors of correlation matrix (p * nv * b array)

$US.org

Eigenvectors of population covariance matrix (p * nv matrix)

$UR.org

Eigenvectors of population correlation matrix (p * nv matrix)

($US.org and $UR.org are provided as references for signs of eigenvectors)

rmvn() returns a N * p matrix with the specified population mean and covariance.

See Also

VE, sqrt_methods

Examples

Lambda <- c(4, 2, 1, 1)
(Sigma <- GenCov(evalues = Lambda, evectors = "random"))
N <- 10
set.seed(35638)
X1 <- rmvn(N = N, Sigma = Sigma)
cSigma <- chol(Sigma)
set.seed(35638)
X2 <- rmvn(N = N, cSigma = cSigma)
stopifnot(all.equal(X1, X2))
# These are identical. Providing cSigma is quicker as it skips sqrtfun(Sigma),
# so this may be useful when multiple simulations are to be run with
# the same population covariance matrix.

# A small simulation
sim_result <- simulateVE(b = 50L, Sigma = Sigma, N = N)
str(sim_result)
# Results are returned as a list (see \dQuote{Value} for details)

# Syntax for parametric bootstrapping
param_boot <- simulateVE(b = 50L, X = X1)

watanabe-j/eigvaldisp documentation built on Dec. 8, 2023, 4:38 a.m.