Dimnames Attribute of an Object

dimnames

Description

Returns or changes the dimnames attribute of an array or data frame. This is a list of the same length as the dimension of the array or data frame.

Usage

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

Arguments

x	any object of matrix, array, or data frame.
value	must be a list whose length is equal to the length of attribute "dim". The length of each item on the list should be equal of the corresponding dim(x) value or NULL.
sep	a character string used as a separator between a base string and the appended sequence number. It is passed to the function make.unique for a unique name. The default is "".
base	a list of character vectors specifying the base string names in turn for replacement of every empty dimension names. The components of base can be recycled if the list is not long enough. For each component, the base name could also be recycled with an appended sequence number when needed. See Examples for more information.

Details

dimnames is a generic function that describes or changes the dimnames attribute of an array (or a matrix).

The dimnames of an object is a list whose length is length(dim(x)). The ith element of dimnames(x) is either of length 0 (not allowed for data frames) or is a vector of dim(x)[i] character strings. In the latter case, consider it a set of labels for the ith dimension of x.

When you make a dimnames assignment, remember the following:

dimnames must be a list whose length is equal to the length of the attribute "dim".
The length of each item in the dimnames list should be equal of the corresponding dim value.
value can be a character vector, or it can be anything that can be coerced to a character vector.

When you delete a dimnames attribute explicitly, follow these rules:

To delete the dimnames attribute of an array (or a matrix), use dimnames(x)<-NULL.
To delete only one dim name, follow the example below.

dimnames has a method for data frames. When working with the data frame dimnames, remember the following:

The dimnames of a data frame include the row.names attribute and the names of the object.
The row and column names must have the same length as the number or rows and columns of the data frame.
The row names must be unique; the column names do not need to be unique.
You cannot remove the dimnames of a data frame.

provideDimnames tries to replace all empty dimension names with the specified base name strings. It makes sure that every dimension has fully-populated and unique names.

Value

dimnames(x)	returns the dimension names of x if they exist. Otherwise, it returns NULL.
provideDimnames(x)	returns x with a full complement of dimension names. Existing ones are retained and dimensions without dimension names are given dimension names.

Note

Array subscripts retain dimnames.

Examples

x <-  array(1:12, dim = c(2, 3, 2), dimnames = list(c("C1", "C2"),
   c("R1", "R2", "R3"), c("I", "II")))
dimnames(x)  # list of dim names
dimnames(x) <- NULL # remove all dim names
dimnames(x) <- list(c("CC1", "CC2"), c("RR1", "RR2", "RR3"),
   c("One", "Two"))  # change the dim names
dimnames(x)[[1]] <- c("a", "b")  # change  the first dim names
dimnames(x)[[3]] <- c("L1", "L2")  # change the third dim names
dimnames(x)[[2]] <- character(0)   # remove the second dim names
# Note -- when creating dimnames initially you may use NULL as
# a shortcut for character(0), but not when modifying dimnames.
# This is illegal: dimnames(x)[[2]] <- NULL
y <- data.frame(matrix(1:12, 3))
dimnames(y)  # list of row name and column name
# dimnames(y) <- NULL
# illegal; Removal of row name and column name is not allowed for data frame
dimnames(y)[[1]] <- c("a", "b", "c")  # change the row names
# dimnames(y)[[1]] <- c("a", "b", "a")
# illegal; row names must be unique
# dimnames(y)[[1]] <- c("a", "b")  # illegal; length not matched
dimnames(y)[[2]] <- c("A", "B", "C", "A")
# legal; column names can be duplicated.
A <- array(1:24, dim = c(2, 3, 4))
 str(dimnames(provideDimnames(A)))
# List of 3
# $ : chr [1:2] "A" "B"
# $ : chr [1:3] "A" "B" "C"
# $ : chr [1:4] "A" "B" "C" "D"
dimnames(A) <- list( c("I", "II"), NULL, NULL)
# base is recycled.
 str(dimnames(provideDimnames(A, base=list(letters, LETTERS[20:26]))))
# List of 3
# $ : chr [1:2] "I" "II"
# $ : chr [1:3] "T" "U" "V"
# $ : chr [1:4] "a" "b" "c" "d"
# append dimension names with sequence number.
str(dimnames(provideDimnames(A, sep= ".", base=list("R", LETTERS[25:26]))))
# List of 3
# $ : chr [1:2] "I" "II"
# $ : chr [1:3] "Y" "Z" "Y1"
# $ : chr [1:4] "R" "R.1" "R.2" "R.3"
# NAs won't be replaced.
dimnames(A) <- list( c(NA, "II"),  c("A", NA, "C"), NULL)
 str(dimnames(provideDimnames(A, base=list("R"))))
# List of 3
# $ : chr [1:2] NA "II"
# $ : chr [1:3] "A" NA "C"
 #$ : chr [1:4] "R" "R1" "R2" "R3"

Package base version 6.1.1-7
Package Index