Correlation wheel plots with circlecorR

Motivation

A traditional correlation matrix carries a large amount of redundant information. For \(k\) variables it has \(k^2\) cells, but only \(k(k-1)/2\) of them are unique: the diagonal is all self-correlations (\(r = 1\)), the two triangles mirror each other, and large blocks of within-category correlations are often irrelevant, and contribute to reduced statistical power. As \(k\) grows, the interesting between-category relationships are buried in this redundancy and the figure becomes unreadable.

The correlation wheel was introduced by Gharibans et al in the first clinical paper to show that spatial dysrhythmias as measured on the body surface, correlated with gastroduodenal symptoms. The correlation wheel shows variables at the periphery of a circle, grouped by category, and only the correlations of interest are drawn as curved links coloured by the strength of their coefficient, and filtered based on custom statistical significance thresholds. circlecorR reproduces these features to generate a correlation wheel plot using standard patient-per-row type dataframes in R, with optionality to customise the grouping, colours, and statistics.

Since then, several notable papers in the field of gastric electrophysiology have leveraged these plots, including:

• Gharibans AA, Coleman TP, Mousa H, Kunkel DC. Spatial patterns from high-resolution electrogastrography correlate with severity of symptoms in patients with functional dyspepsia and gastroparesis. Clin Gastroenterol Hepatol. 2019 Dec;17(13):2668–77. DOI: 10.1016/j.cgh.2019.04.039
• Gharibans AA, Calder S, Varghese C, Waite S, Schamberg G, Daker C, et al. Gastric dysfunction in patients with chronic nausea and vomiting syndromes defined by a noninvasive gastric mapping device. Sci Transl Med. 2022 Sept 21;14(663):eabq3544. DOI: 10.1126/scitranslmed.abq3544
• Wang TH-H, Varghese C, Calder S, Gharibans A, Schamberg G, Bartlett A, et al. Long-term evaluation of gastric electrophysiology, symptoms and quality of life after pancreaticoduodenectomy. HPB (Oxford). 2025 Dec;27(12):1535–42. DOI: 10.1016/j.hpb.2025.09.003
• Xu W, Wang T, Foong D, Schamberg G, Evennett N, Beban G, et al. Characterization of gastric dysfunction after fundoplication using body surface gastric mapping. J Gastrointest Surg. 2024 Mar;28(3):236–45. DOI: 10.1016/j.gassur.2023.12.023
• Xu W, Gharibans AA, Calder S, Schamberg G, Walters A, Jang J, et al. Defining and phenotyping gastric abnormalities in long-term type 1 diabetes using a novel body surface gastric mapping device. Gastro Hep Adv. 2023 Aug 18;2(8):1120–32. DOI: 10.1016/j.gastha.2023.08.005

Installation

# install.packages("remotes")
remotes::install_github("kriz98/circlecorR", build_vignettes = TRUE)

(CRAN release pending.)

Dependencies (circlize and psych) install automatically with the command above.

Quick start: straight from your data

circlecorR is designed to work straight from a data frame – one row per subject and one column per variable – with no separate step to build correlation matrices yourself. Hand that data frame directly to corr_wheel() and it computes the correlations (and p-values) for you.

The only other thing you supply is groups: a named list mapping each category to its variables. This both selects which variables appear (any other columns, such as an ID, are ignored) and sets their order around the wheel.

In homage to Gharibans et al seminal paper, we use a synthetic gastro_symptoms dataset throughout this vignette (see ?gastro_symptoms for its exact shape). This synthetic example dataset is bundled with the package. Swap it for your own data frame (one row per subject) to use your own data.

groups <- list(
  Demographics = c("Age", "BMI"),
  Metrics      = c("Amplitude", "Fed-Fasted AR", "Frequency", "GA-RI"),
  Symptoms     = c("Nausea", "Early satiety", "Bloating",
                   "Upper GI pain", "Lower GI pain", "Heartburn"),
  Scores       = c("GCSI", "PAGI-SYM", "PAGI-QoL", "EQ-5D")
)

# `gastro_symptoms` is a synthetic per-row example dataset shipped with the package
head(gastro_symptoms[, 1:5])
#>   Age  BMI Amplitude Fed-Fasted AR Frequency
#> 1  74 41.0  30.26932     2.0004345  2.808546
#> 2  51 42.8  29.15670     0.7884043  1.760702
#> 3  59 36.2  29.73068     0.1899037  3.483917
#> 4  47 40.8  31.16330    -0.8294263  2.842009
#> 5  29 46.1  31.07111     0.9579552  4.015299
#> 6  50 36.4  29.86780    -2.0601868  1.179358

corr_wheel(
  gastro_symptoms,             # raw data: one row per subject
  groups      = groups,
  method      = "pearson",     # correlation method
  adjust      = "hochberg",    # multiple-comparison adjustment (see below)
  sig_level   = 0.05,          # hide links with adjusted p > 0.05
  r_threshold = 0.3,           # ...and links with |r| < 0.3
  r_limits    = c(-0.6, 0.6)
)

Hiding self- and within-category correlations

Two of the wheel’s most important features are that it never draws self-correlations (the diagonal) and, by default, hides within-category correlations (hide_within_group = TRUE). This removes the redundant parts of the matrix and leaves the between-category structure.

Crucially, this is carried through to the statistics. Multiple-comparison correction penalises you for the number of hypotheses tested. If self- and within-category correlations are never tested, they should not count towards that family. corr_wheel() therefore applies the adjustment over only the correlations it displays. Shrinking the family makes the correction less severe, thus improving power, while remaining statistically consistent with what is shown.

res <- corr_wheel(gastro_symptoms, groups = groups, adjust = "hochberg",
                  r_threshold = 0.3, r_limits = c(-0.6, 0.6))

k <- length(unlist(groups))
cat("Unique correlations in the full matrix:", k * (k - 1) / 2, "\n")
#> Unique correlations in the full matrix: 120
cat("Correlations actually tested (the family):", res$n_tests, "\n")
#> Correlations actually tested (the family): 92

Because the family is smaller, each raw p-value is corrected by a smaller factor. Taking Bonferroni for a transparent example, the same correlation is penalised by the number of tests in its family – here 92 rather than 120:

p_raw <- 5e-4                       # a raw p-value for one correlation
k_all <- k * (k - 1) / 2

cat("Bonferroni across the full matrix:", signif(p_raw * k_all, 3), "\n")
#> Bonferroni across the full matrix: 0.06
cat("Bonferroni across the family only:", signif(p_raw * res$n_tests, 3), "\n")
#> Bonferroni across the family only: 0.046

The step-up methods ("holm", "hochberg", "BH") behave the same way.

If you want the correlation and p-value matrices themselves, for a table, a report, or any other purpose – compute_correlations() is the same function corr_wheel() calls internally, available on its own:

cc <- compute_correlations(gastro_symptoms, method = "pearson")
str(cc)
#> List of 4
#>  $ r     : num [1:16, 1:16] 1 0.000715 -0.094705 -0.208429 -0.007022 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : chr [1:16] "Age" "BMI" "Amplitude" "Fed-Fasted AR" ...
#>   .. ..$ : chr [1:16] "Age" "BMI" "Amplitude" "Fed-Fasted AR" ...
#>  $ p     : num [1:16, 1:16] 0 0.9944 0.3486 0.0374 0.9447 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : chr [1:16] "Age" "BMI" "Amplitude" "Fed-Fasted AR" ...
#>   .. ..$ : chr [1:16] "Age" "BMI" "Amplitude" "Fed-Fasted AR" ...
#>  $ n     : num 100
#>  $ method: chr "pearson"
#>  - attr(*, "class")= chr "circlecor"

Customising the look

corr_wheel_schemes()
#> [1] "default"    "colorblind" "ocean"      "vivid"      "alimetry"

corr_wheel(gastro_symptoms, groups = groups, r_threshold = 0.3,
          r_limits = c(-0.6, 0.6), scheme = "colorblind")

corr_wheel(gastro_symptoms, groups = groups, r_threshold = 0.3,
          r_limits = c(-0.6, 0.6), scheme = "alimetry")

s <- corr_wheel_scheme("ocean")
s$palette[2] <- "grey96"
corr_wheel(gastro_symptoms, groups = groups, r_threshold = 0.3,
          r_limits = c(-0.6, 0.6), scheme = s)

corr_wheel(gastro_symptoms, groups = groups, r_threshold = 0.3,
          r_limits = c(-0.6, 0.6),
          scheme = list(colors = c("#7B2CBF", "#2A9D8F", "#E76F51", "#264653"),
                       palette = c("#2A9D8F", "white", "#E76F51")))

corr_wheel(
  gastro_symptoms, groups = groups, r_threshold = 0.3, r_limits = c(-0.6, 0.6),
  scheme = "colorblind",
  colors = c(Scores = "black"),          # override just one category
  labels = c("GA-RI" = "Rhythm index")
)

corr_wheel(
  gastro_symptoms, groups = groups, r_threshold = 0.3, r_limits = c(-0.6, 0.6),
  tile_height = 0.12,   # thicker blocks
  link_lwd    = 3       # thicker lines
)

corr_wheel(
  gastro_symptoms, groups = groups, r_threshold = 0.3,
  palette  = c("#2166AC", "white", "#B2182B"),   # blue - white - red
  r_limits = c(-0.5, 0.5)
)

Saving to a file

corr_wheel() draws on the active graphics device, so save it the usual way:

png("correlation_wheel.png", width = 2500, height = 2000, res = 300)
corr_wheel(gastro_symptoms, groups = groups, r_threshold = 0.3,
           r_limits = c(-0.6, 0.6))
dev.off()

Argument reference

Everything covered above, at a glance:

corr_wheel() returns (invisibly) the ordered variables, resolved group and colour maps, the colour function, and the masked matrix actually plotted – handy for reproducibility or building a caption.

References