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 
sep 
a character string, used to separate 
base 
a nonempty 
unique 
logical indicating that the dimnames constructed are
unique within each dimension in the sense of 
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 zerolength elements to
NULL
, and a zerolength 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)