Skip to contents

Build a Mixed-Type Correlation Matrix

Source: R/smart_cormat.R
smart_cormat.Rd

Runs smart_cor() on every pair of columns and records both the estimate and the method used for each pair.

Usage

smart_cormat(
  data,
  cols = NULL,
  types = NULL,
  assume_latent_normal = "auto",
  ordinal_threshold = 10,
  ignore_na = TRUE,
  conf_level = 0.95,
  alpha = 0.05,
  bootstrap = "auto",
  n_boot = 500,
  n_perm = 500,
  seed = NULL,
  polyserial_ml = FALSE,
  verbose = TRUE,
  nearPD = FALSE
)

Arguments

data

A data frame or tibble. All columns are used unless cols is specified.

cols

A character vector of column names to include. Default: all columns.

types

An optional named list mapping column names to types ("continuous", "count", "binary", "ordinal", "categorical"). Columns not listed are auto-detected.

assume_latent_normal

"auto" (default), logical, or NULL. Passed to each smart_cor() call. "auto" tests each pair individually via test_bivariate_normality(). NULL asks interactively once for all pairs.

ordinal_threshold

Integer passed to detect_type(). Default: 10.

ignore_na

Logical. If TRUE (default), missing values are handled pairwise (each pair uses its own complete observations). If FALSE, any pair with missing values fails; the failure is reported as a warning (when verbose = TRUE) and the cell is left NA.

conf_level

Numeric between 0 and 1. Confidence level passed to each smart_cor() call. Default: 0.95.

alpha

Significance level for the diagnostic tests, passed to each smart_cor() call. Default: 0.05.

bootstrap

Character or logical, passed to each smart_cor() call: "auto" (default), TRUE, or FALSE.

n_boot

Integer. Bootstrap replications per pair when bootstrapping. Default: 500.

n_perm

Integer. Permutation shuffles for the Theil's U and Freeman's theta p-values. Default: 500.

seed

Optional integer seed passed to each smart_cor() call; the global RNG state is saved and restored around seeded draws.

polyserial_ml

Logical, passed to each smart_cor() call. Default: FALSE; TRUE is recommended (see smart_cor()).

verbose

Logical. If TRUE (default), prints progress information. Set to FALSE for silent operation (useful inside scripts).

nearPD

Logical. If TRUE, adjust the completed correlation matrix with Matrix::nearPD(). Default: FALSE.

Value

An object of class "smartcormat": a list with elements:

correlations

Numeric matrix of correlation estimates.

methods

Character matrix of method codes used for each pair.

types

Named character vector of detected/specified variable types.

details

List of smart_cor() result objects (one per pair), without their diagnostics element.

original_correlations

Matrix before adjustment; present only when nearPD = TRUE.

nearPD

Adjustment diagnostics (normF, iterations, converged); present only when nearPD = TRUE.

Details

For each pair of columns, smart_cor() detects variable types and selects the appropriate method. The result is a symmetric matrix of correlation/association measure estimates annotated with the method used for each cell.

Since different methods are used for different pairs, the resulting matrix may not be positive semi-definite. With nearPD = TRUE, the completed matrix is adjusted using Matrix::nearPD(corr = TRUE). The returned correlations are then positive definite with diagonal 1. original_correlations retains the estimates before adjustment; methods, details, and tidy.smartcormat() still describe those original estimates and their inference. The adjustment does not refit the pairwise models. A matrix containing missing or infinite entries cannot be adjusted.

Diagonal cells hold 1 by definition; the methods matrix records for each diagonal cell the method that a self-pair of that type would get, so every cell of the matrix is labelled the same way: "pearson" for continuous and count variables, "phi", "tetrachoric", or "yules_q" for binary variables (under assume_latent_normal = "auto", TRUE, or FALSE), "polychoric" ("auto" or TRUE) or "kendall" (FALSE) for ordinal variables, and "cramers_v" for categorical variables.

The stored details omit each pair's diagnostics list to keep the object small; the summary fields outlier_flag, normality_p, latent_p, and linearity_p remain, so tidy.smartcormat() reports them.

Examples

path = system.file("extdata", "gss_2024_casestudy.csv", package = "smartcor")
gss = read.csv(path)

smart_cormat(
  gss[, c("age", "coninc", "degree", "sex")],
  assume_latent_normal = FALSE,
  verbose = FALSE
)
#> 
#> ── Smart Correlation Matrix ────────────────────────────────────────────────────
#> 
#> ── Variable types ──
#> 
#> age: "count"
#> coninc: "continuous"
#> degree: "ordinal"
#> sex: "binary"
#> 
#> ── Correlations ──
#> 
#>           age coninc degree    sex
#> age     1.000  0.037  0.021 -0.010
#> coninc  0.037  1.000  0.360 -0.130
#> degree  0.021  0.360  1.000  0.015
#> sex    -0.010 -0.130  0.015  1.000
#> ── Methods used ──
#> 
#>        age coninc degree sex
#> age    Pr  Sp     Kn     RB 
#> coninc Sp  Pr     Kn     RB 
#> degree Kn  Kn     Kn     RB 
#> sex    RB  RB     RB     YQ 
#> 
#> ℹ Legend:
#> "Pr" = Pearson Correlation
#> "Sp" = Spearman Rank Correlation
#> "Kn" = Kendall's Tau-b
#> "RB" = Rank-Biserial Correlation
#> "YQ" = Yule's Q

# Override a detected type when the study design requires it.
smart_cormat(
  gss[, c("age", "coninc", "degree")],
  types = list(age = "continuous", degree = "ordinal"),
  assume_latent_normal = FALSE,
  verbose = FALSE
)
#> 
#> ── Smart Correlation Matrix ────────────────────────────────────────────────────
#> 
#> ── Variable types ──
#> 
#> age: "continuous"
#> coninc: "continuous"
#> degree: "ordinal"
#> 
#> ── Correlations ──
#> 
#>          age coninc degree
#> age    1.000  0.037  0.021
#> coninc 0.037  1.000  0.360
#> degree 0.021  0.360  1.000
#> ── Methods used ──
#> 
#>        age coninc degree
#> age    Pr  Sp     Kn    
#> coninc Sp  Pr     Kn    
#> degree Kn  Kn     Kn    
#> 
#> ℹ Legend:
#> "Pr" = Pearson Correlation
#> "Sp" = Spearman Rank Correlation
#> "Kn" = Kendall's Tau-b