label                 package:Hmisc                 R Documentation

_L_a_b_e_l _A_t_t_r_i_b_u_t_e _o_f _a_n _O_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     '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.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

       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. 

_V_a_l_u_e:

     '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.

_S_e_e _A_l_s_o:

     'sas.get', 'describe'

_E_x_a_m_p_l_e_s:

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

