diag                  package: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)
     diag(x) <- value

Arguments:

       x: a matrix, vector or 1D array.

nrow, ncol: Optional dimensions for the result.

   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' if the matrix 'x' has
     matching column and row names.

     If 'x' is a vector (or 1D array) of length two or more, then
     'diag(x)' returns a diagonal matrix whose diagonal is 'x'.

     If 'x' is a vector of length one then 'diag(x)' returns an
     identity matrix of order the nearest integer to 'x'.  The
     dimension of the returned matrix can be specified by 'nrow' and
     'ncol' (the default is square).

     The replacement form sets the diagonal of the matrix 'x' to the
     given value(s).

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:

     require(stats)
     dim(diag(3))
     diag(10,3,4) # guess what?
     all(diag(1:3) == {m <- matrix(0,3,3); diag(m) <- 1:3; m})

     diag(var(M <- cbind(X = 1:5, Y = stats::rnorm(5))))
     #-> vector with names "X" and "Y"

     rownames(M) <- c(colnames(M),rep("",3));
     M; diag(M) #  named as well

