cbind                  package:base                  R Documentation

_C_o_m_b_i_n_e _R _O_b_j_e_c_t_s _b_y _R_o_w_s _o_r _C_o_l_u_m_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Take a sequence of vector, matrix or data frames arguments and
     combine by _c_olumns or _r_ows, respectively.  These are generic
     functions with methods for other R classes.

_U_s_a_g_e:

     cbind(..., deparse.level = 1)
     rbind(..., deparse.level = 1)

_A_r_g_u_m_e_n_t_s:

     ...: vectors or matrices.  These can be given as named arguments. 
          Other R objects will be coerced as appropriate: see sections
          'Details' and 'Value'.  (For the '"data.frame"' method of
          'cbind' these can be further arguments to 'data.frame' such
          as 'stringsAsFactors'.)

deparse.level: integer controlling the construction of labels in the
          case of non-matrix-like arguments (for the default method):
           'deparse.level = 0' constructs no labels; the default,
          'deparse.level = 1 or 2' constructs labels from the argument
          names, see the 'Value' section below.

_D_e_t_a_i_l_s:

     The functions 'cbind' and '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 'Dispatch' for how the method
     to be used is selected.

     In the default method, all the vectors/matrices must be atomic
     (see '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 'warning' if they are recycled only
     _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 'cbind' ('rbind'), vectors of zero length (including '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.)

_V_a_l_u_e:

     For the default method, a matrix combining the '...' arguments
     column-wise or row-wise.  (Exception: if there are no inputs or
     all the inputs are 'NULL', the value is 'NULL'.)

     The type of a matrix result determined from the highest type of
     any of the inputs in the hierarchy raw < logical < integer < real
     < complex < character < list .

     For 'cbind' ('rbind') the column (row) names are taken from the
     'colnames' ('rownames') of the arguments if these are matrix-like.
      Otherwise from the names of the arguments or where those are not
     supplied and 'deparse.level > 0', by deparsing the expressions
     given, for 'deparse.level = 1' only if that gives a sensible name
     (a 'symbol', see 'is.symbol').

     For '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 '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.

_D_a_t_a _f_r_a_m_e _m_e_t_h_o_d_s:

     The 'cbind' data frame method is just a wrapper for
     'data.frame(..., check.names = FALSE)'.  This means that it will
     split matrix columns in data frame arguments, and convert
     character columns to factors unless 'stringsAsFactors = FALSE' is
     specified.

     The '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 levelsets 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.

_D_i_s_p_a_t_c_h:

     The method dispatching is _not_ done via 'UseMethod()', but by
     C-internal dispatching. Therefore there is no need for, e.g.,
     'rbind.default'.

     The dispatch algorithm is described in the source file
     ('.../src/main/bind.c') as


        1.  For each argument we get the list of possible class
           memberships from the class attribute.

        2.  We inspect each class in turn to see if there is an
           applicable method.

        3.  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.)

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'c' to combine vectors (and lists) as vectors, 'data.frame' to
     combine vectors and matrices as a data frame.

_E_x_a_m_p_l_e_s:

     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