R: 'cbind()' and 'rbind()' recursively built on cbind2/rbind2

cBind {Matrix} | R Documentation

## 'cbind()' and 'rbind()' recursively built on cbind2/rbind2

### Description

The base functions `cbind` and `rbind` are defined for an arbitrary number of arguments and hence have the first formal argument `...`. Now, when S4 objects are found among the arguments, base `cbind()` and `rbind()` internally “dispatch” recursively, calling `cbind2` or `rbind2` respectively, where these have methods defined and so should dispatch appropriately.

`cbind2()` and `rbind2()` are from the methods package, i.e., standard R, and have been provided for binding together two matrices, where in Matrix, we have defined methods for these and the `'Matrix'` matrices.

### Usage

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

    ## and e.g.,
    ## S4 method for signature 'denseMatrix,sparseMatrix'
    cbind2(x,y, sparse = NA, ...)
    ## S4 method for signature 'sparseMatrix,denseMatrix'
    cbind2(x,y, sparse = NA, ...)
    ## S4 method for signature 'denseMatrix,sparseMatrix'
    rbind2(x,y, sparse = NA, ...)
    ## S4 method for signature 'sparseMatrix,denseMatrix'
    rbind2(x,y, sparse = NA, ...)

### Arguments

`..., x, y` | matrix-like R objects to be bound together, see `cbind` and `rbind`.
`sparse` | option `logical` indicating if the result should be sparse, i.e., formally inheriting from `"sparseMatrix"`. The default, `NA`, decides from the “sparsity” of `x` and `y`, see e.g., the R code in `selectMethod(cbind2, c("sparseMatrix","denseMatrix"))`.
`deparse.level` | integer determining under which circumstances column and row names are built from the actual arguments' ‘expression’, see `cbind`.

### Value

typically a ‘matrix-like’ object of a similar `class` as the first argument in `...`.

Note that sometimes by default, the result is a `sparseMatrix` if one of the arguments is (even in the case where this is not efficient). In other cases, the result is chosen to be sparse when there are more zero entries is than non-zero ones (as the default `sparse` in `Matrix()`).

### Historical Remark

Before R version 3.2.0 (April 2015), we have needed a substitute for S4-enabled versions of `cbind` and `rbind`, and provided `cBind` and `rBind` with identical syntax and semantic in order to bind together multiple matrices (`"matrix"` or `"Matrix"` and vectors. With R version 3.2.0 and newer, `cBind` and `rBind` are deprecated and produce a deprecation warning (via `.Deprecated`), and your code should start using `cbind()` and `rbind()` instead.

### Author(s)

Martin Maechler

### See Also

`cbind2`, `cbind`, Documentation in base R's methods package.

Our class definition help pages mentioning `cbind2()` and `rbind2()` methods: `"denseMatrix"`, `"diagonalMatrix"`, `"indMatrix"`.

### Examples

    (a <- matrix(c(2:1,1:2), 2,2))

    (M1 <- cbind(0, rbind(a, 7))) # a traditional matrix

    D <- Diagonal(2)
    (M2 <- cbind(4, a, D, -1, D, 0)) # a sparse Matrix

    stopifnot(validObject(M2), inherits(M2, "sparseMatrix"),
              dim(M2) == c(2,9))

[Package Matrix version 1.3-4 Index]