Extract or replace the diagonal of a matrix, or construct a diagonal matrix.

```
diag(x = 1, nrow, ncol, names = TRUE)
diag(x) <- value
```

x

a matrix, vector or 1D `array`

, or missing.

nrow, ncol

optional dimensions for the result when `x`

is
not a matrix.

names

(when `x`

is a matrix) logical indicating if the
resulting vector, the diagonal of `x`

, should inherit
`names`

from `dimnames(x)`

if available.

value

either a single value or a vector of length equal to that
of the current diagonal. Should be of a mode which can be coerced
to that of `x`

.

If `x`

is a matrix then `diag(x)`

returns the diagonal of
`x`

. The resulting vector will have `names`

if the
matrix `x`

has matching column and rownames.

The replacement form sets the diagonal of the matrix `x`

to the
given value(s).

In all other cases the value is a diagonal matrix with `nrow`

rows and `ncol`

columns (if `ncol`

is not given the matrix
is square). Here `nrow`

is taken from the argument if specified,
otherwise inferred from `x`

: if that is a vector (or 1D array) of
length two or more, then its length is the number of rows, but if it
is of length one and neither `nrow`

nor `ncol`

is specified,
`nrow = as.integer(x)`

.

When a diagonal matrix is returned, the diagonal elements are one
except in the fourth case, when `x`

gives the diagonal elements:
it will be recycled or truncated as needed, but fractional recycling
and truncation will give a warning.

`diag`

has four distinct usages:

`x`

is a matrix, when it extracts the diagonal.`x`

is missing and`nrow`

is specified, it returns an identity matrix.`x`

is a scalar (length-one vector) and the only argument, it returns a square identity matrix of size given by the scalar.`x`

is a ‘numeric’ (`complex`

,`numeric`

,`integer`

,`logical`

, or`raw`

) vector, either of length at least 2 or there were further arguments. This returns a matrix with the given diagonal and zero off-diagonal entries.

It is an error to specify `nrow`

or `ncol`

in the first case.

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
*The New S Language*.
Wadsworth & Brooks/Cole.

# NOT RUN { dim(diag(3)) diag(10, 3, 4) # guess what? all(diag(1:3) == {m <- matrix(0,3,3); diag(m) <- 1:3; m}) ## other "numeric"-like diagonal matrices : diag(c(1i,2i)) # complex diag(TRUE, 3) # logical diag(as.raw(1:3)) # raw (D2 <- diag(2:1, 4)); typeof(D2) # "integer" require(stats) ## diag(<var-cov-matrix>) = variances diag(var(M <- cbind(X = 1:5, Y = rnorm(5)))) #-> vector with names "X" and "Y" rownames(M) <- c(colnames(M), rep("", 3)) M; diag(M) # named as well diag(M, names = FALSE) # w/o names # }