EVOLUTION-MANAGER
Edit File: vec_bind.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: Combine many data frames into one data frame</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 vec_bind {vctrs}"><tr><td>vec_bind {vctrs}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Combine many data frames into one data frame</h2> <h3>Description</h3> <p>This pair of functions binds together data frames (and vectors), either row-wise or column-wise. Row-binding creates a data frame with common type across all arguments. Column-binding creates a data frame with common length across all arguments. </p> <h3>Usage</h3> <pre> vec_rbind( ..., .ptype = NULL, .names_to = rlang::zap(), .name_repair = c("unique", "universal", "check_unique", "unique_quiet", "universal_quiet"), .name_spec = NULL, .error_call = current_env() ) vec_cbind( ..., .ptype = NULL, .size = NULL, .name_repair = c("unique", "universal", "check_unique", "minimal", "unique_quiet", "universal_quiet"), .error_call = current_env() ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>...</code></td> <td> <p>Data frames or vectors. </p> <p>When the inputs are named: </p> <ul> <li> <p><code>vec_rbind()</code> assigns names to row names unless <code>.names_to</code> is supplied. In that case the names are assigned in the column defined by <code>.names_to</code>. </p> </li> <li> <p><code>vec_cbind()</code> creates packed data frame columns with named inputs. </p> </li></ul> <p><code>NULL</code> inputs are silently ignored. Empty (e.g. zero row) inputs will not appear in the output, but will affect the derived <code>.ptype</code>.</p> </td></tr> <tr valign="top"><td><code>.ptype</code></td> <td> <p>If <code>NULL</code>, the default, the output type is determined by computing the common type across all elements of <code>...</code>. </p> <p>Alternatively, you can supply <code>.ptype</code> to give the output known type. If <code>getOption("vctrs.no_guessing")</code> is <code>TRUE</code> you must supply this value: this is a convenient way to make production code demand fixed types.</p> </td></tr> <tr valign="top"><td><code>.names_to</code></td> <td> <p>This controls what to do with input names supplied in <code>...</code>. </p> <ul> <li><p> By default, input names are <a href="../../rlang/html/zap.html">zapped</a>. </p> </li> <li><p> If a string, specifies a column where the input names will be copied. These names are often useful to identify rows with their original input. If a column name is supplied and <code>...</code> is not named, an integer column is used instead. </p> </li> <li><p> If <code>NULL</code>, the input names are used as row names. </p> </li></ul> </td></tr> <tr valign="top"><td><code>.name_repair</code></td> <td> <p>One of <code>"unique"</code>, <code>"universal"</code>, <code>"check_unique"</code>, <code>"unique_quiet"</code>, or <code>"universal_quiet"</code>. See <code><a href="vec_as_names.html">vec_as_names()</a></code> for the meaning of these options. </p> <p>With <code>vec_rbind()</code>, the repair function is applied to all inputs separately. This is because <code>vec_rbind()</code> needs to align their columns before binding the rows, and thus needs all inputs to have unique names. On the other hand, <code>vec_cbind()</code> applies the repair function after all inputs have been concatenated together in a final data frame. Hence <code>vec_cbind()</code> allows the more permissive minimal names repair.</p> </td></tr> <tr valign="top"><td><code>.name_spec</code></td> <td> <p>A name specification (as documented in <code><a href="vec_c.html">vec_c()</a></code>) for combining the outer inputs names in <code>...</code> and the inner row names of the inputs. This only has an effect when <code>.names_to</code> is set to <code>NULL</code>, which causes the input names to be assigned as row names.</p> </td></tr> <tr valign="top"><td><code>.error_call</code></td> <td> <p>The execution environment of a currently running function, e.g. <code>caller_env()</code>. The function will be mentioned in error messages as the source of the error. See the <code>call</code> argument of <code><a href="../../rlang/html/abort.html">abort()</a></code> for more information.</p> </td></tr> <tr valign="top"><td><code>.size</code></td> <td> <p>If, <code>NULL</code>, the default, will determine the number of rows in <code>vec_cbind()</code> output by using the tidyverse <a href="vector_recycling_rules.html">recycling rules</a>. </p> <p>Alternatively, specify the desired number of rows, and any inputs of length 1 will be recycled appropriately.</p> </td></tr> </table> <h3>Value</h3> <p>A data frame, or subclass of data frame. </p> <p>If <code>...</code> is a mix of different data frame subclasses, <code>vec_ptype2()</code> will be used to determine the output type. For <code>vec_rbind()</code>, this will determine the type of the container and the type of each column; for <code>vec_cbind()</code> it only determines the type of the output container. If there are no non-<code>NULL</code> inputs, the result will be <code>data.frame()</code>. </p> <h3>Invariants</h3> <p>All inputs are first converted to a data frame. The conversion for 1d vectors depends on the direction of binding: </p> <ul> <li><p> For <code>vec_rbind()</code>, each element of the vector becomes a column in a single row. </p> </li> <li><p> For <code>vec_cbind()</code>, each element of the vector becomes a row in a single column. </p> </li></ul> <p>Once the inputs have all become data frames, the following invariants are observed for row-binding: </p> <ul> <li> <p><code>vec_size(vec_rbind(x, y)) == vec_size(x) + vec_size(y)</code> </p> </li> <li> <p><code>vec_ptype(vec_rbind(x, y)) = vec_ptype_common(x, y)</code> </p> </li></ul> <p>Note that if an input is an empty vector, it is first converted to a 1-row data frame with 0 columns. Despite being empty, its effective size for the total number of rows is 1. </p> <p>For column-binding, the following invariants apply: </p> <ul> <li> <p><code>vec_size(vec_cbind(x, y)) == vec_size_common(x, y)</code> </p> </li> <li> <p><code>vec_ptype(vec_cbind(x, y)) == vec_cbind(vec_ptype(x), vec_ptype(x))</code> </p> </li></ul> <h3>Dependencies</h3> <h4>vctrs dependencies</h4> <ul> <li> <p><code><a href="vec_cast.html">vec_cast_common()</a></code> </p> </li> <li> <p><code><a href="vec_proxy.html">vec_proxy()</a></code> </p> </li> <li> <p><code><a href="vec_init.html">vec_init()</a></code> </p> </li> <li> <p><code><a href="vec_slice.html">vec_assign()</a></code> </p> </li> <li> <p><code><a href="vec_proxy.html">vec_restore()</a></code> </p> </li></ul> <h4>base dependencies of <code>vec_rbind()</code></h4> <ul> <li> <p><code><a href="../../base/html/c.html">base::c()</a></code> </p> </li></ul> <p>If columns to combine inherit from a common class, <code>vec_rbind()</code> falls back to <code>base::c()</code> if there exists a <code>c()</code> method implemented for this class hierarchy. </p> <h3>See Also</h3> <p><code><a href="vec_c.html">vec_c()</a></code> for combining 1d vectors. </p> <h3>Examples</h3> <pre> # row binding ----------------------------------------- # common columns are coerced to common class vec_rbind( data.frame(x = 1), data.frame(x = FALSE) ) # unique columns are filled with NAs vec_rbind( data.frame(x = 1), data.frame(y = "x") ) # null inputs are ignored vec_rbind( data.frame(x = 1), NULL, data.frame(x = 2) ) # bare vectors are treated as rows vec_rbind( c(x = 1, y = 2), c(x = 3) ) # default names will be supplied if arguments are not named vec_rbind( 1:2, 1:3, 1:4 ) # column binding -------------------------------------- # each input is recycled to have common length vec_cbind( data.frame(x = 1), data.frame(y = 1:3) ) # bare vectors are treated as columns vec_cbind( data.frame(x = 1), y = letters[1:3] ) # if you supply a named data frame, it is packed in a single column data <- vec_cbind( x = data.frame(a = 1, b = 2), y = 1 ) data # Packed data frames are nested in a single column. This makes it # possible to access it through a single name: data$x # since the base print method is suboptimal with packed data # frames, it is recommended to use tibble to work with these: if (rlang::is_installed("tibble")) { vec_cbind(x = tibble::tibble(a = 1, b = 2), y = 1) } # duplicate names are flagged vec_cbind(x = 1, x = 2) </pre> <hr /><div style="text-align: center;">[Package <em>vctrs</em> version 0.5.0 <a href="00Index.html">Index</a>]</div> </body></html>