R: Create Diagonal Matrix Object

Diagonal {Matrix} | R Documentation

## Create Diagonal Matrix Object

### Description

Create a diagonal matrix object, i.e., an object inheriting from `diagonalMatrix` (or a “standard” `CsparseMatrix` diagonal matrix in cases that is prefered).

### Usage

    Diagonal(n, x = NULL)

       .symDiagonal(n, x = rep.int(1,n), uplo = "U",   kind)
        .trDiagonal(n, x = 1,            uplo = "U", unitri=TRUE, kind)
    .sparseDiagonal(n, x = 1,            uplo = "U",
                    shape = if(missing(cols)) "t" else "g",
    	        unitri, kind, cols = if(n) 0:(n - 1L) else integer(0))

### Arguments

`n` | integer specifying the dimension of the (square) matrix. If missing, `length(x)` is used.
`x` | numeric or logical; if missing, a unit diagonal n x n matrix is created.
`uplo` | for `.symDiagonal` (`.trDiagonal`), the resulting sparse `symmetricMatrix` (or `triangularMatrix`) will have slot `uplo` set from this argument, either `"U"` or `"L"`. Only rarely will it make sense to change this from the default.
`shape` | string of 1 character, one of `c("t","s","g")`, to choose a triangular, symmetric or general result matrix.
`unitri` | optional logical indicating if a triangular result should be “unit-triangular”, i.e., with `diag = "U"` slot, if possible. The default, `missing`, is the same as `TRUE`.
`kind` | string of 1 character, one of `c("d","l","n")`, to choose the storage mode of the result, from classes `dsparseMatrix`, `lsparseMatrix`, or `nsparseMatrix`, respectively.
`cols` | integer vector with values from `0:(n-1)`, denoting the columns to subselect conceptually, i.e., get the equivalent of `Diagonal(n,*)[, cols + 1]`.

### Value

`Diagonal()` returns an object of class `ddiMatrix` or `ldiMatrix` (with “superclass” `diagonalMatrix`).

`.symDiagonal()` returns an object of class `dsCMatrix` or `lsCMatrix`, i.e., a sparse symmetric matrix. Analogously, `.triDiagonal` gives a sparse `triangularMatrix`. This can be more efficient than `Diagonal(n)` when the result is combined with further symmetric (sparse) matrices, e.g., in `kronecker`, however not for matrix multiplications where `Diagonal()` is clearly preferred.

`.sparseDiagonal()`, the workhorse of `.symDiagonal` and `.trDiagonal` returns a `CsparseMatrix` (the resulting class depending on `shape` and `kind`) representation of `Diagonal(n)`, or, when `cols` are specified, of `Diagonal(n)[, cols+1]`.

### Author(s)

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)
    Diagonal(x = 10^(3:1))
    Diagonal(x = (1:4) >= 2)#-> "ldiMatrix"

    ## Use Diagonal() + kronecker() for "repeated-block" matrices:
    M1 <- Matrix(0+0:5, 2,3)
    (M <- kronecker(Diagonal(3), M1))

    (S <- crossprod(Matrix(rbinom(60, size=1, prob=0.1), 10,6)))
    (SI <- S + 10*.symDiagonal(6)) # sparse symmetric still
    stopifnot(is(SI, "dsCMatrix"))
    (I4 <- .sparseDiagonal(4, shape="t"))# now (2012-10) unitriangular
    stopifnot(I4@diag == "U", all(I4 == diag(4)))

[Package Matrix version 1.4-1 Index]