Title: Label Attributes for Atomic Vectors
Version: 0.1.2
Description: Labels are a common construct in statistical software providing a human readable description of a variable. While variable names are succinct, quick to type, and follow a language's naming conventions, labels may be more illustrative and may use plain text and spaces. R does not provide native support for labels. Some packages, however, have made this feature available. Most notably, the 'Hmisc' package provides labelling methods for a number of different object. Due to design decisions, these methods are not all exported, and so are unavailable for use in package development. The 'labelVector' package supports labels for atomic vectors in a light-weight design that is suitable for use in other packages.
Depends: R (≥ 2.0.0)
Suggests: Hmisc, knitr, testthat
License: MIT + file LICENSE
RoxygenNote: 7.1.2
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2021-10-08 15:09:26 UTC; benja
Author: Benjamin Nutter [aut, cre]
Maintainer: Benjamin Nutter <benjamin.nutter@gmail.com>
Repository: CRAN
Date/Publication: 2021-10-08 15:40:02 UTC

Extract or Replace Parts of Labelled Vectors

Description

Extraction and replacement methods for labelled vectors.

Usage

## S3 method for class 'labelled'
x[i, ...]

## S3 replacement method for class 'labelled'
x[i, ...] <- value

Arguments

x

An atomic vector inheriting the labelled class.

i

The elements to extract.

...

Arguments to pass to other methods.

value

typically a vector of similar class of length i

See Also

Extract

Examples


x <- set_label(1:10, "Integers")
x[1:3]

x[3] <- pi
x

Extract Label Attribute From a Labelled Vector

Description

Retrieve the label attribute of a labelled vector. If the vector has no label, the vector name is returned as a string.

Usage

get_label(x, ...)

## Default S3 method:
get_label(x, ...)

## S3 method for class 'data.frame'
get_label(x, vars = NULL, ..., return_vector = TRUE)

Arguments

x

An atomic vector.

...

Arguments to pass to other methods.

vars

A character vector of variable names in x for which to retrieve labels. If NULL, all labels are returned.

return_vector

logical. When TRUE, a vector of the variables is returned. Otherwise, a named list mapping variable names to labels is returned. The named list can be useful for restoring labels after various transformations that may drop attributes.

See Also

set_label

Examples

x <- 1:10
x <- set_label(x, "Integers")

get_label(x)

y <- letters
attr(y, "label")    # NULL
get_label(y)        # "y"

# Set labels for variables in a data frame

mtcars2 <-
  set_label(mtcars,
            am = "Automatic / Manual",
            mpg = "Miles per Gallon",
            gear = "Number of gears")

get_label(mtcars2)

Evaluate if a vector is labelled

Description

Functions to determine if a vector has a label.

Usage

is.labelled(x)

is_labelled(x)

Arguments

x

An atomic vector

Value

Returns a logical(1).

Functional Requirements

  1. Return a logical value of length 1.

  2. Cast an error if x is not atomic.

Print Method for Labelled Vectors

Description

Labelled vectors are printed with their label appearing above the content of the vector.

Usage

## S3 method for class 'labelled'
print(x, ...)

Arguments

x

A vector inheriting class labelled

...

Additional arguments to pass to other methods.

Set the label of an atomic vector

Description

Variable labels are a common construct in statistical software, giving users the ability to provide plain text descriptions for variables. These descriptions can be more informative of the variable's purpose, since they need not be restricted to the naming conventions imposed on variable names.

Usage

set_label(x, ...)

## Default S3 method:
set_label(x, label, ...)

## S3 method for class 'data.frame'
set_label(x, ..., .dots = list())

Arguments

x

An atomic vector

...

For the default method, arguments to pass to other methods. For the data.frame method, key-pairs of the pattern variable = 'label'.

label

character(1), A character string denoting the label to assign to the variable.

.dots

for data frames, a named list of key-pairs mapping the variable name to the label.

Source

Frank E Harrell Jr, with contributions from Charles Dupont and many others. (2017). Hmisc: Harrell Miscellaneous. R package version 4.0-3. https://CRAN.R-project.org/package=Hmisc

See Also

get_label

Examples

x <- 1:10
x <- set_label(x, "Integers")
x

# Set labels for variables in a data frame

mtcars2 <-
  set_label(mtcars,
            am = "Automatic / Manual",
            mpg = "Miles per Gallon",
            gear = "Number of gears")

get_label(mtcars2)