Spread a key-value pair across multiple columns

Development on spread() is complete, and for new code we recommend switching to pivot_wider(), which is easier to use, more featureful, and still under active development. df %>% spread(key, value) is equivalent to df %>% pivot_wider(names_from = key, values_from = value)

See more details in vignette("pivot").

spread(data, key, value, fill = NA, convert = FALSE, drop = TRUE,
  sep = NULL)

Arguments

data	A data frame.
key, value	Column names or positions. This is passed to tidyselect::vars_pull(). These arguments are passed by expression and support quasiquotation (you can unquote column names or column positions).
fill	If set, missing values will be replaced with this value. Note that there are two types of missingness in the input: explicit missing values (i.e. NA), and implicit missings, rows that simply aren't present. Both types of missing value will be replaced by fill.
convert	If TRUE, type.convert() with asis = TRUE will be run on each of the new columns. This is useful if the value column was a mix of variables that was coerced to a string. If the class of the value column was factor or date, note that will not be true of the new columns that are produced, which are coerced to character before type conversion.
drop	If FALSE, will keep factor levels that don't appear in the data, filling in missing combinations with fill.
sep	If NULL, the column names will be taken from the values of key variable. If non-NULL, the column names will be given by "<key_name><sep><key_value>".

Examples

library(dplyr)
stocks <- data.frame(
  time = as.Date('2009-01-01') + 0:9,
  X = rnorm(10, 0, 1),
  Y = rnorm(10, 0, 2),
  Z = rnorm(10, 0, 4)
)
stocksm <- stocks %>% gather(stock, price, -time)
stocksm %>% spread(stock, price)
#>          time           X             Y          Z
#> 1  2009-01-01 -1.56651447  1.9526835441 -3.4428971
#> 2  2009-01-02 -1.04057911  2.2930009979  1.6849217
#> 3  2009-01-03  1.01993374  2.4345433749  5.8021729
#> 4  2009-01-04 -0.70208198  0.0009600261  0.7775698
#> 5  2009-01-05  0.97331578  1.5102501123 -2.7648217
#> 6  2009-01-06 -0.07681765  0.6848070209  5.3594397
#> 7  2009-01-07  0.89292492  0.3369456486 10.9444338
#> 8  2009-01-08 -0.77750309  2.7941330176 -3.7764066
#> 9  2009-01-09  0.43679711 -1.3581908643 -7.1242477
#> 10 2009-01-10  0.41344393  1.4752588960 -2.8642347
stocksm %>% spread(time, price)
#>   stock 2009-01-01 2009-01-02 2009-01-03    2009-01-04 2009-01-05  2009-01-06
#> 1     X  -1.566514  -1.040579   1.019934 -0.7020819780  0.9733158 -0.07681765
#> 2     Y   1.952684   2.293001   2.434543  0.0009600261  1.5102501  0.68480702
#> 3     Z  -3.442897   1.684922   5.802173  0.7775697701 -2.7648217  5.35943967
#>   2009-01-07 2009-01-08 2009-01-09 2009-01-10
#> 1  0.8929249 -0.7775031  0.4367971  0.4134439
#> 2  0.3369456  2.7941330 -1.3581909  1.4752589
#> 3 10.9444338 -3.7764066 -7.1242477 -2.8642347

# Spread and gather are complements
df <- data.frame(x = c("a", "b"), y = c(3, 4), z = c(5, 6))
df %>% spread(x, y) %>% gather("x", "y", a:b, na.rm = TRUE)
#>   z x y
#> 1 5 a 3
#> 4 6 b 4

# Use 'convert = TRUE' to produce variables of mixed type
df <- data.frame(row = rep(c(1, 51), each = 3),
                 var = c("Sepal.Length", "Species", "Species_num"),
                 value = c(5.1, "setosa", 1, 7.0, "versicolor", 2))
df %>% spread(var, value) %>% str
#> 'data.frame':	2 obs. of  4 variables:
#>  $ row         : num  1 51
#>  $ Sepal.Length: Factor w/ 6 levels "1","2","5.1",..: 3 4
#>  $ Species     : Factor w/ 6 levels "1","2","5.1",..: 5 6
#>  $ Species_num : Factor w/ 6 levels "1","2","5.1",..: 1 2
df %>% spread(var, value, convert = TRUE) %>% str
#> 'data.frame':	2 obs. of  4 variables:
#>  $ row         : num  1 51
#>  $ Sepal.Length: num  5.1 7
#>  $ Species     : chr  "setosa" "versicolor"
#>  $ Species_num : int  1 2