Exv.VXX: Moments of eigenvalue dispersion indices
In watanabe-j/eigvaldisp: Statistics of Eigenvalue Dispersion Indices
Exv.VXX R Documentation
Moments of eigenvalue dispersion indices
Description
Functions to calculate expectation/variance of (relative) eigenvalue variance
of sample covariance/correlation matrices for a given population
covariance/correlation matrix and degrees of freedom n
Exv.VES(): expectation of eigenvalue variance of covariance matrix
\mathrm{E}[V(\mathbf{S})]
Exv.VRS(): expectation of relative eigenvalue variance of
covariance matrix \mathrm{E}[V_{\mathrm{rel}}(\mathbf{S})]
Exv.VER(): expectation of eigenvalue variance of correlation
matrix \mathrm{E}[V(\mathbf{R})]
Exv.VRR(): expectation of relative eigenvalue variance of
correlation matrix
\mathrm{E}[V_{\mathrm{rel}}(\mathbf{R})]
Var.VES(): variance of eigenvalue variance of
covariance matrix \mathrm{Var}[V(\mathbf{S})]
Var.VRS(): variance of relative eigenvalue variance of
covariance matrix
\mathrm{Var}[V_{\mathrm{rel}}(\mathbf{S})]
Var.VER(): variance of eigenvalue variance of
correlation matrix \mathrm{Var}[V(\mathbf{R})]
Var.VRR(): variance of relative eigenvalue variance of
correlation matrix
\mathrm{Var}[V_{\mathrm{rel}}(\mathbf{R})]
Usage
Exv.VES(
Sigma,
n = 100,
Lambda,
divisor = c("UB", "ML"),
m = switch(divisor, UB = n, ML = n + 1),
drop_0 = FALSE,
tol = .Machine$double.eps * 100,
...
)
Exv.VRS(
Sigma,
n = 100,
Lambda,
drop_0 = FALSE,
tol = .Machine$double.eps * 100,
...
)
Exv.VER(
Rho,
n = 100,
Lambda,
tol = .Machine$double.eps * 100,
tol.hg = 0,
maxiter.hg = 2000,
...
)
Exv.VRR(
Rho,
n = 100,
Lambda,
tol = .Machine$double.eps * 100,
tol.hg = 0,
maxiter.hg = 2000,
...
)
Var.VES(
Sigma,
n = 100,
Lambda,
divisor = c("UB", "ML"),
m = switch(divisor, UB = n, ML = n + 1),
drop_0 = FALSE,
tol = .Machine$double.eps * 100,
...
)
Var.VRS(
Sigma,
n = 100,
Lambda,
drop_0 = FALSE,
tol = .Machine$double.eps * 100,
...
)
Var.VER(Rho, n = 100, Lambda, ...)
Var.VRR(
Rho,
n = 100,
method = c("Pan-Frank", "Konishi"),
Lambda,
fun = c("pfd", "pfv", "pfc", "pf", "klv", "kl", "krv", "kr"),
...
)
Arguments
Sigma
Population covariance matrix; assumed to be validly constructed.
n
Degrees of freedom (not sample sizes); numeric of length 1 or more.
Lambda
Numeric vector of population eigenvalues.
divisor
Either "UB" (default) or "ML",
to decide the default value of m.
m
Divisor for the sample covariance matrix (n* in Watanabe (2022)).
By default equals n.
drop_0
Logical, when TRUE, eigenvalues smaller than tol are dropped.
tol
For covariance-related functions, this is the tolerance/threshold
to be used with drop_0. For correlation-related functions,
this is passed to Exv.r2() along with other arguments.
...
In Var.VRR(), additional arguments are passed to an internal
function which it in turn calls. Otherwise ignored.
Rho
Population correlation matrix; assumed to be validly constructed
(although simple checks are done).
tol.hg, maxiter.hg
Passed to Exv.r2(); see description of that function.
method
For Var.VRR() (and Var.VER()), determines the method
to obtain approximate variance in non-null conditions. Either
"Pan-Frank" (default) or "Konishi". See “Details”.
fun
For Var.VRR() (and Var.VER()), determines the function
to be used to evaluate approximate variance. See
“Details”. Options allowed are: "pfd", "pfv",
"pfc", "pf", "klv", "kl", "krv",
and "kr".
Details
Exv.VES(), Var.VES(), and Exv.VRR() return exact
moments. Exv.VRS() and Var.VRS() return approximations based
on the delta method, except under the null condition
(\mathbf{\Sigma} proportional to the identity matrix)
where exact moments are returned.
Var.VRR() returns the exact variance when p = 2 or
under the null condition (\mathbf{P} is the identity
matrix). Otherwise, asymptotic variance is calculated with the method
of choice: either "Pan-Frank" (default) or "Konishi". They
correspond to Pan and Frank's heuristic approximation and Konishi's
asymptotic theory, respectively (see Watanabe, 2022).
In this case, calculations are handled by one of the internal functions
AVar.VRR_xx() (xx is a suffix to specify R
implementation). For completeness, it is possible to directly specify the
function to be used with the argument fun: for the Pan–Frank method,
"pfd" (default), "pfv", and "pf"; and for the
Konishi method, "klv" (default), "kl", "krv", and
"kr". Within each group, these function yield identical results but
differ in speed (the defaults are the fastest). See
AVar.VRR_xx for details of these functions.
The Pan–Frank method takes a substantial amount of time to be executed
when p is large. Several C++ functions are provided in
the extension package
eigvaldispRcpp to
speed-up the calculation. When this package is available, the default
fun for the Pan–Frank method is set to "pfc". The
option for C++ function is controlled by the argument
cppfun which in turn is passed to AVar.VRR_pfc()
(see AVar.VRR_xx). When this argument is provided, the
argument fun is ignored with a warning, unless one of the Konishi
methods is used (in which case cppfun is ignored with a warning).
Since the eigenvalue variance of a correlation matrix
V(\mathbf{R}) is simply (p - 1) times the
relative eigenvalue variance V_{\mathrm{rel}}(\mathbf{R}) of
the same matrix, their distributions are identical up to this
scaling. Hence, Exv.VER() and Var.VER() calls Exv.VRR()
and Var.VRR() (respectively), whose outputs are scaled and
returned. These functions are provided for completeness, although
there will be little practical demand for these functions (and
V(\mathbf{R}) itself).
As detailed in Watanabe (2022), the distribution of
V_{\mathrm{rel}}(\mathbf{R}) cannot be
uniquely specified by eigenvalues alone. Hence, a full correlation
matrix Rho should preferably be provided. Otherwise, a correlation
matrix is constructed from the eigenvalues Lambda provided using
the function GenCov() with randomly picked eigenvectors.
On the other hand, the choice of eigenvectors does not matter for
covariance matrices, thus either the full covariance matrix Sigma or
vector of eigenvalues Lambda can be provided (although the latter
is slightly faster if available).
When Rho is provided, some simple checks are done: the matrix is
scaled to have diagonals of 1; and if any of these are unequal,
an error is returned.
These moments are derived under the assumption of multivariate normality
(Watanabe, 2022), although the distributions will remain the same for
correlation matrices in all elliptically contoured distributions
(see Anderson, 2003).
Value
A numeric vector of the desired moment, corresponding to n.
References
Watanabe, J. (2022) Statistics of eigenvalue dispersion indices:
quantifying the magnitude of phenotypic integration. Evolution,
76, 4–28. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/evo.14382")}.
See Also
VE for estimation
AVar.VRR_xx for internal functions of Var.VRR
Exv.rx for internal functions for moments of
correlation coefficients
Exv.VXXa for moments of “bias-corrected” versions
Examples
# Covariance matrix
N <- 20
Lambda <- c(4, 2, 1, 1)
(Sigma <- GenCov(evalues = Lambda, evectors = "random"))
VE(S = Sigma)$VE
VE(S = Sigma)$VR
# Population values of V(Sigma) and Vrel(Sigma)
# From population covariance matrix
Exv.VES(Sigma, N - 1)
Var.VES(Sigma, N - 1)
Exv.VRS(Sigma, N - 1)
Var.VRS(Sigma, N - 1)
# Note the amount of bias from the population value obtained above
# From population eigenvalues
Exv.VES(Lambda = Lambda, n = N - 1)
Var.VES(Lambda = Lambda, n = N - 1)
Exv.VRS(Lambda = Lambda, n = N - 1)
Var.VRS(Lambda = Lambda, n = N - 1)
# Same, regardless of the random choice of eigenvectors
# Correlation matrix
(Rho <- GenCov(evalues = Lambda / sum(Lambda) * 4, evectors = "Givens"))
VE(S = Rho)$VR
# Population value of Vrel(Rho)
Exv.VRR(Rho, N - 1)
Var.VRR(Rho, N - 1)
# These results vary with the choice of eigenvalues
# If interested, repeat from the definition of Rho
# Different choices for asymptotic variance of Vrel(R)
# Variance from Pan-Frank method
Var.VRR(Rho, N - 1, method = "Pan-Frank") # Internally sets fun = "pfd"
Var.VRR(Rho, N - 1, fun = "pf") # Slow for large p
Var.VRR(Rho, N - 1, fun = "pfv") # Requires too much RAM for large p
## Not run: Var.VRR(Rho, n = N - 1, fun = "pfc") # Requires eigvaldispRcpp
## Not run: Var.VRR(Rho, n = N - 1, fun = "pfc", cppfun = "Cov_r2P")
# The last two use \proglang{C++} functions provided by extension package eigvaldispRcpp
# fun = "pfc"' can be omitted in the last call.
# The above results are identical (up to rounding error)
# Variance from Konishi's theory
Var.VRR(Rho, N - 1, method = "Konishi") # Internally sets fun = "klv"
Var.VRR(Rho, N - 1, fun = "kl")
Var.VRR(Rho, N - 1, fun = "krv")
Var.VRR(Rho, N - 1, fun = "kr")
# These are identical, but the first one is fast
# On the other hand, these differ from that obtained with
# the Pan-Frank method above
watanabe-j/eigvaldisp documentation built on Dec. 8, 2023, 4:38 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Exv.VXX | R Documentation |
Moments of eigenvalue dispersion indices
Description
Functions to calculate expectation/variance of (relative) eigenvalue variance
of sample covariance/correlation matrices for a given population
covariance/correlation matrix and degrees of freedom n
Exv.VES(): expectation of eigenvalue variance of covariance matrix
\mathrm{E}[V(\mathbf{S})]
Exv.VRS(): expectation of relative eigenvalue variance of
covariance matrix \mathrm{E}[V_{\mathrm{rel}}(\mathbf{S})]
Exv.VER(): expectation of eigenvalue variance of correlation
matrix \mathrm{E}[V(\mathbf{R})]
Exv.VRR(): expectation of relative eigenvalue variance of
correlation matrix
\mathrm{E}[V_{\mathrm{rel}}(\mathbf{R})]
Var.VES(): variance of eigenvalue variance of
covariance matrix \mathrm{Var}[V(\mathbf{S})]
Var.VRS(): variance of relative eigenvalue variance of
covariance matrix
\mathrm{Var}[V_{\mathrm{rel}}(\mathbf{S})]
Var.VER(): variance of eigenvalue variance of
correlation matrix \mathrm{Var}[V(\mathbf{R})]
Var.VRR(): variance of relative eigenvalue variance of
correlation matrix
\mathrm{Var}[V_{\mathrm{rel}}(\mathbf{R})]
Usage
Exv.VES(
Sigma,
n = 100,
Lambda,
divisor = c("UB", "ML"),
m = switch(divisor, UB = n, ML = n + 1),
drop_0 = FALSE,
tol = .Machine$double.eps * 100,
...
)
Exv.VRS(
Sigma,
n = 100,
Lambda,
drop_0 = FALSE,
tol = .Machine$double.eps * 100,
...
)
Exv.VER(
Rho,
n = 100,
Lambda,
tol = .Machine$double.eps * 100,
tol.hg = 0,
maxiter.hg = 2000,
...
)
Exv.VRR(
Rho,
n = 100,
Lambda,
tol = .Machine$double.eps * 100,
tol.hg = 0,
maxiter.hg = 2000,
...
)
Var.VES(
Sigma,
n = 100,
Lambda,
divisor = c("UB", "ML"),
m = switch(divisor, UB = n, ML = n + 1),
drop_0 = FALSE,
tol = .Machine$double.eps * 100,
...
)
Var.VRS(
Sigma,
n = 100,
Lambda,
drop_0 = FALSE,
tol = .Machine$double.eps * 100,
...
)
Var.VER(Rho, n = 100, Lambda, ...)
Var.VRR(
Rho,
n = 100,
method = c("Pan-Frank", "Konishi"),
Lambda,
fun = c("pfd", "pfv", "pfc", "pf", "klv", "kl", "krv", "kr"),
...
)
Arguments
Sigma |
Population covariance matrix; assumed to be validly constructed. |
n |
Degrees of freedom (not sample sizes); numeric of length 1 or more. |
Lambda |
Numeric vector of population eigenvalues. |
divisor |
Either |
m |
Divisor for the sample covariance matrix ( |
drop_0 |
Logical, when |
tol |
For covariance-related functions, this is the tolerance/threshold
to be used with drop_0. For correlation-related functions,
this is passed to |
... |
In |
Rho |
Population correlation matrix; assumed to be validly constructed (although simple checks are done). |
tol.hg, maxiter.hg |
Passed to |
method |
For |
fun |
For |
Details
Exv.VES(), Var.VES(), and Exv.VRR() return exact
moments. Exv.VRS() and Var.VRS() return approximations based
on the delta method, except under the null condition
(\mathbf{\Sigma} proportional to the identity matrix)
where exact moments are returned.
Var.VRR() returns the exact variance when p = 2 or
under the null condition (\mathbf{P} is the identity
matrix). Otherwise, asymptotic variance is calculated with the method
of choice: either "Pan-Frank" (default) or "Konishi". They
correspond to Pan and Frank's heuristic approximation and Konishi's
asymptotic theory, respectively (see Watanabe, 2022).
In this case, calculations are handled by one of the internal functions
AVar.VRR_xx() (xx is a suffix to specify R
implementation). For completeness, it is possible to directly specify the
function to be used with the argument fun: for the Pan–Frank method,
"pfd" (default), "pfv", and "pf"; and for the
Konishi method, "klv" (default), "kl", "krv", and
"kr". Within each group, these function yield identical results but
differ in speed (the defaults are the fastest). See
AVar.VRR_xx for details of these functions.
The Pan–Frank method takes a substantial amount of time to be executed
when p is large. Several C++ functions are provided in
the extension package
eigvaldispRcpp to
speed-up the calculation. When this package is available, the default
fun for the Pan–Frank method is set to "pfc". The
option for C++ function is controlled by the argument
cppfun which in turn is passed to AVar.VRR_pfc()
(see AVar.VRR_xx). When this argument is provided, the
argument fun is ignored with a warning, unless one of the Konishi
methods is used (in which case cppfun is ignored with a warning).
Since the eigenvalue variance of a correlation matrix
V(\mathbf{R}) is simply (p - 1) times the
relative eigenvalue variance V_{\mathrm{rel}}(\mathbf{R}) of
the same matrix, their distributions are identical up to this
scaling. Hence, Exv.VER() and Var.VER() calls Exv.VRR()
and Var.VRR() (respectively), whose outputs are scaled and
returned. These functions are provided for completeness, although
there will be little practical demand for these functions (and
V(\mathbf{R}) itself).
As detailed in Watanabe (2022), the distribution of
V_{\mathrm{rel}}(\mathbf{R}) cannot be
uniquely specified by eigenvalues alone. Hence, a full correlation
matrix Rho should preferably be provided. Otherwise, a correlation
matrix is constructed from the eigenvalues Lambda provided using
the function GenCov() with randomly picked eigenvectors.
On the other hand, the choice of eigenvectors does not matter for
covariance matrices, thus either the full covariance matrix Sigma or
vector of eigenvalues Lambda can be provided (although the latter
is slightly faster if available).
When Rho is provided, some simple checks are done: the matrix is
scaled to have diagonals of 1; and if any of these are unequal,
an error is returned.
These moments are derived under the assumption of multivariate normality (Watanabe, 2022), although the distributions will remain the same for correlation matrices in all elliptically contoured distributions (see Anderson, 2003).
Value
A numeric vector of the desired moment, corresponding to n.
References
Watanabe, J. (2022) Statistics of eigenvalue dispersion indices: quantifying the magnitude of phenotypic integration. Evolution, 76, 4–28. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/evo.14382")}.
See Also
VE for estimation
AVar.VRR_xx for internal functions of Var.VRR
Exv.rx for internal functions for moments of
correlation coefficients
Exv.VXXa for moments of “bias-corrected” versions
Examples
# Covariance matrix
N <- 20
Lambda <- c(4, 2, 1, 1)
(Sigma <- GenCov(evalues = Lambda, evectors = "random"))
VE(S = Sigma)$VE
VE(S = Sigma)$VR
# Population values of V(Sigma) and Vrel(Sigma)
# From population covariance matrix
Exv.VES(Sigma, N - 1)
Var.VES(Sigma, N - 1)
Exv.VRS(Sigma, N - 1)
Var.VRS(Sigma, N - 1)
# Note the amount of bias from the population value obtained above
# From population eigenvalues
Exv.VES(Lambda = Lambda, n = N - 1)
Var.VES(Lambda = Lambda, n = N - 1)
Exv.VRS(Lambda = Lambda, n = N - 1)
Var.VRS(Lambda = Lambda, n = N - 1)
# Same, regardless of the random choice of eigenvectors
# Correlation matrix
(Rho <- GenCov(evalues = Lambda / sum(Lambda) * 4, evectors = "Givens"))
VE(S = Rho)$VR
# Population value of Vrel(Rho)
Exv.VRR(Rho, N - 1)
Var.VRR(Rho, N - 1)
# These results vary with the choice of eigenvalues
# If interested, repeat from the definition of Rho
# Different choices for asymptotic variance of Vrel(R)
# Variance from Pan-Frank method
Var.VRR(Rho, N - 1, method = "Pan-Frank") # Internally sets fun = "pfd"
Var.VRR(Rho, N - 1, fun = "pf") # Slow for large p
Var.VRR(Rho, N - 1, fun = "pfv") # Requires too much RAM for large p
## Not run: Var.VRR(Rho, n = N - 1, fun = "pfc") # Requires eigvaldispRcpp
## Not run: Var.VRR(Rho, n = N - 1, fun = "pfc", cppfun = "Cov_r2P")
# The last two use \proglang{C++} functions provided by extension package eigvaldispRcpp
# fun = "pfc"' can be omitted in the last call.
# The above results are identical (up to rounding error)
# Variance from Konishi's theory
Var.VRR(Rho, N - 1, method = "Konishi") # Internally sets fun = "klv"
Var.VRR(Rho, N - 1, fun = "kl")
Var.VRR(Rho, N - 1, fun = "krv")
Var.VRR(Rho, N - 1, fun = "kr")
# These are identical, but the first one is fast
# On the other hand, these differ from that obtained with
# the Pan-Frank method above
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.