ggcorrmat
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
The function ggstatsplot::ggcorrmat
provides a quick way to produce
publicationready correlation matrix (aka correlalogram) plot. The function
can also be used for quick data exploration. In addition to the plot, it can
also be used to get a correlation coefficient matrix or the associated pvalue
matrix. Currently, the plot can display Pearson's r, Spearman's rho, and
Kendall's tau, and robust correlation coefficient (percentage bend
correlation; see ?WRS2::pbcor
). This function is a convenient wrapper around
ggcorrplot::ggcorrplot
function with some additional functionality.
We will see examples of how to use this function in this vignette with the
gapminder
and diamonds
dataset.
To begin with, here are some instances where you would want to use
ggcorrmat

 to easily visualize a correlation matrix using
ggplot2
 to quickly explore correlation between (all) numeric variables in the dataset
Note before: The following demo uses the pipe operator (%>%
), so in case
you are not familiar with this operator, here is a good explanation:
http://r4ds.had.co.nz/pipes.html
Correlation matrix plot with ggcorrmat
For the first example, we will use the gapminder
dataset (available in
eponymous package on CRAN)
provides values for life expectancy, Gross Domestic Product (GDP) per capita,
and population, every five years, from 1952 to 2007, for each of 142 countries
and was collected by the Gapminder Foundation. Let's have a look at the data
library(gapminder)
library(dplyr)
dplyr::glimpse(x = gapminder)
Let's say we are interested in studying correlation between population of a country, average life expectancy, and GDP per capita across countries only for the year 2007.
The simplest way to get a correlation matrix is to stick to the defaults
library(ggstatsplot)
# select data only from the year 2007
gapminder_2007 < dplyr::filter(.data = gapminder::gapminder, year == 2007)
# producing the correlation matrix
ggstatsplot::ggcorrmat(
data = gapminder_2007, # data from which variable is to be taken
cor.vars = lifeExp:gdpPercap # specifying correlation matrix variables
)
This plot can be further modified with additional arguments
ggstatsplot::ggcorrmat(
data = gapminder_2007, # data from which variable is to be taken
cor.vars = lifeExp:gdpPercap, # specifying correlation matrix variables
cor.vars.names = c("Life Expectancy",
"population",
"GDP (per capita)"),
corr.method = "kendall", # which correlation coefficient is to be computed
lab.col = "red", # label color
ggtheme = ggplot2::theme_light(), # selected ggplot2 theme
ggstatsplot.layer = FALSE, # turn off default ggestatsplot theme overlay
matrix.type = "lower", # correlation matrix structure
colors = NULL, # turning off manual specification of colors
palette = "category10_d3", # choosing a color palette
package = "ggsci", # package to which color palette belongs
title = "Gapminder correlation matrix", # custom title
subtitle = "Source: Gapminder Foundation" # custom subtitle
)
As seen from this correlation matrix, although there is no relationship between population and life expectancy worldwide, at least in 2007, there is a strong positive relationship between GDP, a wellestablished indicator of a country's economic performance.
Given that there were only three variables, this doesn't look that impressive.
So let's work with another example from ggplot2
package: the diamonds
dataset. This dataset
contains the prices and other attributes of almost 54,000 diamonds.
Let's have a look at the data
library(ggplot2)
dplyr::glimpse(x = ggplot2::diamonds)
Let's see the correlation matrix between different attributes of the diamond and the price.
# for reproducibility
set.seed(123)
# let's use just 5% of the data to speed it up
ggstatsplot::ggcorrmat(
data = dplyr::sample_frac(tbl = ggplot2::diamonds, size = 0.05),
cor.vars = c(carat, depth:z), # note how the variables are getting selected
cor.vars.names = c(
"carat",
"total depth",
"table",
"price",
"length (in mm)",
"width (in mm)",
"depth (in mm)"
),
hc.order = TRUE # use hierarchical clustering
)
We can make a number of changes to this basic correlation matrix. For example,
since we were interested in relationship between price and other attributes,
let's make the price
column to the the first column. Additionally, since we are
running 6 correlations that are of a priori interest to us, we can adjust our
threshold of significance to (0.05/6 ~ 0.008). Additionally, let's use a
nonparametric correlation coefficient. Please note that it is important to
always make sure that the order in which cor.vars
and cor.vars.names
are
entered is in sync. Otherwise, wrong column labels will be displayed.
# for reproducibility
set.seed(123)
# let's use just 5% of the data to speed it up
ggstatsplot::ggcorrmat(
data = dplyr::sample_frac(tbl = ggplot2::diamonds, size = 0.05),
cor.vars = c(price, carat, depth:table, x:z), # note how the variables are getting selected
cor.vars.names = c(
"price",
"carat",
"total depth",
"table",
"length (in mm)",
"width (in mm)",
"depth (in mm)"
),
corr.method = "spearman",
sig.level = 0.008,
matrix.type = "lower",
title = "Relationship between diamond attributes and price",
subtitle = "Dataset: Diamonds from ggplot2 package",
colors = c("#0072B2", "#D55E00", "#CC79A7"),
lab.col = "yellow",
lab.size = 6,
pch = 7,
pch.col = "white",
pch.cex = 14,
caption = expression( # changing the default caption text for the plot
paste(italic("Note"), ": Point shape denotes correlation nonsignificant at p < 0.008; adjusted for 6 comparisons")
)
)
As seen here, and unsurprisingly, the strongest predictor of the diamond price is its carat value, which a unit of mass equal to 200 mg. In other words, the heavier the diamond, the more expensive it is going to be.
Correlation statistics matrix with ggcorrmat
Another utility of ggcorrmat
is in obtaining matrix of correlation
coefficients and their pvalues for a quick and dirty exploratory data
analysis. For example, for the correlation matrix we just ran, we can get a
coefficient matrix and a pvalue matrix.
# for reproducibility
set.seed(123)
# to get correlations
ggstatsplot::ggcorrmat(
data = dplyr::sample_frac(tbl = ggplot2::diamonds, size = 0.15),
cor.vars = c(price, carat, depth:table, x:z),
output = "correlations",
corr.method = "robust",
digits = 3
)
# to get pvalues
ggstatsplot::ggcorrmat(
data = dplyr::sample_frac(tbl = ggplot2::diamonds, size = 0.15),
cor.vars = c(price, carat, depth:table, x:z),
output = "pvalues",
corr.method = "robust",
digits = 3
)
Grouped analysis with grouped_ggcorrmat
What if we want to do the same analysis separately for each quality of the
diamond cut
(Fair, Good, Very Good, Premium, Ideal)? In that case, we will
have to either write a for
loop or use purrr
, none of which seem like an
exciting prospect.
ggstatsplot
provides a special helper function for such instances:
grouped_ggcorrmat
. This is merely a wrapper function around
ggstatsplot::combine_plots
. It applies ggcorrmat
across all levels of
a specified grouping variable and then combines list of individual plots
into a single plot. Note that the grouping variable can be anything: conditions
in a given study, groups in a study sample, different studies, etc.
# for reproducibility
set.seed(123)
# let's use just 5% of the data to speed it up
ggstatsplot::grouped_ggcorrmat(
# arguments relevant for ggstatsplot::ggcorrmat
data = dplyr::sample_frac(tbl = ggplot2::diamonds, size = 0.05),
corr.method = "r", # percentage bend correlation coefficient
beta = 0.2, # bending constant
p.adjust.method = "holm", # method to adjust pvalues for multiple comparisons
grouping.var = cut,
title.prefix = "Quality of cut",
cor.vars = c(carat, depth:z),
cor.vars.names = c(
"carat",
"total depth",
"table",
"price",
"length (in mm)",
"width (in mm)",
"depth (in mm)"
),
lab.size = 3.5,
# arguments relevant for ggstatsplot::combine_plots
title.text = "Relationship between diamond attributes and price across cut",
title.size = 16,
title.color = "red",
caption.text = "Dataset: Diamonds from ggplot2 package",
caption.size = 14,
caption.color = "blue",
labels = c("(a)","(b)","(c)","(d)","(e)"),
nrow = 3,
ncol = 2
)
Note that this function also makes it easy to run the same correlation matrix
across different levels of a factor/grouping variable. For example, if we wanted
to get the same correlation coefficient matrix for color
of the diamond, we
can do the following
# for reproducibility
set.seed(123)
# let's use just 5% of the data to speed it up
ggstatsplot::grouped_ggcorrmat(
data = dplyr::sample_frac(tbl = ggplot2::diamonds, size = 0.05),
grouping.var = cut,
cor.vars = c(price, carat, depth:table, x:z),
output = "correlations",
corr.method = "robust",
digits = 3
)
As this example illustrates, there is a minimal coding overhead to explore
correlations in your dataset with the grouped_ggcorrmat
function.
Grouped analysis with ggcorrmat
+ purrr
Although grouped_
function is good for quickly exploring the data, it reduces
the flexibility with which this function can be used. This is the because the
common parameters used are applied to plots corresponding to all levels of the
grouping variable and there is no way to customize the arguments for different
levels of the grouping variable. We will see how this can be done using the
purrr
package.
See the associated vignette here: https://indrajeetpatil.github.io/ggstatsplot/articles/web_only/purrr_examples.html
Summary of tests
Following tests are carried out for each type of analyses
Type  Test 

Parametric  Pearson's correlation coefficient 
Nonparametric  Spearman's rank correlation coefficient 
Robust  Percentage bend correlation coefficient 
Bayes Factor  Pearson's correlation coefficient 
Suggestions
If you find any bugs or have any suggestions/remarks, please file an issue on
GitHub
: https://github.com/IndrajeetPatil/ggstatsplot/issues
Session Information
For details, see https://indrajeetpatil.github.io/ggstatsplot/articles/web_only/session_info.html