Construct a Classed Matrix

Construct a Matrix of a class that inherits from Matrix.

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.

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.

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".

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
#> 3 x 2 sparse Matrix of class "dgCMatrix"
#>         
#> [1,] . .
#> [2,] . .
#> [3,] . .
Matrix(0, 3, 2, sparse=FALSE)# -> 'dense'
#> 3 x 2 Matrix of class "dgeMatrix"
#>      [,1] [,2]
#> [1,]    0    0
#> [2,]    0    0
#> [3,]    0    0

## 4 cases - 3 different results :
Matrix(0, 2, 2)              # diagonal !
#> 2 x 2 diagonal matrix of class "ddiMatrix"
#>      [,1] [,2]
#> [1,]    0    .
#> [2,]    .    0
Matrix(0, 2, 2, sparse=FALSE)# (ditto)
#> 2 x 2 diagonal matrix of class "ddiMatrix"
#>      [,1] [,2]
#> [1,]    0    .
#> [2,]    .    0
Matrix(0, 2, 2,               doDiag=FALSE)# -> sparse symm. "dsCMatrix"
#> 2 x 2 sparse Matrix of class "dsCMatrix"
#>         
#> [1,] . .
#> [2,] . .
Matrix(0, 2, 2, sparse=FALSE, doDiag=FALSE)# -> dense  symm. "dsyMatrix"
#> 2 x 2 Matrix of class "dsyMatrix"
#>      [,1] [,2]
#> [1,]    0    0
#> [2,]    0    0

Matrix(1:6, 3, 2)           # a 3 by 2 matrix (+ integer warning)
#> 3 x 2 Matrix of class "dgeMatrix"
#>      [,1] [,2]
#> [1,]    1    4
#> [2,]    2    5
#> [3,]    3    6
Matrix(1:6 + 1, nrow=3)
#> 3 x 2 Matrix of class "dgeMatrix"
#>      [,1] [,2]
#> [1,]    2    5
#> [2,]    3    6
#> [3,]    4    7

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

Matrix(1:9, nrow=3,
       dimnames = list(c("a", "b", "c"), c("A", "B", "C")))
#> 3 x 3 Matrix of class "dgeMatrix"
#>   A B C
#> a 1 4 7
#> b 2 5 8
#> c 3 6 9
(I3 <- Matrix(diag(3)))# identity, i.e., unit "diagonalMatrix"
#> 3 x 3 diagonal matrix of class "ddiMatrix"
#>      [,1] [,2] [,3]
#> [1,]    1    .    .
#> [2,]    .    1    .
#> [3,]    .    .    1
str(I3) # note  'diag = "U"' and the empty 'x' slot
#> Formal class 'ddiMatrix' [package "Matrix"] with 4 slots
#>   ..@ diag    : chr "U"
#>   ..@ Dim     : int [1:2] 3 3
#>   ..@ Dimnames:List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>   ..@ x       : num(0) 

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