CovCorTest

Statistical Tests for Covariance and Correlation Matrices and Their Structures

R-CMD-check Codecov test coverage CRAN status

CovCorTest provides statistical tests for hypotheses about covariance matrices, correlation matrices, and structured covariance or correlation matrices in one-sample and multiple-group designs.

The package offers predefined hypotheses as well as custom linear hypotheses specified through a hypothesis matrix C and null vector Xi. Depending on the selected test, p-values are approximated using bootstrap ("BT"), Monte Carlo ("MC"), or Taylor-based Monte Carlo ("TAY") procedures.

Installation

Install the released version from CRAN:

install.packages("CovCorTest")

Install the development version from GitHub:

# install.packages("devtools")
devtools::install_github("sjedhoff/CovCorTest")

Main functions

Observations must be stored in rows and variables in columns. Multiple groups can be supplied as a list of matrices or data frames. Alternatively, they can be combined in one matrix and their sample sizes supplied through nv.

Quick start

The following example uses two groups from the EEGwide data included with MANOVA.RM:

library(CovCorTest)

data("EEGwide", package = "MANOVA.RM")
vars <- colnames(EEGwide)[1:6]

data <- list(
  AD = EEGwide[
    EEGwide$sex == "M" & EEGwide$diagnosis == "AD",
    vars
  ],
  MCI = EEGwide[
    EEGwide$sex == "M" & EEGwide$diagnosis == "MCI",
    vars
  ]
)

nv <- vapply(data, nrow, integer(1))

Test equality of the covariance matrices:

set.seed(31415)

cov_result <- test_covariance(
  X = data,
  nv = nv,
  hypothesis = "equal",
  method = "BT",
  repetitions = 1000
)

cov_result
cov_result$pvalue

Test equality of the correlation matrices:

set.seed(31415)

cor_result <- test_correlation(
  X = data,
  nv = nv,
  hypothesis = "equal-correlated",
  method = "BT",
  repetitions = 1000
)

cor_result

Perform the combined test:

set.seed(31415)

combined_result <- test_combined(
  X = data,
  nv = nv,
  repetitions = 1000
)

combined_result
combined_result$pvalue_Total

Test whether the covariance matrix of one group is diagonal:

set.seed(31415)

structure_result <- test_covariance_structure(
  X = data$AD,
  structure = "diagonal",
  method = "BT",
  repetitions = 1000
)

structure_result

For banded structures, specify the number of off-diagonals that may be nonzero:

set.seed(31415)

banded_result <- test_correlation_structure(
  X = data$AD,
  structure = "banded-toeplitz",
  bandwidth = 2,
  method = "BT",
  repetitions = 1000
)

banded_result

Other predefined hypotheses and structures are documented on the individual function help pages:

?test_covariance
?test_correlation
?test_covariance_structure
?test_correlation_structure

At least 500 resampling repetitions are recommended. Larger values generally provide more precise p-values but require more computation time.

Custom hypotheses

Advanced users can supply a custom hypothesis matrix C and null vector Xi directly. get_hypothesis() can construct them for a linear covariance model:

d <- ncol(data$AD)
p <- d * (d + 1) / 2
diagonal_positions <- cumsum(c(1, d:2))

variance_component <- numeric(p)
variance_component[diagonal_positions] <- 1

V <- cbind(
  variance_component,
  1 - variance_component
)

hypothesis <- get_hypothesis(
  v0 = rep(0, p),
  V = V
)

set.seed(31415)

custom_result <- test_covariance(
  X = data$AD,
  C = hypothesis$hypothesis_matrix,
  Xi = hypothesis$hypothesis_vector,
  method = "MC",
  repetitions = 1000
)

custom_result

By default, the tests use AM = 1, which replaces the original hypothesis matrix with a lower-dimensional companion matrix without changing the ANOVA-type test statistic. Set AM = 0 to disable this transformation.

Citation

If you use CovCorTest in a scientific publication, please cite:

Sattler, P. and Jedhoff, S. (2025). Testing Hypotheses Regarding Covariance and Correlation Matrices with the R Package CovCorTest. arXiv:2507.03406.
https://doi.org/10.48550/arXiv.2507.03406

The citation and BibTeX entry are also available in R:

citation("CovCorTest")
toBibtex(citation("CovCorTest"))

Depending on the procedures used, please also cite the corresponding methodological paper.

Methodological references