[ RDocumentation ](/)

Moon  [ ](https://github.com/datacamp/rdocumentation-2.0) [ Learn R
](https://www.datacamp.com/learn/r)

Search all packages and functions

[ base  (version  3.6.2  ) ](/packages/base/versions/3.6.2)

#  diag: 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 ](/link/array?package=base&version=3.6.2) ` ,
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
](/link/names?package=base&version=3.6.2) ` 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 ` .

##  Value

If ` x ` is a matrix then ` diag(x) ` returns the diagonal of ` x ` . The
resulting vector will have ` [ names ](/link/names?package=base&version=3.6.2)
` 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.

##  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 ](/link/complex?package=base&version=3.6.2) ` , ` numeric ` , ` integer ` , ` [ logical ](/link/logical?package=base&version=3.6.2) ` , or ` [ raw ](/link/raw?package=base&version=3.6.2) ` ) 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.

##  References

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

##  See Also

` [ upper.tri ](/link/upper.tri?package=base&version=3.6.2) ` , ` [ lower.tri
](/link/lower.tri?package=base&version=3.6.2) ` , ` [ matrix
](/link/matrix?package=base&version=3.6.2) ` .

##  Examples

[ Run this code
](https://app.datacamp.com/workspace/preview?_tag=rdocs&rdocsPath=packages%2Fbase%2Fversions%2F3.6.2%2Ftopics%2Fdiag&utm_source=r-docs&utm_medium=docs&utm_term=diag&utm_content=run_example_in_workspace)

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

Run the code above in your browser using  [ DataCamp Workspace
](https://app.datacamp.com/workspace/preview?_tag=rdocs&rd