# diag

##### Matrix Diagonals

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

- Keywords
- array

##### Usage

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

##### Arguments

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

.

##### Details

`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.

##### Value

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.

##### Note

Using `diag(x)`

can have unexpected effects if `x`

is a
vector that could be of length one. Use ```
diag(x, nrow =
length(x))
```

for consistent behaviour.

##### References

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

##### See Also

##### Examples

`library(base)`

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

*Documentation reproduced from package base, version 3.6.0, License: Part of R 3.6.0*