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.

### See Also

`sas.get`, `describe`

### 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))}

[Package Contents]