R: Dimnames of an Object

dimnames {base} | R Documentation

## Dimnames of an Object

### Description

Retrieve or set the dimnames of an object.

### Usage

    dimnames(x)
    dimnames(x) <- value

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

### 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.
`unique` | logical indicating that the dimnames constructed are unique within each dimension in the sense of `make.unique`.

### 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. If `unique` is true as by default, they are unique within each component via `make.unique(*, sep=sep)`.

### Value

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.

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

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

[Package base version 3.5.1 Index]