R: Combine two Objects by Columns or Rows

cbind2 {methods} | R Documentation

## Combine two Objects by Columns or Rows

### Description

Combine two matrix-like R objects by columns (`cbind2`) or rows (`rbind2`). These are (S4) generic functions with default methods.

### Usage

    cbind2(x, y, ...)
    rbind2(x, y, ...)

### Arguments

`x` | any R object, typically matrix-like.
`y` | any R object, typically similar to `x`, or missing completely.
`...` | optional arguments for methods.

### Details

The main use of `cbind2` (`rbind2`) is to be called recursively by `cbind()` (`rbind()`) when both of these requirements are met:

- There is at least one argument that is an S4 object, and

- S3 dispatch fails (see the Dispatch section under cbind).

The methods on `cbind2` and `rbind2` effectively define the type promotion policy when combining a heterogeneous set of arguments. The homogeneous case, where all objects derive from some S4 class, can be handled via S4 dispatch on the `...` argument via an externally defined S4 `cbind` (`rbind`) generic.

Since (for legacy reasons) S3 dispatch is attempted first, it is generally a good idea to additionally define an S3 method on `cbind` (`rbind`) for the S4 class. The S3 method will be invoked when the arguments include objects of the S4 class, along with arguments of classes for which no S3 method exists. Also, in case there is an argument that selects a different S3 method (like the one for `data.frame`), this S3 method serves to introduce an ambiguity in dispatch that triggers the recursive fallback to `cbind2` (`rbind2`). Otherwise, the other S3 method would be called, which may not be appropriate.

### Value

A matrix (or matrix like object) combining the columns (or rows) of `x` and `y`. Note that methods must construct `colnames` and `rownames` from the corresponding column and row names of `x` and `y` (but not from deparsing argument names such as in `cbind(..., deparse.level = d)` for d >= 1).

### Methods

`signature(x = "ANY", y = "ANY")`

  the default method using R's internal code.

`signature(x = "ANY", y = "missing")`

  the default method for one argument using R's internal code.

### See Also

`cbind`, `rbind`; further, `cBind`, `rBind` in the Matrix package.

### Examples

    cbind2(1:3, 4)
    m <- matrix(3:8, 2,3, dimnames=list(c("a","b"), LETTERS[1:3]))
    cbind2(1:2, m) # keeps dimnames from m

    ## rbind() and cbind() now make use of rbind2()/cbind2() methods
    setClass("Num", contains="numeric")
    setMethod("cbind2", c("Num", "missing"),
              function(x,y, ...) { cat("Num-miss--meth\n"); as.matrix(x)})
    setMethod("cbind2", c("Num","ANY"), function(x,y, ...) {
        cat("Num-A.--method\n") ; cbind(getDataPart(x), y, ...) })
    setMethod("cbind2", c("ANY","Num"), function(x,y, ...) {
        cat("A.-Num--method\n") ; cbind(x, getDataPart(y), ...) })

    a <- new("Num", 1:3)
    trace("cbind2")
    cbind(a)
    cbind(a, four=4, 7:9)# calling cbind2() twice

    cbind(m,a, ch=c("D","E"), a*3)
    cbind(1,a, m) # ok with a warning
    untrace("cbind2")

[Package methods version 4.0.5 Index]