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

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.2-17 Index]