Written and maintained by CASRAI Editorial Board
Published
On this page
corrr is an R package that turns correlation matrices into tidy data frames you can filter, reshape, print and plot with the same pipe-based verbs used elsewhere in the tidyverse. Its main function, correlate(), works like base R’s cor() but returns a data frame (class cor_df) with a term column, so a correlation table can be reordered, trimmed to one triangle, stretched to long format or drawn as a plot in a few chained calls. The CRAN page lists version 0.4.5 (published 2025-08-18), maintained by Max Kuhn and released under the MIT licence.
What corrr is used for in research
Researchers reach for corrr when a plain correlation matrix is awkward to work with: too many variables to read, a need to show only one triangle, a need to list the strongest pairs, or a need to report results as a table in a manuscript. The package title on CRAN is “Correlations in R”, and its documentation describes a workflow built around data frames of correlations rather than matrices, so results can be explored with corrr’s own functions or with tidyverse tools.
The package does not introduce a new correlation statistic. correlate() computes Pearson, Kendall or Spearman coefficients through the same options as stats::cor(); what corrr adds is the surrounding toolkit:
focus()keeps selected variables as columns and removes them (or all other variables) from the rows.shave()sets the upper or lower triangle toNA, so each pair appears once.rearrange()reorders variables so that strongly correlated ones sit next to each other.stretch()converts the matrix-shaped result to long format (x, y, r), one row per pair.fashion()formats the result for printing, with leading zeros removed and the diagonal left blank.rplot()andnetwork_plot()draw the result with ggplot2.
For the statistics behind the coefficient, see CASRAI’s guides on the correlation coefficient and on Spearman correlation. For other ways to build and plot a matrix in R (including packages that corrr does not replace), see correlation matrix in R and cor() in R.
How to install or access corrr
corrr is distributed on CRAN, so installation uses the standard R command from the project site and CRAN page:
- Install the released version:
install.packages("corrr"). - Load it in each session:
library(corrr). - Optional, for the development version:
remotes::install_github("tidymodels/corrr")(this needs the remotes package).
The CRAN page states that corrr depends on R 3.4 or later and imports dplyr (1.0.0 or later), ggplot2 (2.2.0 or later), ggrepel (0.6.5 or later), glue, purrr, rlang, seriation (1.2-0 or later) and tibble (2.0 or later). seriation is the package behind rearrange(), and ggrepel supplies the label placement used in network_plot(). These are installed automatically with corrr. If installation from CRAN, Bioconductor or GitHub is new to you, how to install R packages walks through the general routes.
How to build a tidy correlation table with corrr step by step
The example below follows the pattern in the package documentation and uses mtcars, a dataset that ships with R. Substitute your own data frame of numeric variables.
- Load the package.
library(corrr). The documentation examples also load dplyr for the pipe and column selection. - Compute the correlations.
x <- correlate(mtcars). R prints a message that the correlation was computed with method ‘pearson’ and missing values treated using ‘pairwise.complete.obs’. Those are the defaults, and they are what you should report in a methods section unless you change them. - Choose a different method if needed.
correlate(mtcars, method = "spearman")ormethod = "kendall". The documented options formethodare pearson, kendall and spearman. - Focus on the variables of interest.
focus(x, mpg, cyl)returns the correlations of mpg and cyl with every other variable, one row per remaining variable. To drop variables from both the columns and the rows, use negative selection with mirroring:focus(x, -disp, -mpg, mirror = TRUE). - Group related variables.
rearrange(x)reorders variables using the default seriation method;method = "HC"selects a different seriation method, andabsolute = TRUE(the default) means strength is judged by absolute correlation, ignoring sign. - Show each pair once.
shave(x)sets the upper triangle toNA;shave(x, upper = FALSE)sets the lower triangle instead. - Format for a table.
fashion(x)prints a cleanly formatted matrix with two decimals by default;fashion(x, decimals = 1)shortens it.
The documentation’s single-pipeline version of steps 2 to 7 reads:
mtcars %>% correlate() %>% focus(-cyl, -vs, mirror = TRUE) %>% rearrange() %>% shave() %>% fashion()
This produces a lower-triangle table with the strongest-related variables grouped together. In the documented output, for example, drat correlates .68 with mpg, am correlates .60 with mpg and .71 with drat, and gear correlates .48 with mpg, .70 with drat and .79 with am.
Making a list of pairs with stretch()
For a supplementary table that lists each pair once, shave first and then stretch. x <- shave(correlate(mtcars)) followed by stretch(x, na.rm = TRUE) returns a three-column tibble (x, y, r). In the package reference, the full matrix of 11 variables stretches to 121 rows, dropping the NA diagonal gives 110 rows (each pair twice), and shaving first gives 55 rows, each correlation appearing once. The arguments are na.rm (default FALSE) and remove.dups (default FALSE).
Plotting
rplot(x) draws one point per correlation: point size reflects the absolute value and colour reflects the signed value. Its arguments include legend, shape, colours, print_cor and .order (“default” keeps the column order, “alphabet” sorts variable names). network_plot(x, min_cor = .2) places more strongly correlated variables closer together and joins them with paths; positive correlations are blue and negative ones red by default. min_cor (default 0.3) sets the minimum absolute correlation drawn, so raising it thins the plot. Other arguments are legend (“full”, “range” or “none”), colours, repel and curved.
How to read the output
A correlate() result is a tibble whose first column, term, holds the variable names; the remaining columns hold the correlation of each term with each variable. Three features trip up first-time readers.
- The diagonal is
NA. By defaultcorrelate()setsdiagonal = NArather than 1, so a variable’s correlation with itself does not clutter pipelines or plots. Setting a number there overrides it. - The matrix is symmetric. Every pair appears twice. Use
shave()orstretch()with shaving to show it once. - A blank cell is not zero.
fashion()printsNAas an empty string (na_print = ""), so a blank cell is the diagonal or a shaved cell. Correlations near zero print as small values such as .09.
Sign and size follow the usual rules for correlation coefficients; how to read a correlation matrix covers interpretation and the limits of reading a coefficient in isolation. A correlation table says nothing about causation or about whether a relationship is linear, whichever package produced it.
Where corrr differs from stats::cor()
The two functions share the same method options but not the same defaults, which matters when you move code between them.
| Setting | corrr correlate() | stats::cor() |
|---|---|---|
Missing-value handling (use) |
“pairwise.complete.obs” | “everything” |
Method (method) |
“pearson” (also kendall, spearman) | “pearson” (also kendall, spearman) |
| Diagonal | diagonal = NA |
Not an argument; no diagonal setting |
| Return value | Tibble of class cor_df with a term column |
Correlation of the columns of x (and y) as supplied |
| Message on use | Prints method and missing-value treatment unless quiet = TRUE |
None |
The accepted use values for both are “everything”, “all.obs”, “complete.obs”, “na.or.complete” and “pairwise.complete.obs”. With pairwise deletion each coefficient is computed from the rows that are complete for that pair, so different cells can rest on different sample sizes. If your analysis plan requires every coefficient to come from the same rows, set use = "complete.obs" explicitly and report it. For how missingness mechanisms affect that choice, see MCAR, MAR and MNAR.
Troubleshooting corrr
- The console prints “Correlation computed with” every time. This message reports the method and missing-value treatment. Pass
quiet = TRUEtocorrelate()to suppress it, for example in a report. - Code written for an older version refers to a
rownamecolumn. The documentation says the first column was namedrownamebefore version 0.4.3 and is namedtermnow. Update anyselect(),filter()or join that uses the old name. - Results differ from
cor()on the same data. Compare theuseargument first:correlate()defaults to pairwise deletion,cor()to “everything”. Datasets with missing values will not match until both use the same option. focus()drops rows you expected to keep. Withoutmirror = TRUE, the selected variables stay in the columns and are excluded from the rows; withmirror = TRUEthe same exclusion applies to rows and the result remains acor_df.- The network plot is empty or cluttered.
min_coris a threshold on absolute correlation between 0 and 1. Lower it if no paths are drawn, raise it if the plot is crowded. - Installation fails on a dependency. The package needs R 3.4 or later and the imports listed above; update R and the failing dependency, then reinstall.
- Data held in a database. The documentation notes that
correlate()supports a Spark connection, with the results collected into memory.
Free alternatives to corrr
corrr is itself free and open source (MIT licence). These R packages cover overlapping ground; each description below is taken from the package’s CRAN or R documentation page.
| Tool | What its documentation says it does | When it is the simpler choice |
|---|---|---|
| stats::cor() (base R) | Computes variance, covariance or correlation; for matrices or data frames it gives the correlations between columns | You need one matrix and no tidyverse reshaping, with no extra package |
| corrplot | Visual exploratory tool on a correlation matrix, with automatic variable reordering | You want a matrix-style graphic rather than a data frame |
| psych | General toolbox for multivariate analysis and scale construction, including correlations | Your workflow is psychometric (factor analysis, reliability) and already uses psych |
Other correlation-matrix routes in R are compared in correlation matrix in R.
Sources
- CRAN: corrr, Correlations in R, checked 2026-11-17
- tidymodels: corrr package site, checked 2026-11-17
- corrr reference: correlate(), checked 2026-11-17
- corrr reference: stretch(), checked 2026-11-17
- corrr reference: rplot(), checked 2026-11-17
- corrr reference: network_plot(), checked 2026-11-17
- R documentation: cor {stats}, checked 2026-11-17
- CRAN: corrplot, checked 2026-11-17
- CRAN: psych, checked 2026-11-17
Data: corrr functions and their documented defaults
Compiled from the corrr reference pages on corrr.tidymodels.org (correlate, focus, shave, rearrange, stretch, fashion, rplot, network_plot): each function's purpose, its key arguments with the defaults shown in the usage section, and what it returns. Defaults are as documented on the pkgdown reference pages on the date read.
| Function | Purpose | Key arguments and defaults | Returns |
|---|---|---|---|
| correlate() | Compute a correlation data frame, like cor() | use = "pairwise.complete.obs"; method = "pearson"; diagonal = NA; quiet = FALSE | cor_df (tibble with term column) |
| focus() | Keep chosen variables as columns and remove them or all others from rows | mirror = FALSE | tibble, or cor_df if mirror = TRUE |
| shave() | Set the upper or lower triangle to NA | upper = TRUE | cor_df |
| rearrange() | Group highly correlated variables together | method = "PC" (text says PCA); absolute = TRUE | cor_df |
| stretch() | Convert to long format (x, y, r) | na.rm = FALSE; remove.dups = FALSE | tibble with three columns |
| fashion() | Format a correlation data frame for printing | decimals = 2; leading_zeros = FALSE; na_print = "" | noquote matrix or data frame |
| rplot() | Plot correlations as sized, coloured points | legend = TRUE; shape = 16; print_cor = FALSE; .order = "default" | ggplot2 plot |
| network_plot() | Plot variables as a network joined by correlation paths | min_cor = 0.3; legend = "full"; repel = TRUE; curved = TRUE | ggplot2 plot |
Sources
- corrr reference: correlate() (accessed 2026-11-17)
- corrr reference: rearrange() (accessed 2026-11-17)
- corrr reference: network_plot() (accessed 2026-11-17)
- corrr reference: fashion() (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







