comets (version 0.2-2)

gcm: Generalised covariance measure test

Description

Generalised covariance measure test

Usage

gcm(
  Y,
  X,
  Z,
  alternative = c("two.sided", "less", "greater"),
  reg_YonZ = "rf",
  reg_XonZ = "rf",
  args_YonZ = NULL,
  args_XonZ = NULL,
  type = c("quadratic", "max", "scalar"),
  B = 499L,
  coin = FALSE,
  cointrol = list(distribution = "asymptotic"),
  return_fitted_models = FALSE,
  multivariate = c("none", "YonZ", "XonZ", "both"),
  ...
)

Value

Object of class 'gcm' and 'htest' with the following components:

statistic

The value of the test statistic.

p.value

The p-value for the hypothesis

parameter

In case X is multidimensional, this is the degrees of freedom used for the chi-squared test.

hypothesis

String specifying the null hypothesis.

null.value

String specifying the null hypothesis.

method

The string "Generalised covariance measure test".

data.name

A character string giving the name(s) of the data.

rY

Residuals for the Y on Z regression.

rX

Residuals for the X on Z regression.

models

List of fitted regressions if return_fitted_models is TRUE.

Arguments

Y

Vector or matrix of response values.

X

Matrix or data.frame of covariates.

Z

Matrix or data.frame of covariates.

alternative

A character string specifying the alternative hypothesis, must be one of "two.sided" (default), "greater" or "less". Only applies if type = "quadratic" and Y and X are one-dimensional.

reg_YonZ

Character string or function specifying the regression for Y on Z. See ?regressions for more detail.

reg_XonZ

Character string or function specifying the regression for X on Z. See ?regressions for more detail.

args_YonZ

A list of named arguments passed to reg_YonZ.

args_XonZ

A list of named arguments passed to reg_XonZ.

type

Type of test statistic, either "quadratic" (default) or "max". If "max" is specified, the p-value is computed based on a bootstrap approximation of the null distribution with B samples.

B

Number of bootstrap samples. Only applies if type = "max" is used.

coin

Logical; whether or not to use the coin package for computing the test statistic and p-value. The coin package computes variances with n - 1 degrees of freedom. The default is TRUE.

cointrol

List; further arguments passed to independence_test.

return_fitted_models

Logical; whether to return the fitted regressions (default is FALSE).

multivariate

Character; specifying which regression can handle multivariate outcomes ("none", "YonZ", "XonZ", or "both"). If "none", then the regression is run using each column in Y (or X) as the response.

...

Additional arguments passed to reg_YonZ.

Details

The generalised covariance measure test tests whether the conditional covariance of Y and X given Z is zero. This implementation also supports the TRAM-GCM test for survival responses, which tests whether the expected conditional covariance between the score residuals of a Y on Z regression and X is zero.

References

Rajen D. Shah, Jonas Peters "The hardness of conditional independence testing and the generalised covariance measure," The Annals of Statistics, 48(3), 1514-1538. tools:::Rd_expr_doi("10.1214/19-aos1857")

Kook, L., Saengkyongam, S., Lundborg, A. R., Hothorn, T., & Peters, J. (2025). Model-based causal feature selection for general response types. Journal of the American Statistical Association, 120(550), 1090-1101. tools:::Rd_expr_doi("10.1080/01621459.2024.2395588")

Examples

n <- 1e2
X <- matrix(rnorm(2 * n), ncol = 2)
colnames(X) <- c("X1", "X2")
Z <- matrix(rnorm(2 * n), ncol = 2)
colnames(Z) <- c("Z1", "Z2")
Y <- X[, 2]^2 + Z[, 2] + rnorm(n)
(gcm1 <- gcm(Y, X, Z))