R: Construct a Classed Matrix

Matrix {Matrix} | R Documentation

## Construct a Classed Matrix

### Description

Construct a Matrix of a class that inherits from `Matrix`.

### Usage

    Matrix(data=NA, nrow=1, ncol=1, byrow=FALSE, dimnames=NULL,
           sparse = NULL, doDiag = TRUE, forceCheck = FALSE)

### Arguments

`data` | an optional numeric data vector or matrix.
`nrow` | when `data` is not a matrix, the desired number of rows
`ncol` | when `data` is not a matrix, the desired number of columns
`byrow` | logical. If `FALSE` (the default) the matrix is filled by columns, otherwise the matrix is filled by rows.
`dimnames` | a `dimnames` attribute for the matrix: a `list` of two character components. They are set if not `NULL` (as per default).
`sparse` | logical or `NULL`, specifying if the result should be sparse or not. By default, it is made sparse when more than half of the entries are 0.
`doDiag` | logical indicating if a `diagonalMatrix` object should be returned when the resulting matrix is diagonal (mathematically). As class `diagonalMatrix` `extends` `sparseMatrix`, this is a natural default for all values of `sparse`. Otherwise, if `doDiag` is false, a dense or sparse (depending on `sparse`) symmetric matrix will be returned.
`forceCheck` | logical indicating if the checks for structure should even happen when `data` is already a `"Matrix"` object.

### Details

If either of `nrow` or `ncol` is not given, an attempt is made to infer it from the length of `data` and the other parameter. Further, `Matrix()` makes efforts to keep `logical` matrices logical, i.e., inheriting from class `lMatrix`, and to determine specially structured matrices such as symmetric, triangular or diagonal ones. Note that a symmetric matrix also needs symmetric `dimnames`, e.g., by specifying `dimnames = list(NULL,NULL)`, see the examples.

Most of the time, the function works via a traditional (full) `matrix`. However, `Matrix(0, nrow,ncol)` directly constructs an “empty” sparseMatrix, as does `Matrix(FALSE, *)`.

Although it is sometime possible to mix unclassed matrices (created with `matrix`) with ones of class `"Matrix"`, it is much safer to always use carefully constructed ones of class `"Matrix"`.

### Value

Returns matrix of a class that inherits from `"Matrix"`. Only if `data` is not a `matrix` and does not already inherit from class `Matrix` are the arguments `nrow`, `ncol` and `byrow` made use of.

### See Also

The classes `Matrix`, `symmetricMatrix`, `triangularMatrix`, and `diagonalMatrix`; further, `matrix`.

Special matrices can be constructed, e.g., via `sparseMatrix` (sparse), `bdiag` (block-diagonal), `bandSparse` (banded sparse), or `Diagonal`.

### Examples

    Matrix(0, 3, 2)             # 3 by 2 matrix of zeros -> sparse
    Matrix(0, 3, 2, sparse=FALSE)# -> 'dense'

    ## 4 cases - 3 different results :
    Matrix(0, 2, 2)              # diagonal !
    Matrix(0, 2, 2, sparse=FALSE)# (ditto)
    Matrix(0, 2, 2,               doDiag=FALSE)# -> sparse symm. "dsCMatrix"
    Matrix(0, 2, 2, sparse=FALSE, doDiag=FALSE)# -> dense  symm. "dsyMatrix"

    Matrix(1:6, 3, 2)           # a 3 by 2 matrix (+ integer warning)
    Matrix(1:6 + 1, nrow=3)

    ## logical ones:
    Matrix(diag(4) >  0) # -> "ldiMatrix" with diag = "U"
    Matrix(diag(4) >  0, sparse=TRUE) #  (ditto)
    Matrix(diag(4) >= 0) # -> "lsyMatrix" (of all 'TRUE')
    ## triangular
    l3 <- upper.tri(matrix(,3,3))
    (M <- Matrix(l3))   # -> "ltCMatrix"
    Matrix(! l3)        # -> "ltrMatrix"
    as(l3, "CsparseMatrix")# "lgCMatrix"

    Matrix(1:9, nrow=3,
           dimnames = list(c("a", "b", "c"), c("A", "B", "C")))
    (I3 <- Matrix(diag(3)))# identity, i.e., unit "diagonalMatrix"
    str(I3) # note  'diag = "U"' and the empty 'x' slot

    (A <- cbind(a=c(2,1), b=1:2))# symmetric *apart* from dimnames
    Matrix(A)                    # hence 'dgeMatrix'
    (As <- Matrix(A, dimnames = list(NULL,NULL)))# -> symmetric
    forceSymmetric(A) # also symmetric, w/ symm. dimnames
    stopifnot(is(As, "symmetricMatrix"),
              is(Matrix(0, 3,3), "sparseMatrix"),
              is(Matrix(FALSE, 1,1), "sparseMatrix"))

[Package Matrix version 1.3-4 Index]