dimnames                package:base                R Documentation

Dimnames of an Object

Description:

     Retrieve or set the dimnames of an object.

Usage:

     dimnames(x)
     dimnames(x) <- value

Arguments:

       x: an R object, for example a matrix, array or data frame.

   value: a possible value for 'dimnames(x)': see the 'Value' section.

Details:

     The functions 'dimnames' and 'dimnames<-' are generic.

     For an 'array' (and hence in particular, for a 'matrix'), they
     retrieve or set the 'dimnames' attribute (see attributes) of the
     object.  A list 'value' can have names, and these will be used to
     label the dimensions of the array where appropriate.

     The replacement method for arrays/matrices coerces vector and
     factor elements of 'value' to character, but does not dispatch
     methods for 'as.character'.  It coerces zero-length elements to
     'NULL', and a zero-length list to 'NULL'.  If 'value' is a list
     shorter than the number of dimensions, as from R 2.8.0 it is
     extended with 'NULL's to the needed length.

     Both have methods for data frames.  The dimnames of a data frame
     are its 'row.names' and its 'names'.  For the replacement method
     each component of 'value' will be coerced by 'as.character'.

     For a 1D matrix the 'names' are the same thing as the (only)
     component of the 'dimnames'.

Value:

     The dimnames of a matrix or array can be 'NULL' or a list of the
     same length as 'dim(x)'.  If a list, its components are either
     'NULL' or a character vector with positive length of the
     appropriate dimension of 'x'.  The list can be named.

     For the '"data.frame"' method both dimnames are character vectors,
     and the rownames must contain no duplicates nor missing values.

Note:

     Setting components of the dimnames, e.g. 'dimnames(A)[[1]] <-
     value' is a common paradigm, but note that it will not work if the
     value assigned is 'NULL'.  Use 'rownames' instead, or (as it does)
     manipulate the whole dimnames list.

References:

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

See Also:

     'rownames', 'colnames'; 'array', 'matrix', 'data.frame'.

Examples:

     ## simple versions of rownames and colnames
     ## could be defined as follows
     rownames0 <- function(x) dimnames(x)[[1]]
     colnames0 <- function(x) dimnames(x)[[2]]

