# Diagonal: Create Diagonal Matrix Object In Matrix: Sparse and Dense Matrix Classes and Methods

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

 ```1 2 3 4 5 6 7``` ```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]`.

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

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13``` ```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))) ```

Matrix documentation built on June 11, 2021, 3 p.m.