cdda.indep: Conditional Direction Dependence Analysis: Independence Properties

Description

cdda.indep evaluates asymmetries of predictor-error independence of competing conditional models (y ~ x * m vs. x ~ y * m with m being a continuous or categorical moderator).

print returns the output of standard linear model coefficients for competing target and alternative models.

plot returns graphs for results of cdda.indep.

summary returns test statistics from the cdda.indep class object.

Usage

cdda.indep(
  formula = NULL,
  pred = NULL,
  mod = NULL,
  modval = NULL,
  data = list(),
  hetero = FALSE,
  diff = FALSE,
  nlfun = NULL,
  hsic.method = "gamma",
  B = 200,
  boot.type = "perc",
  conf.level = 0.95,
  parallelize = FALSE,
  cores = 1,
  ...
)
# S3 method for cdda.indep
print(x, ...)
# S3 method for cdda.indep
plot(x = NULL, stat = NULL, ylim = NULL, ...)
# S3 method for cdda.indep
summary(
  object,
  nlfun = FALSE,
  hetero = FALSE,
  hsic = TRUE,
  hsic.diff = FALSE,
  dcor = TRUE,
  dcor.diff = FALSE,
  mi.diff = FALSE,
  ...
)

Value

An object of class dda.indep containing the results of independence tests of Conditional Direction Dependence Analysis.

An object of class cdda.indep with competing model coefficients.

Arguments

formula

Symbolic formula of the model to be tested or an lm object.

pred

A character indicating the variable name of the predictor which serves as the outcome in the alternative model.

mod

A character indicating the variable name of the moderator.

modval

Characters or a numeric sequence specifying the moderator values used in post-hoc probing. Possible characters include c("mean", "median", "JN").modval = "mean" tests the interaction effect at the moderator values M – 1SD, M, and M + 1SD; modval = "median" uses Q1, Md, and Q3. The Johnson-Neyman approach is applied when modval = "JN" with conditional effects being evaluated at the boundary values of the significance regions. When a numeric sequence is specified,the pick-a-point approach is used for the selected numeric values.

data

A required data frame containing the variables in the model.

hetero

A logical value indicating whether separate homoscedasticity tests should be returned when using summary, default is FALSE.

diff

A logical value indicating whether differences in HSIC, dCor, and MI values should be computed. Bootstrap confidence intervals are computed using B bootstrap samples.

nlfun

Determines handling of non-linear correlation tests depending on the function used:

For cdda.indep: Either a numeric value or a function of .Primitive type used for non-linear correlation tests. When numeric, the value is used in a power transformation.
For summary: A logical value indicating whether non-linear correlation tests should be returned in the output. Default is FALSE.

hsic.method

A character indicating the inference method for the Hilbert-Schmidt Independence Criterion. Must be one of the four specifications c("gamma", "eigenvalue", "boot", "permutation").hsic.method = "gamma" is the default.

B

Number of permutations for separate dCor tests and number of resamples when hsic.method = c("boot", "permutation") or diff = TRUE.

boot.type

A character indicating the type of bootstrap confidence intervals. Must be one of the two specifications c("perc", "bca"). boot.type = "perc" is the default.

conf.level

Confidence level for bootstrap confidence intervals.

parallelize

A logical value indicating whether bootstrapping is performed on multiple cores. Only used if diff = TRUE.

cores

A numeric value indicating the number of cores. Only used if parallelize = TRUE.

...

Additional arguments to be passed to the function.

x

An object of class cdda.indep when using print or plot.

stat

A character indicating the CDDA statistic to be plotted with the options c("hsic.diff", "dcor.diff", "mi.diff").

ylim

A numeric vector of length 2 indicating the y-axis limits if NULL, the function will set the limits automatically.

object

An object of class cdda.indep when using summary.

hsic

A logical value indicating whether deparate HSIC tests should be returned when using summary, default is TRUE.

hsic.diff

A logical value indicating whether HSIC difference statistics should be returned when using summary, default is FALSE.

dcor

A logical value indicating whether separate Distance Correlation (dCor) tests should be returned when using summary, default is TRUE.

dcor.diff

A logical value indicating whether dCor difference statistics should be returned when using summary, default is FALSE.

mi.diff

A logical value indicating whether Mutual Information (MI) difference statistics should be returned when using summary, default is FALSE.

References

Wiedermann, W., & von Eye, A. (2025). Direction Dependence Analysis: Foundations and Statistical Methods. Cambridge, UK: Cambridge University Press.

Examples

Run this code

set.seed(321)
n <- 700

## --- generate moderator

z <- sort(rnorm(n))
z1 <- z[z <= 0]
z2 <- z[z > 0]

## --- x -> y when z <= 0

x1 <- rchisq(length(z1), df = 4) - 4
e1 <- rchisq(length(z1), df = 3) - 3
y1 <- 0.5 * x1 + e1

## --- y -> x when m z > 0

y2 <- rchisq(length(z2), df = 4) - 4
e2 <- rchisq(length(z2), df = 3) - 3
x2 <- 0.25 * y2 + e2

y <- c(y1, y2); x <- c(x1, x2)

d <- data.frame(x, y, z)

m <- lm(y ~ x * z, data = d)


result <- cdda.indep(m,
                     pred = "x",
                     mod = "z",
                     modval = c(-1, 1),
                     data = d,
                     hetero = TRUE,
                     diff = TRUE,
                     parallelize = TRUE,
                     cores = 2,
                     nlfun = 2,
                     B = 2)
# Note: Only 2 bootstrap samples are created here to lower computation time


print(result)

plot(result, stat = "dcor.diff")

summary(result, hetero = FALSE)