Skip to main content
v2026.11,986 entries · CC-BY 4.0

corrr R Package: Install, correlate() and Tidy Correlation Output

How to install corrr, build tidy correlation tables with correlate(), focus(), shave() and stretch(), and read the output.

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 to NA, 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() and network_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:

  1. Install the released version: install.packages("corrr").
  2. Load it in each session: library(corrr).
  3. 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.

  1. Load the package. library(corrr). The documentation examples also load dplyr for the pipe and column selection.
  2. 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.
  3. Choose a different method if needed. correlate(mtcars, method = "spearman") or method = "kendall". The documented options for method are pearson, kendall and spearman.
  4. 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).
  5. Group related variables. rearrange(x) reorders variables using the default seriation method; method = "HC" selects a different seriation method, and absolute = TRUE (the default) means strength is judged by absolute correlation, ignoring sign.
  6. Show each pair once. shave(x) sets the upper triangle to NA; shave(x, upper = FALSE) sets the lower triangle instead.
  7. 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 default correlate() sets diagonal = NA rather 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() or stretch() with shaving to show it once.
  • A blank cell is not zero. fashion() prints NA as 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 = TRUE to correlate() to suppress it, for example in a report.
  • Code written for an older version refers to a rowname column. The documentation says the first column was named rowname before version 0.4.3 and is named term now. Update any select(), filter() or join that uses the old name.
  • Results differ from cor() on the same data. Compare the use argument 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. Without mirror = TRUE, the selected variables stay in the columns and are excluded from the rows; with mirror = TRUE the same exclusion applies to rows and the result remains a cor_df.
  • The network plot is empty or cluttered. min_cor is 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

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.

corrr functions and their documented defaults
FunctionPurposeKey arguments and defaultsReturns
correlate()Compute a correlation data frame, like cor()use = "pairwise.complete.obs"; method = "pearson"; diagonal = NA; quiet = FALSEcor_df (tibble with term column)
focus()Keep chosen variables as columns and remove them or all others from rowsmirror = FALSEtibble, or cor_df if mirror = TRUE
shave()Set the upper or lower triangle to NAupper = TRUEcor_df
rearrange()Group highly correlated variables togethermethod = "PC" (text says PCA); absolute = TRUEcor_df
stretch()Convert to long format (x, y, r)na.rm = FALSE; remove.dups = FALSEtibble with three columns
fashion()Format a correlation data frame for printingdecimals = 2; leading_zeros = FALSE; na_print = ""noquote matrix or data frame
rplot()Plot correlations as sized, coloured pointslegend = TRUE; shape = 16; print_cor = FALSE; .order = "default"ggplot2 plot
network_plot()Plot variables as a network joined by correlation pathsmin_cor = 0.3; legend = "full"; repel = TRUE; curved = TRUEggplot2 plot

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · full access

Ask about corrr R Package: Install, correlate() and Tidy Correlation Output

Full access: large monthly usage, up to 10 source passages behind each answer, and MCP and API access for Claude Code, Codex and other CLIs. Cancel any time.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →