README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  dpi = 150,
  out.width = "70%",
  fig.align = "center"
)
```

[![R build status](https://github.com/kassambara/ggcorrplot/workflows/R-CMD-check/badge.svg)](https://github.com/kassambara/ggcorrplot/actions)
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/ggcorrplot)](https://cran.r-project.org/package=ggcorrplot)
[![CRAN Checks](https://badges.cranchecks.info/summary/ggcorrplot.svg)](https://cran.r-project.org/web/checks/check_results_ggcorrplot.html)
[![Downloads](https://cranlogs.r-pkg.org/badges/ggcorrplot)](https://cran.r-project.org/package=ggcorrplot)
[![Total Downloads](https://cranlogs.r-pkg.org/badges/grand-total/ggcorrplot?color=orange)](https://cranlogs.r-pkg.org/badges/grand-total/ggcorrplot)

# ggcorrplot: Visualization of a correlation matrix using ggplot2 <img src="man/figures/logo.png" align="right" height="139" alt="ggcorrplot hex logo" />

**ggcorrplot** draws a correlation matrix as a **ggplot2** plot. Because the
result is a plain ggplot object, you can restyle it, annotate it, and combine it
with other layers using the usual `+` syntax.

It can:

- reorder the matrix by **hierarchical clustering** and outline the clusters,
- show only the **lower** or **upper** triangle, or a **mixed** layout with a
  different glyph per triangle,
- overlay the **correlation coefficients** and mark the **statistically
  significant** cells (including a standalone **significance map**), and
- compute the matrix of **correlation p-values** with `cor_pmat()`.

Learn more in [ggcorrplot: Correlation Matrix Heatmap in R with
ggplot2](https://www.datanovia.com/learn/biostatistics/correlation/ggcorrplot-in-r).

## Installation

Install the released version from CRAN:

```{r, eval = FALSE}
install.packages("ggcorrplot")
```

Or the development version from GitHub:

```{r, eval = FALSE}
if (!require(devtools)) install.packages("devtools")
devtools::install_github("kassambara/ggcorrplot")
```

```{r, message = FALSE, warning = FALSE}
library(ggcorrplot)
```

## Getting started

The examples below use the `mtcars` data set. `cor()` builds the correlation
matrix and `cor_pmat()` [in **ggcorrplot**] computes the matrix of correlation
p-values.

```{r}
data(mtcars)
corr <- round(cor(mtcars), 1)
corr[1:4, 1:4]

# Matrix of correlation p-values
p.mat <- cor_pmat(mtcars)
p.mat[1:4, 1:4]
```

## Correlation matrix visualization

The default draws each correlation as a colored square; `method = "circle"`
encodes the value with the circle area instead.

```{r basic, fig.width = 5.2, fig.height = 5, fig.show = "hold", out.width = "49%", fig.align = "default"}
ggcorrplot(corr)
ggcorrplot(corr, method = "circle")
```

### Sized glyphs in boxed cells

`scale.square = TRUE` sizes the squares by the absolute correlation, so strong
correlations dominate; `cell.grid = TRUE` draws a light box around every cell so
the glyphs sit inside a grid instead of floating on the axis lines.

```{r boxed, fig.width = 5.2, fig.height = 5, fig.show = "hold", out.width = "49%", fig.align = "default"}
ggcorrplot(corr, scale.square = TRUE, cell.grid = TRUE, outline.color = "white")
ggcorrplot(corr, method = "circle", cell.grid = TRUE)
```

### Reorder by clustering, and outline the clusters

`hc.order = TRUE` reorders the variables by hierarchical clustering so that
correlated variables sit together. `hc.rect` then draws rectangles around the
clusters obtained by cutting the tree.

```{r cluster, fig.width = 5.2, fig.height = 5, fig.show = "hold", out.width = "49%", fig.align = "default"}
ggcorrplot(corr, hc.order = TRUE, outline.color = "white")
ggcorrplot(corr, hc.order = TRUE, hc.rect = 3, outline.color = "white")
```

### Lower / upper triangle

For a symmetric matrix the two triangles are redundant, so you can keep just one.

```{r triangle, fig.width = 5.2, fig.height = 5, fig.show = "hold", out.width = "49%", fig.align = "default"}
ggcorrplot(corr, hc.order = TRUE, type = "lower", outline.color = "white")
ggcorrplot(corr, hc.order = TRUE, type = "upper", outline.color = "white")
```

### Mixed layout

`lower.method` and `upper.method` draw a **different glyph in each triangle** —
here the coefficients as numbers below the diagonal and circles above it, with
the variable names on the diagonal. Adding `cell.grid = TRUE` boxes every cell
for the tidy corrplot look.

```{r mixed, fig.width = 6, fig.height = 5.6}
ggcorrplot(corr,
  lower.method = "number", upper.method = "circle",
  cell.grid = TRUE, show.legend = FALSE
)
```

### Add the coefficients

```{r labels, fig.width = 5.6, fig.height = 5.4}
ggcorrplot(corr, hc.order = TRUE, type = "lower", lab = TRUE)
```

## Highlighting significance

Passing `p.mat` marks the cells whose correlation is not significant at
`sig.level` (default 0.05). By default a cross is drawn over them (`insig =
"pch"`); `insig = "blank"` hides them instead.

```{r insig, fig.width = 5.2, fig.height = 5, fig.show = "hold", out.width = "49%", fig.align = "default"}
# Cross out the non-significant coefficients
ggcorrplot(corr, hc.order = TRUE, type = "lower", p.mat = p.mat)
# Leave them blank
ggcorrplot(corr, hc.order = TRUE, type = "lower", p.mat = p.mat, insig = "blank")
```

### Significance map

`insig = "stars"` flips the emphasis: instead of crossing out the
non-significant cells, it marks the **significant** ones with significance stars
(`***`, `**`, `*` for p <= 0.001, 0.01, 0.05 -- fixed thresholds, not
`sig.level`). With the default `lab = FALSE`
this is a standalone significance map; with `lab = TRUE` the stars are appended
to the coefficients (e.g. `-0.85***`).

```{r stars, fig.width = 5.6, fig.height = 5.4}
ggcorrplot(corr, p.mat = p.mat, insig = "stars")
```

## Colors and theme

`ggcorrplot()` returns a ggplot object, so any ggplot2 theme applies. `colors`
sets the low / mid / high gradient. For the ggplot2 side of this, see [ggplot2
Colours in R: Change Colours by
Group](https://www.datanovia.com/learn/data-visualization/ggplot2/colors) and
[ggplot2 Themes in R: Customize the
Look](https://www.datanovia.com/learn/data-visualization/ggplot2/themes).

```{r colors, fig.width = 5.6, fig.height = 5.4}
ggcorrplot(corr,
  hc.order = TRUE, type = "lower", outline.color = "white",
  ggtheme = ggplot2::theme_gray,
  colors = c("#6D9EC1", "white", "#E46726")
)
```

## Related tutorials

- [ggcorrplot: Correlation Matrix Heatmap in R with
  ggplot2](https://www.datanovia.com/learn/biostatistics/correlation/ggcorrplot-in-r)
- [Correlation Matrix in R: Compute, Visualize &
  P-values](https://www.datanovia.com/learn/biostatistics/correlation/correlation-matrix-in-r)
- [Correlogram in R: Visualize a Correlation Matrix with
  corrplot](https://www.datanovia.com/learn/biostatistics/correlation/correlogram-in-r)