| Title: | Statistical Tests for Covariance and Correlation Matrices and their Structures |
| Version: | 1.2.0 |
| Maintainer: | Svenja Jedhoff <jedhoff@statistik.tu-dortmund.de> |
| Description: | A compilation of tests for hypotheses regarding covariance and correlation matrices for one or more groups. The hypothesis can be specified through a corresponding hypothesis matrix and a vector or by choosing one of the basic hypotheses, while for the structure test, only the latter works. Thereby Monte-Carlo and Bootstrap-techniques are used, and the respective method must be chosen, and the functions provide p-values and mostly also estimators of calculated covariance matrices of test statistics. For more details on the methodology, see Sattler et al. (2022) <doi:10.1016/j.jspi.2021.12.001>, Sattler and Pauly (2024) <doi:10.1007/s11749-023-00906-6>, Sattler and Dobler (2026) <doi:10.1016/j.jmva.2025.105517>, and Sattler and Jedhoff (2025) <doi:10.48550/arXiv.2507.03406>. |
| License: | GPL (≥ 3) |
| Imports: | MANOVA.RM, matrixcalc, Rdpack |
| Suggests: | testthat (≥ 3.0.0) |
| RdMacros: | Rdpack |
| Config/testthat/edition: | 3 |
| Encoding: | UTF-8 |
| URL: | https://github.com/sjedhoff/CovCorTest |
| BugReports: | https://github.com/sjedhoff/CovCorTest/issues |
| Config/roxygen2/version: | 8.0.0 |
| RoxygenNote: | 7.3.3 |
| NeedsCompilation: | no |
| Packaged: | 2026-07-30 07:49:55 UTC; jedhoff |
| Author: | Paavo Sattler |
| Repository: | CRAN |
| Date/Publication: | 2026-07-30 13:20:02 UTC |
CovCorTest: Tests for covariance and correlation matrices
Description
The CovCorTest package provides statistical tests for hypotheses about covariance matrices, correlation matrices, and structured covariance or correlation matrices. It also provides a combined procedure for comparing the covariance and correlation matrices of two groups.
The procedures are based on ANOVA-type statistics and use bootstrap, Monte Carlo, or Taylor-based Monte Carlo approximations, depending on the selected test. The methods require comparatively weak distributional assumptions and support both one-sample and multiple-group designs.
Data format
The main testing functions accept observations in either of two forms:
A numeric matrix or data frame with observations in rows and variables in columns.
A list of numeric matrices or data frames, with one element per group. Within every element, observations are stored in rows and variables in columns.
If multiple groups are combined into one matrix, the argument nv
specifies the sample size of each group. When a list is supplied, the group
sizes can be inferred from the numbers of rows.
All groups must contain the same variables. Observations containing missing values are removed before the test is calculated.
Tests for covariance matrices
test_covariance() tests hypotheses about one or more covariance matrices.
A predefined hypothesis can be selected using the hypothesis
argument. The available hypotheses are:
"equal"-
Tests equality of covariance matrices across groups. For a single group, it tests equality of the diagonal elements.
"equal-trace"-
Tests equality of covariance-matrix traces across multiple groups.
"equal-diagonals"-
Tests equality of the diagonal elements across multiple groups.
"given-trace"-
Tests whether the trace of a single covariance matrix is equal to a specified scalar.
"given-matrix"-
Tests whether a single covariance matrix is equal to a specified matrix.
"uncorrelated"-
Tests whether all off-diagonal elements of a single covariance matrix are zero.
Custom linear hypotheses can be specified using a hypothesis matrix
C and a corresponding null vector Xi. The underlying
covariance-testing methodology is described by
Sattler et al. (2022).
Tests for correlation matrices
test_correlation() tests hypotheses about one or more correlation
matrices. The predefined hypotheses are:
"equal-correlated"-
Tests equality of correlation matrices across groups.
"uncorrelated"-
Tests whether all correlations in a single group are zero.
As with test_covariance(), custom linear hypotheses can be supplied using
C and Xi. The correlation-testing methodology is described by
Sattler and Pauly (2024).
Covariance-structure tests
test_covariance_structure() tests whether the covariance matrix of one
group has a specified structure. The implemented structures include:
autoregressive,
"autoregressive"or"ar";first-order autoregressive,
"FO-autoregressive"or"FO-ar";diagonal,
"diagonal"or"diag";sphericity,
"sphericity"or"spher";compound symmetry,
"compoundsymmetry"or"cs";Toeplitz,
"toeplitz"or"toep";constant off-diagonal,
"constant-offdiagonal"or"const-offdiag";standard Toeplitz,
"standard-toeplitz"or"std-toep";banded,
"banded"or"band";banded Toeplitz,
"banded-toeplitz"or"band-toep".
For banded structures, bandwidth specifies the number of
off-diagonals that may be nonzero.
Correlation-structure tests
test_correlation_structure() tests whether the correlation matrix of one
group has a specified structure. The implemented structures include:
heterogeneous autoregressive,
"Hautoregressive"or"Har";diagonal,
"diagonal"or"diag";heterogeneous compound symmetry,
"Hcompoundsymmetry"or"Hcs";heterogeneous Toeplitz,
"Htoeplitz"or"Htoep";banded,
"banded"or"band";banded Toeplitz,
"banded-toeplitz"or"band-toep".
The covariance- and correlation-structure procedures are described by Sattler and Dobler (2026).
Combined test
test_combined() simultaneously compares the variances and correlations of
exactly two groups. It returns separate p-values for equality of the
variances and equality of the correlations, together with a p-value for the
global combined hypothesis.
The combined procedure is based on the correlation-testing methodology of Sattler and Pauly (2024).
Resampling methods
Depending on the function, the following methods are available:
"BT"-
A parametric bootstrap approximation.
"MC"-
A Monte Carlo approximation based on the estimated asymptotic distribution.
"TAY"-
A Taylor-based Monte Carlo approximation available for correlation procedures.
The repetitions argument controls the number of generated resampling
observations. At least 500 repetitions are recommended. Larger values
generally provide more precise p-values but require more computation time.
Alternative hypothesis matrices
By default, the main procedures use AM = 1. This replaces the
original hypothesis matrix with a lower-dimensional companion matrix that
yields the same ANOVA-type test statistic. The original and transformed
hypothesis matrices are retained in the returned object. This approach is
described by Sattler and Rosenbaum (2025).
Setting AM = 0 disables this transformation.
Constructing custom hypotheses
get_hypothesis() constructs a hypothesis matrix and vector for a linear
covariance model. It can be used together with test_covariance() when the
required hypothesis is not among the predefined alternatives.
Returned objects
Covariance, correlation, and structure tests return an object of class CovTest. Important components include:
-
pvalue: the estimated p-value; -
Teststatistic: the observed ANOVA-type statistic; -
CovarianceMatrix: the estimated covariance matrix of the statistic; -
CandXi: the hypothesis used in the calculation; -
C_originalandXi_original: the hypothesis before the optional companion-matrix transformation; -
resampling_method: the selected approximation; -
repetitions: the number of resampling repetitions; -
nv: the sample sizes.
The combined test returns an object of class CombTest containing separate variance, correlation, and global p-values.
Citation
When using CovCorTest, cite the package paper (Sattler and Jedhoff 2025).
Author(s)
Maintainer: Svenja Jedhoff jedhoff@statistik.tu-dortmund.de (ORCID)
Authors:
Paavo Sattler paavo.sattler@tu-dortmund.de (ORCID)
Other contributors:
Markus Pauly (ORCID) [contributor]
Arne C Bathke (ORCID) [contributor]
Dennis Dobler (ORCID) [contributor]
References
Sattler P, Bathke AC, Pauly M (2022).
“Testing Hypotheses about Covariance Matrices in General MANOVA Designs.”
Journal of Statistical Planning and Inference, 219, 134–146.
doi:10.1016/j.jspi.2021.12.001.
Sattler P, Dobler D (2026).
“Testing for Patterns and Structures in Covariance and Correlation Matrices.”
Journal of Multivariate Analysis, 211, 105517.
doi:10.1016/j.jmva.2025.105517.
Sattler P, Jedhoff S (2025).
“Testing Hypotheses Regarding Covariance and Correlation Matrices with the R Package CovCorTest.”
arXiv.
doi:10.48550/arXiv.2507.03406, arXiv:2507.03406, https://arxiv.org/abs/2507.03406.
Sattler P, Pauly M (2024).
“Testing hypotheses about correlation matrices in general MANOVA designs.”
TEST, 33(2), 496–516.
ISSN 1863-8260, doi:10.1007/s11749-023-00906-6.
Sattler P, Rosenbaum M (2025).
“Choice of the hypothesis matrix for using the Anova-type-statistic.”
Statistics & Probability Letters, 219, 110356.
doi:10.1016/j.spl.2025.110356.
See Also
test_covariance(), test_correlation(),
test_covariance_structure(), test_correlation_structure(),
test_combined(), and get_hypothesis().
Anova-Type-statistic
Description
Anova-Type-statistic
Usage
ATS(N, vVarData, C, HatCov, Xi = 0)
Arguments
N |
number of observations |
vVarData |
a matrix of vectorized covariance/correlation data |
C |
hypothesis matrix for calculating the ATS |
HatCov |
covariance matrix |
Xi |
a vector defining together with C the investigated hypothesis |
Value
a vector
ATS for transformed vectors
Description
A function which calculates the Anova-type-statistic based on a transformation function
Usage
ATS_fun(N, X, C, v, a, d, p, fun)
Arguments
N |
sample size |
X |
matrix containing the bootstrap observations as columns |
C |
the hypothesis matrix |
v |
vectorized empirical covariance matrix of the original data |
a |
vector containing the indices which belongs to the diagonal of the covariance matrix |
d |
dimension of the covariance matrix |
p |
dimension of the vectorized matrix |
fun |
transformation function, that should be used.
|
Value
a scalar, the value of the ATS
Anova-Type-Statistic with weighted sum
Description
Calculation of a Anova-Type-Statistic using
Usage
ATSwS(A, repetitions)
Arguments
A |
a matrix |
repetitions |
a scalar, number of runs |
Value
a vector of the length of repetitions
Bootstrap for one and multiple groups
Description
This function generates normal distributed random vectors. For one group, nv random vectors with covariance matrix HatCov are generated and the corresponding value of the ATS is generated. For multiple groups the corresponding sample sizes from nv are used. The weighted sum of covariance matrices is calculated and used to calculate the value of the ATS.
Usage
Bootstrap(N.sim, nv, C, MSrootHatCov)
Arguments
N.sim |
control variable for using sapply |
nv |
scalar (one group) or vector (multiple groups) of sample sizes for the bootstrap samples |
C |
hypothesis matrix for calculating the ATS |
MSrootHatCov |
matrix (one group) or list of matrices (multiple groups) of roots of the covariance matrices, to generate the bootstrap sample |
Value
a scalar, the value of the ATS
Bootstrap using transformation for one group
Description
This function generates n1 normal distributed random vectors with covariance matrix HatCov, which matrix root MSrootHatCov is given and expectation vector vX. For the generated bootstrap sample the value of the ATS based on a transformation is calculated
Usage
Bootstrap_trans(N.sim, n1, a, d, p, C, MSrootHatCov, vX, fun)
Arguments
N.sim |
control variable for using sapply |
n1 |
a scalar, declaring the sample size for the bootstrap sample |
a |
vector containing the indices which belong to the diagonal of the covariance matrix |
d |
dimension of the covariance matrix |
p |
dimension of the vectorized matrix |
C |
a hypothesis matrix for calculating the ATS |
MSrootHatCov |
matrix root of the covariance matrix HatCov, to generate the bootstrap sample |
vX |
the expectation vector for the bootstrap sample |
fun |
transformation function, that should be used.
|
Value
a scalar, the value of the ATS
Check bandwidth argument
Description
Checks whether the bandwidth argument is valid for banded covariance or correlation structures. The bandwidth specifies the number of off-diagonals that are allowed to be non-zero. It must be a positive integer and smaller than the maximal possible bandwidth, since bandwidth zero corresponds to a diagonal structure and the maximal bandwidth would impose no restriction.
Usage
CheckBandwidth(bandwidth, d)
Arguments
bandwidth |
A positive integer specifying the number of allowed off-diagonals. |
d |
Integer. Dimension of the covariance or correlation matrix. |
Value
The checked bandwidth as an integer.
Validate the number of resampling repetitions
Description
Checks that the requested number of repetitions is a single, finite, positive integer. A warning is issued when the number is below the recommended minimum because the resulting p-value may be imprecise.
Usage
CheckRepetitions(repetitions, minimum_recommended = 500L)
Arguments
repetitions |
A single positive integer specifying the number of resampling repetitions. |
minimum_recommended |
A single positive integer specifying the number of repetitions below which a warning is issued. The default is 500. |
Value
The validated number of repetitions as an integer.
Combined covariance and correlation test result
Description
Constructs an object of class CombTest. Objects of this class
represent results from the combined test for equality of covariance and
correlation matrices.
Usage
CombTest(
pvalue_Variances = NA_real_,
pvalue_Correlations = NA_real_,
pvalue_Total = NA_real_,
Teststatistic = NA_real_,
repetitions = NA_integer_,
nv = integer()
)
Arguments
pvalue_Variances |
Numeric. The p-value for equality of the variances. |
pvalue_Correlations |
Numeric. The p-value for equality of the correlations. |
pvalue_Total |
Numeric. The p-value for the global combined hypothesis. |
Teststatistic |
Numeric. The value of the combined test statistic. |
repetitions |
Integer. The number of resampling repetitions. |
nv |
Integer vector containing the sample sizes of the two groups. |
Details
A CombTest object contains the following components:
pvalue_Variances-
Numeric. The p-value for equality of the variances.
pvalue_Correlations-
Numeric. The p-value for equality of the correlations.
pvalue_Total-
Numeric. The p-value for the global combined hypothesis.
Teststatistic-
Numeric. The value of the combined test statistic.
repetitions-
Integer. The number of resampling repetitions.
nv-
Integer vector. The sample sizes of the two groups.
Value
An object of class CombTest.
Examples
result <- CombTest(
pvalue_Variances = 0.12,
pvalue_Correlations = 0.08,
pvalue_Total = 0.08,
Teststatistic = 2.4,
repetitions = 1000L,
nv = c(20L, 25L)
)
CovTest Object
Description
This help page describes the structure of the CovTest class,
which is used to represent the results of a covariance and correlation test.
Usage
CovTest()
Details
A CovTest object is a list with the following components:
methodCharacter. Either 'Covariance' or 'Correlation'.
pvalueNumeric. The p-value of the test.
TeststatisticNumeric. The test statistic.
CovarianceMatrixMatrix. The covariance estimator for the teststatistic.
CNumeric matrix. The hypothesis matrix used for the computation of the test statistic. If
AM = 1, this may be the alternative hypothesis matrix used internally.XiNumeric vector. The hypothesis vector used together with
C. IfAM = 1, this may be the transformed hypothesis vector used internally.AMInteger. Indicates whether the alternative hypothesis matrix was used.
C_originalNumeric matrix. The original hypothesis matrix before the optional transformation by
AM, if applicable.Xi_originalNumeric vector. The original hypothesis vector before the optional transformation by
AM, if applicable.resampling_methodCharacter. The resampling method used in the test.
repetitionsInteger. The number of repetitions used in resampling.
hypothesisCharacter. The hypothesis being tested.
nvNumeric. The sample size or the number of variables.
Value
An object of class CovTest.
Jacobian matrix for transformation functions
Description
A function which calculates the Jacobian matrix for a given
transformation function subdiagonal_mean_ratio_cor or
subdiagonal_mean_ratio_fct
Usage
Jacobian(X, a, d, p, fun)
Arguments
X |
vectorized covariance matrix for which the Jacobian matrix is applied |
a |
vector containing the indices which belong to the diagonal of the covariance matrix |
d |
dimension of the covariance matrix |
p |
dimension of the vectorized matrix |
fun |
transformation function, that should be used.
|
Value
the Jacobian matrix applied for the given vector
Function to transform the data into a list, if there are not already
Description
Function to transform the data into a list, if there are not already
Usage
Listcheck(X, nv = NULL)
Arguments
X |
object that should be checked |
nv |
number of subjects per group |
Value
A list with two components
X |
Dataset in the right format: for a single group, a single matrix. For multiple groups, a list with an element for each group containing a matrix. |
nv |
Number of subjects per group: NV for a single group and a vector for multiple groups. |
Auxiliary function to calculate the covariance of the vectorized correlation matrix
Description
Auxiliary function to calculate the covariance of the vectorized correlation matrix
Usage
Qvech(X, n)
Arguments
X |
matrix |
n |
number of columns |
Value
matrix
Function for the Taylor-based Monte-Carlo-approximation for one group
Description
An auxiliary function to calculate the values for the Taylor-based Monte-Carlo-approximation for one group. After receiving some auxiliary matrices and data, the Monte-Carlo observations are generated and different parts of the final sum are defined. Based on this a number of the Taylor-based ATS are calculated, where the number can be chosen.
Usage
Tayapp1G(
repetitions,
C,
MSrootStUpsi,
CorData,
MvrH,
Trace,
M4,
L,
P,
Q,
n1,
Atilde = NULL,
Jacobi = NULL
)
Arguments
repetitions |
a number specifying the number of runs for the approximation |
C |
the used hypothesis matrix |
MSrootStUpsi |
the matrix root of the covariance matrix for the Taylor observations |
CorData |
the calculated correlation matrix |
MvrH |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
Trace |
a trace used in the ATS for the test statistic |
M4 |
a auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
L |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
P |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
Q |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
n1 |
the total sample size, a scalar |
Atilde |
an auxiliary matrix for the transformation from row-wise vectorization |
Jacobi |
the Jacobian matrix of the transformation function applied for the diagonal vectorized correlation to diagonalwise vectorization. used for the transformation function 'subdiagonal_mean_ratio_cor', else NULL |
Value
a matrix containing the values of the Taylor ATS for a number of repetitions
Function for the Taylor-based Monte-Carlo-approximation for multiple groups
Description
An auxiliary function to calculate the values for the Taylor-based Monte-Carlo-approximation for multiple groups. After receiving some auxiliary matrices and data, the Monte-Carlo observations are generated and different parts of the final sum are defined. Based on this a number of the Taylor-based ATS are calculated, where the number can be chosen.
Usage
TayappMG(repetitions, C, MSrootStUpsi, CorData, MvrH, Trace, M4, L, P, Q, nv)
Arguments
repetitions |
a number specifying the number of runs for the approximation |
C |
the used hypothesis matrix |
MSrootStUpsi |
the matrix root of the covariance matrix for the Taylor observations |
CorData |
the calculated correlation matrix |
MvrH |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
Trace |
a trace used in the ATS for the test statistic |
M4 |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
L |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
P |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
Q |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
nv |
vector of sample sizes |
Value
a matrix containing the values of the Taylor ATS for a number of repetitions
The Taylor-based Monte-Carlo-approximation for a combined test
Description
An auxiliary function to calculate the values for the Taylor-based Monte-Carlo-approximation for the combined test. After receiving some auxiliary matrices and data, the Monte-Carlo observations are generated, and different parts of the final sum are defined. Based on this, a number of the Taylor-based vectors are calculated, where the number can be chosen.
Usage
TaylorCombined(
repetitions,
MSrootHatCov,
CorData,
MvrH1,
MvrH2,
M4,
L,
P,
Q,
nv
)
Arguments
repetitions |
a number specifying the number of runs for the approximation |
MSrootHatCov |
the matrix root of the covariance matrix for the Taylor observations |
CorData |
the calculated correlation matrix |
MvrH1 |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
MvrH2 |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
M4 |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
L |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
P |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
Q |
an auxiliary matrix for the transformation from vectorized covariances to vectorized correlations |
nv |
vector of sample sizes |
Value
a matrix containing the values of the test vector for a number of repetitions
Weighted direct sums for lists the corresponding components of a matrix w, containing the weights. These, now weighted matrices are put together to one larger block-diagonal matrix.
Description
Weighted direct sums for lists the corresponding components of a matrix w, containing the weights. These, now weighted matrices are put together to one larger block-diagonal matrix.
Usage
WDirect.sumL(X, w)
Arguments
X |
matrix |
w |
weight matrix |
Value
matrix
Diagonal vectorization
Description
Diagonal vectorization of the upper triangular matrix
Usage
dvech(X, a, d, p, inc_diag)
Arguments
X |
quadratic matrix which should be diagonalized |
a |
vector containing the indices which belong to the diagonal of the matrix |
d |
dimension of the matrix which should be vectorized |
p |
dimension of the vectorized matrix |
inc_diag |
TRUE or FALSE: should the diagonal be included? |
Value
vector
Format a resampling-based p-value
Description
Formats a p-value obtained from a finite number of resampling repetitions.
If none of the resampled statistics is at least as extreme as the observed
statistic, the estimated p-value is zero and is displayed using the
resolution bound 1 / repetitions.
Usage
format_resampling_pvalue(pvalue, repetitions, digits = 4L)
Arguments
pvalue |
A single numeric p-value between zero and one. |
repetitions |
A single positive integer specifying the number of resampling repetitions. |
digits |
A single positive integer specifying the number of significant digits used for a nonzero p-value. |
Value
A character string containing the formatted p-value.
Function to generate bootstrap observations
Description
Function to generate bootstrap observations
Usage
generateData(WSigma, nv)
Arguments
WSigma |
weight matrix |
nv |
number of observations in the groups |
Value
a matrix
Extend a matrix to full rank using identity columns
Description
This function extends a matrix V (assumed to have fewer than p columns)
to full rank by iteratively appending standard basis vectors from the identity matrix,
ensuring that each added column increases the rank.
Usage
get_extended_matrix(V, tol = sqrt(.Machine$double.eps))
Arguments
V |
A numeric matrix with |
tol |
A non-negative numeric scalar specifying the tolerance used by
|
Details
The function assumes that nrow(V) equals the intended dimension p of the parameter space.
It adds columns from the identity matrix (i.e., standard basis vectors) only when they increase the rank,
and stops when full rank is achieved.
Value
A numeric matrix of dimension p x p with full column rank.
Construct hypothesis matrix and vector from linear covariance model structure
Description
Computes a hypothesis matrix C and hypothesis vector zeta based on a given
parameter vector v0 and a matrix V representing the model structure
(e.g., vectorized components of a linear covariance structure model).
Usage
get_hypothesis(v0, V)
Arguments
v0 |
A numeric vector of length |
V |
A numeric matrix of size |
Details
The function extends V to full rank using get_extended_matrix, constructs a contrast
matrix E for the complement of the model-implied space, and computes the corresponding hypothesis matrix C.
Value
A list with two elements:
hypothesis_matrixA numeric matrix
Csuch that the hypothesis can be written asC %*% theta = zetahypothesis_vectorThe numeric vector
zeta, computed asC %*% v0
References
Sattler P, Dobler D (2026). “Testing for Patterns and Structures in Covariance and Correlation Matrices.” Journal of Multivariate Analysis, 211, 105517. doi:10.1016/j.jmva.2025.105517.
Examples
# Load the data
data("EEGwide", package = "MANOVA.RM")
X <- as.matrix(EEGwide[EEGwide$sex == "W" & EEGwide$diagnosis == "AD",
c("brainrate_temporal", "brainrate_frontal","brainrate_central",
"complexity_temporal","complexity_frontal", "complexity_central")])
v0 <- rep(0,21)
v_auxiliary <- c(1, rep(0,5), 1, rep(0,4), 1, rep(0,3), 1, rep(0,2), 1, 0, 1)
V <- cbind(v_auxiliary, 1-v_auxiliary)
h <- get_hypothesis(v0,V)
set.seed(123)
test_covariance(X = X,C = h$hypothesis_matrix, Xi = h$hypothesis_vector,
method = "MC", repetitions = 1000)
Print function for CombTest object
Description
Print function for CombTest object
Usage
## S3 method for class 'CombTest'
print(x, ...)
Arguments
x |
an |
... |
additional parameters |
Value
no return, just print
Print function for CovTest object
Description
Print function for CovTest object
Usage
## S3 method for class 'CovTest'
print(x, ...)
Arguments
x |
an |
... |
additional parameters |
Value
no return, just print
Root transformation of the vectorized correlation matrix
Description
A function calculating the roots of a vectorized covariance matrix. The roots increasing, so square root for the first secondary diagonals, third root for the second secondary diagonal and so on. For roots with even order the absolute value of the argument is used, since the arguments can be negative.
Usage
subdiagonal_mean_ratio_cor(v, a, d)
Arguments
v |
vectorized correlation matrix which should be transformed |
a |
vector containing the indices which belong to the diagonal of the correlation matrix |
d |
dimension of the correlation matrix |
Value
a transformed vector
Transformation of the vectorized covariance matrix by quotients of means
Description
A function which calculates the mean of the secondary diagonals and divide them through the next one. Since the elements can be negative, for the denominator absolute values are used.
Usage
subdiagonal_mean_ratio_fct(v, a, d)
Arguments
v |
vectorized covariance matrix which should be transformed |
a |
vector containing the indices which belong to the diagonal of the covariance matrix |
d |
dimension of the covariance matrix |
Value
a transformed vector
Combined test for equality of covariance matrices and correlation matrices
Description
For two groups a combined test for equality of covariance matrices and equality of correlation matrices between these groups is conducted. Both hypotheses can be rejected or only the larger one, the equality of the covariance matrices
Usage
test_combined(X, nv = NULL, repetitions = 1000)
Arguments
X |
a list or matrix containing the observation vectors. In case of a list, each matrix in this list is another group, where the observation vectors are the rows. For a matrix, all groups are together in one matrix and nv is used to indicate the group sizes. |
nv |
vector of group sizes |
repetitions |
a scalar, indicate the number of runs for the chosen method. The predefined value is 1.000, and the number should not be below 500. |
Value
an object of the class CovTest.
Examples
# Load the data
data("EEGwide", package = "MANOVA.RM")
vars <- colnames(EEGwide)[1:6]
# Part the data into two diagnosis groups
X_list <- list(EEGwide[EEGwide$sex=="M" & EEGwide$diagnosis=="AD",vars],
EEGwide[EEGwide$sex=="M" & EEGwide$diagnosis=="MCI",vars])
nv <- unlist(lapply(X_list, nrow))
set.seed(31415)
test_combined(X_list, nv)
Test for Correlation Matrices
Description
This function conducts statistical tests for hypotheses
regarding correlation matrices.
Users can either select from predefined hypotheses or
provide their own contrast matrix C and vector Xi for custom hypotheses.
It supports both bootstrap and Monte Carlo resampling methods to
obtain the p-value of the ANOVA-type statistic (ATS).
Usage
test_correlation(
X,
nv = NULL,
C = NULL,
Xi = NULL,
AM = 1,
hypothesis = NULL,
method = "BT",
repetitions = 1000
)
Arguments
X |
A list or a matrix containing the observation vectors. If a list,
each entry is a group, with observations as rows. If a matrix,
all groups are combined, and |
nv |
(Optional) A vector indicating group sizes, needed when
|
C |
A hypothesis matrix specifying the null hypothesis.
Optional if |
Xi |
A numeric vector specifying the expected values of the contrasts
under the null hypothesis. Optional if |
AM |
Binary variable indicating whether the computations should use an alternative hypothesis matrix as proposed by Sattler and Rosenbaum (2025). This matrix has fewer rows than the original hypothesis matrix while leaving the resulting test statistics unchanged. By default, this alternative matrix is used. |
hypothesis |
A character specifying one of the predefined hypotheses:
If |
method |
Character string indicating the resampling method to use.
One of |
repetitions |
Integer. Number of resampling repetitions (default is 1000). |
Value
An object of class "CovTest".
References
Sattler, P. and Pauly, M. (2024). Testing hypotheses about correlation matrices in general MANOVA designs. TEST, 33(2), 496–516. doi:10.1007/s11749-023-00906-6
Examples
# Example with one group:
set.seed(31415)
X <- matrix(rnorm(5 * 100), ncol = 5)
test_correlation(X, hypothesis = "uncorrelated",
method = "BT", repetitions = 100)
Test for structure of data's correlation matrix
Description
With this function the correlation matrix of data can be checked for one of the predefined structures. Depending on the chosen method a bootstrap, the Taylor-based Monte-Carlo approach or Monte-Carlo-technique is used to calculate the p-value of the Anova-type-statistic(ATS) based on a specified number of runs.
Usage
test_correlation_structure(
X,
structure,
AM = 1,
method = "BT",
repetitions = 1000,
bandwidth = NA
)
Arguments
X |
a matrix containing the observation vectors as rows (one group) |
structure |
a character specifying the structure regarding them the correlation matrix should be checked. Options are "Hautoregressive" ("Har"), "diagonal" ("diag"), "Hcompoundsymmetry" ("Hcs") and "Htoeplitz" ("Htoep"), "banded" ("band"), and "banded-toeplitz" ("band-toep"). For banded structures, all correlations outside the specified bandwidth, i.e. from the bandwidth + 1-th off-diagonal onward, are assumed to be zero. |
AM |
Binary variable indicating whether the computations should use an alternative hypothesis matrix as proposed by Sattler and Rosenbaum (2025). This matrix has fewer rows than the original hypothesis matrix while leaving the resulting test statistics unchanged. By default, this alternative matrix is used. |
method |
a character, to chose whether bootstrap("BT") or Taylor-based Monte-Carlo-approach("TAY") or Monte-Carlo-technique("MC") is used, while bootstrap is the predefined method. |
repetitions |
a scalar, indicate the number of runs for the chosen method. The predefined value is 1,000, and the number should not be below 500. |
bandwidth |
Optional positive integer specifying the number of
off-diagonals allowed to be non-zero for banded correlation structures.
Only used for |
Value
an object of the class CovTest
References
Sattler P, Dobler D (2026). “Testing for Patterns and Structures in Covariance and Correlation Matrices.” Journal of Multivariate Analysis, 211, 105517. doi:10.1016/j.jmva.2025.105517.
Examples
# Load the data
data("EEGwide", package = "MANOVA.RM")
# Select only the females with the diagnosis AD
X <- as.matrix(EEGwide[EEGwide$sex == "W" & EEGwide$diagnosis == "AD",
c("brainrate_temporal", "brainrate_frontal","brainrate_central",
"complexity_temporal","complexity_frontal",
"complexity_central")])
test_correlation_structure(X = X, structure = "diagonal", method = "MC")
Test for Covariance Matrices
Description
This function conducts statistical tests for hypotheses
regarding covariance matrices. Users can either select from predefined
hypotheses (e.g., equal covariance, equal trace, etc.) or
provide their own contrast matrix C and vector Xi for custom hypotheses.
It supports both bootstrap and Monte Carlo resampling methods to
obtain the p-value of the ANOVA-type statistic (ATS).
Usage
test_covariance(
X,
nv = NULL,
C = NULL,
Xi = NULL,
AM = 1,
hypothesis = NULL,
A = NULL,
method = "MC",
repetitions = 1000
)
Arguments
X |
A list or a matrix containing the observation vectors. If a list,
each entry is a group, with observations as rows. If a matrix, all
groups are combined, and |
nv |
(Optional) A vector indicating group sizes, needed when |
C |
(Optional) A user-defined contrast matrix for testing custom
hypotheses. Must match dimensions with |
Xi |
(Optional) A numeric vector used in combination with |
AM |
Binary variable indicating whether the computations should use an alternative hypothesis matrix as proposed by Sattler and Rosenbaum (2025). This matrix has fewer rows than the original hypothesis matrix while leaving the resulting test statistics unchanged. By default, this alternative matrix is used. |
hypothesis |
A character specifying one of the predefined hypotheses:
If |
A |
Optional scalar or matrix to define the hypothesis value when
|
method |
A character indicating the resampling method:
|
repetitions |
Number of repetitions to use for the resampling method (default: 1000, should be >= 500). |
Value
An object of class CovTest.
References
Sattler P, Bathke AC, Pauly M (2022). “Testing Hypotheses about Covariance Matrices in General MANOVA Designs.” Journal of Statistical Planning and Inference, 219, 134–146. doi:10.1016/j.jspi.2021.12.001.
Examples
# Load the data
data("EEGwide", package = "MANOVA.RM")
vars <- colnames(EEGwide)[1:6]
X <- EEGwide[EEGwide$sex == "M" & EEGwide$diagnosis == "AD",vars]
# Testing the trace
C <- matrix(c(1,0,0,0,0,0,1,0,0,0,0,1,0,0,0,1,0,0,1,0,1),
nrow = 1, ncol = 21)
Xi <- 2
set.seed(31415)
test_covariance(X = X, nv = NULL, C = C, Xi = Xi, AM = 1,
method = "BT", repetitions = 1000)
Test for structure of data's covariance matrix
Description
This function conducts the test for the covariance matrix of data regarding structures. Depending on the chosen method a bootstrap or Monte-Carlo-technique is used to calculate p-value of the Anova-type-statistic(ATS) based on a specified number of runs.
Usage
test_covariance_structure(
X,
structure,
AM = 1,
method = "BT",
repetitions = 1000,
bandwidth = NA
)
Arguments
X |
a matrix or data frame containing the observation vectors as rows (one group only) |
structure |
a character specifying the structure regarding the covariance matrix should be checked. Options are "autoregressive" ("ar"), "FO-autoregressive" ("FO-ar"), "diagonal" ("diag"), "sphericity" ("spher"), "compoundsymmetry" ("cs") and "toeplitz" ("toep"), "constant-offdiagonal" ("const-offdiag"), "standard-toeplitz" ("std-toep"), "banded" ("band"), and "banded-toeplitz" ("band-toep"). For banded structures, all entries outside the specified bandwidth, i.e. from the bandwidth + 1-th off-diagonal onward, are assumed to be zero. |
AM |
Binary variable indicating whether the computations should use an alternative hypothesis matrix as proposed by Sattler and Rosenbaum (2025). This matrix has fewer rows than the original hypothesis matrix while leaving the resulting test statistics unchanged. By default, this alternative matrix is used. |
method |
a character, to chose whether bootstrap("BT") or Monte-Carlo-technique("MC") is used, while bootstrap is the predefined method. |
repetitions |
a scalar, indicate the number of runs for the chosen method. The predefined value is 1,000, and the number should not be below 500. |
bandwidth |
Optional positive integer specifying the number of
off-diagonals allowed to be non-zero for banded covariance structures.
Only used for "banded" and "banded-toeplitz" structures,
with default |
Value
an object of the class CovTest
References
Sattler P, Dobler D (2026). “Testing for Patterns and Structures in Covariance and Correlation Matrices.” Journal of Multivariate Analysis, 211, 105517. doi:10.1016/j.jmva.2025.105517.
Examples
# Load the data
data("EEGwide", package = "MANOVA.RM")
# Select only the females with the diagnosis AD
X <- as.matrix(EEGwide[EEGwide$sex == "W" & EEGwide$diagnosis == "AD",
c("brainrate_temporal", "brainrate_frontal",
"brainrate_central","complexity_temporal",
"complexity_frontal", "complexity_central")])
test_covariance_structure(X = X, structure = "diagonal", method = "MC")
Function to calculate dvech(X t(X))
Description
Function to calculate dvech(X t(X))
Usage
vdtcrossprod(X, a, d, p)
Arguments
X |
matrix |
a |
indices that belong to the diagonal of the matrix |
d |
dimension of the matrix |
p |
dimension of the vectorized matrix |
Value
vector
Vectorization of the upper triangular part of the matrix
Description
Vectorization of the upper triangular part of the matrix
Usage
vechp(X)
Arguments
X |
A square numeric matrix. |
Value
A vector containing the upper triangular part of X.
Function to calculate vech(X t(X))
Description
Function to calculate vech(X t(X))
Usage
vtcrossprod(X)
Arguments
X |
matrix |
Value
vector