gather {tidyr} | R Documentation |
Gather columns into key-value pairs
Description
Development on gather()
is complete, and for new code we recommend
switching to pivot_longer()
, which is easier to use, more featureful, and
still under active development.
df %>% gather("key", "value", x, y, z)
is equivalent to
df %>% pivot_longer(c(x, y, z), names_to = "key", values_to = "value")
See more details in vignette("pivot")
.
Usage
gather(
data,
key = "key",
value = "value",
...,
na.rm = FALSE,
convert = FALSE,
factor_key = FALSE
)
Arguments
data |
A data frame. |
key , value |
Names of new key and value columns, as strings or symbols. This argument is passed by expression and supports
quasiquotation (you can unquote strings
and symbols). The name is captured from the expression with
|
... |
A selection of columns. If empty, all variables are
selected. You can supply bare variable names, select all
variables between x and z with |
na.rm |
If |
convert |
If |
factor_key |
If |
Rules for selection
Arguments for selecting columns are passed to tidyselect::vars_select()
and are treated specially. Unlike other verbs, selecting functions make a
strict distinction between data expressions and context expressions.
A data expression is either a bare name like
x
or an expression likex:y
orc(x, y)
. In a data expression, you can only refer to columns from the data frame.Everything else is a context expression in which you can only refer to objects that you have defined with
<-
.
For instance, col1:col3
is a data expression that refers to data
columns, while seq(start, end)
is a context expression that
refers to objects from the contexts.
If you need to refer to contextual objects from a data expression, you can
use all_of()
or any_of()
. These functions are used to select
data-variables whose names are stored in a env-variable. For instance,
all_of(a)
selects the variables listed in the character vector a
.
For more details, see the tidyselect::select_helpers()
documentation.
Examples
# From https://stackoverflow.com/questions/1181060
stocks <- tibble(
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)