Package 'moderncor'

Title: Unified Interface for Modern and Classical Correlation Coefficients
Description: Provides a single unified interface for computing a wide variety of classical and modern correlation and association measures. Continuous methods include classical correlations (Pearson, Spearman, Kendall), modern dependence measures (distance correlation, maximal information coefficient, Hilbert-Schmidt independence criterion, Chatterjee's xi, Hoeffding's D, mutual information), robust correlations (biweight midcorrelation, percentage bend, Winsorized), ordinal correlations (polychoric, tetrachoric), partial and semi-partial correlations, and nonparametric measures (ball correlation, Bergsma-Dassios tau*). Categorical association measures (Cramer's V, phi coefficient, Goodman-Kruskal gamma, Somers' D, contingency coefficient, Tschuprow's T) are available via moderncor_cat().
Authors: Toshihiro Iguchi [aut, cre]
Maintainer: Toshihiro Iguchi <[email protected]>
License: GPL-3
Version: 0.2.0
Built: 2026-06-24 13:30:06 UTC
Source: https://github.com/cran/moderncor

Help Index

Convert moderncor object to a data.frame

Description

Convert moderncor object to a data.frame

Usage

## S3 method for class 'moderncor'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x

An object of class "moderncor".
row.names

Ignored.
optional

Ignored.
...

Additional arguments.

Value

A data.frame.

Convert moderncor_cat object to a data.frame

Description

Convert moderncor_cat object to a data.frame

Usage

## S3 method for class 'moderncor_cat'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x

An object of class "moderncor_cat".
row.names

Ignored.
optional

Ignored.
...

Additional arguments.

Value

A data.frame.

List all available correlation methods

Description

List all available correlation methods

Usage

available_methods()

Value

A data.frame with method names, labels, and package requirements.

Examples

available_methods()

List all available categorical association methods

Description

List all available categorical association methods

Usage

available_methods_cat()

Value

A data.frame with method names, labels, package requirements, and type.

Examples

available_methods_cat()

Get detailed information about a specific correlation method

Description

Get detailed information about a specific correlation method

Usage

method_info(method)

Arguments

method

Character: the method name.

Value

A list with method details.

Examples

method_info("pearson")

Compute classical and modern correlation coefficients

Description

This function provides a single unified interface to compute a wide range of classical and modern correlation and association measures.

Usage

moderncor(
  x,
  y = NULL,
  z = NULL,
  method = c("pearson", "spearman", "kendall", "dcor", "mic", "hsic", "xi", "hoeffding",
    "mutual_info", "biweight", "percentage_bend", "winsorized", "polychoric",
    "tetrachoric", "partial", "semi_partial", "ball", "tau_star"),
  alternative = c("two.sided", "less", "greater"),
  p_value = TRUE,
  use = c("complete.obs", "everything", "pairwise.complete.obs"),
  method_partial = c("pearson", "spearman", "kendall"),
  ...
)

Arguments

x

A numeric vector, matrix, or data.frame.
y

A numeric vector, or NULL if x is a matrix or data.frame.
z

A numeric vector, matrix, or data.frame representing control variables. Required for partial and semi-partial correlations.
method

Character: the association method to compute. Must be one of:

  • "pearson": Pearson product-moment correlation (linear).

  • "spearman": Spearman rank correlation (monotonic).

  • "kendall": Kendall rank correlation (monotonic).

  • "dcor": Distance correlation (general dependence).

  • "mic": Maximal Information Coefficient (general dependence).

  • "hsic": Hilbert-Schmidt Independence Criterion (general dependence).

  • "xi": Chatterjee's Xi correlation (functional dependence).

  • "hoeffding": Hoeffding's D statistic (general dependence).

  • "mutual_info": Mutual Information (information-theoretic dependence).

  • "biweight": Biweight midcorrelation (robust).

  • "percentage_bend": Percentage bend correlation (robust).

  • "winsorized": Winsorized correlation (robust).

  • "polychoric": Polychoric correlation (ordinal).

  • "tetrachoric": Tetrachoric correlation (ordinal).

  • "partial": Partial correlation controlling for variables in z.

  • "semi_partial": Semi-partial correlation controlling for variables in z.

  • "ball": Ball correlation (general dependence).

  • "tau_star": Bergsma-Dassios Tau* (general dependence).

alternative

Character: alternative hypothesis. Must be one of "two.sided", "less", or "greater". Note that this is only supported for classic methods (Pearson, Spearman, Kendall). For modern and general dependence measures, it is ignored with a warning.
p_value

Logical: whether to compute the p-value. Default is TRUE. For some modern methods (e.g. MIC, HSIC, Mutual Information), computing p-values can be slow because they rely on permutation tests. Set to FALSE for fast computation of estimates only.
use

Character: how to handle missing values. Must be one of:

  • "complete.obs": Remove observations with missing values (default).

  • "everything": Keep missing values (results in NA if present).

  • "pairwise.complete.obs": Compute correlations pairwise using all complete observations for each pair (only applicable for matrix/data.frame inputs).

method_partial

Character: correlation method to use for partial/semi-partial. Must be one of "pearson", "spearman", or "kendall".
...

Additional arguments passed to the underlying compute functions. For example, B for the number of permutations in MIC or Mutual Information, or R for distance correlation.

Details

Most methods delegate both the estimate and the p-value to the original implementing package. The biweight midcorrelation is an exception: because no CRAN package provides it (the reference implementation lives in the Bioconductor-only WGCNA package), moderncor computes the estimate from the standard formula (Wilcox 2012) and approximates its p-value with a Student's t statistic, t=r(n−2)/(1−r2)t = r\sqrt{(n - 2) / (1 - r^2)} on n−2n - 2 degrees of freedom (the same approximation used by WGCNA::bicorAndPvalue). This p-value is therefore approximate and should be interpreted with care for small samples or heavily contaminated data.

Value

An object of class "moderncor".

References

Wilcox, R. R. (2012). Introduction to Robust Estimation and Hypothesis Testing (3rd ed.). Academic Press.

Examples

# Generate some non-linear data (parabolic relationship)
set.seed(123)
x <- runif(100, -1, 1)
y <- x^2 + rnorm(100, sd = 0.1)

# Pearson correlation (close to 0 due to non-linearity)
moderncor(x, y, method = "pearson")

# Distance correlation (captures non-linear association)
moderncor(x, y, method = "dcor")

# Chatterjee's Xi correlation
moderncor(x, y, method = "xi")

# Compute correlation matrix for iris dataset (first 4 columns)
moderncor(iris[, 1:4], method = "pearson")

Compute correlation/association coefficients for categorical variables

Description

Compute correlation/association coefficients for categorical variables

Usage

moderncor_cat(
  x,
  y = NULL,
  method = c("cramers_v", "phi", "gamma", "somers_d", "contingency", "tschuprow"),
  use = c("complete.obs", "everything", "pairwise.complete.obs"),
  ...
)

Arguments

x

A factor vector, character vector, numeric vector (treated as categorical), data.frame, or matrix.
y

A factor vector, character vector, numeric vector (treated as categorical), or NULL.
method

Character: the categorical association method to compute. Must be one of:

  • "cramers_v": Cramer's V.

  • "phi": Phi Coefficient.

  • "gamma": Goodman-Kruskal Gamma (for ordinal factors).

  • "somers_d": Somers' D (for ordinal factors).

  • "contingency": Contingency Coefficient.

  • "tschuprow": Tschuprow's T.

use

Character: how to handle missing values. Must be one of: "complete.obs", "everything", or "pairwise.complete.obs".
...

Additional arguments passed to the underlying compute functions.

Value

An object of class "moderncor_cat".

Print a moderncor object

Description

Print a moderncor object

Usage

## S3 method for class 'moderncor'
print(x, digits = 4, ...)

Arguments

x

An object of class "moderncor".
digits

Integer: number of decimal places to print.
...

Additional arguments.

Value

The input object invisibly.

Print a moderncor_cat object

Description

Print a moderncor_cat object

Usage

## S3 method for class 'moderncor_cat'
print(x, digits = 4, ...)

Arguments

x

An object of class "moderncor_cat".
digits

Integer: number of decimal places to print.
...

Additional arguments.

Value

The input object invisibly.

Print a summary.moderncor object

Description

Print a summary.moderncor object

Usage

## S3 method for class 'summary.moderncor'
print(x, digits = 4, ...)

Arguments

x

An object of class "summary.moderncor".
digits

Integer: number of decimal places to print.
...

Additional arguments.

Value

The input object invisibly.

Print a summary.moderncor_cat object

Description

Print a summary.moderncor_cat object

Usage

## S3 method for class 'summary.moderncor_cat'
print(x, digits = 4, ...)

Arguments

x

An object of class "summary.moderncor_cat".
digits

Integer: number of decimal places to print.
...

Additional arguments.

Value

The input object invisibly.

Summarize a moderncor object

Description

Summarize a moderncor object

Usage

## S3 method for class 'moderncor'
summary(object, ...)

Arguments

object

An object of class "moderncor".
...

Additional arguments.

Value

An object of class "summary.moderncor".

Summarize a moderncor_cat object

Description

Summarize a moderncor_cat object

Usage

## S3 method for class 'moderncor_cat'
summary(object, ...)

Arguments

object

An object of class "moderncor_cat".
...

Additional arguments.

Value

An object of class "summary.moderncor_cat".