# dimnames {base}

### Description

Retrieve or set the dimnames of an object.

### Usage

dimnames(x) dimnames(x) <- value provideDimnames(x, sep = "", base = list(LETTERS))

### Arguments

- x
- an R object, for example a matrix, array or data frame.
- value
- a possible value for
`dimnames(x)`

: see the ‘Value’ section. - sep
- a character string, used to separate
`base`

symbols and digits in the constructed dimnames. - base
- 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.

### 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, 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`

.

Both are primitive functions.

`provideDimnames(x)`

provides `dimnames`

where “missing”, such that its result has `character`

dimnames for each component.

### Values

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.

### References

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

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

### See Also

### Examples

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

Documentation reproduced from R 3.0.2. License: GPL-2.