Build a Mixed-Type Correlation Matrix — smart

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,
  bootstrap = "auto",
  n_boot = 500,
  n_perm = 500,
  seed = NULL,
  verbose = TRUE
)

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.
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 Theil's U 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.
verbose: Logical. If TRUE (default), prints progress information. Set to FALSE for silent operation (useful inside scripts).

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

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. This is expected and reflects the heterogeneous nature of the data.

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.

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.0000  0.019  0.028 -0.0087
#> coninc  0.0190  1.000  0.450 -0.1000
#> degree  0.0280  0.450  1.000  0.0150
#> sex    -0.0087 -0.100  0.015  1.0000
#> ── Methods used ──
#> 
#>        age coninc degree sex
#> age    Pr  Pr     Sp     PB 
#> coninc Pr  Pr     Sp     PB 
#> degree Sp  Sp     Kn     RB 
#> sex    PB  PB     RB     Ph 
#> 
#> ℹ Legend:
#> "Pr" = Pearson Correlation
#> "Sp" = Spearman Rank Correlation
#> "PB" = Point-Biserial Correlation (= Pearson)
#> "Kn" = Kendall's Tau-b
#> "RB" = Rank-Biserial Correlation
#> "Ph" = Phi Coefficient (= Pearson for 0/1)

# 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.019  0.028
#> coninc 0.019  1.000  0.450
#> degree 0.028  0.450  1.000
#> ── Methods used ──
#> 
#>        age coninc degree
#> age    Pr  Pr     Sp    
#> coninc Pr  Pr     Sp    
#> degree Sp  Sp     Kn    
#> 
#> ℹ Legend:
#> "Pr" = Pearson Correlation
#> "Sp" = Spearman Rank Correlation
#> "Kn" = Kendall's Tau-b