tidyr (version 0.5.1)

gather: Gather columns into key-value pairs.


Gather takes multiple columns and collapses into key-value pairs, duplicating all other columns as needed. You use gather() when you notice that you have columns that are not variables.


gather(data, key, value, ..., na.rm = FALSE, convert = FALSE, factor_key = FALSE)


A data frame.
key, value
Names of key and value columns to create in output.
Specification of columns to gather. Use bare variable names. Select all variables between x and z with x:z, exclude y with -y. For more options, see the select documentation.
If TRUE, will remove rows from output where the value column in NA.
If TRUE will automatically run type.convert on the key column. This is useful if the column names are actually numeric, integer, or logical.
If FALSE, the default, the key values will be stored as a character vector. If TRUE, will be stored as a factor, which preserves the original ordering of the columns.

See Also

gather_ for a version that uses regular evaluation and is suitable for programming with.


# From http://stackoverflow.com/questions/1181060
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)

gather(stocks, stock, price, -time)
stocks %>% gather(stock, price, -time)

# get first observation for each Species in iris data -- base R
mini_iris <- iris[c(1, 51, 101), ]
# gather Sepal.Length, Sepal.Width, Petal.Length, Petal.Width
gather(mini_iris, key = flower_att, value = measurement,
       Sepal.Length, Sepal.Width, Petal.Length, Petal.Width)
# same result but less verbose
gather(mini_iris, key = flower_att, value = measurement, -Species)

# repeat iris example using dplyr and the pipe operator
mini_iris <-
  iris %>%
  group_by(Species) %>%
mini_iris %>% gather(key = flower_att, value = measurement, -Species)