EVOLUTION-MANAGER
Edit File: gather.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Gather columns into key-value pairs</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for gather {tidyr}"><tr><td>gather {tidyr}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Gather columns into key-value pairs</h2> <h3>Description</h3> <a href='https://www.tidyverse.org/lifecycle/#retired'><img src='figures/lifecycle-retired.svg' alt='Retired lifecycle'></a> <p>Development on <code>gather()</code> is complete, and for new code we recommend switching to <code>pivot_longer()</code>, which is easier to use, more featureful, and still under active development. <code>df %>% gather("key", "value", x, y, z)</code> is equivalent to <code>df %>% pivot_longer(c(x, y, z), names_to = "key", values_to = "value")</code> </p> <p>See more details in <code>vignette("pivot")</code>. </p> <h3>Usage</h3> <pre> gather( data, key = "key", value = "value", ..., na.rm = FALSE, convert = FALSE, factor_key = FALSE ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>data</code></td> <td> <p>A data frame.</p> </td></tr> <tr valign="top"><td><code>key, value</code></td> <td> <p>Names of new key and value columns, as strings or symbols. </p> <p>This argument is passed by expression and supports <a href="../../rlang/html/nse-force.html">quasiquotation</a> (you can unquote strings and symbols). The name is captured from the expression with <code><a href="../../rlang/html/nse-defuse.html">rlang::ensym()</a></code> (note that this kind of interface where symbols do not represent actual objects is now discouraged in the tidyverse; we support it here for backward compatibility).</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>A selection of columns. If empty, all variables are selected. You can supply bare variable names, select all variables between x and z with <code>x:z</code>, exclude y with <code>-y</code>. For more options, see the <code><a href="../../dplyr/html/select.html">dplyr::select()</a></code> documentation. See also the section on selection rules below.</p> </td></tr> <tr valign="top"><td><code>na.rm</code></td> <td> <p>If <code>TRUE</code>, will remove rows from output where the value column is <code>NA</code>.</p> </td></tr> <tr valign="top"><td><code>convert</code></td> <td> <p>If <code>TRUE</code> will automatically run <code><a href="../../utils/html/type.convert.html">type.convert()</a></code> on the key column. This is useful if the column types are actually numeric, integer, or logical.</p> </td></tr> <tr valign="top"><td><code>factor_key</code></td> <td> <p>If <code>FALSE</code>, the default, the key values will be stored as a character vector. If <code>TRUE</code>, will be stored as a factor, which preserves the original ordering of the columns.</p> </td></tr> </table> <h3>Rules for selection</h3> <p>Arguments for selecting columns are passed to <code><a href="../../tidyselect/html/vars_select.html">tidyselect::vars_select()</a></code> and are treated specially. Unlike other verbs, selecting functions make a strict distinction between data expressions and context expressions. </p> <ul> <li><p> A data expression is either a bare name like <code>x</code> or an expression like <code>x:y</code> or <code>c(x, y)</code>. In a data expression, you can only refer to columns from the data frame. </p> </li> <li><p> Everything else is a context expression in which you can only refer to objects that you have defined with <code style="white-space: pre;"><-</code>. </p> </li></ul> <p>For instance, <code>col1:col3</code> is a data expression that refers to data columns, while <code>seq(start, end)</code> is a context expression that refers to objects from the contexts. </p> <p>If you need to refer to contextual objects from a data expression, you can use <code>all_of()</code> or <code>any_of()</code>. These functions are used to select data-variables whose names are stored in a env-variable. For instance, <code>all_of(a)</code> selects the variables listed in the character vector <code>a</code>. For more details, see the <code><a href="../../tidyselect/html/language.html">tidyselect::select_helpers()</a></code> documentation. </p> <h3>Examples</h3> <pre> library(dplyr) # 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) # repeat iris example using dplyr and the pipe operator library(dplyr) mini_iris <- iris %>% group_by(Species) %>% slice(1) mini_iris %>% gather(key = "flower_att", value = "measurement", -Species) </pre> <hr /><div style="text-align: center;">[Package <em>tidyr</em> version 1.1.2 <a href="00Index.html">Index</a>]</div> </body></html>