matrixCorr

CRAN downloads

matrixCorr computes correlation and related association matrices from small to high-dimensional data using simple, consistent functions and sensible defaults. It includes shrinkage and robust options for noisy or p >= n settings, plus convenient print/plot/summary methods. Performance-critical paths are implemented in C++ with BLAS/OpenMP and memory-aware symmetric updates. The API accepts base matrices and data frames and returns standard R objects via a consistent S3 interface.

Contributions from other researchers who want to add new correlation methods are very welcome. A central goal of matrixCorr is to keep efficient correlation and agreement estimation in one package with a common interface and consistent outputs, so methods can be extended, compared, and used without repeated translation across packages.

Supported measures include Pearson, Spearman, Kendall, distance correlation, partial correlation, robust biweight mid-correlation, percentage bend, Winsorized, skipped correlation, and latent categorical/ordinal correlations (tetrachoric, polychoric, polyserial, and biserial), plus repeated-measures correlation (rmcorr()); agreement tools cover Bland-Altman (two-method and repeated-measures), Lin’s concordance correlation coefficient (including repeated-measures LMM/REML extensions), and intraclass correlation for both wide and repeated-measures designs.

Features

High-performance C++ backend using Rcpp
General correlations such as pearson_corr(), spearman_rho(), kendall_tau()
Robust correlation metrics (bicor(), pbcor(), wincor(), skipped_corr())
Distance correlation (dcor())
Partial correlation (pcorr())
Latent categorical/ordinal correlations (tetrachoric(), polychoric(), polyserial(), biserial())
Repeated-measures correlation (rmcorr())
Shrinkage for \(p >> n\) (shrinkage_corr())
Agreement metrics
- Bland-Altman (two-method ba() and repeated-measures ba_rm()),
- Lin’s concordance correlation coefficient (pairwise ccc(), repeated-measures LMM/REML ccc_rm_reml() and non-parametric ccc_rm_ustat()),
- Intraclass correlation (wide-data icc() with pairwise and overall scope, repeated-measures REML icc_rm_reml())
Interactive Shiny viewers for matrix-style outputs with a dedicated repeated-measures correlation viewer (view_rmcorr_shiny())

Installation

# Install from CRAN
install.packages("matrixCorr")

# Development version from GitHub
# install.packages("remotes")
remotes::install_github("Prof-ThiagoOliveira/matrixCorr")

Quick start

Wide-data correlation workflow

library(matrixCorr)

set.seed(1)
X <- as.data.frame(matrix(rnorm(300 * 6), ncol = 6))
names(X) <- paste0("V", 1:6)

R_pear <- pearson_corr(X, ci = TRUE)
R_bicor <- bicor(X)

print(R_pear, digits = 2)
#> Pearson correlation matrix
#>   method      : pearson
#>   dimensions  : 6 x 6
#>   ci          : yes
#> 
#>       V1    V2    V3    V4    V5    V6
#> V1  1.00  0.02  0.04 -0.02 -0.07  0.01
#> V2  0.02  1.00  0.04  0.03 -0.05  0.13
#> V3  0.04  0.04  1.00 -0.06  0.08 -0.14
#> V4 -0.02  0.03 -0.06  1.00  0.07  0.03
#> V5 -0.07 -0.05  0.08  0.07  1.00  0.04
#> V6  0.01  0.13 -0.14  0.03  0.04  1.00
summary(R_pear)
#> Pearson correlation summary
#>   method      : pearson
#>   dimensions  : 6 x 6
#>   pairs       : 15
#>   n_complete  : 300
#>   estimate    : -0.1410 to 0.1272
#>   most_negative: V3-V6 (-0.1410)
#>   most_positive: V2-V6 (0.1272)
#>   ci          : 95%
#>   ci_method   : fisher_z
#>   ci_width    : 0.222 to 0.226
#>   cross_zero  : 13 pair(s)
#> 
#> Strongest pairs by |estimate|
#> 
#>  item1 item2 estimate n_complete lwr    upr   
#>  V3    V6    -0.1410  300        -0.250 -0.028
#>  V2    V6     0.1272  300         0.014  0.237
#>  V3    V5     0.0776  300        -0.036  0.189
#>  V4    V5     0.0724  300        -0.041  0.184
#>  V1    V5    -0.0650  300        -0.177  0.049
#> ... 10 more rows not shown (omitted)
#> Use as.data.frame()/tidy()/as.matrix() to inspect the full result.
plot(R_bicor)

The same matrix-style workflow extends to Spearman, Kendall, distance correlation, partial correlation, shrinkage correlation, latent correlation, and the robust estimators pbcor(), wincor(), and skipped_corr().

Agreement and repeated-measures workflow

set.seed(6)
S <- 24
Tm <- 4
id <- factor(rep(seq_len(S), each = 2 * Tm))
method <- factor(rep(rep(c("A", "B"), each = Tm), times = S))
time <- rep(rep(seq_len(Tm), times = 2), times = S)

u <- rnorm(S, 0, 0.9)[as.integer(id)]
um <- rnorm(S * 2, 0, 0.25)
um <- um[(as.integer(id) - 1L) * 2L + as.integer(method)]
y <- u + um + (method == "B") * 0.2 + rnorm(length(id), 0, 0.35)

dat_rm <- data.frame(y, id, method, time)

fit_ccc_rm <- ccc_rm_reml(
  dat_rm,
  response = "y",
  subject = "id",
  method = "method",
  time = "time"
)

summary(fit_ccc_rm)
#> 
#> Repeated-measures concordance (REML)
#> 
#> Concordance estimates
#> 
#>  item1 item2 estimate n_subjects n_obs SB     se_ccc
#>  A     B     0.8996   24         96    0.0554 0.0184
#> 
#> Variance components
#> 
#>  sigma2_subject sigma2_subject_method sigma2_subject_time sigma2_error
#>  0.7941         0                     0                   0.1329      
#> 
#> AR(1) diagnostics
#> 
#>  ar1_rho ar1_rho_lag1 ar1_rho_mom ar1_pairs ar1_pval use_ar1 ar1_recommend
#>  0.0179  0.0179       0.0179      144       0.8298   FALSE   FALSE

Agreement and reliability methods use the same general inspection pattern, but they target different quantities. The package includes Bland-Altman analysis, concordance correlation, and intraclass correlation for both wide and repeated-measures designs.

Vignettes

The package documentation is organised as a set of workflow vignettes. The README is intentionally brief; the vignettes are the main user guide.

Start here:

vignette("v01-matrixCorr-introduction", package = "matrixCorr") introduces the package structure, common object behaviour, and shared display conventions.
vignette("v02-wide-correlation-workflows", package = "matrixCorr") covers Pearson, Spearman, Kendall, distance correlation, and the general wide-data matrix workflow.
vignette("v03-robust-and-highdim-correlation", package = "matrixCorr") covers robust estimators, shrinkage, and high-dimensional settings.
vignette("v04-latent-and-mixed-scale-correlation", package = "matrixCorr") covers tetrachoric, polychoric, polyserial, and biserial correlation.
vignette("v05-agreement-and-icc-wide", package = "matrixCorr") covers Bland-Altman analysis, concordance, and intraclass correlation for wide data.
vignette("v06-repeated-measures-workflows", package = "matrixCorr") covers repeated-measures correlation, repeated agreement, and repeated reliability workflows.

If you want a compact overview of the available estimators, start with the introduction vignette and then move to the workflow family that matches your data layout and scientific question.

Contributing

Issues and pull requests are welcome. Please see CONTRIBUTING.md for guidelines and cran-comments.md/DESCRIPTION for package metadata.

License

MIT Thiago de Paula Oliveira

See inst/LICENSE for the full MIT license text.