R: Label Attribute of an Object

label {Hmisc}

R Documentation

Label Attribute of an Object

Description

label(x) retrieves the label attribute of x. label(x) <- "a label" stores the label attribute, and also puts the class labelled as the first class of x (for S-Plus 5 and later this class is not used and methods for handling this class are not defined so the "label" and "units" attributes are lost upon subsetting). The reason for having this class is so that the subscripting method for labelled, [.labelled, can preserve the label attribute in R and S-Plus 2000. Also, the print method for labelled objects prefaces the print with the object's label (and units if there). If the variable is also given a "units" attribute using the units function, subsetting the variable (using [.labelled) will also retain the "units" attribute.

label can optionally append a "units" attribute to the string, and it can optionally return a string or expression (for R's plotmath facility) suitable for plotting. labelPlotmath is a function that also has this function, when the input arguments are the 'label' and 'units' rather than a vector having those attributes. When plotmath mode is used to construct labels, the 'label' or 'units' may contain math expressions but they are typed verbatim if they contain percent signs, blanks, or underscores.

Label (actually Label.data.frame) is a function which generates S-Plus source code that makes the labels in all the variables in a data frame easy to edit.

llist is like list except that it preserves the names or labels of the component variables in the variables label attribute. This can be useful when looping over variables or using sapply or lapply. By using llist instead of list one can annotate the output with the current variable's name or label. llist also defines a names attribute for the list and pulls the names from the arguments' expressions for non-named arguments.

plotmathTranslate is a simple function that translates certain character strings to character strings that can be used as part of R plotmath expressions. If the input string has a space or percent inside, the string is surrounded by a call to plotmath's paste function.

as.data.frame.labelled is a utility function that is called by [.data.frame. It is just a copy of as.data.frame.vector. data.frame.labelled is another utility function, that adds a class "labelled" to every variable in a data frame that has a "label" attribute but not a "labelled" class.

reLabelled is used to add a 'labelled' class back to variables in data frame that have a 'label' attribute but no 'labelled' oldClass. Useful for changing cleanup.import()'d S-Plus 6 data frames back to general form for R and S-Plus 2000.

Usage

label(x, units=FALSE, plot=FALSE, default=NULL, grid=FALSE)

label(x) <- value

labelPlotmath(label, units=NULL, plotmath=.R., grid=FALSE)

## S3 method for class 'labelled':
print(x, ...)   ## or x - calls print.labelled

Label(object, ...)

## S3 method for class 'data.frame':
Label(object, file='', append=FALSE, ...)

llist(..., labels=TRUE)

plotmathTranslate(x)

data.frame.labelled(object)

reLabelled(object)

Arguments

`x`	any object (for `plotmathTranslate` is a character string)
`units`	set to `TRUE` to append the `'units'` attribute (if present) to the returned label. The `'units'` are surrounded by brackets. For `labelPlotmath` is a character string containing the units of measurement.
`plot`	set to `TRUE` to return a label suitable for R's `plotmath` facility (returns an expression instead of a character string) if R is in effect. If `units` is also `TRUE`, and if both `'label'` and `'units'` attributes are present, the `'units'` will appear after the label but in smaller type and will not be surrounded by brackets.
`default`	if `x` does not have a `'label'` attribute and `default` (a character string) is specified, the label will be taken as `default`
`grid`	Currently R's `lattice` and `grid` functions do not support `plotmath` expressions for `xlab` and `ylab` arguments. When using `lattice` functions in R, set the argument `grid` to `TRUE` so that `labelPlotmath` can return an ordinary character string instead of an expression.
`label`	a character string containing a variable's label
`plotmath`	set to `TRUE` to have `labelMathplot` return an expression for plotting using R's `plotmath` facility. If R is not in effect, an ordinary character string is returned.
`value`	the label of the object, or "".
`object`	a data frame
`...`	a list of variables or expressions to be formed into a `list`. Ignored for `print.labelled`.
`file`	the name of a file to which to write S-Plus source code. Default is `""`, meaning standard output.
`append`	set to `TRUE` to append code generated by `Label` to file `file`
`labels`	set to `FALSE` to make `llist` ignore the variables' `label` attribute and use the variables' names.

Value

label returns the label attribute of x, if any; otherwise, "". label is used most often for the individual variables in data frames. The function sas.get copies labels over from SAS if they exist.

Examples

age <- c(21,65,43)
y   <- 1:3
label(age) <- "Age in Years"
plot(age, y, xlab=label(age))

x1 <- 1:10
x2 <- 10:1
label(x2) <- 'Label for x2'
units(x2) <- 'mmHg'
x2
x2[1:5]
dframe <- data.frame(x1, x2)
Label(dframe)

##In these examples of llist, note that labels are printed after
##variable names, because of print.labelled
a <- 1:3
b <- 4:6
label(b) <- 'B Label'
llist(a,b)
llist(a,b,d=0)
llist(a,b,0)

w <- llist(a, b>5, d=101:103)
sapply(w, function(x){
  hist(as.numeric(x), xlab=label(x))
  # locator(1)   ## wait for mouse click
})

# Or: for(u in w) {hist(u); title(label(u))}