Visualization of a Correlation Matrix using 'ggplot2'
Overview
The 'ggcorrplot' package can be used to visualize easily a correlation matrix using 'ggplot2'. It provides a solution for reordering the correlation matrix and displays the significance level on the plot. It also includes a function for computing a matrix of correlation p-values.
New features
- New argument
cell.gridto draw a light rectangle around every cell (behind the glyphs) and drop the through-center gridlines, so the sized glyphs (method = "circle"orscale.square = TRUE) sit inside boxed cells -- the corrplot boxed-cell look:ggcorrplot(corr, method = "circle", cell.grid = TRUE). The cell border color is set with the companion argumentcell.grid.col(default"grey90"). Defaults toFALSE; has no effect on a full-tile square heatmap, whose tiles already carry anoutline.colorborder. - New argument
scale.squareto size the squares by the absolute correlation whenmethod = "square":ggcorrplot(corr, scale.square = TRUE)scales each square (larger = stronger correlation) on top of the fill color, the classic corrplot size-scaled square look. Defaults toFALSE(constant full-cell squares, unchanged); has no effect formethod = "circle"(circles are always sized).
Show all changes in 0.3.0Hide the rest of the changes in 0.3.0
- New argument
presetfor publication-grade output in one token:ggcorrplot(corr, preset = "publication")sets white cell outlines and the colorblind-safe"RdBu"palette. It only fills arguments you did not supply, so anything you pass explicitly (e.g.outline.color,colors,palette) overrides the preset. Defaults toNULL(no preset), leaving existing calls unchanged. - New argument
paletteto pick a built-in colorblind-safe diverging palette for the fill gradient:ggcorrplot(corr, palette = "RdBu")(or"PuOr"). Each is an 11-stop ramp with white at zero and the usual cool = negative / warm = positive polarity, so it is a one-word alternative to spelling outcolors. Defaults toNULL(usecolors), leaving existing calls unchanged. - New value
insig = "stars"to mark the significant cells with significance stars (***/**/*for p <= 0.001/0.01/0.05 -- fixed thresholds, notsig.level) instead of crossing out the insignificant ones. Works withoutlab, soggcorrplot(corr, p.mat = p.mat, insig = "stars")is a standalone significance map. The defaultinsig = "pch"is unchanged. - New arguments
lower.methodandupper.methodfor a mixed layout: a different glyph per triangle, e.g. the coefficients as numbers in the lower triangle, circles in the upper, and the variable names on the diagonal (ggcorrplot(corr, lower.method = "number", upper.method = "circle")). Each accepts "square", "circle" or "number"; both default toNULL, leaving the single-method output unchanged (#85). Requested by @Breeze-Hu. - New argument
hc.rectto draw rectangles around the clusters of a hierarchically-ordered correlogram:ggcorrplot(corr, hc.order = TRUE, hc.rect = 3)frames the 3 clusters obtained by cutting the tree. Defaults toNULL(no rectangles). The rectangle outline color is set with the companion argumenthc.rect.col(default"gray30", e.g.hc.rect.col = "white").
Main changes
- The plot axis is now always drawn in the matrix (row/column) order. This fixes a bug where
hc.order = TRUEwas silently ignored for correlation matrices with numeric-looking variable names (e.g."1","2", ...):reshape2::melttype-converted such names to a continuous axis sorted by value, discarding the clustering order (#37). As a consequence, theas.isargument no longer affects the plot (it is kept only for backward compatibility) -- a call usingas.is = TRUE, which previously produced an alphabetically-ordered axis, now follows the matrix order like every other call. Reported by @cabaez (#37). show.diag = FALSEon a non-square matrix no longer blanks the wrong cells. The diagonal has no positional meaning for an m x n matrix, yet the removal wipedmin(m, n)cells along the leading diagonal; it now removes only the genuine self-pairs (a row and column naming the same variable), leaving a matrix with disjoint row and column variables untouched. Square matrices, and non-square matrices without dimnames, are unaffected. Follows up the non-square support requested by @mt1022 (#5) and @qalid7 (#10).
Minor changes
- Added an introductory vignette,
vignette("ggcorrplot"), walking through the package end to end: the inputs, glyphs and layouts, clustering, coefficient labels, significance styles, and theming. - Added a second vignette,
vignette("publication-ready-correlation-plots"), a gallery of finished publication-ready correlogram recipes (clustered, triangle, significance, circle, colorblind palette, edgeless heatmap, rectangular predictor-by-outcome matrix, and full ggplot2 polish). - Internal refactor: the data-preparation pipeline and the glyph-layer construction are now factored into internal helpers, with no change to the output of any existing call. This is groundwork for forthcoming per-triangle layout options.
- The help page and the README now link to the Datanovia correlation tutorials for worked examples of the plot and of the p-value matrix.
From NEWS.md in the release
Install
Health
- OK13 OK2026-08-05
- NOTE12 OK, 1 NOTE2026-08-01
- OK13 OK2026-07-11
- NOTE12 OK, 2 NOTE2026-03-10
Documentation
- Help pages
- 1
- Examples that run
- 100%1 run in a plain check
- Exported functions with examples
- 100%
- Documented parameters
- 76%
- Return-value docs
- 100%
- Help pages citing references
- 0%
Downloads
Repository
- PRs merged (all time)
- 87%
- Median days to close, 50 most recently updated closed issues
- 915
- Median days to close, 50 most recently updated closed PRs
- 0
Stars over time
Forks over time
Releases over time
Issues over time
PRs over time
Commits over time
9 development-tooling and community-health practices detected across 6 families in the upstream repository
Checks run against github.com/kassambara/ggcorrplot on 2026-10-11.
The R CMD check workflow runs on Linux, macOS and Windows, and on R-devel
Show all practicesHide 2 practices
Dependencies
Installing ggcorrplot adds 23 packages (12 with compiled code, 27 MB of source tarballs). Heaviest: stringi 11 MB, ggplot2 6.0 MB, Rcpp 1.8 MB.
Show all 22 packagesHide all 22 packages
Code & Tests
People & History
Pick two releases to compare their code metrics.
- 0.3.0Latest
- 0.2.02026-07-08 · diff ↗
- RR 4.6.0 released · 2026-04-24
- RR 4.5.0 released · 2025-04-11
- RR 4.4.0 released · 2024-04-24
- 0.1.4.12023-09-05 · diff ↗
- RR 4.3.0 released · 2023-04-21
- 0.1.42022-09-27 · diff ↗
- RR 4.2.0 released · 2022-04-22
- RR 4.1.0 released · 2021-05-18
- RR 4.0.0 released · 2020-04-24
- 0.1.32019-05-19 · diff ↗
- RR 3.6.0 released · 2019-04-26
- 0.1.22018-09-11 · diff ↗
- RR 3.5.0 released · 2018-04-23
- RR 3.4.0 released · 2017-04-21
Show 3 earlier eventsHide 3 earlier events
- RR 3.3.0 released · 2016-05-03
- 0.1.12016-01-12
- RR 3.2.0 released · 2015-04-16
Package metadata
- First published
- 2016-01-12
- Total releases
- 7 / 10 yrs
- License
- GPL-2 OSI
- Minimum R
- ≥ 3.3
- Download size
- 3.4 MB
Cite
Cite this package
Run in R for the authors' preferred citation:
citation("ggcorrplot")The package provides a citation file that builds its entry when R runs it. Run citation() to see it.
Cite the R Observatory
For a number measured here: a download total, a coverage figure, an archival date.
From data release v2026-10-18, which the citation names so these numbers can be found later. More on citing and the projects behind them.