Package {CovCorTest}


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 ORCID iD [aut], Svenja Jedhoff ORCID iD [cre, aut], Markus Pauly ORCID iD [ctb], Arne C Bathke ORCID iD [ctb], Dennis Dobler ORCID iD [ctb]
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:

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:

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:

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:

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:

Other contributors:

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. subdiagonal_mean_ratio_fct or subdiagonal_mean_ratio_cor

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. subdiagonal_mean_ratio_fct or subdiagonal_mean_ratio_cor

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:

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 matrix. The hypothesis matrix used for the computation of the test statistic. If AM = 1, this may be the alternative hypothesis matrix used internally.

Xi

Numeric vector. The hypothesis vector used together with C. If AM = 1, this may be the transformed hypothesis vector used internally.

AM

Integer. Indicates whether the alternative hypothesis matrix was used.

C_original

Numeric matrix. The original hypothesis matrix before the optional transformation by AM, if applicable.

Xi_original

Numeric vector. The original hypothesis vector before the optional transformation by AM, if applicable.

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

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. subdiagonal_mean_ratio_fct or subdiagonal_mean_ratio_cor

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 p rows and fewer than p columns.

tol

A non-negative numeric scalar specifying the tolerance used by qr when determining the numerical rank of V. Columns associated with values smaller than this tolerance are treated as linearly dependent. The default is sqrt(.Machine$double.eps).

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 p (number of parameters). Represents the parameter vector at which the hypothesis is to be evaluated.

V

A numeric matrix of size ⁠p x q⁠, representing the structured design or constraint matrix for the model. Here, the vectorised matrices from the linear covariance structure model build the columns of V.

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_matrix

A numeric matrix C such that the hypothesis can be written as C %*% theta = zeta

hypothesis_vector

The numeric vector zeta, computed as C %*% 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 CombTest object

...

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 CovTest object

...

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 must be used to indicate group sizes.

nv

(Optional) A vector indicating group sizes, needed when X is a combined matrix or for multiple groups.

C

A hypothesis matrix specifying the null hypothesis. Optional if hypothesis is provided.

Xi

A numeric vector specifying the expected values of the contrasts under the null hypothesis. Optional if hypothesis is provided.

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:

  • "equal-correlated" — equal correlation matrices

  • "uncorrelated" — test if variables are uncorrelated (single group only)

If C and Xi are provided, this can be set to NULL.

method

Character string indicating the resampling method to use. One of "BT" (bootstrap), "MC" (Monte Carlo), or "TAY" (Taylor approximation).

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 "banded" and "banded-toeplitz" structures, with default NA.

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 must be used to indicate group sizes.

nv

(Optional) A vector indicating group sizes, needed when X is a combined matrix or for multiple groups.

C

(Optional) A user-defined contrast matrix for testing custom hypotheses. Must match dimensions with Xi.

Xi

(Optional) A numeric vector used in combination with C to specify a custom hypothesis.

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:

  • "equal" — equal covariance matrices

  • "equal-trace" — equal traces across groups

  • "equal-diagonals" — equal variances across groups

  • "given-trace" — test against a given trace (single group only)

  • "given-matrix" — test against a given covariance matrix (single group only)

  • "uncorrelated" — test if variables are uncorrelated (single group only)

If C and Xi are provided, this can be set to NULL.

A

Optional scalar or matrix to define the hypothesis value when hypothesis is "given-trace" (scalar) or "given-matrix" (matrix). Ignored for other hypotheses.

method

A character indicating the resampling method: "BT" (Bootstrap) or "MC" (Monte Carlo).

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

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

mirror server hosted at Truenetwork, Russian Federation.