Package {moderncor}

Type: Package
Title: Unified Interface for Modern and Classical Correlation Coefficients
Version: 0.2.0
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().
License: GPL-3
URL: https://github.com/ToshihiroIguchi/moderncor
BugReports: https://github.com/ToshihiroIguchi/moderncor/issues
Encoding: UTF-8
Imports: stats, energy, XICOR
Suggests: minerva, Hmisc, dHSIC, infotheo, WRS2, psych, ppcor, Ball, TauStar, DescTools, testthat (≥ 3.0.0), knitr, rmarkdown
Config/testthat/edition: 3
VignetteBuilder: knitr
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-06-20 11:46:22 UTC; toshi
Author: Toshihiro Iguchi [aut, cre]
Maintainer: Toshihiro Iguchi <toshihiro.iguchi.github@gmail.com>
Repository: CRAN
Date/Publication: 2026-06-24 09:50:02 UTC

moderncor: Unified Interface for Modern and Classical Correlation Coefficients

Description

The moderncor package provides a single, unified interface to compute a wide range of classical and modern correlation and association measures.

Author(s)

Maintainer: Toshihiro Iguchi toshihiro.iguchi.github@gmail.com

Authors:

See Also

Useful links:

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()

Check if a suggested package is available

Description

Check if a suggested package is available

Usage

check_suggested(pkg, method)

Arguments

pkg

The package name.

method

The method requesting the package.

Compute Ball Correlation

Description

Compute Ball Correlation

Usage

compute_ball(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to Ball::bcov.test or Ball::bcor.

Value

A list of correlation results.

Compute Biweight Midcorrelation

Description

Compute Biweight Midcorrelation

Usage

compute_biweight(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis ("two.sided", "greater", "less").

p_value

Logical: whether to compute p-value.

...

Additional arguments (currently unused).

Value

A list of correlation results.

Compute Distance Correlation (dCor)

Description

Compute Distance Correlation (dCor)

Usage

compute_dcor(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to energy::dcor.test or energy::dcor.

Value

A list of correlation results.

Compute Hoeffding's D

Description

Compute Hoeffding's D

Usage

compute_hoeffding(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments.

Value

A list of correlation results.

Compute Hilbert-Schmidt Independence Criterion (HSIC)

Description

Compute Hilbert-Schmidt Independence Criterion (HSIC)

Usage

compute_hsic(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to dHSIC::dhsic.test or dHSIC::dhsic.

Value

A list of correlation results.

Compute Kendall rank correlation coefficient

Description

Compute Kendall rank correlation coefficient

Usage

compute_kendall(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis.

p_value

Logical: whether to compute p-value.

...

Additional arguments.

Value

A list of correlation results.

Compute correlation matrix for all variable pairs

Description

Compute correlation matrix for all variable pairs

Usage

compute_matrix(
  mat,
  z = NULL,
  method,
  use,
  alternative,
  p_value,
  call,
  method_partial = "pearson",
  ...
)

Arguments

mat

Numeric matrix.

z

Numeric vector, matrix, or data.frame representing control variables.

method

Character: correlation method.

use

Character: missing value treatment.

alternative

Character: alternative hypothesis.

p_value

Logical: whether to compute p-values.

call

The original function call.

method_partial

Character: correlation method to use for partial/semi-partial.

...

Additional arguments.

Value

A moderncor object for matrix input.

Compute categorical correlation matrix for all variable pairs

Description

Compute categorical correlation matrix for all variable pairs

Usage

compute_matrix_cat(df, method, use, call, ...)

Compute Maximal Information Coefficient (MIC)

Description

Compute Maximal Information Coefficient (MIC)

Usage

compute_mic(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value via permutation.

...

Additional arguments passed to minerva::mine.

Value

A list of correlation results.

Compute Mutual Information

Description

Compute Mutual Information

Usage

compute_mutual_info(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value via permutation.

...

Additional arguments passed to infotheo::mutinformation or discretization.

Value

A list of correlation results.

Dispatch to the appropriate pair-wise compute function

Description

Dispatch to the appropriate pair-wise compute function

Usage

compute_pair(
  x,
  y,
  z = NULL,
  method,
  alternative,
  p_value,
  method_partial = "pearson",
  ...
)

Arguments

x

Numeric vector.

y

Numeric vector.

z

Numeric vector, matrix, or data.frame representing control variables.

method

Character: correlation method.

alternative

Character: alternative hypothesis.

p_value

Logical: whether to calculate p-value.

method_partial

Character: correlation method to use for partial/semi-partial.

...

Additional arguments.

Value

A list of correlation results.

Dispatch to the appropriate pair-wise compute function for categorical variables

Description

Dispatch to the appropriate pair-wise compute function for categorical variables

Usage

compute_pair_cat(x, y, method, ...)

Compute Partial Correlation

Description

Compute Partial Correlation

Usage

compute_partial(
  x,
  y,
  z,
  method_partial = "pearson",
  alternative = "two.sided",
  p_value = TRUE,
  ...
)

Arguments

x

Numeric vector.

y

Numeric vector.

z

Numeric vector, matrix, or data.frame representing control variables.

method_partial

Character: correlation method to use ("pearson", "spearman", "kendall").

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to ppcor::pcor.test.

Value

A list of correlation results.

Compute Pearson correlation coefficient

Description

Compute Pearson correlation coefficient

Usage

compute_pearson(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis.

p_value

Logical: whether to compute p-value.

...

Additional arguments.

Value

A list of correlation results.

Compute Percentage Bend Correlation

Description

Compute Percentage Bend Correlation

Usage

compute_percentage_bend(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to WRS2::pbcor.

Value

A list of correlation results.

Compute Polychoric Correlation

Description

Compute Polychoric Correlation

Usage

compute_polychoric(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric/factor vector.

y

Numeric/factor vector.

alternative

Character: alternative hypothesis (ignored).

p_value

Logical: whether to compute p-value (not supported for this method).

...

Additional arguments passed to psych::polychoric.

Value

A list of correlation results.

Compute Semi-partial Correlation

Description

Compute Semi-partial Correlation

Usage

compute_semi_partial(
  x,
  y,
  z,
  method_partial = "pearson",
  alternative = "two.sided",
  p_value = TRUE,
  ...
)

Arguments

x

Numeric vector.

y

Numeric vector.

z

Numeric vector, matrix, or data.frame representing control variables.

method_partial

Character: correlation method to use ("pearson", "spearman", "kendall").

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to ppcor::spcor.test.

Value

A list of correlation results.

Compute Spearman rank correlation coefficient

Description

Compute Spearman rank correlation coefficient

Usage

compute_spearman(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis.

p_value

Logical: whether to compute p-value.

...

Additional arguments.

Value

A list of correlation results.

Compute Bergsma-Dassios Tau* Correlation

Description

Compute Bergsma-Dassios Tau* Correlation

Usage

compute_tau_star(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to TauStar::tauStarTest.

Value

A list of correlation results.

Compute Tetrachoric Correlation

Description

Compute Tetrachoric Correlation

Usage

compute_tetrachoric(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric/factor vector.

y

Numeric/factor vector.

alternative

Character: alternative hypothesis (ignored).

p_value

Logical: whether to compute p-value (not supported for this method).

...

Additional arguments passed to psych::tetrachoric.

Value

A list of correlation results.

Compute Winsorized Correlation

Description

Compute Winsorized Correlation

Usage

compute_winsorized(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to WRS2::wincor.

Value

A list of correlation results.

Compute Chatterjee's Xi Correlation

Description

Compute Chatterjee's Xi Correlation

Usage

compute_xi(x, y, alternative = "two.sided", p_value = TRUE, ...)

Arguments

x

Numeric vector.

y

Numeric vector.

alternative

Character: alternative hypothesis (ignored with warning if not "two.sided").

p_value

Logical: whether to compute p-value.

...

Additional arguments passed to XICOR::xicor.

Value

A list of correlation results.

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")

Information about categorical association methods

Description

Information about categorical association methods

Usage

method_info_cat(method)

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\sqrt{(n - 2) / (1 - r^2)} on n - 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".

Validate and normalize input for moderncor

Description

Validate and normalize input for moderncor

Usage

validate_input(x, y, z = NULL, method, use)

Arguments

x

A numeric vector, matrix, or data.frame.

y

A numeric vector, or NULL.

method

Character: the correlation method.

use

Character: how to handle missing values.

Value

A list containing the normalized data and input type.

Validate and normalize input for moderncor_cat

Description

Validate and normalize input for moderncor_cat

Usage

validate_input_cat(x, y, use)