Title:	Statistical Tests for Covariance and Correlation Matrices and their Structures
Version:	1.0.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>, and Sattler and Dobler (2025) <doi:10.48550/arXiv.2310.11799>.
License:	GPL (≥ 3)
Imports:	MANOVA.RM, matrixcalc
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
URL:	https://github.com/sjedhoff/CovCorTest
BugReports:	https://github.com/sjedhoff/CovCorTest/issues
NeedsCompilation:	no
Packaged:	2025-06-05 08:10:37 UTC; jedhoff
Author:	Paavo Sattler [aut], Svenja Jedhoff [cre, aut], Markus Pauly [ctb], Arne C Bathke [ctb], Dennis Dobler [ctb]
Repository:	CRAN
Date/Publication:	2025-06-06 13:30:13 UTC

Anova-Type-statistic

Description

Anova-Type-statistic

Usage

ATS(N, vVarData, C, HatCov, Xi = 0)

Arguments

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

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

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

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

Value

a scalar, the value of the ATS

CombTest Object

Description

This help page describes the structure of the CombTest class, which is used to represent the results the combined covariance and correlation test.

Usage

CombTest()

Details

A CombTest object is a list with the following components:

method

Character. Either 'Covariance' or 'Correlation'.

pvalue-Variances

Numeric. The p-value of the test regarding the covariances.

pvalue-Correlations

Numeric. The p-value of the test regarding the correlations.

pvalue-Total

Numeric. The p-value of the whole test of the global hypothesis.

Teststatistic

Numeric. The test statistic.

resampling_method

Character. The resampling method used in the test.

repetitions

Integer. The number of repetitions used in resampling.

nv

Numeric. The sample size or the number of variables.

Value

An object of class CombTest.

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:

method

Character. Either 'Covariance' or 'Correlation'.

pvalue

Numeric. The p-value of the test.

Teststatistic

Numeric. The test statistic.

CovarianceMatrix

Matrix. The covariance estimator for the teststatistic.

C

Numeric. A constant or vector of constants used in the test.

Xi

Numeric. A parameter related to the test.

resampling_method

Character. The resampling method used in the test.

repetitions

Integer. The number of repetitions used in resampling.

hypothesis

Character. The hypothesis being tested.

nv

Numeric. 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

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)

Arguments

Value

A list with two components

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

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

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

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

Value

a matrix containing the values of the test vector for a number of repetitions

Weighted direct sums for lists

Description

Hereby the matrices which are part of a list are multiplied with 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

Value

matrix

Diagonal vectorization

Description

Diagonal vectorization of the upper triangular matrix

Usage

dvech(X, a, d, p, inc_diag)

Arguments

Value

vector

Function to generate bootstrap observations

Description

Function to generate bootstrap observations

Usage

generateData(WSigma, nv)

Arguments

Value

a matrix

Print function for CombTest object

Description

Print function for CombTest object

Usage

## S3 method for class 'CombTest'
print(x, ...)

Arguments

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

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

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

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

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 six groups of sex and diagnosis
X_list <- list(t(EEGwide[EEGwide$sex=="M" & EEGwide$diagnosis=="AD",vars]),
               t(EEGwide[EEGwide$sex=="M" & EEGwide$diagnosis=="MCI",vars]))

nv <- unlist(lapply(X_list, ncol))
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,
  hypothesis = NULL,
  method = "BT",
  repetitions = 1000
)

Arguments

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), nrow = 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, method = "BT", repetitions = 1000)

Arguments

Value

an object of the class CovTest

References

Sattler, P. and Dobler, D. (2025). Testing for patterns and structures in covariance and correlation matrices. arXiv preprint https://arxiv.org/abs/2310.11799

Examples

# Load the data
data("EEGwide", package = "MANOVA.RM")

# Select only the males 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,
  hypothesis = NULL,
  A = NULL,
  method = "MC",
  repetitions = 1000
)

Arguments

Value

An object of class CovTest.

References

Sattler, P., Bathke, A. C., and 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 <- t(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, 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, method = "BT", repetitions = 1000)

Arguments

Value

an object of the class CovTest

References

Sattler, P. and Dobler, D. (2025). Testing for patterns and structures in covariance and correlation matrices. arXiv preprint https://arxiv.org/abs/2310.11799

Examples

# Load the data
data("EEGwide", package = "MANOVA.RM")

# Select only the males 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

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

Value

vector

Function to calculate vech(X t(X))

Description

Function to calculate vech(X t(X))

Usage

vtcrossprod(X)

Arguments

Value

vector