Labelr - An Introduction"

In labelr: Label Data Frames, Variables, and Values

knitr::opts_chunk$set(
  collapse = TRUE,
  error = TRUE,
  comment = "### >"
)

A Whirlwind Tour

labelr supports creation and use of multiple types of labels for data.frames and their columns. This is an ad hoc introduction to core and ancillary labelr functionalities and uses cases.

Types of Labels

labelr supports the following kinds of labels:

1. Frame labels - Each data.frame may be given a single "frame label", which can be used to describe the data set's key general features or characteristics (e.g., source, date produced or published, high-level contents).

2. Name labels - Each data.frame column (variable) may be given exactly one name label, which is an extended variable name or brief description of the variable. Name labels are equivalent to what Stata and SAS call "variable labels."

3. Value labels - Specific values of a data.frame column (variable) can be labeled as well. The package supports three (3) kinds of value labels.

   • One-to-one labels - The canonical value-labeling use case entails mapping distinct values of a variable to distinct labels in a one-to-one fashion, so that each value label uniquely identifies a substantive value. For instance, an administrative data set might assign the integers 1-7 to seven distinct racial/ethnic groups, and value labels would be critical in mapping those numbers to socially substantive racial/ethnic category concepts (e.g., Which number corresponds to the category "Asian American?").

   • Many-to-one labels - In an alternative use case, value labels may serve to distill or "bucket" distinct variable values in a way that deliberately "throws away" information for purposes of simplification. For example, one may wish to give the single label "Agree" to the responses "Very Strongly Agree," "Strongly Agree," and "Agree." Or one may wish to differentiate self-identified "White" respondents from "People of Color," applying the latter value label to all categories other than "White."

   • Numerical range labels - Finally, one may wish to carve a numerical variable into qualitative bins, such as dichotomizing a variable or dividing it into quantiles. Numerical range labels support one-to-many assignment of a single value label to a range of numerical values for a given variable.

Core Use Cases and Capabilities

More specifically, labelr functions support the following actions:

1. Assigning variable value labels, name labels, and a frame label to data.frames and modifying those labels thereafter.

2. Generating and accessing simple look-up table-style data.frames to inform or remind you about a data.frame's frame labels, its columns' name labels, or the value labels that correspond to its unique values.

3. Swapping out variable (column) names for variable name labels and back again.

4. Replacing variables' actual values with their corresponding value labels.

5. Augmenting a data.frame by adding columns of variable value labels that can exist alongside the original columns (variables) from which they were derived.

6. Engaging in base::subset()-like row-filtering, using value labels to guide the filtering but returning a subsetted data.frame in terms of the original variable values.

7. Tabulating value frequencies that can be expressed in terms of raw values or value labels -- again, without explicitly modifying or converting the raw data.frame values.

8. Preserving and restoring a data.frame's labels in the event that some unsupported R operation destroys them.

9. Applying a single value-labeling scheme to many variables at once (for example, assigning the same set of Likert-scale labels to all variables that share a common variable name character substring).

Disclaimer Regarding Base R Data Frames

Note: To minimize dependencies and reduce unexpected behaviors, key labelr functions will coerce augmented/non-standard data.frames (e.g., tibbles, data.tables) to labeled data.frames of class labeled.data.frame. If you work with non-standard data.frames, the suggested workflow is to affix and use labelr labels before transforming the labeled.data.frame to a one of these other non-standard data.frame classes, if at all. While some augmented data.frames and their functions may "play well" with labelr-style labels and functions, this is not guaranteed. Experiment as desired and at your own discretion.

Adding and Looking up Frame, Name, and Value Labels

We'll start our exploration of core labelr functions with a fake "demographic" data.frame. First, though, let's load the package labelr.

Load the Package

# install.packages("labelr") #CRAN version
# install.packages("devtools") # Step 1 to get GitHub version
# devtools::install_github("rhartmano/labelr") #Step 2 to get GitHub version
library(labelr)

Make Toy Demographic Data.Frame

We'll use make_demo_data() (included with labelr) to create the fictional data set.

set.seed(555) # for reproducibility
df <- make_demo_data(n = 1000) # you can specify the number of fictional obs.

# make a backup for later comparison
df_copy <- df

Add a Variable "FRAME label" Using add_frame_lab()

We'll start our labeling session by providing a fittingly fictional high-level description of this fictional data set. labelr calls this a FRAME label.

df <- add_frame_lab(df, frame.lab = "Demographic and reaction time test score
                    records collected by Royal Statistical Agency of
                    Fictionaslavica. Data fictionally collected in the year
                    1987. As published in A. Smithee (1988). Some Fictional Data
                    for Your Amusement. Mad Magazine, 10(1), 1-24.")


get_frame_lab(df)

Add Variable NAME Labels Using add_name_labs()

Now, let's add (some fairly trivial) variable NAME labels

df <- add_name_labs(df, name.labs = c(
  "age" = "Age in years",
  "raceth" = "Racial/ethnic identity group category",
  "gender" = "Gender identity category",
  "edu" = "Highest education level attained",
  "x1" = "Space Invaders reaction time test scores",
  "x2" = "Galaga reaction time test scores"
))

Even if we do nothing else with these name labels, we can access or manipulate a simple lookup table as needed.

get_name_labs(df)

Add VALUE labels Using add_val_labs()

Now, let's do some VALUE labeling. First, let's use add_val_labs() to add one-to-one value labels for the variable "raceth".

df <- add_val_labs(df, # data.frame with to-be-value-labeled column
  vars = "raceth", # quoted variable name of to-be-labeled col
  vals = c(1:7), # to-be-labeled values 1 through 7, inclusive
  labs = c(
    "White", "Black", "Hispanic", # ordered labels for vals 1-7
    "Asian", "AIAN", "Multi", "Other"
  ),
  max.unique.vals = 10 # max number of unique values permitted
)

Add Value Labels Using add_val1()

Now let's add value labels for the variable "gender." Function add_val1 is a variant of add_val_labs that allows you to supply the variable name unquoted, provided you are value-labeling only one variable. (It's not evident from the above, but add_val_labs supports labeling multiple variables at once).

df <- add_val1(
  data = df,
  var = gender, # contrast this var argument to the vars argument demo'd above
  vals = c(0, 1, 2, 3, 4), # the values to be labeled
  labs = c("M", "F", "TR", "NB", "Diff-Term"), # the labels, applied in order, to the vals
  max.unique.vals = 10
)

Once again, we can create a lookup table, this time for our labels-to-values mappings. Because we used add_val_labs() and add_val(), each unique value of our value-labeled variables will (must) have one unique label (one-to-one mapping), and any unique values that were not explicitly assigned a label were given one automatically (the value itself, coerced to character as needed).

get_val_labs(df)

Add NUMERICAL RANGE Labels Using add_quant_labs()

Traditionally, value labels are intended for categorical variables, such as binary, nominal, or (integer) ordinal variables with limited numbers of distinct categories. Further, as just noted, value labels that are added using add_val_labs (or add_val1) are constrained to map one-to-one to distinct values: No two distinct values could share a value label or vice versa.

If you wish to relax these constraints and apply a label to a range of values of a numeric variable, such as labeling each value according to the quintile or decile to which it belongs, you can use add_quant_labs() (or add_quant1) to do so.

Here, we will use add_quant_labs with the partial argument set to TRUE to apply quintile range labels to all variables of df that have an "x" in their names (i.e., vars "x1" and "x2"). We demonstrate this capability further at the end of the separate "Special Topics" vignette.

df_temp <- add_quant_labs(
  data = df,
  vars = "x",
  qtiles = 5,
  partial = TRUE
)

get_val_labs(df_temp)

For these variables, get_val_labs() shows the quantity values that define the requested quantile thresholds (in this case, quintiles), with all values at or below the given threshold (and above the previous threshold) receiving the corresponding label.

Be careful with setting partial to TRUE like this: If your data set featured a column called "sex" or that featured the string "tax" or the suffix "max" in its name, add_quant_labs() would attempt to apply the value labeling scheme to that column as well!

(One more side note: If you wish to apply quantile-based value labels to all numeric variables at once, you may wish to explore all_quant_labs().)

Moving on. We can use the same function to assign arbitrary, user-specified range labels. Here, we assign numerical range labels based on an arbitrary cutpoint that differentiates values of "x1" and "x2" that are at or below 100 from values that are at or below 150 (but greater than 100).

df_temp <- add_quant_labs(
  data = df_temp,
  vars = "x",
  vals = c(100, 150),
  partial = TRUE
)

get_val_labs(df_temp)

Having demonstrated the basic functionality on our df_temp copy of df, let's ignore that data.frame and return our focus to df. We'll use add_quant1 to apply quintile range labeling to the variable "x1" only. Note that add_quant1 is like add_quant_labs, but accepts only a single variable, whose name can be supplied without quotes. The opposite trade-off holds for add_quant_labs: The relationship between these two functions mirrors the relationship between add_val_labs and add_val1.

df <- add_quant1(df, # data.frame
  x1, # variable to value-label
  qtiles = 5
) # number of quintiles to use in defining numerical range labels

We'll preserve the "x1" range labels going forward, keeping "x2" unlabeled.

Add MANY-TO-ONE VALUE Labels Using add_m1_lab()

If you wish to apply a single label to multiple distinct values that are not necessarily part of a numerical range, this can be done through successive calls to add_m1_lab() Here, the "m1" is shorthand for "many to one," as in "many values get the same one value label."

Note that each call to add_m1_lab() applies a single value label, so, multiple calls are needed to apply multiple labels. Here, we illustrate this workflow, applying the label "Some College+" to values 3, 4, or 5 of the variable "edu", then applying other distinct labels to values 1 and 2, respectively.

df <- add_m1_lab(df, "edu", vals = c(3:5), lab = "Some College+")
df <- add_m1_lab(df, "edu", vals = 1, lab = "Not HS Grad")
df <- add_m1_lab(df, "edu", vals = 2, lab = "HSG, No College")

get_val_labs(df)

As with the other value-adding functions, there is a variant of add_m1_lab that allows you to value-label a single variable whose name is unquoted. It is add1m1().

Where Do We Stand?

All of this is nice, but have we really accomplished anything? A casual view of the data.frame raises some doubts:

head(df_copy, 3) # our pre-labeling copy of the data.frame

head(df, 3) # our latest, post-labeling version of same data.frame

These two data.frames still look identical.

Rest assured, labeling has introduced some unobtrusive but important features for us to use.

"Using" Value Labels

Now that our data.frame has labels, let's demonstrate some ways that we can use them.

Show First, Last, or Random Rows with Value Labels Overlaid

Base R includes the head() and tail() functions, which allow you to show the first n or last n rows of a data.frame. In addition, the "car" package offers a similar function called some(), which allows you to show a random n rows of a data.frame.

labelr provides versions of these functions that will display value labels in place of values, without actually altering the values in the underlying data.frame. Let's demonstrate each of the three standard functions, followed by its labelr counterpart. Note that the unconventional rownames (e.g., "T-1," "N-2") are provided as an aid to help you visually locate a literal row that may appear across calls.

head(df, 5) # Base R function utils::head()

headl(df, 5) # labelr function headl() (note the "l")

tail(df, 5) # Base R function utils::tail()

taill(df, 5) # labelr function taill() (note the extra "l")

set.seed(293)
car::some(df, 5) # car package function car::some()

set.seed(293)
somel(df, 5) # labelr function somel() (note the "l")

Note that some() and somel() both return random rows, but they will not necessarily return the same random rows, even with the same random number seed.

Swap out Values for Labels with use_val_labs() and uvl()

We can generalize this overlaying (aka "turning on" aka "swapping in") of value labels to the entire data.frame. For example, we might do this temporarily, to visualize the labels in place of values.

use_val_labs(df)[1:20, ] # headl() is just a more compact shortcut for this

Or we can wrap a call to this function around our data.frame and pass the result to other functions. Here is an illustration that passes a use_val_labs() -wrapped data.frame to the qsu()function of the collapse package. To save typing, we'll use uvl(), a more compact alias for use_val_labs().

First we show the unwrapped call to collapse::qsu(), followed by an otherwise identical call that wraps the data.frame in uvl(). Focus your eyes on the leftmost column of the console outputs of the respective calls (i.e., the rownames of the object generated by qsu::collapse()).

# `collapse::qsu()`
# with labels "off" (i.e., using regular values of "raceth" as by var)
(by_demog_val <- collapse::qsu(df, cols = c("x2"), by = ~raceth))

# with labels "on" (i.e., using labels, thanks to `uvl()`)
(by_demog_lab <- collapse::qsu(uvl(df), cols = c("x2"), by = ~raceth))

This second call would achieve the same result if we used use_val_labs(), but uvl() is more compact for typing and printing purposes.

Non-standard Evaluation using with_val_labs() and wvn

labelr also offers an option to overlay ("swap out") value labels using base::with()-like non-standard evaluation. This is helpful in a few specific cases.

with(df, table(gender, raceth)) # base::with()

with_val_labs(df, table(gender, raceth)) # labelr::with_val_labs()

wvl(df, table(gender, raceth)) # labelr::wvl is a more compact alias

In a little bit, we'll see that we have some parallel options for overlaying ("turning on") NAME labels.

Add value labels back to the data.frame with add_lab_cols()

If all this wrapping and interactive toggling back and forth is making you dizzy, we could do something more permanent.

For example, we can assign the result of a use_val_labs() call to an object. The result will be a data.frame with the same names and dimensions as the one supplied, with value labels replacing values for all value-labeled variables (or for a subset of those variables, if you specify them). Those variables will be coerced to character (if they were not already). Since there is no simple "undo" facility for this action, it is safest to assign the result to a new object.

df_labd <- use_val_labs(df)
head(df_labd) # note, this is utils::head(), not labelr::headl()

Perhaps better still, we do not need to choose between values and labels. We can use add_lab_cols() to preserve all existing variables (columns), including the value-labeled ones, while adding to our data.frame an additional labels-as-values column for each value-labeled column.

Easier done than said. Take a look:

df_plus_labs <- add_lab_cols(df)
head(df_plus_labs[c("gender", "gender_lab", "raceth", "raceth_lab")])

"Filter values using labels" with flab()

We also can filter a value-labeled data.frame using value labels, returning a subsetted data.frame in terms of the original values. In other words, we can use the more semantically meaningful value labels to guide our subsetting, even as they remain "invisible" and "in the background" of the returned, filtered data.frame. Again, I find this "easier done than said."

head(df)

df1 <- flab(df, raceth == "Asian" & gender == "F")

head(df1, 5) # returned df1 is in terms of values, just like df

headl(df1, 5) # note use of labelr::headl; labels are there

We've used these two variables' value labels to guide our filtering, without ever explicitly changing the contents of our columns from values to labels. For instance, note that we did NOT make an explicit call to use_val_labs() or add_lab_cols() before our call to flab(). So long as we are providing actually existing value labels that have been previously applied to the columns in question, flab() knows where to find them and how to use them.

"Subset using labels" with slab()

As with base::subset(), we can also limit which columns we return. In this case, we filter on two value-labeled columns and return a data.frame consisting of only those columns.

df2 <- slab(df, raceth == "Black" & gender == "M", gender, raceth)
head(df2, 10)

In the case of slab(), we simply list the desired columns -- unquoted and comma-separated -- after the filter

"Using" NAME labels

Just as we used use_val_labs() to swap out values for value labels, we can use use_name_labs() to swap out variable names for variable NAME labels. Let's illustrate this with the mtcars data.frame.

First we'll construct a vector of named labels.

names_labs_vec <- c(
  "mpg" = "Miles/(US) gallon",
  "cyl" = "Number of cylinders",
  "disp" = "Displacement (cu.in.)",
  "hp" = "Gross horsepower",
  "drat" = "Rear axle ratio",
  "wt" = "Weight (1000 lbs)",
  "qsec" = "1/4 mile time",
  "vs" = "Engine (0 = V-shaped, 1 = straight)",
  "am" = "Transmission (0 = automatic, 1 = manual)",
  "gear" = "Number of forward gears",
  "carb" = "Number of carburetors"
)

Now, we will apply them to mtcars and assign the resulting data.frame to a new data.frame called mt2.

mt2 <- add_name_labs(mtcars,
  vars = names(names_labs_vec),
  labs = names_labs_vec
)

Here is an alternative add_name_labs() syntax that would get us to the same end state:

mt2 <- add_name_labs(mtcars,
  name.labs = c(
    "mpg" = "Miles/(US) gallon",
    "cyl" = "Number of cylinders",
    "disp" = "Displacement (cu.in.)",
    "hp" = "Gross horsepower",
    "drat" = "Rear axle ratio",
    "wt" = "Weight (1000 lbs)",
    "qsec" = "1/4 mile time",
    "vs" = "Engine (0 = V-shaped, 1 = straight)",
    "am" = "Transmission (0 = automatic, 1 = manual)",
    "gear" = "Number of forward gears",
    "carb" = "Number of carburetors"
  )
)

Now, let's swap out names for NAME labels.

mt2 <- use_name_labs(mt2)

head(mt2[c(1, 2)])

Yikes, the longer column names stretch things out quite a bit. Even so, if we wish to keep our name labels "on" and work with them as our new column names, one approach is to use get_name_labs to get a look-up table, then use copy-and-paste or RStudio auto-complete capabilities to "hand jam" these into subsequent calls.

For example:

lm(`Miles/(US) gallon` ~ `Number of cylinders`, data = mt2) # pasting in var names
lm(mpg ~ cyl, data = use_var_names(mt2)) # same result if name labels are "off"

While this works, freehand typing or copy-and-paste is clunky and quickly becomes tedious. There are other less painful ways we can use these NAME labels, once we've swapped them in for our original column names using use_name_labs() (as in the above example). For instance, we can take advantage of commands that work over all columns of a data.frame and, hence, don't require us to type individual column names. Here are a few illustrative examples.

sapply(mt2, median) # get the median for every name-labeled variable

collapse::qsu(mt2) # use an external package for more informative descriptives

Another approach is to use with_name_labs() (or its more compact alias wnl()), which will automatically display name labels in place of column names in fairly flexible ways. with_name_labs() is an alternative to use_name_labs() that you can call on the regular, name-labeled data.frame. You should not call it on a data.frame after swapping in name labels with use_name_labs().

With that said, let's revert back to our original column names, then we'll verify that the name labels are still there in the background, then we'll take with_name_labs() for a spin.

# invert our prior use_name_labs() call
mt2 <- use_var_names(mt2) # revert from name labels back to original colnames
head(mt2[c(1, 2)])

# first, show that mt2 now has original column names swapped back in
head(mt2)

# verify that the name labels are still present and available in the background
get_name_labs(mt2)

Note that this sort of switching back and forth between your original column names and name labels (i.e., use_name_labs() and use_var_names()) assumes you are not otherwise modifying either set of names in the interim.

Now, pay attention to the variable names in the console output of the following calls to with_name_labs().You'll be using the familiar column names in your function call expressions, but their corresponding name labels will appear in the console output.

# demo with_name_labs() (note that with_name_labs() will achieve same result)
with_name_labs(mt2, t.test(mpg ~ am)) # wnl() is alias for with_name_labs()

with_name_labs(mt2, lm(mpg ~ am))

wnl(mt2, summary(mt2)) # wnl() is alias for with_name_labs()

wnl(mt2, xtabs(~gear)) # wnl() is alias for with_name_labs()

with(mt2, xtabs(~gear)) # compare this base::with() call to wnl() call above

Keep in mind that with_name_labs() is intended for self-contained calls involving exploratory analysis activities -- things like simple plots, descriptives, and models. The underlying function is based on simple regular expressions and will throw an error if you attempt to use it in contexts involving (1) exotic or non-standard operators, (2) multi-step workflows (e.g., pipes), OR (3) data management and cleaning commands. Still, as shown above, it plays well with a range of "workhorse" exploratory and descriptive commands.

Alias Functions and Conclusion

This concludes our whirlwind tour of labelr functionalities. You've graduated.

Well, almost. Before you go, here is a list of aliases for common functions. Other than its name, each alias function is identical to (i.e., performs the same operations, returning the same result as) the parent function that it aliases. More concise and more cryptic, these alias functions will save you some typing at the console (and some characters in your scripts).

The available aliases are as follows:

• add_val_labs alias is avl

• get_val_labs alias is gvl

• drop_val_labs alias is dvl

• add_val1 alias is avl1

• drop_val1 alias is dvl1

• add_quant_labs alias is aql

• all_quant_labs alias is allq

• add_quant1 alias is aq1

• add_m1_lab alias is am1l

• use_val_labs alias is uvl

• use_val_lab1 alias is uvl1

• with_val_labs alias is wvl

• add_lab_cols alias is alc

• add_lab_col1 alias is alc1

• add_lab_dummies is ald

• add_lab_dumm1 is ald1

• lab_int_to_factor is int2f

• factor_to_lab_int is f2int

• add_name_labs is anl

• get_name_labs alias is gnl

• drop_name_labs alias is dnl

• use_name_labs alias is unl

• use_var_names alias is uvn

• with_name_labs alias is wnl

• with_both_labs alias is wbl

• add_frame_lab alias is afl

• get_frame_lab alias is gfl

• drop_frame_lab alias is dfl

• axis_lab is alb

• as_labeled_data_frame is aldf

• as_base_data_frame is adf

labelr documentation built on Sept. 11, 2024, 9:05 p.m.