EVOLUTION-MANAGER
Edit File: dimnames.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Dimnames of an Object</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for dimnames {base}"><tr><td>dimnames {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Dimnames of an Object</h2> <h3>Description</h3> <p>Retrieve or set the dimnames of an object. </p> <h3>Usage</h3> <pre> dimnames(x) dimnames(x) <- value provideDimnames(x, sep = "", base = list(LETTERS), unique = TRUE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x</code></td> <td> <p>an <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> object, for example a matrix, array or data frame.</p> </td></tr> <tr valign="top"><td><code>value</code></td> <td> <p>a possible value for <code>dimnames(x)</code>: see the ‘Value’ section.</p> </td></tr> <tr valign="top"><td><code>sep</code></td> <td> <p>a character string, used to separate <code>base</code> symbols and digits in the constructed dimnames.</p> </td></tr> <tr valign="top"><td><code>base</code></td> <td> <p>a non-empty <code><a href="list.html">list</a></code> 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.</p> </td></tr> <tr valign="top"><td><code>unique</code></td> <td> <p>logical indicating that the dimnames constructed are unique within each dimension in the sense of <code><a href="make.unique.html">make.unique</a></code>.</p> </td></tr> </table> <h3>Details</h3> <p>The functions <code>dimnames</code> and <code>dimnames<-</code> are generic. </p> <p>For an <code><a href="array.html">array</a></code> (and hence in particular, for a <code><a href="matrix.html">matrix</a></code>), they retrieve or set the <code>dimnames</code> attribute (see <a href="attributes.html">attributes</a>) of the object. A list <code>value</code> can have names, and these will be used to label the dimensions of the array where appropriate. </p> <p>The replacement method for arrays/matrices coerces vector and factor elements of <code>value</code> to character, but does not dispatch methods for <code>as.character</code>. It coerces zero-length elements to <code>NULL</code>, and a zero-length list to <code>NULL</code>. If <code>value</code> is a list shorter than the number of dimensions, it is extended with <code>NULL</code>s to the needed length. </p> <p>Both have methods for data frames. The dimnames of a data frame are its <code><a href="row.names.html">row.names</a></code> and its <code><a href="names.html">names</a></code>. For the replacement method each component of <code>value</code> will be coerced by <code><a href="character.html">as.character</a></code>. </p> <p>For a 1D matrix the <code><a href="names.html">names</a></code> are the same thing as the (only) component of the <code>dimnames</code>. </p> <p>Both are <a href="Primitive.html">primitive</a> functions. </p> <p><code>provideDimnames(x)</code> provides <code>dimnames</code> where “missing”, such that its result has <code><a href="character.html">character</a></code> dimnames for each component. If <code>unique</code> is true as by default, they are unique within each component via <code><a href="make.unique.html">make.unique</a>(*, sep=sep)</code>. </p> <h3>Value</h3> <p>The dimnames of a matrix or array can be <code>NULL</code> (which is not stored) or a list of the same length as <code>dim(x)</code>. If a list, its components are either <code>NULL</code> or a character vector with positive length of the appropriate dimension of <code>x</code>. The list can have names. It is possible that all components are <code>NULL</code>: such dimnames may get converted to <code>NULL</code>. </p> <p>For the <code>"data.frame"</code> method both dimnames are character vectors, and the rownames must contain no duplicates nor missing values. </p> <p><code>provideDimnames(x)</code> returns <code>x</code>, with “<code>NULL</code> - free” <code>dimnames</code>, i.e. each component a character vector of correct length. </p> <h3>Note</h3> <p>Setting components of the dimnames, e.g., <code>dimnames(A)[[1]] <- value</code> is a common paradigm, but note that it will not work if the value assigned is <code>NULL</code>. Use <code><a href="colnames.html">rownames</a></code> instead, or (as it does) manipulate the whole dimnames list. </p> <h3>References</h3> <p>Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) <em>The New S Language</em>. Wadsworth & Brooks/Cole. </p> <h3>See Also</h3> <p><code><a href="colnames.html">rownames</a></code>, <code><a href="colnames.html">colnames</a></code>; <code><a href="array.html">array</a></code>, <code><a href="matrix.html">matrix</a></code>, <code><a href="data.frame.html">data.frame</a></code>. </p> <h3>Examples</h3> <pre> ## 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) </pre> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>