Package {tidycorrgram}

Type: Package
Title: Tidy Correlation Matrices and 'ggplot2' Correlograms
Version: 0.1.0
Author: Xinyu Zhang [aut, cre]
Maintainer: Xinyu Zhang <zhangx60@uci.edu>
Description: Computes correlation matrices as tidy data frames and creates publication-ready correlograms with 'ggplot2'. The package is designed for teaching and exploratory analysis workflows where users want one consistent interface for selecting numeric variables, calculating pairwise correlations, optionally estimating p-values, reordering variables, and drawing tile, point, or mixed correlograms.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
Depends: R (≥ 4.1.0)
Imports: ggplot2, stats
URL: https://github.com/zhangx60/tidycorrgram
BugReports: https://github.com/zhangx60/tidycorrgram/issues
NeedsCompilation: no
Packaged: 2026-06-07 05:02:14 UTC; isabelzhang
Repository: CRAN
Date/Publication: 2026-06-15 11:50:02 UTC

Tidy Correlation Matrices and ggplot2 Correlograms

Description

Compute correlation matrices as tidy data frames and create publication-ready correlograms with ggplot2.

Details

The main functions are corrgram_data for computing tidy correlation tables and corrgram for drawing correlograms.

See Also

corrgram_data, corrgram

Create a correlogram

Description

corrgram() computes correlations and returns a ggplot2 correlogram.

Usage

corrgram(
  data,
  columns = NULL,
  method = c("pearson", "kendall", "spearman"),
  use = "pairwise.complete.obs",
  triangle = c("lower", "full", "upper"),
  diagonal = TRUE,
  reorder = c("hclust", "none", "alphabetical"),
  p_values = FALSE,
  adjust = c("none", "holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr"),
  alpha = 0.05,
  exact = NULL,
  geom = c("tile", "point", "mixed"),
  labels = FALSE,
  label_digits = 2,
  palette = corrgram_palette(),
  significant_only = FALSE
)

Arguments

data

A data frame.

columns

Optional column selection. Use NULL to select all numeric columns, a character vector of names, a numeric vector of positions, or a logical vector with length ncol(data).

method

Correlation method passed to stats::cor() and stats::cor.test().

use

Missing-value handling passed to stats::cor().

triangle

Which part of the matrix to return: "full", "lower", or "upper".

diagonal

Should diagonal values be retained?

reorder

Variable ordering. "none" preserves the selected column order, "alphabetical" sorts names, and "hclust" uses hierarchical clustering on 1 - abs(correlation).

p_values

Should pairwise correlation p-values be computed?

adjust

P-value adjustment method passed to stats::p.adjust().

alpha

Significance threshold used to create the significant column when p_values = TRUE.

exact

Passed to stats::cor.test() for rank-based methods. The default NULL lets R choose.

geom

Plot style. "tile" uses colored squares, "point" uses sized circles, and "mixed" combines both.

labels

Should correlation values be drawn as text?

label_digits

Number of digits for text labels.

palette

A named color vector with low, mid, and high values.

significant_only

If TRUE, non-significant off-diagonal cells are removed using adjusted p-values and alpha. This sets p_values = TRUE.

Value

A ggplot2 object.

See Also

corrgram_data, corrgram_palette

Examples

corrgram(mtcars, columns = c("mpg", "disp", "hp", "wt"))
corrgram(mtcars, geom = "point", triangle = "upper", diagonal = FALSE)

Compute a tidy correlation matrix

Description

corrgram_data() selects numeric columns, computes pairwise correlations, and returns the matrix as a tidy data frame that is ready for ggplot2.

Usage

corrgram_data(
  data,
  columns = NULL,
  method = c("pearson", "kendall", "spearman"),
  use = "pairwise.complete.obs",
  triangle = c("full", "lower", "upper"),
  diagonal = TRUE,
  reorder = c("none", "hclust", "alphabetical"),
  p_values = FALSE,
  adjust = c("none", "holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr"),
  alpha = 0.05,
  exact = NULL
)

Arguments

data

A data frame.

columns

Optional column selection. Use NULL to select all numeric columns, a character vector of names, a numeric vector of positions, or a logical vector with length ncol(data).

method

Correlation method passed to stats::cor() and stats::cor.test().

use

Missing-value handling passed to stats::cor().

triangle

Which part of the matrix to return: "full", "lower", or "upper".

diagonal

Should diagonal values be retained?

reorder

Variable ordering. "none" preserves the selected column order, "alphabetical" sorts names, and "hclust" uses hierarchical clustering on 1 - abs(correlation).

p_values

Should pairwise correlation p-values be computed?

adjust

P-value adjustment method passed to stats::p.adjust().

alpha

Significance threshold used to create the significant column when p_values = TRUE.

exact

Passed to stats::cor.test() for rank-based methods. The default NULL lets R choose.

Value

A data frame with columns var1, var2, r, abs_r, row, and col. If p_values = TRUE, it also includes p, p_adjusted, and significant.

Examples

corrgram_data(mtcars, columns = c("mpg", "disp", "hp", "wt"))
corrgram_data(mtcars, triangle = "lower", diagonal = FALSE)

Create a diverging correlogram palette

Description

Create a reusable three-color diverging palette for corrgram.

Usage

corrgram_palette(low = "#3B4CC0", mid = "#F7F7F7", high = "#B40426")

Arguments

low

Color used for correlations near -1.

mid

Color used for correlations near 0.

high

Color used for correlations near 1.

Value

A named character vector with low, mid, and high.

Examples

corrgram_palette()
corrgram_palette(low = "#2166AC", mid = "white", high = "#B2182B")