corrkit

Correlations that say what they show

corrkit hex logo

Documentation Get started GitHub

A correlation is one number, but which one, computed how, tested against what? corrkit computes nothing new: every coefficient, p-value and confidence interval comes from a validated engine (stats, ppcor, psych, correlation). On top of them it adds one way of working: one computing function, raw p-values by default and an explicit family when they are adjusted, a dedicated reading of binary variables, and heatmaps, forest plots and gt tables whose subtitles and captions state the method, the engine, the formula and how to read the result.

The notation follows Makowski et al. (2020), Methods and algorithms for correlation analysis in R, and is typeset in the figures (rs, rxy.z, rrb).

Installation

# install.packages("remotes")
remotes::install_github("Clement-Poupelin/corrkit")

# recommended engines and features
install.packages(c("ppcor", "psych", "correlation", "effectsize", "ggtext"))

What it does

Family Main functions Purpose
Compute cor_compute(), partial_cor_test() every pair of a set of variables (matrix), predictors × outcomes (cross) or one pair; simple or partial; Pearson, Spearman, Kendall and robust coefficients
Explore print(), summary(), as.matrix(), as.data.frame() the coefficients and their stars, the settings of the analysis, the strongest pairs, the numbers
Multiple testing p_adjust, adjust_by raw p-values by default; on request an adjustment over a named family (all pairs, the predictors of each outcome, the outcomes of each predictor)
Figures plot(type = "heatmap" / "forest" / "scatter"), plot_cor_heatmap(), plot_cor_forest(), plot_cor_pair() annotated heatmap, each coefficient with its confidence interval, the scatter or added-variable plot of one pair
Tables tbl_cor(layout = "matrix" / "wide" / "long") gt tables with the colour scale of the heatmaps, confidence intervals and source notes
Binary variables cor_binary_effects(), tbl_cor_binary(), cor_binary_note() separate blocks in every output, rank-biserial correlation and mean difference to report, reading note in English or French
Style theme_pub(), COR_PAL, p_to_stars() publication theme, diverging palette, significance stars

Example

library(corrkit)
d   <- simulate_cor_data(200)            # biomarkers, scores and covariates of known structure
lab <- attr(d, "labels")

# every pair of a set of variables
cm <- cor_compute(d, c("CRP", "IL6", "BDNF", "NfL", "depression", "fatigue", "BIN_CRP"),
                  labels = lab)
summary(cm)
plot(cm)                                 # annotated heatmap
tbl_cor(cm, layout = "long")             # one row per pair: n, coefficient, CI, p

# biomarkers x scores, adjusted for age and sex, BH over the biomarkers of each score
cc <- cor_compute(d, x = c("CRP", "IL6", "NfL", "BIN_CRP"), y = c("depression", "fatigue", "cognition"),
                  covariates = c("age", "sex"), p_adjust = "BH", adjust_by = "y", labels = lab)
plot(cc, type = "forest")                # each partial coefficient with its CI
plot(cc, type = "scatter", pair = c("NfL", "cognition"))

# what to report for a binary biomarker instead of its correlation
tbl_cor_binary(cor_binary_effects(cc))

The rendered figures and tables are in the articles of the documentation: Getting started, Full analysis of a matrix, Cross and partial correlations and Binary variables.

Tutorials

Each tutorial runs on the simulated data simulate_cor_data() shipped with the package, with all outputs and figures. The tutorials are written in French.

Getting started

cor_compute(), what the result contains, summary() and the correlation matrix.

Full analysis of a matrix

Every output (heatmap, forest plot, scatter, tables), their options, the engines and the typesetting of the formulas.

Multiple-testing corrections

Why raw p-values by default, FWER and FDR, the six methods of p.adjust(), a simulation of true and false positives, choosing the family.

Comparing correlation coefficients

Pearson, Spearman, Kendall and robust coefficients, in theory and on six simulated situations: outliers, heavy tails, non-monotone relations.

Cross and partial correlations

Predictors × outcomes, adjustment for covariates, added-variable plots, ppcor / residuals / lm() equivalences.

Binary variables

Point-biserial and rank-biserial correlations, why a cut biomarker correlates less, what to report instead.

Function reference

Every function, its arguments and runnable examples, grouped by family.

Companion packages

vernissage describes and draws clinical cohorts (overview tables, distributions, visits, radar and forest plots); lodestar handles limits of detection and cut-offs, the usual source of the binary biomarkers that corrkit treats apart.