Dimnames of an Object

Retrieve or set the dimnames of an object.

manip, array
dimnames(x) <- value

provideDimnames(x, sep = "", base = list(LETTERS), unique = TRUE)


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


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


a character string, used to separate base symbols and digits in the constructed dimnames.


a non-empty list of character vectors. The list components are used in turn (and recycled when needed) to construct replacements for empty dimnames components. See also the examples.


logical indicating that the dimnames constructed are unique within each dimension in the sense of make.unique.


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, it is extended with NULLs 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.

Both are primitive functions.

provideDimnames(x) provides dimnames where “missing”, such that its result has character dimnames for each component. If unique is true as by default, they are unique within each component via make.unique(*, sep=sep).


The dimnames of a matrix or array can be NULL (which is not stored) 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 have names. It is possible that all components are NULL: such dimnames may get converted to NULL.

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

provideDimnames(x) returns x, with “NULL - free” dimnames, i.e.each component a character vector of correct length.


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.


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.

  • dimnames
  • dimnames<-
  • dimnames.data.frame
  • dimnames<-.data.frame
  • provideDimnames
library(base) # NOT RUN { ## simple versions of rownames and colnames ## could be defined as follows rownames0 <- function(x) dimnames(x)[[1]] colnames0 <- function(x) dimnames(x)[[2]] (dn <- dimnames(A <- provideDimnames(N <- array(1:24, dim = 2:4)))) A0 <- A; dimnames(A)[2:3] <- list(NULL) stopifnot(identical(A0, provideDimnames(A))) strd <- function(x) utils::str(dimnames(x)) strd(provideDimnames(A, base= list(letters[-(1:9)], tail(LETTERS)))) strd(provideDimnames(N, base= list(letters[-(1:9)], tail(LETTERS)))) # recycling strd(provideDimnames(A, base= list(c("AA","BB")))) # recycling on both levels ## set "empty dimnames": provideDimnames(rbind(1, 2:3), base = list(""), unique=FALSE) # }
Documentation reproduced from package base, version 3.5.2, License: Part of R 3.5.2

Community examples

Looks like there are no examples yet.