# Diagonal

##### Create Diagonal Matrix Object

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 \times 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]`

.

##### 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

```
# NOT RUN {
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)))
# }
```

*Documentation reproduced from package Matrix, version 1.2-18, License: GPL (>= 2) | file LICENCE*