# tidyr

## Overview

The goal of tidyr is to help you create **tidy data**. Tidy data is data
where:

1.  Each variable is a column; each column is a variable.
2.  Each observation is a row; each row is an observation.
3.  Each value is a cell; each cell is a single value.

Tidy data describes a standard way of storing data that is used wherever
possible throughout the [tidyverse](https://tidyverse.org/). If you
ensure that your data is tidy, you’ll spend less time fighting with the
tools and more time working on your analysis. Learn more about tidy data
in
[`vignette("tidy-data")`](https://tidyr.tidyverse.org/articles/tidy-data.md).

## Installation

``` r
# The easiest way to get tidyr is to install the whole tidyverse:
install.packages("tidyverse")

# Alternatively, install just tidyr:
install.packages("tidyr")

# Or the development version from GitHub:
# install.packages("pak")
pak::pak("tidyverse/tidyr")
```

## Cheatsheet

[![](https://raw.githubusercontent.com/rstudio/cheatsheets/master/pngs/thumbnails/tidyr-thumbs.png)](https://github.com/rstudio/cheatsheets/blob/master/tidyr.pdf)

## Getting started

``` r
library(tidyr)
```

tidyr functions fall into five main categories:

- “Pivoting” which converts between long and wide forms. tidyr 1.0.0
  introduces
  [`pivot_longer()`](https://tidyr.tidyverse.org/reference/pivot_longer.md)
  and
  [`pivot_wider()`](https://tidyr.tidyverse.org/reference/pivot_wider.md),
  replacing the older
  [`spread()`](https://tidyr.tidyverse.org/reference/spread.md) and
  [`gather()`](https://tidyr.tidyverse.org/reference/gather.md)
  functions. See
  [`vignette("pivot")`](https://tidyr.tidyverse.org/articles/pivot.md)
  for more details.

- “Rectangling”, which turns deeply nested lists (as from JSON) into
  tidy tibbles. See
  [`unnest_longer()`](https://tidyr.tidyverse.org/reference/unnest_longer.md),
  [`unnest_wider()`](https://tidyr.tidyverse.org/reference/unnest_wider.md),
  [`hoist()`](https://tidyr.tidyverse.org/reference/hoist.md), and
  [`vignette("rectangle")`](https://tidyr.tidyverse.org/articles/rectangle.md)
  for more details.

- Nesting converts grouped data to a form where each group becomes a
  single row containing a nested data frame, and unnesting does the
  opposite. See
  [`nest()`](https://tidyr.tidyverse.org/reference/nest.md),
  [`unnest()`](https://tidyr.tidyverse.org/reference/unnest.md), and
  [`vignette("nest")`](https://tidyr.tidyverse.org/articles/nest.md) for
  more details.

- Splitting and combining character columns. Use
  [`separate_wider_delim()`](https://tidyr.tidyverse.org/reference/separate_wider_delim.md),
  [`separate_wider_position()`](https://tidyr.tidyverse.org/reference/separate_wider_delim.md),
  and
  [`separate_wider_regex()`](https://tidyr.tidyverse.org/reference/separate_wider_delim.md)
  to pull a single character column into multiple columns; use
  [`unite()`](https://tidyr.tidyverse.org/reference/unite.md) to combine
  multiple columns into a single character column.

- Make implicit missing values explicit with
  [`complete()`](https://tidyr.tidyverse.org/reference/complete.md);
  make explicit missing values implicit with
  [`drop_na()`](https://tidyr.tidyverse.org/reference/drop_na.md);
  replace missing values with next/previous value with
  [`fill()`](https://tidyr.tidyverse.org/reference/fill.md), or a known
  value with
  [`replace_na()`](https://tidyr.tidyverse.org/reference/replace_na.md).

## Related work

tidyr
[supersedes](https://lifecycle.r-lib.org/articles/stages.html#superseded)
reshape2 (2010-2014) and reshape (2005-2010). Somewhat
counterintuitively, each iteration of the package has done less. tidyr
is designed specifically for tidying data, not general reshaping
(reshape2), or the general aggregation (reshape).

[data.table](https://rdatatable.gitlab.io/data.table) provides
high-performance implementations of `melt()` and `dcast()`

If you’d like to read more about data reshaping from a CS perspective,
I’d recommend the following three papers:

- [Wrangler: Interactive visual specification of data transformation
  scripts](http://vis.stanford.edu/papers/wrangler)

- [An interactive framework for data
  cleaning](https://www2.eecs.berkeley.edu/Pubs/TechRpts/2000/CSD-00-1110.pdf)
  (Potter’s wheel)

- [On efficiently implementing SchemaSQL on a SQL database
  system](https://www.vldb.org/conf/1999/P45.pdf)

To guide your reading, here’s a translation between the terminology used
in different places:

| tidyr 1.0.0    | pivot longer | pivot wider |
|----------------|--------------|-------------|
| tidyr \< 1.0.0 | gather       | spread      |
| reshape(2)     | melt         | cast        |
| spreadsheets   | unpivot      | pivot       |
| databases      | fold         | unfold      |

## Getting help

If you encounter a clear bug, please file a minimal reproducible example
on [github](https://github.com/tidyverse/tidyr/issues). For questions
and other discussion, please use
[forum.posit.co](https://forum.posit.co/).

------------------------------------------------------------------------

Please note that the tidyr project is released with a [Contributor Code
of Conduct](https://tidyr.tidyverse.org/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.

# Package index

## Pivoting

**Pivoting** changes the representation of a rectangular dataset,
without changing the data inside of it. See
[`vignette("pivot")`](https://tidyr.tidyverse.org/articles/pivot.md) for
more details and examples.

- [`pivot_longer()`](https://tidyr.tidyverse.org/reference/pivot_longer.md)
  : Pivot data from wide to long
- [`pivot_wider()`](https://tidyr.tidyverse.org/reference/pivot_wider.md)
  : Pivot data from long to wide

## Rectangling

**Rectangling** turns deeply nested lists into tidy tibbles. See
[`vignette("rectangle")`](https://tidyr.tidyverse.org/articles/rectangle.md)
for more details and examples.

- [`unnest_longer()`](https://tidyr.tidyverse.org/reference/unnest_longer.md)
  : Unnest a list-column into rows
- [`unnest_wider()`](https://tidyr.tidyverse.org/reference/unnest_wider.md)
  : Unnest a list-column into columns
- [`unnest()`](https://tidyr.tidyverse.org/reference/unnest.md) : Unnest
  a list-column of data frames into rows and columns
- [`hoist()`](https://tidyr.tidyverse.org/reference/hoist.md) : Hoist
  values out of list-columns

## Character vectors

Multiple variables are sometimes pasted together into a single column,
and these tools help you separate back out into individual columns.

- [`separate_longer_delim()`](https://tidyr.tidyverse.org/reference/separate_longer_delim.md)
  [`separate_longer_position()`](https://tidyr.tidyverse.org/reference/separate_longer_delim.md)
  **\[experimental\]** : Split a string into rows
- [`separate_wider_delim()`](https://tidyr.tidyverse.org/reference/separate_wider_delim.md)
  [`separate_wider_position()`](https://tidyr.tidyverse.org/reference/separate_wider_delim.md)
  [`separate_wider_regex()`](https://tidyr.tidyverse.org/reference/separate_wider_delim.md)
  **\[experimental\]** : Split a string into columns
- [`unite()`](https://tidyr.tidyverse.org/reference/unite.md) : Unite
  multiple columns into one by pasting strings together

## Missing values

Tools for converting between implicit (absent rows) and explicit (`NA`)
missing values, and for handling explicit `NA`s.

- [`complete()`](https://tidyr.tidyverse.org/reference/complete.md) :
  Complete a data frame with missing combinations of data
- [`drop_na()`](https://tidyr.tidyverse.org/reference/drop_na.md) : Drop
  rows containing missing values
- [`expand()`](https://tidyr.tidyverse.org/reference/expand.md)
  [`crossing()`](https://tidyr.tidyverse.org/reference/expand.md)
  [`nesting()`](https://tidyr.tidyverse.org/reference/expand.md) :
  Expand data frame to include all possible combinations of values
- [`expand_grid()`](https://tidyr.tidyverse.org/reference/expand_grid.md)
  : Create a tibble from all combinations of inputs
- [`fill()`](https://tidyr.tidyverse.org/reference/fill.md) : Fill in
  missing values with previous or next value
- [`full_seq()`](https://tidyr.tidyverse.org/reference/full_seq.md) :
  Create the full sequence of values in a vector
- [`replace_na()`](https://tidyr.tidyverse.org/reference/replace_na.md)
  : Replace NAs with specified values

## Miscellanea

- [`chop()`](https://tidyr.tidyverse.org/reference/chop.md)
  [`unchop()`](https://tidyr.tidyverse.org/reference/chop.md) : Chop and
  unchop
- [`pack()`](https://tidyr.tidyverse.org/reference/pack.md)
  [`unpack()`](https://tidyr.tidyverse.org/reference/pack.md) : Pack and
  unpack
- [`uncount()`](https://tidyr.tidyverse.org/reference/uncount.md) :
  "Uncount" a data frame
- [`nest()`](https://tidyr.tidyverse.org/reference/nest.md) : Nest rows
  into a list-column of data frames

## Data

- [`billboard`](https://tidyr.tidyverse.org/reference/billboard.md) :
  Song rankings for Billboard top 100 in the year 2000
- [`cms_patient_experience`](https://tidyr.tidyverse.org/reference/cms_patient_experience.md)
  [`cms_patient_care`](https://tidyr.tidyverse.org/reference/cms_patient_experience.md)
  : Data from the Centers for Medicare & Medicaid Services
- [`construction`](https://tidyr.tidyverse.org/reference/construction.md)
  : Completed construction in the US in 2018
- [`fish_encounters`](https://tidyr.tidyverse.org/reference/fish_encounters.md)
  : Fish encounters
- [`household`](https://tidyr.tidyverse.org/reference/household.md) :
  Household data
- [`relig_income`](https://tidyr.tidyverse.org/reference/relig_income.md)
  : Pew religion and income survey
- [`smiths`](https://tidyr.tidyverse.org/reference/smiths.md) : Some
  data about the Smith family
- [`table1`](https://tidyr.tidyverse.org/reference/table1.md)
  [`table2`](https://tidyr.tidyverse.org/reference/table1.md)
  [`table3`](https://tidyr.tidyverse.org/reference/table1.md)
  [`table4a`](https://tidyr.tidyverse.org/reference/table1.md)
  [`table4b`](https://tidyr.tidyverse.org/reference/table1.md)
  [`table5`](https://tidyr.tidyverse.org/reference/table1.md) : Example
  tabular representations
- [`us_rent_income`](https://tidyr.tidyverse.org/reference/us_rent_income.md)
  : US rent and income data
- [`who`](https://tidyr.tidyverse.org/reference/who.md)
  [`who2`](https://tidyr.tidyverse.org/reference/who.md)
  [`population`](https://tidyr.tidyverse.org/reference/who.md) : World
  Health Organization TB data
- [`world_bank_pop`](https://tidyr.tidyverse.org/reference/world_bank_pop.md)
  : Population data from the World Bank

## Superseded

Superseded functions have been replaced by superior solutions, but due
to their widespread use will not go away. However, they will not get any
new features and will only receive critical bug fixes.

- [`extract()`](https://tidyr.tidyverse.org/reference/extract.md)
  **\[superseded\]** : Extract a character column into multiple columns
  using regular expression groups

- [`separate()`](https://tidyr.tidyverse.org/reference/separate.md)
  **\[superseded\]** : Separate a character column into multiple columns
  with a regular expression or numeric locations

- [`separate_rows()`](https://tidyr.tidyverse.org/reference/separate_rows.md)
  **\[superseded\]** : Separate a collapsed column into multiple rows

- [`spread()`](https://tidyr.tidyverse.org/reference/spread.md)
  **\[superseded\]** : Spread a key-value pair across multiple columns

- [`gather()`](https://tidyr.tidyverse.org/reference/gather.md)
  **\[superseded\]** : Gather columns into key-value pairs

- [`nest_legacy()`](https://tidyr.tidyverse.org/reference/nest_legacy.md)
  [`unnest_legacy()`](https://tidyr.tidyverse.org/reference/nest_legacy.md)
  **\[superseded\]** :

  Legacy versions of
  [`nest()`](https://tidyr.tidyverse.org/reference/nest.md) and
  [`unnest()`](https://tidyr.tidyverse.org/reference/unnest.md)

# Articles

### Tidying tools

- [Pivoting](https://tidyr.tidyverse.org/articles/pivot.md):

  Learn how use the new
  [`pivot_longer()`](https://tidyr.tidyverse.org/reference/pivot_longer.md)
  and
  [`pivot_wider()`](https://tidyr.tidyverse.org/reference/pivot_wider.md)
  functions which change the representation of a dataset without
  changing the data it contains.

- [Rectangling](https://tidyr.tidyverse.org/articles/rectangle.md):

  Rectangling is the art and craft of taking a deeply nested list (often
  sourced from wild caught JSON or XML) and taming it into a tidy data
  set of rows and columns. This vignette introduces you to the main
  rectangling tools provided by tidyr:
  [`unnest_longer()`](https://tidyr.tidyverse.org/reference/unnest_longer.md),
  [`unnest_wider()`](https://tidyr.tidyverse.org/reference/unnest_wider.md),
  and [`hoist()`](https://tidyr.tidyverse.org/reference/hoist.md).

- [Nested data](https://tidyr.tidyverse.org/articles/nest.md):

  A nested data frame contains a list-column of data frames. It’s an
  alternative way of representing grouped data, that works particularly
  well when you’re modelling.

### Theory

- [Tidy data](https://tidyr.tidyverse.org/articles/tidy-data.md):

  A tidy dataset has variables in columns, observations in rows, and one
  value in each cell. This vignette introduces the theory of “tidy data”
  and shows you how it saves you time during data analysis.

### Developer

- [Programming with
  tidyr](https://tidyr.tidyverse.org/articles/programming.md):

  Notes on programming with tidy evaluation as it relates to tidyr.

- [In packages](https://tidyr.tidyverse.org/articles/in-packages.md):

  Things to bear in mind when using tidyr in a package.