Construct a Diagonal Matrix

Construct a formally diagonal Matrix, i.e., an object inheriting from virtual class diagonalMatrix (or, if desired, a mathematically diagonal CsparseMatrix).

Usage

Diagonal(n, x = NULL, names = FALSE)

.sparseDiagonal(n, x = NULL, uplo = "U", shape = "t", unitri = TRUE, kind, cols)
    .trDiagonal(n, x = NULL, uplo = "U", unitri = TRUE, kind)
   .symDiagonal(n, x = NULL, uplo = "U", kind)

Arguments

n

integer indicating the dimension of the (square) matrix. If missing, then length(x) is used.

x

numeric or logical vector listing values for the diagonal entries, to be recycled as necessary. If NULL (the default), then the result is a unit diagonal matrix. .sparseDiagonal() and friends ignore non-NULL x when kind = "n".

names

either logical TRUE or FALSE or then a character vector of length n. If true and names(x) is not NULL, use that as both row and column names for the resulting matrix. When a character vector, use it for both dimnames.

uplo

one of c("U","L"), specifying the uplo slot of the result if the result is formally triangular of symmetric.

shape

one of c("t","s","g"), indicating if the result should be formally triangular, symmetric, or “general”. The result will inherit from virtual class triangularMatrix, symmetricMatrix, or generalMatrix, respectively.

unitri

logical indicating if a formally triangular result with ones on the diagonal should be formally unit triangular, i.e., with diag slot equal to "U" rather than "N".

kind

one of c("d","l","n"), indicating the “mode” of the result: numeric, logical, or pattern. The result will inherit from virtual class dsparseMatrix, lsparseMatrix, or nsparseMatrix, respectively. Values other than "n" are ignored when x is non-NULL; in that case the mode is determined by typeof(x).

cols

optional integer vector with values in 0:(n-1), indexing columns of the specified diagonal matrix. If specified, then the result is (mathematically) D[, cols+1] rather than D, where D = Diagonal(n, x), and it is always “general” (i.e., shape is ignored).

Value

Diagonal() returns an object inheriting from virtual class diagonalMatrix.

.sparseDiagonal() returns a CsparseMatrix representation of Diagonal(n, x) or, if cols is given, of Diagonal(n, x)[, cols+1]. The precise class of the result depends on shape and kind.

.trDiagonal() and .symDiagonal() are simple wrappers, for .sparseDiagonal(shape = "t") and .sparseDiagonal(shape = "s"), respectively.

.sparseDiagonal() exists primarily to leverage efficient C-level methods available for CsparseMatrix.

Author

Martin Maechler

See also

the generic function diag for extraction of the diagonal from a matrix works for all “Matrices”.

bandSparse constructs a banded sparse matrix from its non-zero sub-/super - diagonals. band(A) returns a band matrix containing some sub-/super - diagonals of A.

Matrix for general matrix construction; further, class diagonalMatrix.

Examples

Diagonal(3)
#> 3 x 3 diagonal matrix of class "ddiMatrix"
#>      [,1] [,2] [,3]
#> [1,]    1    .    .
#> [2,]    .    1    .
#> [3,]    .    .    1
Diagonal(x = 10^(3:1))
#> 3 x 3 diagonal matrix of class "ddiMatrix"
#>      [,1] [,2] [,3]
#> [1,] 1000    .    .
#> [2,]    .  100    .
#> [3,]    .    .   10
Diagonal(x = (1:4) >= 2)#-> "ldiMatrix"
#> 4 x 4 diagonal matrix of class "ldiMatrix"
#>       [,1] [,2] [,3] [,4]
#> [1,] FALSE    .    .    .
#> [2,]     . TRUE    .    .
#> [3,]     .    . TRUE    .
#> [4,]     .    .    . TRUE

## Use Diagonal() + kronecker() for "repeated-block" matrices:
M1 <- Matrix(0+0:5, 2,3)
(M <- kronecker(Diagonal(3), M1))
#> 6 x 9 sparse Matrix of class "dgCMatrix"
#>                       
#> [1,] . 2 4 . . . . . .
#> [2,] 1 3 5 . . . . . .
#> [3,] . . . . 2 4 . . .
#> [4,] . . . 1 3 5 . . .
#> [5,] . . . . . . . 2 4
#> [6,] . . . . . . 1 3 5

(S <- crossprod(Matrix(rbinom(60, size=1, prob=0.1), 10,6)))
#> 6 x 6 sparse Matrix of class "dsCMatrix"
#>                 
#> [1,] 1 . . . . .
#> [2,] . . . . . .
#> [3,] . . . . . .
#> [4,] . . . 3 1 .
#> [5,] . . . 1 1 .
#> [6,] . . . . . .
(SI <- S + 10*.symDiagonal(6)) # sparse symmetric still
#> 6 x 6 sparse Matrix of class "dsCMatrix"
#>                       
#> [1,] 11  .  .  .  .  .
#> [2,]  . 10  .  .  .  .
#> [3,]  .  . 10  .  .  .
#> [4,]  .  .  . 13  1  .
#> [5,]  .  .  .  1 11  .
#> [6,]  .  .  .  .  . 10
stopifnot(is(SI, "dsCMatrix"))
(I4 <- .sparseDiagonal(4, shape="t"))# now (2012-10) unitriangular
#> 4 x 4 sparse Matrix of class "dtCMatrix" (unitriangular)
#>             
#> [1,] I . . .
#> [2,] . I . .
#> [3,] . . I .
#> [4,] . . . I
stopifnot(I4@diag == "U", all(I4 == diag(4)))