R: Matrix Diagonals

diag {base} | R Documentation

## Matrix Diagonals

### Description

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

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

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

2. `x` is missing and `nrow` is specified, it returns an identity matrix.

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

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

`upper.tri`, `lower.tri`, `matrix`.

### Examples

    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

[Package base version 3.5.1 Index]