| % File src/library/base/man/cbind.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2019 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{cbind} |
| \alias{cbind}%%--do C-internal method dispatching !! |
| \alias{rbind} |
| \alias{cbind.data.frame} |
| \alias{rbind.data.frame} |
| \alias{.__H__.cbind} |
| \alias{.__H__.rbind} |
| \concept{insert} |
| \title{Combine R Objects by Rows or Columns} |
| \description{ |
| Take a sequence of vector, matrix or data-frame arguments and combine |
| by \emph{c}olumns or \emph{r}ows, respectively. These are generic |
| functions with methods for other \R classes. |
| } |
| \usage{ |
| cbind(\dots, deparse.level = 1) |
| rbind(\dots, deparse.level = 1) |
| \method{rbind}{data.frame}(\dots, deparse.level = 1, make.row.names = TRUE, |
| stringsAsFactors = default.stringsAsFactors(), factor.exclude = NA) |
| } |
| \arguments{ |
| \item{\dots}{(generalized) vectors or matrices. These can be given as named |
| arguments. Other \R objects may be coerced as appropriate, or S4 |
| methods may be used: see sections \sQuote{Details} and |
| \sQuote{Value}. (For the \code{"data.frame"} method of \code{cbind} |
| these can be further arguments to \code{\link{data.frame}} such as |
| \code{stringsAsFactors}.)} |
| \item{deparse.level}{integer controlling the construction of labels in |
| the case of non-matrix-like arguments (for the default method):\cr |
| \code{deparse.level = 0} constructs no labels; the default,\cr |
| \code{deparse.level = 1 or 2} constructs labels from the argument |
| names, see the \sQuote{Value} section below.} |
| \item{make.row.names}{(only for data frame method:) logical |
| indicating if unique and valid \code{\link{row.names}} should be |
| constructed from the arguments.} |
| \item{stringsAsFactors}{logical, passed to \code{\link{as.data.frame}}; |
| only has an effect when the \code{\dots} arguments contain a |
| (non-\code{data.frame}) \code{\link{character}}.} |
| \item{factor.exclude}{if the data frames contain factors, |
| \code{TRUE} ensures that \code{NA} levels of factors are kept, see |
| \PR{17562} and the \sQuote{Data frame methods}. In \R versions up |
| to 3.6.x, \code{factor.exclude = NA} has been implicitly hardcoded |
| (\R <= 3.6.0) or the default (\R = 3.6.x, x >= 1).} |
| } |
| \details{ |
| The functions \code{cbind} and \code{rbind} are S3 generic, with |
| methods for data frames. The data frame method will be used if at |
| least one argument is a data frame and the rest are vectors or |
| matrices. There can be other methods; in particular, there is one for |
| time series objects. See the section on \sQuote{Dispatch} for how |
| the method to be used is selected. If some of the arguments are of an |
| S4 class, i.e., \code{\link{isS4}(.)} is true, S4 methods are sought |
| also, and the hidden \code{cbind} / \code{rbind} functions |
| from package \pkg{methods} maybe called, which in turn build on |
| \code{\link{cbind2}} or \code{\link{rbind2}}, respectively. In that |
| case, \code{deparse.level} is obeyed, similarly to the default method. |
| |
| In the default method, all the vectors/matrices must be atomic (see |
| \code{\link{vector}}) or lists. Expressions are not allowed. |
| Language objects (such as formulae and calls) and pairlists will be |
| coerced to lists: other objects (such as names and external pointers) |
| will be included as elements in a list result. Any classes the inputs |
| might have are discarded (in particular, factors are replaced by their |
| internal codes). |
| |
| If there are several matrix arguments, they must all have the same |
| number of columns (or rows) and this will be the number of columns (or |
| rows) of the result. If all the arguments are vectors, the number of |
| columns (rows) in the result is equal to the length of the longest |
| vector. Values in shorter arguments are recycled to achieve this |
| length (with a \code{\link{warning}} if they are recycled only |
| \emph{fractionally}). |
| |
| When the arguments consist of a mix of matrices and vectors the number |
| of columns (rows) of the result is determined by the number of columns |
| (rows) of the matrix arguments. Any vectors have their values |
| recycled or subsetted to achieve this length. |
| |
| For \code{cbind} (\code{rbind}), vectors of zero length (including |
| \code{NULL}) are ignored unless the result would have zero rows |
| (columns), for S compatibility. |
| (Zero-extent matrices do not occur in S3 and are not ignored in \R.) |
| |
| Matrices are restricted to less than \eqn{2^{31}}{2^31} rows and |
| columns even on 64-bit systems. So input vectors have the same length |
| restriction: as from \R 3.2.0 input matrices with more elements (but |
| meeting the row and column restrictions) are allowed. |
| } |
| \section{Data frame methods}{ |
| The \code{cbind} data frame method is just a wrapper for |
| \code{\link{data.frame}(..., check.names = FALSE)}. This means that |
| it will split matrix columns in data frame arguments, and convert |
| character columns to factors unless \code{stringsAsFactors = FALSE} is |
| specified. |
| |
| The \code{rbind} data frame method first drops all zero-column and |
| zero-row arguments. (If that leaves none, it returns the first |
| argument with columns otherwise a zero-column zero-row data frame.) |
| It then takes the classes of the columns from the |
| first data frame, and matches columns by name (rather than by |
| position). Factors have their levels expanded as necessary (in the |
| order of the levels of the level sets of the factors encountered) and |
| the result is an ordered factor if and only if all the components were |
| ordered factors. (The last point differs from S-PLUS.) Old-style |
| categories (integer vectors with levels) are promoted to factors. |
| |
| Note that for result column \code{j}, \code{\link{factor}(., exclude = X(j))} |
| is applied, where \preformatted{ X(j) := if(isTRUE(factor.exclude)) { |
| if(!NA.lev[j]) NA # else NULL |
| } else factor.exclude} |
| |
| where \code{NA.lev[j]} is true iff any contributing data frame has had a |
| \code{\link{factor}} in column \code{j} with an explicit \code{NA} level. |
| } |
| \value{ |
| For the default method, a matrix combining the \code{\dots} arguments |
| column-wise or row-wise. (Exception: if there are no inputs or all |
| the inputs are \code{NULL}, the value is \code{NULL}.) |
| |
| The type of a matrix result determined from the highest type of any of |
| the inputs in the hierarchy raw < logical < integer < double < complex < |
| character < list . |
| |
| For \code{cbind} (\code{rbind}) the column (row) names are taken from |
| the \code{colnames} (\code{rownames}) of the arguments if these are |
| matrix-like. Otherwise from the names of the arguments or where those |
| are not supplied and \code{deparse.level > 0}, by deparsing the |
| expressions given, for \code{deparse.level = 1} only if that gives a |
| sensible name (a \sQuote{symbol}, see \code{\link{is.symbol}}). |
| |
| For \code{cbind} row names are taken from the first argument with |
| appropriate names: rownames for a matrix, or names for a vector of |
| length the number of rows of the result. |
| |
| For \code{rbind} column names are taken from the first argument with |
| appropriate names: colnames for a matrix, or names for a vector of |
| length the number of columns of the result. |
| } |
| \section{Dispatch}{ |
| The method dispatching is \emph{not} done via |
| \code{\link{UseMethod}()}, but by C-internal dispatching. |
| Therefore there is no need for, e.g., \code{rbind.default}. |
| |
| The dispatch algorithm is described in the source file |
| (\file{.../src/main/bind.c}) as |
| |
| \enumerate{ |
| \item For each argument we get the list of possible class |
| memberships from the class attribute. |
| |
| \item We inspect each class in turn to see if there is an |
| applicable method. |
| |
| \item If we find an applicable method we make sure that it is |
| identical to any method determined for prior arguments. |
| If it is identical, we proceed, otherwise we immediately |
| drop through to the default code. |
| } |
| If you want to combine other objects with data frames, it may be |
| necessary to coerce them to data frames first. (Note that this |
| algorithm can result in calling the data frame method if all the |
| arguments are either data frames or vectors, and this will result in |
| the coercion of character vectors to factors.) |
| } |
| \references{ |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| } |
| \seealso{ |
| \code{\link{c}} to combine vectors (and lists) as vectors, |
| \code{\link{data.frame}} to combine vectors and matrices as a data |
| frame. |
| } |
| \examples{ |
| m <- cbind(1, 1:7) # the '1' (= shorter vector) is recycled |
| m |
| m <- cbind(m, 8:14)[, c(1, 3, 2)] # insert a column |
| m |
| cbind(1:7, diag(3)) # vector is subset -> warning |
| |
| cbind(0, rbind(1, 1:3)) |
| cbind(I = 0, X = rbind(a = 1, b = 1:3)) # use some names |
| xx <- data.frame(I = rep(0,2)) |
| cbind(xx, X = rbind(a = 1, b = 1:3)) # named differently |
| |
| cbind(0, matrix(1, nrow = 0, ncol = 4)) #> Warning (making sense) |
| dim(cbind(0, matrix(1, nrow = 2, ncol = 0))) #-> 2 x 1 |
| |
| ## deparse.level |
| dd <- 10 |
| rbind(1:4, c = 2, "a++" = 10, dd, deparse.level = 0) # middle 2 rownames |
| rbind(1:4, c = 2, "a++" = 10, dd, deparse.level = 1) # 3 rownames (default) |
| rbind(1:4, c = 2, "a++" = 10, dd, deparse.level = 2) # 4 rownames |
| |
| ## cheap row names: |
| b0 <- gl(3,4, labels=letters[1:3]) |
| bf <- setNames(b0, paste0("o", seq_along(b0))) |
| df <- data.frame(a = 1, B = b0, f = gl(4,3)) |
| df. <- data.frame(a = 1, B = bf, f = gl(4,3)) |
| new <- data.frame(a = 8, B ="B", f = "1") |
| (df1 <- rbind(df , new)) |
| (df.1 <- rbind(df., new)) |
| stopifnot(identical(df1, rbind(df, new, make.row.names=FALSE)), |
| identical(df1, rbind(df., new, make.row.names=FALSE))) |
| \dontshow{ |
| ## Testing a semi-official use: |
| d2 <- rbind.data.frame(as.list(df), as.list(new)) |
| d3 <- rbind.data.frame(as.list(df), as.list(new), make.row.names=FALSE) |
| stopifnot(identical(.row_names_info(d3), -13L)) |
| ## no longer: attr(d2, "row.names")[c(1,13)] == c("13", "131") |
| row.names(d2) <- attr(d3, "row.names")# = 1:13 |
| stopifnot(identical(d2, d3)) |
| } |
| } |
| \keyword{array} |
| \keyword{manip} |