Vector Look-Ups and Safer Sampling
A collection of utility functions that facilitate looking up vector values from a lookup table, annotate values in at table for clearer viewing, and support a safer approach to vector sampling, sequence generation, and aggregation.
Installation
You can install the released version of zmisc from CRAN with:
install.packages("zmisc")You can use pak to install the development version of
zmisc from GitHub with:
pak::pak("torfason/zmisc")Quick and easy value lookups
The functions lookup()
and lookuper()
are used to look up values from a lookup table, which can be supplied as
a vector, a list, or a
data.frame. The functions are in some ways similar to the
Excel function VLOOKUP(), but are designed to work smoothly
in an R workflow, in particular within pipes.
lookup: Get or set value labels of a labelled variable
Gets or sets the value labels (labels attribute) of a
labelled vector. The getters/setters should be used rather than
manipulating attributes directly, since these functions perform checks
to ensure that the result, and the resulting labelled variable, are
valid.
Safer sampling, sequencing and aggregation
The functions zample(), zeq(), and zingle() are intended to make your code less likely to break in mysterious ways when you encounter unexpected boundary conditions. The zample() and zeq() are almost identical to the sample() and seq() functions, but a bit safer.
Getting a better view on variables
The notate()
function adds annotations to factor and
labelled variables that make it easier to see both values
and labels/levels when using the View() function
notate: Lookup values from a lookup table
The lookup() function implements lookup of values (such as variable names) from a lookup table which maps keys onto values (such as variable labels or descriptions).
The lookup table can be in the form of a two-column
data.frame, in the form of a named vector, or
in the form of a list. If the table is in the form of a
data.frame, the key column should be named either
key or name, and the value column should be
named value (for the value). If the lookup table is in the
form of a named vector or list, the names are
used as the key, and the returned value is taken from the values in the
vector or list.
The underlying lookup is done using base::match(), and
all atomic data types except factor are supported. Factors
are omitted due to the ambiguity in what should be looked up (the values
or the levels). It is important that x,
.default and the columns of lookup_table are
all of the same type (specifically of the same
base::mode()). If the lookup table is specified as a
vector or list, only the
character variables are supported, because
name(lookup_table) is always of mode
character.
Original values are returned if they are not found in the lookup
table. Alternatively, a .default can be specified for
values that are not found. Note that it is possible to specify
NA as one of the keys to look up NA values (only when using
a data.frame as lookup table).
Any names or attributes of x are preserved.
Examples
fruit_lookup_vector <- c(a = "Apple", b = "Banana", c = "Cherry")
lookup(letters[1:5], fruit_lookup_vector)
lookup(letters[1:5], fruit_lookup_vector, .default = NA)
mtcars_lookup_data_frame <- data.frame(
name = c("mpg", "hp", "wt"),
value = c("Miles/(US) gallon", "Gross horsepower", "Weight (1000 lbs)"))
lookup(names(mtcars), mtcars_lookup_data_frame)
# A more complex example, with numeric and NA values
numeric_lookup_table <- data.frame(
key = c(1:5, NA), value = c(sqrt(1:5), 99999))
lookup(c(0:6, NA), numeric_lookup_table)