Package 'labelr'

Description

add_factor_info searches a data.frame for labelr-specific factor meta-data, which it records and retains for future use. It is used by other labelr functions and need not be used directly by labelr end users.

Usage

add_factor_info(data)

Arguments

Value

a data.frame.

Examples

# this function does not strictly require prior or other use of labelr
ir2 <- add_factor_info(iris)
mt2 <- add_factor_info(mtcars)
get_factor_info(mtcars) # none
get_factor_info(iris) # none
get_factor_info(mt2) # none
get_factor_info(ir2) # some!

Description

Add a 500-or-fewer-characters high-level descriptive label for your data.frame as whole (e.g., nature, originator, population / sample, year created, general contents, article citation).

Usage

add_frame_lab(data, frame.lab = NULL)

afl(data, frame.lab = NULL)

Arguments

Details

add_frame_lab assigns an overall descriptive "frame label" for a data.frame, which can be retrieved using get_frame_lab.

Note: afl is a compact alias for add_frame_lab: they do the same thing, and the former is easier to type

Value

A data.frame, with a frame.lab attribute added to the attributes meta-data

Examples

# add frame.lab to mtcars and assign to new data.frame mt2
mt2 <- add_frame_lab(mtcars, frame.lab = "Data extracted from the 1974 Motor
                    Trend US magazine, comprising fuel consumption and 10
                    aspects of automobile design and performance for 32
                    automobiles (1973–74 models). Source: Henderson and
                    Velleman (1981), Building multiple regression models
                    interactively. Biometrics, 37, 391–411.")

attr(mt2, "frame.lab") # check for attribute

get_frame_lab(mt2) # return frame.lab alongside data.frame name as a data.frame

Description

add_lab_atts allows one to apply a list of labelr label attribute meta-data (created by get_all_lab_atts) to a data.frame.

Usage

add_lab_atts(
  data,
  lab.atts.list,
  strip.first = FALSE,
  num.convert = FALSE,
  clean = TRUE
)

Arguments

Details

See get_all_lab_atts.

add_lab_atts allows one to add or restore label attributes from a free- standing list (created by get_all_lab_atts) to a data.frame.

Value

a data.frame object with label attribute information (re-) attached (if it exists in the specified lab.atts.list).

Examples

# make toy demographic (gender, raceth, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function

# let's add variable VALUE labels for variable "raceth"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Hispanic", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

get_val_labs(df, "raceth") # it's here

zlab.df <- get_all_lab_atts(df) # back up labelr attributes for df

df <- strip_labs(df) # this removes labs from df

get_val_labs(df, "raceth") # it's gone

check_any_lab_atts(df) # FALSE (means "no labs here")

df <- add_lab_atts(df, zlab.df) # restore them

Description

For a single value-labeled column of a data.frame, create a copy of that column that replaces all of its values with the corresponding value labels and added that copy to the supplied data.frame.

Usage

add_lab_col1(data, var, suffix = "_lab")

alc1(data, var, suffix = "_lab")

Arguments

Details

Note 1: add_lab_col1 is a variant of add_lab_cols that allows you to specify only one variable at a time but that allows you to pass its name without quoting it (compare add_lab_col1(mtcars, am) to add_lab_cols(mtcars, "am")).

Note 2: alc1 is a compact alias for add_lab_col1: they do the same thing, and the former is easier to type.

Note 3: This command is intended exclusively for interactive use. In particular, the var argument must be the literal name of a single variable (column) found in the supplied data.frame and may NOT be, e.g., the name of a character vector that contains the variable (column name) of interest. If you wish to supply a character vector with the names of variables (columns) of interest, use add_lab_cols().

add_lab_col1 creates a "labels-on" version of a value-labeled column and adds that new column to the supplied data.frame. Here, "labels-on" means that the column's original values are replaced with the corresponding value labels. Note that this column does not replace but is added to its parent/source columns in the returned data.frame. The resulting "labels-on" column is a simple, self-contained character column that cannot itself be converted or reverted to the original ("labels-off") values of its parent/source column. See add_lab_cols for a list of other functions that may be useful in working with value labels.

Value

A data.frame consisting of the originally supplied data.frame, along with the labels-on column added to it.

Examples

# add "labels-on" version of "am" to copy of mtcars
df <- mtcars # copy of mtcars

# now, add value labels
df <- add_val1(
  data = df,
  var = am,
  vals = c(0, 1),
  labs = c("automatic", "manual")
)

# add value labels-on version of "am" to df, assign to df_plus
df_plus <- add_lab_col1(df, am)
head(df_plus[c("am", "am_lab")])

Description

Add copies of value-labeled columns to a data.frame, where the new columns' values are replaced with the corresponding value labels.

Usage

add_lab_cols(data, vars = NULL, suffix = "_lab")

alc(data, vars = NULL, suffix = "_lab")

Arguments

Details

Note: alc is a compact alias for add_lab_cols: they do the same thing, and the former is easier to type.

add_lab_cols adds one or more "labels-on" columns to a data.frame, where "labels-on" means that the column's original values are replaced with the corresponding value labels. Note that these columns do not replace but are added to their parent/source columns in the returned data.frame. The resulting "labels-on" columns are simple, self-contained character columns that cannot themselves be converted or reverted to the original ("labels-off") values of their parent/source columns.

For other ways of accessing or leveraging value labels, see, e.g., use_val_labs, val_labs_vec, add_lab_dummies, lab_int_to_factor, flab, slab, get_val_labs, with_val_labs, headl, taill, somel, and tabl. In particular, see use_val_labs if, rather than adding a "labels-on" column to a data.frame, you wish to replace a column's values with the corresponding value labels. See val_labs_vec if you wish to convert a single, value-labeled column's values to labels and return the result as a stand-alone vector.

Value

A data.frame consisting of the originally supplied data.frame, along with (all or the select) labels-on variable versions added to it.

Examples

# one variable at a time, mtcars
df <- mtcars
# now, add value labels
df <- add_val_labs(
  data = df,
  vars = "am",
  vals = c(0, 1),
  labs = c("automatic", "manual")
)

df <- add_val_labs(
  data = df,
  vars = "carb",
  vals = c(1, 2, 3, 4, 6, 8),
  labs = c(
    "1-carb", "2-carbs",
    "3-carbs", "4-carbs",
    "6-carbs", "8-carbs"
  )
)

# var arg can be unquoted if using add_val1()
# note that this is not add_val_labs(); add_val1() has "var" (not "vars) arg
df <- add_val1(
  data = df,
  var = cyl, # note, "var," not "vars" arg
  vals = c(4, 6, 8),
  labs = c(
    "four-cyl",
    "six-cyl",
    "eight-cyl"
  )
)

df <- add_val_labs(
  data = df,
  vars = "gear",
  vals = c(3, 4),
  labs = c(
    "3-speed",
    "4-speed"
  )
)

# Oops, we forgot 5-speeds; let's finish the job.
df <- add_val_labs(
  data = df,
  vars = "gear",
  vals = 5,
  labs = "5-speed"
)

# add value labels-on versions of the foregoing to df and return as "df_plus"
df_plus <- add_lab_cols(df)
head(df_plus)
head(df_plus[c("am", "am_lab")])

Description

For a single value-labeled data.frame column, create a dummy (aka indicator) variable for each of that column's unique value labels.

Usage

add_lab_dumm1(
  data,
  var,
  simple.names = TRUE,
  sep = "_",
  prefix.length = 4,
  suffix.length = 7
)

ald1(
  data,
  var,
  simple.names = TRUE,
  sep = "_",
  prefix.length = 4,
  suffix.length = 7
)

Arguments

Details

Note 1: add_lab_dumm1 is a variant of add_lab_dummies that allows you to specify only one var to label at a time but that allows you to pass its name without quoting.

Note 2: ald1 is a compact alias for add_lab_dumm1: they do the same thing, and the former is easier to type

Note 3: If the default of simple.names is used, dummy variable column names will be the "parent" variable column name, followed by a separator character (by default, "_"), followed by a number, to differentiate each dummy variable from the others in the set. If one of the automatically generated dummy column names is already "taken" by a pre-existing data.frame column, an error to this effect will be thrown. If simple.names = FALSE, then prefix.length and suffix.length arguments will be used to construct dummy variable column names using the leading characters of the parent column name, followed by a separator character, followed by the leading characters of the value label. (white spaces in the value label will be replaced with the separator character).

Note 4: This command is intended exclusively for interactive use. In particular, the var argument must be the literal name of a single variable (column) found in the supplied data.frame and may NOT be, e.g., the name of a character vector that contains the variable (column name) of interest. If you wish to supply a character vector with the names of variables (columns) of interest, use add_lab_dummies().

Value

A data.frame with dummy variables added for all value labels of the value-labeled column supplied to the var argument.

Examples

# one variable at a time, mtcars
df <- mtcars

# now, add 1-to-1 value labels
df <- add_val_labs(
  data = df,
  vars = "am",
  vals = c(0, 1),
  labs = c("automatic", "manual")
)

df <- add_val_labs(
  data = df,
  vars = "carb",
  vals = c(1, 2, 3, 4, 6, 8),
  labs = c(
    "1-carb", "2-carbs",
    "3-carbs", "4-carbs",
    "6-carbs", "8-carbs"
  )
)

# var arg can be unquoted if using add_val1()
# note that this is not add_val_labs(); add_val1() has "var" (not "vars) arg
df <- add_val1(
  data = df,
  var = cyl, # note, "var," not "vars" arg
  vals = c(4, 6, 8),
  labs = c(
    "four-cyl",
    "six-cyl",
    "eight-cyl"
  )
)

# add many-to-1 value labels
df <- add_m1_lab(
  data = df,
  vars = "gear",
  vals = 4:5,
  lab = "4+"
)

# add quartile-based numerical range value labels
df <- add_quant_labs(
  data = df,
  vars = "disp",
  qtiles = 4
)

# add "pretty" cut-based numerical range value labels
(mpg_bins <- pretty(range(df$mpg, na.rm = TRUE)))

df <- add_quant_labs(data = df, vars = "mpg", vals = mpg_bins)

# add dummy variables for value labels of column "mpg"
df1 <- add_lab_dumm1(df,
  var = mpg,
  simple.names = TRUE
) # simple.names = TRUE is default
df1

# add dummy variables for value labels of column "am"
df2 <- add_lab_dumm1(df, am,
  sep = ".", simple.names = FALSE,
  prefix.length = 2, suffix.length = 6
)
df2

Description

For one or more value-labeled data.frame columns, create a dummy (aka indicator) variable for each unique value label.

Usage

add_lab_dummies(
  data,
  vars,
  simple.names = TRUE,
  sep = "_",
  prefix.length = 4,
  suffix.length = 7
)

ald(
  data,
  vars,
  simple.names = TRUE,
  sep = "_",
  prefix.length = 4,
  suffix.length = 7
)

Arguments

Details

If the default of simple.names is used, dummy variable column names will be the "parent" variable column name, followed by a separator character (by default, "_"), followed by a number, to differentiate each dummy variable from the others in the set. If one of the automatically generated dummy column names is already "taken" by a pre-existing data.frame column, an error to this effect will be thrown. If simple.names = FALSE, then prefix.length and suffix.length arguments will be used to construct dummy variable column names using the leading characters of the parent column name, followed by a separator character, followed by the leading characters of the value label. (white spaces in the value label will be replaced with the separator character).

Note: ald() is an alias function that behaves identically to add_lab_dummies.

Value

A data.frame with dummy variables added for all value labels of the value-labeled columns supplied to the vars argument.

Examples

# one variable at a time, mtcars
df <- mtcars

# now, add 1-to-1 value labels
df <- add_val_labs(
  data = df,
  vars = "am",
  vals = c(0, 1),
  labs = c("automatic", "manual")
)

df <- add_val_labs(
  data = df,
  vars = "carb",
  vals = c(1, 2, 3, 4, 6, 8),
  labs = c(
    "1-carb", "2-carbs",
    "3-carbs", "4-carbs",
    "6-carbs", "8-carbs"
  )
)

# var arg can be unquoted if using add_val1()
# note that this is not add_val_labs(); add_val1() has "var" (not "vars) arg
df <- add_val1(
  data = df,
  var = cyl, # note, "var," not "vars" arg
  vals = c(4, 6, 8),
  labs = c(
    "four-cyl",
    "six-cyl",
    "eight-cyl"
  )
)

# add many-to-1 value labels
df <- add_m1_lab(
  data = df,
  vars = "gear",
  vals = 4:5,
  lab = "4+"
)

# add quartile-based numerical range value labels
df <- add_quant_labs(
  data = df,
  vars = "disp",
  qtiles = 4
)

# add "pretty" cut-based numerical range value labels
(mpg_bins <- pretty(range(df$mpg, na.rm = TRUE)))

df <- add_quant_labs(data = df, vars = "mpg", vals = mpg_bins)

# add dummy variables for the labels of column "am"
df2 <- add_lab_dummies(df, "am",
  sep = ".", simple.names = FALSE,
  prefix.length = 2, suffix.length = 6
)
df2

# add dummy variables for the labels of columns "mpg", "gear", and "cyl
df3 <- add_lab_dummies(df, c("mpg", "gear", "cyl"), simple.names = TRUE) # default
df3

Description

Apply a single variable value label to multiple values of a variable ("m1" is shorthand for "many values get one label").

Usage

add_m1_lab(
  data,
  vars,
  vals,
  lab,
  partial = FALSE,
  not.vars = NULL,
  max.unique.vals = 10,
  init = FALSE
)

am1l(
  data,
  vars,
  vals,
  lab,
  partial = FALSE,
  not.vars = NULL,
  max.unique.vals = 10,
  init = FALSE
)

Arguments

Details

' add_m1_lab⁠(and⁠add1m1⁠) allows the user to assign the same value label to multiple distinct values of a variable ("m1" is short for "many-to-one"). This is in contrast to ⁠add_val_labsandadd_val1', which require a strict one-to-one mapping of distinct variable values and distinct value labels.

Note 1: Each call to add_m1_lab accepts only one value label, which may be applied to multiple distinct values of the specified column(s). Additional labels can be applied to other values of the same column(s) by making additional calls to add_m1_lab (see the example).

Note 2: am1l is a compact alias for add_m1_lab: they do the same thing, and the former is easier to type

Value

A data.frame, with new variable value labels added (call get_val_labs to see them), other provisional/default labelr label information added, and previous user-added labelr label information preserved.

Examples

df <- mtcars

df <- add_m1_lab(df,
  vars = "carb",
  vals = 1:3,
  lab = "<=3",
  max.unique.vals = 10
)

df <- add_m1_lab(df,
  vars = "carb",
  vals = c(4, 6, 8),
  lab = ">=4",
  max.unique.vals = 10
)

get_val_lab1(df, carb)

head(use_val_labs(df), 8) # they're there

Description

Add descriptive variable name labels (up to one per column) to the columns of a data.frame.

Usage

add_name_labs(
  data,
  name.labs = NULL,
  vars = NULL,
  labs = NULL,
  init.max = NULL
)

anl(data, name.labs = NULL, vars = NULL, labs = NULL, init.max = NULL)

Arguments

Details

Note: anl is a compact alias for add_name_labs: they do the same thing, and the former is easier to type.

add_name_labs works with get_name_labs, use_name_labs, and use_var_names to facilitate the creation, accessing, and substitution of variable name labels for variable names.

Each variable (column) of a data.frame can receive one and only one "name label," which typically is a noun phrase that expounds the meaning of contents of the variable's name (e.g., "Weight in ounces at birth" might be a name label for a column called "wgt"). add_name_labs takes a data.frame and either a named character vector (names are current variable names, values are proposed name labels) supplied to the name.labs arg or two separate character vectors (one each for current variable names and proposed variable name labels, respectively) supplied to vars and labs args, respectively. If using the second approach, the order of each entry matters (e.g., the first variable name entry to the vars argument will be given the label of the first name label entry to the labs argument, and so on).

Note that any non-name-labeled columns will receive their own names as default name labels (e.g., if var "mpg" of mtcars is not assigned a name label, it will be given the default name label of "mpg"). Note also that other labelr functions (e.g., add_val_labs) will initialize name labels and other labelr attribute meta-data in this same fashion. Name labels can be removed with drop_name_labs.

Value

A data.frame, with new name labels added (call get_name_labs to see them), other provisional/default labelr label information added, and previous user-added labelr label information preserved.

Examples

# create a data set
df <- mtcars

# variable names and their 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"
)

# assign variable labels
df <- add_name_labs(df,
  vars = names(names_labs_vec),
  labs = names_labs_vec
)

# see what we have
get_name_labs(df)

# use these
df_labs_as_names <- use_name_labs(df)
head(df_labs_as_names)[1:3] # these are verbose, so, only show first three
head(df)[1:3]

# now revert back
df_names_as_before <- use_var_names(df_labs_as_names)
head(df_names_as_before)[1:3] # indeed, they are as before
identical(head(df), head(df_names_as_before))

# strip name label meta-data information from df
# NOT same as use_var_names(), which preserves the info but "turns it off"
# this strips the name labels meta-data from df altogether
df <- drop_name_labs(df)

# see what we have
get_name_labs(df) # they're gone

# alternative syntax (if you have a named vector like names_labs_vec)
# assign variable name labels
df <- add_name_labs(df,
  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"
  )
)

# replace two variable name labels, keeping the others
df <- add_name_labs(df,
  name.labs = c(
    "disp" = toupper("displacement"),
    "mpg" = toupper("miles per gallon")
  )
)

attributes(df) # show all attributes
get_name_labs(df) # show only the variable name labels
get_name_labs(df, var = c("disp", "mpg"))

# again, strip name label meta-data information from df
# NOT same as use_var_names(), which preserves the info but "turns it off"
df <- drop_name_labs(df)

# see what we have
get_name_labs(df) # they're gone

# alternative syntax to add name labels
df <- add_name_labs(df,
  vars = c("carb", "am"),
  labs = c("how many carburetors?", "automatic or stick?")
)

# see what we have
get_name_labs(df) # they're back! (and placeholders for others)

# add another
df <- add_name_labs(df,
  vars = c("mpg"),
  labs = c("miles per gallon, of course")
)

# see what we have
get_name_labs(df) # it's been added, and others preserved

head(use_name_labs(df)[c(1, 9, 11)]) # verbose, but they're there

Description

Add variable-specific value labels based on threshold cuts of a numerical variable.

Usage

add_quant_labs(
  data,
  vars,
  qtiles = NULL,
  vals = NULL,
  labs = NULL,
  partial = FALSE,
  not.vars = NULL
)

aql(
  data,
  vars,
  qtiles = NULL,
  vals = NULL,
  labs = NULL,
  partial = FALSE,
  not.vars = NULL
)

Arguments

Details

Note: aql is a compact alias for add_quant_labs: they do the same thing, and the former is easier to type.

Numerical variables that feature decimals or large numbers of distinct values are not eligible to receive conventional value labels. add_quant_labs allows one to label such variables according to user-supplied value thresholds (i.e., cutpoints) OR quantile membership, Thus, unlike value labels added with add_val_labs (and add_val1), add_quant_labs (and add_quant1) will apply the same value label to all values that fall within the numerical value range defined by each threshold (cutpoint). For still another value-labeling approach, see add_m1_lab (and add1m1).

Note: Quantity labels cannot be added incrementally through repeated calls to add_quant_labs: each new call will overwrite all value labels applied to the specified vars in any previous add_quant_labs calls. This is in contrast to add_val_labs (which allows for incremental value-labeling) and add_m1_lab (which requires incremental value-labeling).

Value

A data.frame, with new variable value labels added (call get_val_labs to see them), other provisional/default labelr label information added, and previous user-added labelr label information preserved.

Examples

# mtcars demo
df <- mtcars
# now, add value labels
df <- add_val_labs(
  data = df,
  vars = "am",
  vals = c(0, 1),
  labs = c("automatic", "manual")
)

# label variable "mpg" in terms of 5 quintiles
df <- add_quant_labs(data = df, vars = "mpg", qtiles = 5)

# label variable "disp" in terms of "pretty" cutpoints
vals2use <- pretty(c(min(df$disp), max(df$disp)))[-1] # establish cutpoints
df <- add_quant_labs(data = df, vars = "disp", vals = vals2use)
df_labson <- use_val_labs(df)
head(df_labson)

Description

Add variable-specific value labels based on threshold cuts of a single numerical variable.

Usage

add_quant1(data, var, qtiles = NULL, vals = NULL, labs = NULL)

aql1(data, var, qtiles = NULL, vals = NULL, labs = NULL)

Arguments

Details

add_quant1 is a variant of add_quant_labs that allows you to specify only one var to label but allows you to pass its name without quoting it (compare add_quant1(mtcars, mpg) to add_quant_labs(mtcars, "mpg").

Numerical variables that feature decimals or large numbers of distinct values are not eligible to receive conventional value labels. add_quant1 allows one to label such variables according to user-supplied value thresholds (i.e., cutpoints) OR quantile membership, Thus, unlike value labels added with add_val_labs (and add_val1), add_quant1 (and add_quant_labs) will apply the same value label to all values that fall within the numerical value range defined by each threshold (cutpoint). For still another value-labeling approach, see add_m1_lab (and add1m1).

Note 1: Quantity labels cannot be added incrementally through repeated calls to add_quant1: each new call will overwrite all value labels applied to the specified vars in any previous add_quant1 calls. This is in contrast to add_val_labs (which allows for incremental value-labeling) and add_m1_lab (which requires incremental value-labeling).

Note 2: aql1 is a compact alias for add_quant1: they do the same thing, and the former is easier to type

Note 3: This command is intended exclusively for interactive use. In particular, the var argument must be the literal name of a single variable (column) found in the supplied data.frame and may NOT be, e.g., the name of a character vector that contains the variable (column name) of interest. If you wish to supply a character vector with the names of variables (columns) of interest, use add_quant_labs().

Value

A data.frame, with new variable value labels added (call get_val_labs to see them), other provisional/default labelr label information added, and previous user-added labelr label information preserved.

Examples

# mtcars demo
df <- mtcars
# now, add value labels
df <- add_val_labs(
  data = df,
  vars = "am",
  vals = c(0, 1),
  labs = c("automatic", "manual")
)

# label variable "mpg" in terms of 5 quintiles
df <- add_quant1(data = df, mpg, qtiles = 5)

# label variable "disp" in terms of "pretty" cutpoints
vals2use <- pretty(c(min(df$disp), max(df$disp)))[-1] # establish cutpoints
df <- add_quant1(data = df, disp, vals = vals2use)
df_labson <- use_val_labs(df)
head(df_labson)

Description

Add variable value-specific, descriptive value labels to a data.frame.

Usage

add_val_labs(
  data,
  vars,
  vals,
  labs,
  partial = FALSE,
  not.vars = NULL,
  max.unique.vals = 10,
  init = FALSE
)

avl(
  data,
  vars,
  vals,
  labs,
  partial = FALSE,
  not.vars = NULL,
  max.unique.vals = 10,
  init = FALSE
)

Arguments

Details

Note: avl is a compact alias for add_val_labs: they do the same thing, and the former is easier to type

add_val_labs is intended for associating value labels with binary, nominal, or ordinal (e.g., integer) variables, where each of a limited number of distinct values is to be associated one-to-one with a distinct value label. To assign labels to ranges of numerical variables, see add_quant_labs (or add_quant1). To apply the same label to multiple distinct values of a variable, see add_m1_lab or add1m1.

add_val_labs works with other labelr functions (e.g., add_val1, drop_val_labs, get_val_labs, use_val_labs, add_lab_cols) to facilitate the creation, accessing, modification, use, or deletion of variable value labels.

When using add_val_labs or add_val1, each distinct variable value can receive one and only one value label, and for any given variable, each unique label can be assigned to only one unique value (e.g., mtcars$gear==3 and mtcars$gear==4 cannot both share a single "3 or 4 gears" label: each of these two distinct values must have its own label). This latter constraint may be relaxed by using add_m1_lab.

If partial = TRUE, add_val_labs will apply the specified labeling scheme to all variables that contain a key variable name substring of interest (supplied to the vars argument), which may be one or more variables found in the data.frame (see Example #2).

Value

A data.frame, with new variable value labels added (call get_val_labs to see them), other provisional/default labelr label information added, and previous user-added labelr label information preserved.

Examples

# Example #1 - mtcars example, one variable at a time
# one variable at a time, mtcars
df <- mtcars
# now, add value labels
df <- add_val_labs(
  data = df,
  vars = "am",
  vals = c(0, 1),
  labs = c("automatic", "manual")
)

df <- add_val_labs(
  data = df,
  vars = "carb",
  vals = c(1, 2, 3, 4, 6, 8),
  labs = c(
    "1-carb", "2-carbs",
    "3-carbs", "4-carbs",
    "6-carbs", "8-carbs"
  )
)

# var arg can be unquoted if using add_val1()
# note that this is not add_val_labs(); add_val1() has "var" (not "vars" arg)
df <- add_val1(
  data = df,
  var = cyl, # note, "var," not "vars" arg
  vals = c(4, 6, 8),
  labs = c(
    "four-cyl",
    "six-cyl",
    "eight-cyl"
  )
)

df <- add_val_labs(
  data = df,
  vars = "gear",
  vals = c(3, 4),
  labs = c(
    "3-speed",
    "4-speed"
  )
)

# Oops, we forgot 5-speeds; let's finish the job.
df <- add_val_labs(
  data = df,
  vars = "gear",
  vals = 5,
  labs = "5-speed"
)

head(use_val_labs(df), 3) # they're there

# Example #2 - (Fake) Likert Data
# add val labs to multiple variables at once
# make a "Likert"-type fake data set to demo
# note, by default, add_val_labs() "vars" arg will do partial matching
# in this case, we catch all vars with "x" in their name
set.seed(272)
dflik <- make_likert_data(scale = 1:7)
vals2label <- 1:7
labs2use <- c(
  "VSD",
  "SD",
  "D",
  "N",
  "A",
  "SA",
  "VSA"
)

dflik <- add_val_labs(
  data = dflik, vars = c("x", "y3"), # note the vars args
  vals = vals2label,
  labs = labs2use,
  partial = TRUE
)

# note, all "x" vars get the labs, as does "y3"
# see vars = args above
lik1 <- use_val_labs(dflik)
head(lik1)
# keep a copy
dflik_conv <- use_val_labs(dflik)
head(dflik_conv, 3)

Description

Add variable value-specific, descriptive value labels to a data.frame.

Usage

add_val1(data, var, vals, labs, max.unique.vals = 10, init = FALSE)

avl1(data, var, vals, labs, max.unique.vals = 10, init = FALSE)

Arguments

Details

add_val1 is intended for associating value labels with binary, nominal, or ordinal (e.g., integer) variables, where each of a limited number of distinct values is to be associated one-to-one with a distinct value label. To assign labels to ranges of numerical variables, see add_quant_labs (or add_quant1). To apply the same label to multiple distinct values of a variable, see add_m1_lab or add1m1.

add_val1 works with other labelr functions (e.g., add_val_labs, drop_val_labs, get_val_labs, use_val_labs, add_lab_cols) to facilitate the creation, accessing, modification, use, or deletion of variable value labels.

Note 1: add_val1 is a variant of add_val_labs that allows you to specify only one var to label at a time but that allows you to pass its name without quoting it (compare add_val1(mtcars, am) to add_val_labs(mtcars, "am").

Note 2: avl1 is a compact alias for add_val1: they do the same thing, and the former is easier to type

Note 3: This command is intended exclusively for interactive use. In particular, the var argument must be the literal name of a single variable (column) found in the supplied data.frame and may NOT be, e.g., the name of a character vector that contains the variable (column name) of interest. If you wish to supply a character vector with the names of variables (columns) of interest, use add_val_labs().

Value

A data.frame, with new name labels added (call get_val_labs to see them), other provisional/default labelr label information added, and previous user-added labelr label information preserved.

Examples

# one variable at a time, mtcars
df <- mtcars
# add value labels
# first, using add_val_labs() -- add_val1() example is below
df <- add_val_labs(
  data = df,
  vars = "carb", # note, vars arg; add_val1() takes var arg
  vals = c(1, 2, 3, 4, 6, 8),
  labs = c(
    "1-carb", "2-carbs",
    "3-carbs", "4-carbs",
    "6-carbs", "8-carbs"
  )
)

# now, using add_val1(), where single var arg can be unquoted (cyl, not "cyl")
# note that this is not add_val_labs();
df <- add_val1(
  data = df,
  var = cyl, # note, var arg, not vars arg
  vals = c(4, 6, 8),
  labs = c(
    "four-cyl",
    "six-cyl",
    "eight-cyl"
  )
)

Description

Apply a single variable value label to multiple values of a variable ("m1" is shorthand for "many values get one label").

Usage

add1m1(data, var, vals, lab, max.unique.vals = 10, init = FALSE)

Arguments

Details

Note 1: add1m1 is a variant of add_m1_lab that allows you to specify only one var to label but allows you to pass its name without quoting it (compare add1m1(mtcars, am, ...) to add_m1_lab(mtcars, "carb", ...).

Note 2: add1m1 (and add_m1_lab) allows the user to assign the same value label to multiple distinct values of a variable ("m1" is short for "many-to-one"). This is in contrast to add_val1 (and add_val_labs), which requires a strict one-to-one mapping of distinct variable values and distinct value labels.

Note 3: This command is intended exclusively for interactive use. In particular, the var argument must be the literal name of a single variable (column) found in the supplied data.frame and may NOT be, e.g., the name of a character vector that contains the variable (column name) of interest. If you wish to supply a character vector with the names of variables (columns) of interest, use add_m1_lab().

Value

A data.frame, with new variable value labels added (call get_val_labs to see them), other provisional/default labelr label information added, and previous user-added labelr label information preserved.

Examples

df <- mtcars

df <- add1m1(df,
  var = carb,
  vals = 1:3,
  lab = "<=3",
  max.unique.vals = 10
)

df <- add1m1(df,
  var = carb,
  vals = c(4, 6, 8),
  lab = ">=4",
  max.unique.vals = 10
)

head(use_val_labs(df), 8) # they're there

Description

Add variable-specific quantile-based value labels to all numeric variables of a data.frame that meet specified conditions.

Usage

all_quant_labs(data, qtiles = 5, not.vars = NULL, unique.vals.thresh = 10)

allq(data, qtiles = 5, not.vars = NULL, unique.vals.thresh = 10)

Arguments

Details

Note: allq is a compact alias for all_quant_labs: they do the same thing, and the former is easier to type.

Numerical variables that feature decimals or large numbers of distinct values are not eligible to receive conventional add_val_labs()-style value labels. all_quant_labs allows one to label such variables based on quantile thresholds.

Value

A data.frame, with new variable value labels added.

Examples

# mtcars demo
df <- mtcars
get_val_labs(df) # none
# add quintile val labs for all numeric vars with >10 unique vals
df <- all_quant_labs(data = df, qtiles = 5, unique.vals.thresh = 10)
get_val_labs(df) # here now
headl(df) # show them; note this is labelr::headl(), not utils::head()

Description

For a given vector, does the length of (number of values in) the vector equal the number of unique values in the vector?

Note: all_univ is a compact alias for all_uniquev: they do the same thing, and the former is easier to type

Usage

all_uniquev(x, na.rm = TRUE)

all_univ(x, na.rm = TRUE)

Arguments

Value

a 1L logical.

Examples

all_uniquev(mtcars$am) # FALSE

set.seed(35994)
z <- runif(25)
all_univ(z) # TRUE; all_univ is an alias for all_uniquev()

z[c(1, 2)] <- NA # two NA values added
all_univ(z, na.rm = FALSE) # FALSE, because the two NA values are not unique

Description

as_base_data_frame noisily converts an augmented data.frame to a Base R data.frame.

Usage

as_base_data_frame(data, fact.to.char = FALSE, irreg.to.na = FALSE)

adf(data, fact.to.char = FALSE, irreg.to.na = FALSE)

Arguments

Details

Note: adf is a compact alias for as_base_data_frame: they do the same thing, and the former is easier to type

To minimize dependencies and complexities, labelr label-assigning functions are designed to work exclusively with Base R data.frames, not alternative data structures like matrices or augmented data.frames, such as data.tables or tibbles. The suggested labeling workflow is to first assign and work with labels using a Base R data.frame and then convert the resulting object to an augmented data.frame as desired and without any assumption that labelr labels or functions will smoothly interoperate with the augmented data.frame construct or functions that depend on it.

as_base_data_frame determines whether data argument is a conventional Base R data.frame, some kind of augmented data.frame (e.g., data.table, tibble), or not a data.frame at all (e.g., matrix). If the object has multiple classes, one of which is a data.frame, the object is coerced to be a conventional Base R data.frame, and a message to that effect is issued. If the supplied object is not any kind of data.frame (i.e., a matrix is not any kind of data.frame, while a data.table is a kind of data.frame), an error is thrown. If the supplied object already is a Base R data.frame with no additional classes (i.e., not an augmented data.frame), that supplied object is returned with no changes made and no messages.

Value

a data.frame object with any additional classes removed.

Examples

x1 <- runif(10)
x2 <- as.character(sample(c(1:20), 10, replace = TRUE))
x3 <- sample(letters, size = 10, replace = TRUE)
df <- data.frame(x1, x2, x3)
dft <- tibble::as_tibble(df)
class(dft)
df_vanilla <- as_base_data_frame(dft)
class(df_vanilla)

Description

as_base_data_frame2 noisily converts an augmented data.frame to a Base R data.frame, with any factors converted to character vectors, and any irregular values (see irregular2()) converted to NA.

Usage

as_base_data_frame2(data, fact.to.char = TRUE, irreg.to.na = TRUE)

adf2(data, fact.to.char = TRUE, irreg.to.na = TRUE)

Arguments

Details

Note: adf2 is a compact alias for as_base_data_frame: they do the same thing, and the former is easier to type

as_base_data_frame2 is a variant of as_base_data_frame with different default values for fact.to.char and irreg.to.na. Whereas both of these default to FALSE in as_base_data_frame, they both default to TRUE in as_base_data_frame2. This is the only difference between the two functions. As such, as_base_data_frame2 is intended as a simple shortcut to save typing if one prefers to reverse these default logical argument values.

Value

a data.frame object with any additional classes removed.

Examples

iris_tib <- tibble::as_tibble(iris)
class(iris_tib)
iris_tib$Sepal.Length[1] <- Inf
head(iris_tib, 1)
iris_df <- as_base_data_frame2(iris_tib)
class(iris_df)
sapply(iris_df, class)
head(iris_df, 1)

Description

as_labeled_data_frame quietly assigns the class labeled.data.frame to a data.frame and discards other augmented data.frame classes, returning a data.frame with classes labeled.data.frame and data.frame.

Usage

as_labeled_data_frame(data, fact.to.char = FALSE, irreg.to.na = FALSE)

aldf(data, fact.to.char = FALSE, irreg.to.na = FALSE)

Arguments

Details

Note 1: aldf is a compact alias for as_labeled_data_frame: they do the same thing, and the former is easier to type

Note 2: as_labeled_data_frame is used internally by other labelr commands and is not intended for interactive use.

To minimize dependencies and complexities, labelr label-assigning functions are designed to work exclusively with Base R data.frames, not alternative data structures like matrices or augmented data.frames, such as data.tables or tibbles.

as_labeled_data_frame determines whether data argument is a conventional Base R data.frame, some kind of augmented data.frame (e.g., data.table, tibble), or not a data.frame at all (e.g., matrix). If the submitted object is a type of data.frame, the object will be returned with the class labeled.data.frame applied, the class data.frame retained, and any other previous class attributes discarded. If the supplied object is not any kind of data.frame (i.e., a matrix is not any kind of data.frame, while a data.table is a kind of data.frame), an error is thrown.

Value

an object of classes labeled.data.frame and data.frame, with any additional classes removed.

Examples

x1 <- runif(10)
x2 <- as.character(sample(c(1:20), 10, replace = TRUE))
x3 <- sample(letters, size = 10, replace = TRUE)
df <- data.frame(x1, x2, x3)
dft <- tibble::as_tibble(df)
class(dft)
dfl <- as_labeled_data_frame(dft)
class(dfl)

Description

as_num identifies the character variables of a data.frame that can be coerced to numeric without generating new NA values and, for those variables where this can be done, it makes those conversions (similar to Stata's destring command).

Usage

as_num(data, nan2na = TRUE, inf2na = TRUE)

Arguments

Details

Core labelr functions coerce integers to characters and back, which as_num facilitates. Note that character values of "NA" (including "na", "Na", and "nA") will be converted to NA and, by default, so will other "irregular" values (in the sense of check_irregular).

Value

a data.frame object with all applicable character variables coerced to numeric.

Examples

set.seed(123)
x1 <- runif(10)
x2 <- as.character(sample(c(1:20), 10, replace = TRUE))
x3 <- sample(letters, size = 10, replace = TRUE)
df <- data.frame(x1, x2, x3)
head(df, 3)
sapply(df, class)
class(df$x2)

df <- as_num(df)
head(df,3)
sapply(df, class)
class(df$x2)

Description

as_numv determines whether a character vector can be coerced to numeric without generating new NA values and, if so, it makes that conversion (similar to Stata's destring command).

Usage

as_numv(x, nan2na = TRUE, inf2na = TRUE)

Arguments

Details

Core labelr functions coerce integers to characters and back, which as_numv facilitates. Note that character values of "NA" (including "na", "Na", and "nA") will be converted to NA and, by default, so will other "irregular" values (in the sense of check_irregular).

Value

a vector, converted to numeric if feasible (else, the same character vector that was supplied).

Examples

set.seed(123)
x1 <- runif(10)
x2 <- as.character(sample(c(1:20), 10, replace = TRUE))
x2_num <- as_numv(x2)
class(x2)
class(x2_num)
head(x2)

Description

axis_lab accepts a data.frame and single unquoted variable name and returns that variable's name label for use in axis labeling or plot labeling function options.

Usage

axis_lab(data, var)

alb(data, var)

Arguments

Details

Note 1: alb is a compact alias for axis_lab: they do the same thing, and the former is easier to type.

Note 2: This command is intended exclusively for interactive use. In particular, the var argument must be the literal name of a single variable (column) found in the supplied data.frame and may NOT be, e.g., the name of a character vector that contains the variable (column name) of interest.

Value

a 1L character vector with var's name label.

Examples

# copy mtcars to df
# create a data set
df <- mtcars

# variable names and their labels
names_labs_vec <- c(
  "mpg" = "Miles/(US) gallon",
  "cyl" = "Number of cylinders",
  "wt" = "Weight (1000 lbs)"
)

df <- add_name_labs(df, name.labs = names_labs_vec)

# ggplot example of axis_lab()
library(ggplot2)
p <- ggplot(df, aes(mpg, wt, color = cyl)) +
  geom_point()
p <- p +
  labs(color = axis_lab(df, cyl)) +
  xlab(axis_lab(df, mpg)) +
  ylab(axis_lab(df, wt))

# Base R plot example (using alb() alias)
with(df, plot(mpg, wt,
  xlab = alb(df, mpg),
  ylab = alb(df, wt)
))

Description

check_any_lab_atts returns FALSE if your data.frame has no labelr-generated meta-data attributes (still) associated with it (at all or of a specific sub-type), and TRUE if it does.

Usage

check_any_lab_atts(data, labs = "any")

Arguments

Details

By default (labs = "any"), this function looks to see if your data.frame's attributes includes any attribute with a name containing the substring "frame.lab", "name.labs", "val.labs", and/or "factor." These are the core substrings of the label meta-data attributes that labelr creates and manipulates. If you wish to narrow your search for a specific labelr, attribute, you may supply this as a character (sub)string (e.g., check_any_lab_atts(df, "val.labs.cyl") to see if the variable "cyl" has variable value label meta-data). But make sure that your second argument is meaningful (e.g., check_any_lab_atts(iris, "row.") will return TRUE true based on the presence of a standard "row.names" attribute, which has nothing to do with labels.

Value

TRUE if any instance of the default or user-specified meta-data attribute is found, FALSE if not.

Examples

# make toy demographic (gender, raceth, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function
# let's add variable VALUE labels for variable "raceth"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Hispanic", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

check_any_lab_atts(df)

Description

check_class determines whether a vector's class is among those specified.

Usage

check_class(
  x,
  classes = c("numeric", "integer", "logical", "character", "factor", "ordered"),
  strict = TRUE
)

Arguments

Details

By default (strict = TRUE), if a vector is of multiple classes, all of its classes must be among those specified via the classes argument.

Value

a 1L logical vector indicating whether x's class is found among those passed to the classes argument.

Examples

check_class(mtcars$mpg) # TRUE
check_class(mtcars$mpg, classes = c("numeric", "factor")) # TRUE
check_class(iris$Species) # TRUE
check_class(iris$Species, classes = c("logical", "numeric")) # FALSE
check_class(mtcars$mpg, classes = c("logical", "character", "factor")) # FALSE

Description

Check a vector for the presence of "irregular" values, defined as NA values, other arbitrary values you specify, and (by default): NaN, Inf, -Inf, and character variants of same (i.e., upper, lower, or mixed-case variants of "NA","NAN","INF","-INF").

Usage

check_irregular(
  x,
  nan.include = TRUE,
  inf.include = TRUE,
  special = c("NA", "NAN", "INF", "-INF"),
  other = NULL,
  any = FALSE
)

Arguments

Details

check_irregular is used by core labelr functions (e.g., add_val_labs) to ensure that NA and other irregular (e.g., Inf) values are handled in a simple and consistent – and, hence, rigid – fashion. It is not intended as a user- facing command as part of a labelr data-analytic workflow, though it may be useful in other applications where one wishes to test a vector against a focal and user-extensible class of NA-esque (or other) offending values.

Value

A logical vector (1L if any==TRUE; length of x if any==FALSE).

Examples

# below is FALSE, because there is nothing NA-like in this vector
check_irregular(1:10)

# below is TRUE, because we're treating 99 as "NA-esque"
check_irregular(1:100, other = 99)

# below is TRUE, because of NA val
check_irregular(c(1:100, NA))

# below is TRUE, because nan.include is on (by default)
check_irregular(c(1:100, NaN), nan.include = TRUE)

# below is TRUE, because inf.include is on (by default)
check_irregular(c(1:100, Inf), inf.include = TRUE)

# below is TRUE, because inf.include is on (by default)
check_irregular(c(1:100, -Inf), inf.include = TRUE)

# below is FALSE, it's just letters
check_irregular(letters)

# below is TRUE - see default vals for arg special (function not case-sens)
check_irregular(c(letters, "NA"))

# below is TRUE - see default vals for arg special (function not case-sens)
check_irregular(c(letters, "NAN"))

# below is TRUE - see default vals for arg special (function not case-sens)
check_irregular(c(letters, "-iNf"))

# below is FALSE, search for irregular vals is not substring/regex-based
check_irregular(c(letters, "nan-iNf"))

Description

check_labs_att returns TRUE if your data.frame has the specific attribute indicated and FALSE if it does not.

Usage

check_labs_att(data, att = NULL)

Arguments

Value

TRUE if any instance of the default or user-specified meta-data attribute is found, FALSE if not.

Examples

# make toy demographic (gender, raceth, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function
# let's add variable VALUE labels for variable "race"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Hispanic", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

check_labs_att(df) # is any valid labelr lab(el) attribute present?
check_labs_att(df, "val.labs.race") # "race" lab specifically TRUE

Description

Drops name.lab and val.lab attributes associated with columns that are not present in the data.frame (i.e., have been dropped) and re-arranges data.frame attributes so that they appear in a clean, logical order.

Usage

clean_data_atts(data)

Arguments

Details

labelr meta-data exist as data.frame attributes, added through interactive use in a potentially haphazard order. This function, which is used inside other labelr functions, drops labels for variables that are not (no longer) present in the data.frame and re-arranges label and other data.frame attributes to put them in a more, logical, user-readable order when accessed via, e.g., attributes().

Value

A data.frame, with attributes re-arranged.

Examples

# make toy demographic (age, gender, raceth) data set
set.seed(555)
df <- make_demo_data(n = 1000)

# let's add variable VALUE labels for variable "raceth"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Latino", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

# let's add variable VALUE labels for variable "gender"
df <- add_val1(
  data = df, gender, vals = c(0, 1, 2),
  labs = c("M", "F", "O"), max.unique.vals = 50
)

# let's add variable NAME labels
df <- add_name_labs(df, name.labs = c(
  "age" = "Age in years",
  "raceth" = "raceth category",
  "gender" = "gender assigned at birth"
))


# let's add a frame label
df <- add_frame_lab(df, frame.lab = "This is a fictional data set that includes
                    demographic variables. It is generated by
                    labelr::make_demo_data")

# show attributes
attributes(df)

# re-arrange and show attributes
df2 <- clean_data_atts(df)
attributes(df2)

# confirm that attributes from df are all present in df2
all(attributes(df) %in% attributes(df2)) # TRUE

Description

Convert a data.frame with Haven package-style labels to a data.frame with labelr name labels and add_val_labs-style one-to-one, value labels.

Usage

convert_labs(data, max.unique.vals = 50)

Arguments

Value

a data.frame.

Examples

# convert haven vector labels to labelr value labels
library(haven)
library(tibble)
x1 <- labelled(1:8, c(good = 1, bad = 5))
x2 <- labelled(1:8, c(good = 1, mediocre = 4, bad = 5, horrible = 8))

# make this a tibble
hdf <- tibble::tibble(x1, x2)
hdf # how it looks

# convert value labels to labelr label values
hdf1 <- convert_labs(hdf)

# show select values of hdf1
head(hdf1)

# show that labelr labels are there for the using
head(use_val_labs(hdf1))

# filter hdf1 using x1's "bad" labelr value label (with flab())
head(flab(hdf1, x1 == "bad"), 3)

# filter hdf1 using x1's "good" value label (with flab())
head(flab(hdf1, x1 == "good"), 3)

# return select rows and columns with slab()
slab(hdf1, x2 %in% c("good", 2), x2)
slab(hdf1, x2 %in% c("good", 2), x1)

Description

Note: copy_var copies an existing variable and its value labels from a data.frame to another new or (if force = TRUE) existing variable of the data.frame.

Usage

copy_var(data, from.var, to.var, force = FALSE)

Arguments

Details

Any non-labelr R operation that changes a variable's (column's) name or that copies its contents to another variable (column) with a different name will not associate the original variable's value labels with the new variable name. To mitigate this, copy_var allows one to copy both a variable (column) and its value labels and assign those to another variable.

Value

A data.frame.

Examples

# make toy demographic (gender, raceth, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function
# let's add variable VALUE labels for variable "raceth"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Hispanic", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

head(df, 4)
df <- copy_var(df, from.var = raceth, to.var = re_copy)
df <- copy_var(df, from.var = x1, to.var = var1)
head(df, 4)
get_val_labs(df)

Description

Remove the frame label attribute (see add_frame_lab) from a data.frame, if one is present.

Usage

drop_frame_lab(data)

dfl(data)

Arguments

Details

See add_frame_lab for more on this labeling construct.

Note: dfl is a compact alias for drop_frame_lab: they do the same thing, and the former is easier to type.

Value

a data.frame (with any previously applied frame.lab attribute removed).

Examples

# add frame.lab to mtcars and assign to new data.frame mt2
mt2 <- add_frame_lab(mtcars, frame.lab = "Data extracted from the 1974 Motor
                    Trend US magazine, comprising fuel consumption and 10
                    aspects of automobile design and performance for 32
                    automobiles (1973–74 models). Source: Henderson and
                    Velleman (1981), Building multiple regression models
                    interactively. Biometrics, 37, 391–411.")

get_frame_lab(mt2) # return frame.lab alongside data.frame name as a data.frame
drop_frame_lab(mt2) # remove this frame.lab
get_frame_lab(mt2) # the data.frame name now doubles as its frame label
is.null(attributes(data)[["frame.lab"]]) # the attribute is NULL

Description

Remove one or more descriptive variable name label attributes previously added to a data.frame using add_name_labs.

Note: dnl is a compact alias for drop_name_labs: they do the same thing, and the former is easier to type

Usage

drop_name_labs(data, vars = NULL)

dnl(data, vars = NULL)

Arguments

Details

drop_name_labs works with add_name_labs, get_name_labs and use_name_labs to facilitate creation, accessing, substitution, and removal of variable name labels for variable names. Each variable (column) of a data.frame can receive one and only one "name label," which typically is a noun phrase that expounds the meaning or contents of the variable's name (e.g., "Weight in ounces at birth" might be a viable name label for a column called "wgt"). drop_name_labs takes a data.frame and (optionally) a character vector of variables whose name labels should be discarded: If only a data.frame is provided, all variable name labels will be dropped. You can assign new name labels using new calls to add_name_labs (If you wish to change some or all name labels, you do not need to call drop_name_labs: you can simply pass the new name labels to add_name_labs, and they will overwrite the old ones (including any automatically generated provisional ones), while leaving in place any previously added name labels that you do not explicitly replace).

Value

The same data.frame you submitted, except that the selected name label attribute meta-data has been removed.

Examples

# create a data set
df <- mtcars

# variable names and their 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"
)

# assign variable labels
df <- add_name_labs(df,
  vars = names(names_labs_vec),
  labs = names_labs_vec
)

# see what we have
get_name_labs(df)

# drop the name label for var/col "am"
df <- drop_name_labs(df, "am")

# see what this did to the name label for "am"
get_name_labs(df)

# now, drop all of the name labels
df <- drop_name_labs(df)
get_name_labs(df) # they're gone

Description

Drop all value labels previously applied to one or more variables using add_val_labs, add_quant_labs,add_m1_lab, and related functions (e.g., add_val1) or aliases (e.g., avl).

Note: dvl is a compact alias for drop_val_labs: they do the same thing, and the former is easier to type

Usage

drop_val_labs(data, vars = NULL, partial = FALSE, not.vars = NULL)

dvl(data, vars = NULL, partial = FALSE, not.vars = NULL)

Arguments

Details

drop_val_labs works with other labelr functions (e.g., add_val_labs, get_val_labs, use_val_labs, add_lab_cols) to facilitate the creation, accessing, modification, use, or deletion of variable value labels.

Value

A data.frame, with all value labels dropped from specified variables.

Examples

# make a "Likert"-type fake data set to demo
# note, by default, add_val_labs() "vars" arg will do partial matching
# in this case, we catch all vars with "x" in their name
set.seed(272)
dflik <- make_likert_data(scale = 1:7)
vals2label <- 1:7
labs2use <- c(
  "VSD",
  "SD",
  "D",
  "N",
  "A",
  "SA",
  "VSA"
)

dflik <- add_val_labs(
  data = dflik, vars = c("x", "y3"), # note the vars args
  vals = vals2label,
  labs = labs2use,
  partial = TRUE
)

dfdrop <- drop_val_labs(dflik,
  vars = c("x2", "y3"),
  partial = FALSE
)

# var x2's value labels are gone, like we asked for
get_val_labs(dfdrop, "x2")

# var x1's value labels are intact, b/c we didn't ask to drop them
get_val_labs(dfdrop, "x1")

dfxgone <- drop_val_labs(dflik,
  c("x"),
  partial = TRUE
)

# still a lot of value labels, but all are for "y" vars,
# ...none is left for "x" vars
get_val_labs(dfxgone)

Description

Drop all value labels previously applied to one or more variables using add_val_labs, add_quant_labs,add_m1_lab, and related functions (e.g., add_val1) or aliases (e.g., avl).

Note: dvl1 is a compact alias for drop_val1: they do the same thing, and the former is easier to type

Usage

drop_val1(data, var)

dvl1(data, var)

Arguments

Details

Note: drop_val1 is the drop_val_labs analogue to add_val1: just as add_val1 is a variant of add_val_labs that allows you to specify only one variable at a time unquoted for value labeling, drop_val1 allows you to pass one unquoted variable name at a time for value dropping. See those functions for further details regarding the conventions.

Value

A data.frame, with all value labels dropped from specified variable.

Examples

# make a "Likert"-type fake data set to demo
# note, by default, add_val_labs() "vars" arg will do partial matching
# in this case, we catch all vars with "x" in their name
set.seed(272)
dflik <- make_likert_data(scale = 1:7)
vals2label <- 1:7
labs2use <- c(
  "VSD",
  "SD",
  "D",
  "N",
  "A",
  "SA",
  "VSA"
)

dflik <- add_val1(
  data = dflik, var = x3,
  vals = vals2label,
  labs = labs2use
)

# see what this did
get_val_labs(dflik, "x3")

dfdrop <- drop_val1(dflik,
  var = x3
) # odd choice, but ok

# var x3's value labels are gone, like we asked for
get_val_labs(dfdrop, "x3")

Description

Convenience function to convert all factor variables to character.

Usage

fact2char(data)

f2c(data)

Arguments

Value

a data.frame identical to data, with exception that any factors have been converted to character variables.

Examples

sapply(iris, class)
head(iris)

iris_ch <- fact2char(iris)

sapply(iris_ch, class)
head(iris_ch)

Description

factor_to_lab_int converts a factor variable (column) of a data.frame to a value-labeled integer variable and converts the factor level labels to labelr value labels, returning the modified data.frame.

Usage

factor_to_lab_int(data, var)

f2int(data, var)

Arguments

Details

Note 1: f2int is a compact alias for factor_to_lab_int: they do the same thing, and the former is easier to type.

Note 2: factor_to_lab_int() is NOT an "undo" for lab_int_to_factor(). factor_to_lab_int() will assign sequential integer values from 1 to k (the number of distinct factor levels) in factor level order, and this will not necessarily match the integer values of a variable previously subjected to a lab_int_to_factor() call. See extended second example below for demo.

Value

a data.frame.

Examples

class(iris[["Species"]])
iris_df <- factor_to_lab_int(iris, Species)
class(iris_df[["Species"]])
get_val_labs(iris_df, "Species")

# copy data.frame mtcars to mt2
carb_orig_int <- mtcars

# !NOTE! factor_to_lab_int() is NOT an "undo" for lab_int_to_factor()
# Integer values will be sequential integers in factor level order
# Demo this

# add value labels to mtcars$carb; and assign data.frame to carb_orig_int
carb_orig_int <- add_val_labs(
  data = mtcars,
  vars = "carb",
  vals = c(1, 2, 3, 4, 6, 8),
  labs = c(
    "1c", "2c", # a tad silly, but these value labels will demo the principle
    "3c", "4c",
    "6c", "8c"
  )
)

# carb as labeled numeric
class(carb_orig_int$carb) # numeric
levels(carb_orig_int$carb) # none, not a factor
head(carb_orig_int$carb, 3) # compare to carb_to_int (below)
mean(carb_orig_int$carb) # compare to carb_to_int (below)
lm(mpg ~ carb, data = carb_orig_int) # compare to carb_to_int (below)
(adj_r2_int <- summary(lm(mpg ~ carb, data = carb_orig_int))$adj.r.squared)
AIC(lm(mpg ~ carb, data = carb_orig_int)) # compare to carb_to_int (below)

# carb as factor
carb_fac <- carb_orig_int # copy carb_orig_int to new data.frame carb_fac
carb_fac <- lab_int_to_factor(carb_fac, carb) # alias int2f() also works
class(carb_fac$carb) # factor
levels(carb_fac$carb) # has levels
head(carb_fac$carb, 3)
lm(mpg ~ carb, data = carb_fac) # factor
(adj_r2_fac <- summary(lm(mpg ~ carb, data = carb_fac))$adj.r.squared)
AIC(lm(mpg ~ carb, data = carb_fac)) # compare to R2, AIC for carb_to_int

# ??back?? to integer? Not quite. Compare carb_to_int to carb_orig_int
carb_to_int <- carb_fac # copy carb_fac to carb_to_int
carb_to_int <- factor_to_lab_int(carb_to_int, carb) # alias int2f() also works
class(carb_to_int$carb) # Is an integer
levels(carb_to_int$carb) # NOT a factor
mean(carb_to_int$carb) # NOT the same as carb_orig_int
lm(mpg ~ carb, data = carb_to_int) # NOT the same as carb_orig_int
(adj_r2_fac <- summary(lm(mpg ~ carb, data = carb_to_int))$adj.r.squared)
AIC(lm(mpg ~ carb, data = carb_to_int)) # NOT the same as carb_orig_int

Description

flab ("filter using labels") allows one to filter-subset a data.frame based on variable-specific value label attributes.

Usage

flab(data, condition)

Arguments

Details

flab accepts a labelr value-labeled data.frame, followed by condition- based row-filtering instructions (akin to base::subset or dplyr::filter), expressed in terms of variable value labels that exist only as meta-data (i.e., not visible using View(), head(), etc.), and returns the filtered data.frame in terms of the values themselves. In other words, value labels are supplied to the flab() call to direct the filtering process, but those value labels are not displayed in the cells of the returned data.frame – the raw values themselves are. This functionality may be useful for interactively subsetting a data.frame, where character value labels may be more intuitive and easily recalled than the underlying variable values themselves (e.g., raceth=="White" & gender="F" may be more intuitive or readily recalled than raceth==3 & gender==2).

Note 1: When using flab, any conditional row-filtering syntax involving value-labeled variables must be expressed in terms of those variables' value labels, not the raw values themselves. Filtering on non-value-labeled variables is also permitted, with those variables' filtering conditions being expressed in terms of raw values. Further, flab() calls may reference both types of columns (i.e., value-labeled variables and non-value-labeled variables), provided filtering conditions for the former are expressed in terms of value labels.

Note 2: flab (and labelr more broadly) is intended for moderate-sized (or smaller) data.frames, defined loosely as those with a few million or fewer rows. With a conventional (c. 2024) laptop, labelr operations on modest- sized (~100K rows) take seconds (or less); with larger (> a few million rows) data.frames, labelr may take several minutes (or run out of memory and fail altogether!), depending on the complexity of the call and the number and type of cells implicated in it.

See also slab, use_val_labs, add_val_labs, add_val1, add_quant_labs, add_quant1,
get_val_labs, drop_val_labs. For label-preserving subsetting tools that subset in terms of raw values (not value labels), see sfilter, sbrac, ssubset, sdrop.

Value

a labelr label attribute-preserving data.frame consisting of the selected rows that meet the filtering condition(s).

Examples

# make toy demographic (gender, raceth, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function
# let's add variable VALUE labels for variable "raceth"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Hispanic", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

# let's add variable VALUE labels for variable "gender"
# note that, if we are labeling a single variable, we can use add_val1()
# distinction between add_val1() and add_val_labs() will become more meaningful
# when we get to our Likert example
df <- add_val1(
  data = df, gender, vals = c(0, 1, 2, 3, 4),
  labs = c("M", "F", "TR", "NB", "Diff-Term"), max.unique.vals = 50
)

# see what we did
# get_val_labs(df)
get_val_labs(df, "gender")
get_val_labs(df, "raceth")

# use --labels-- to filter w/ flab() ("*F*ilter *lab*el")
dflab <- flab(df, raceth == "Asian" & gender == "F")
head(dflab, 4)

# equivalently, use --values--- to filter w/ sfilter() ("*S*afe filter")
dfsf <- sfilter(df, raceth == 3 & gender == 1)
head(dfsf, 4)

Description

get_all_factors returns a list of character vectors, where each character vector is a given factor variable's unique levels, and where the vector is given the same name as the factor variable itself. If the data.frame contains no factors, an empty (length 0) list is returned.

Usage

get_all_factors(data)

Arguments

Value

A list of 0, 1, or more character variables.

Examples

class(get_all_factors(iris))
length(get_all_factors(iris))
zz <- iris
zz$u <- zz$Species # zz has two factor variables
class(get_all_factors(zz))
length(get_all_factors(zz))
get_all_factors(mtcars)
length(get_all_factors(mtcars))

Description

get_all_lab_atts returns a list of labelr-generated meta-data attributes attached to a data.frame, all of which should have names beginning with one of these character strings: "frame.lab", "name.labs",
"val.labs", "factor.".

Usage

get_all_lab_atts(data, atts = c("name.labs|val.labs|frame.lab|factor."))

Arguments

Value

A free-standing list of labelr attributes.

Examples

# make toy demographic (gender, raceth, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function
# let's add variable VALUE labels for variable "raceth"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Hispanic", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

get_all_lab_atts(df) # returns all; is default
get_all_lab_atts(df, "val.labs") # returns only "val.labs" attributes
get_all_lab_atts(df, "class") # You can (but probably should not) use this way.

Description

get_factor_atts searches a labelr labeled data.frame for factors. If any are found, a list of character vectors of factor levels is returned, with each character vector being the set of unique levels for a factor variable, and with each character vector named according to the convention "factor." + variable name (e.g.,"factor.Species" for iris$Species). Used internally by other labelr functions to get information about factors in labeled data.frames.

Usage

get_factor_atts(data)

Arguments

Value

A list of character vectors, each named according to the convention "factor." + variable name (e.g.,"factor.Species" for iris$Species). If the data.frame lacks labelr attributes or lacks factors, an empty list will be returned.

Examples

ir2 <- iris
unique(ir2$Species)

ir2 <- add_val_labs(ir2,
  vars = "Species", vals = c(
    "setosa",
    "versicolor",
    "virginica"
  ),
  labs = c("se", "ve", "vi")
)
get_val_labs(ir2)
head(use_val_labs(ir2))
get_factor_atts(iris) # no such info: iris is not labelr labeled
get_factor_atts(ir2) # this one has info: it's labelr labeled

Description

get_factor_info searches a labelr labeled data.frame for factors. If any are found, a data.frame is returned with the name and unique factor levels of each, along with a logical indicator of whether the factor is ordered, with one row per level per factor. If none are found, a one-row data.frame of NA values is returned.

Usage

get_factor_info(data, var = NULL)

Arguments

Value

A data.frame with three columns: "factor.var" (the name of the factor variable in question), "levels" (the given level of that factor, expressed as a character), and "ordered" (TRUE if so, FALSE if not). If no factors are present in the supplied data.frame, a one-row data.frame of same structure with all three cells set to NA.

Examples

ir2 <- iris
unique(ir2$Species)

ir2 <- add_val_labs(ir2,
  vars = "Species", vals = c(
    "setosa",
    "versicolor",
    "virginica"
  ),
  labs = c("se", "ve", "vi")
)
get_val_labs(ir2)
head(use_val_labs(ir2))
get_factor_info(iris) # no such info: iris is not labelr labeled
get_factor_info(ir2) # this one has info: it's labelr labeled

Description

For a frame-labeled data.frame, get_frame_lab returns a derivative 1x2 data.frame that lists the data.frame name and its frame.lab attribute.

Note: gfl is a compact alias for get_frame_lab: they do the same thing, and the former is easier to type.

Usage

get_frame_lab(data)

gfl(data)

Arguments

Details

get_frame_lab returns the overall descriptive "frame label" that is assigned to a data.frame using add_frame_lab.

Value

A 1x2 data.frame, consisting of "data.frame" and "frame.lab" values for the supplied data.frame. If the supplied data.frame does not have a frame label, its name also will be used as its frame label (i.e., both entries of the returned 1x2 data.frame will be the data.frame name).

Examples

# add frame.lab to mtcars and assign to new data.frame mt2
mt2 <- add_frame_lab(mtcars, frame.lab = "Data extracted from the 1974 Motor
                      Trend US magazine, comprising fuel consumption and 10
                      aspects of automobile design and performance for 32
                      automobiles (1973–74 models). Source: Henderson and
                      Velleman (1981), Building multiple regression models
                      interactively. Biometrics, 37, 391–411.")

attr(mt2, "frame.lab") # check for attribute

# return frame.lab alongside data.frame name as a data.frame
get_frame_lab(mt2)

Description

get_labs_att returns the specified piece of labelr lab(el) attribute meta- data information if it is present.

Usage

get_labs_att(data, att)

Arguments

Value

A list.

Examples

# make toy demographic (gender, raceth, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function
# let's add variable VALUE labels for variable "raceth"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Hispanic", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

Description

For a name-labeled data.frame, get_name_labs returns a derivative data.frame that lists each variable and its variable name label.

Note: gnl is a compact alias for get_name_labs: they do the same thing, and the former is easier to type

Usage

get_name_labs(data, vars = NULL)

gnl(data, vars = NULL)

Arguments

Value

A two-column data.frame, consisting of "var" and "lab" columns, where each row corresponds to a unique variable (column) from the user- supplied data.frame.

Examples

# create a data set
df <- mtcars

# variable names and their 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"
)

# assign variable labels
df <- add_name_labs(df,
  vars = names(names_labs_vec),
  labs = names_labs_vec
)

# see what we have
get_name_labs(df)

Description

For a data.frame with value-labeled variables, get_val_lab1 returns a derivative data.frame or vector that shows the value-to-label mapping for each unique value of that value-labeled variable.

Usage

get_val_lab1(data, var, simplify = FALSE)

gvl1(data, var, simplify = FALSE)

Arguments

Details

get_val1 is a variant of get_val_labs that allows you to specify only one var whose value-to-label mapping you wish to look up.

Note 1: As with get_val_labs(), get_val_lab1() exists to provide a visual, human-interpretable quick look at how value labels map to underlying values and is NOT intended for use in automated querying, subsetting, or other manipulation of those value labels. Further: Unlike get_val_labs(), which may return value-to-label mappings for –several– variables of potentially different atomic types, get_val_lab1() limits itself to returning the value labels of a –single– variable (column) of the supplied data.frame.

For this reason, and in contrast to the behavior of get_val_labs(), if get_val_lab1()'s simplify argument is set to FALSE (the default), the returned data.frame will express var values as numeric if this can be done without creating new NA values (i.e., in the sense of as_numv()). In contrast, if simplify is TRUE, the look-up table information will be returned as a named character vector.

Note 2: gvl1 is a compact alias for get_val_lab1: they do the same thing, and the former is easier to type

Value

By default, a three-column data.frame, consisting of "var", "vals", and "labs" columns, where each row corresponds to a unique value of var OR – for variables labeled using add_quant_labs (or add_quant1) – the approximate (i.e., possibly rounded) upper bound of numerical values that fall within that label's range of coverage. If simplify is FALSE, a character vector will returned.

Examples

# add val labs to multiple variables at once
# make a "Likert"-type fake data set to demo
# note, by default, add_val_labs() "vars" arg will do partial matching
# in this case, we catch all vars with "x" in their name
set.seed(272)
dflik <- make_likert_data(scale = 1:7)
vals2label <- 1:7
labs2use <- c(
  "VSD",
  "SD",
  "D",
  "N",
  "A",
  "SA",
  "VSA"
)

dflik <- add_val_labs(
  data = dflik, vars = c("x", "y3"), # note the vars args
  vals = vals2label,
  labs = labs2use,
  partial = TRUE
)

# note, all "x" vars get the labs, as does "y3"
get_val_lab1(dflik, x1)

get_val_lab1(dflik, x1, simplify = TRUE)

Description

For a data.frame with value-labeled variables, get_val_labs returns a derivative data.frame that shows the value-to-label mapping for each unique value of each value-labeled variable.

Usage

get_val_labs(data, var = NULL)

gvl(data, var = NULL)

Arguments

Details

Note 1: get_val_labs returns a data.frame that is intended strictly to facilitate human-in-the-loop –visual– display and inspection of what (if any) value label has been associated with each variable value. It is –not– intended for use in automated querying or subsetting or as an indicator of of the supplied data.frame's columns' underlying classes or atomic types. In particular, all columns of the –returned– data.frame object are coerced to character for display purposes, as a result of concatenating value information from different variables of potentially different atomic types or classes. For example, all elements of the "vals" column are expressed as character even if the underlying values themselves are numeric.

Note 2: gvl is a compact alias for get_val_labs: they do the same thing, and the former is easier to type

Value

A three-column data.frame, consisting of "var", "vals", and "labs" columns, where each row corresponds to a unique value of a value-labeled variable (column) from the user-supplied data.frame OR – for variables labeled using add_quant_labs (or add_quant1) – the upper bound of numerical values that fall within that label's range of coverage. Note that all variables of the returned data.frame are coerced to character (see Note 1 of details).

Examples

# add val labs to multiple variables at once
# make a "Likert"-type fake data set to demo
# note, by default, add_val_labs() "vars" arg will do partial matching
# in this case, we catch all vars with "x" in their name
set.seed(272)
dflik <- make_likert_data(scale = 1:7)
vals2label <- 1:7
labs2use <- c(
  "VSD",
  "SD",
  "D",
  "N",
  "A",
  "SA",
  "VSA"
)

dflik <- add_val_labs(
  data = dflik, vars = c("x", "y3"), # note the vars args
  vals = vals2label,
  labs = labs2use,
  partial = TRUE
)

# note, all "x" vars get the labs, as does "y3"
get_val_labs(dflik)
get_val_labs(dflik, "x1")

Description

greml takes two character vectors of strings and, for each pattern represented by an element of the first vector, searches all elements of the second vector to see if any of those elements of the second vector matches that pattern element of the first vector.

Usage

greml(patterns, x, ignore.case = TRUE, vals = FALSE)

Arguments

Details

This function accepts a character vector of text substring patterns or regular expressions (patterns argument), and searches a second character vector (x argument) to determine which elements of the first vector (patterns) match at least one element anywhere in the second vector (x). If vals = TRUE (default is FALSE), each matched pattern element is returned; if vals = FALSE, a vector of named logical values equal in length to the object supplied to the patterns argument is returned, indicating for each patterns element whether a match for it was found anywhere in x (TRUE if so, FALSE if not), with the names corresponding to the elements of the patterns vector. If ignore.case = TRUE (the default), neither vector is treated case- sensitively (both are coerced to lower-case before other operations occur).

Used internally by various labelr functions (e.g., use_val_labs). Note that this is the same search and syntax that is performed by gremlr() (gremlr means "greml in reverse"), except that, whereas greml returns matches in terms of the patterns argument (i.e., which patterns elements match at least one x element), gremlr returns matches in terms of the x argument.

Value

a vector, either character (if vals = TRUE) or logical (if vals = FALSE).

Examples

# search for "AB" (case-sensitively) anywhere in subsequent vector
greml(c("AB"), c("ab", "ab", "abc", "z"), vals = TRUE, ignore.case = FALSE)
# character(0)

# search for "AB" (non-case-sensitively; the default) anywhere in next vector
greml(c("AB"), c("ab", "ab", "abc", "z"), vals = TRUE, ignore.case = TRUE)
# [1] "AB"

# other searches
greml(c("AB"), c("ab", "ab", "abc", "z"), vals = TRUE, ignore.case = FALSE)
greml(c("ab"), c("ab", "ab", "abc", "z"), vals = FALSE)
greml(c("ab", "Q"), c("ab", "ab", "abc", "z"), vals = FALSE)
greml(c("a|b", "Q"), c("a", "b", "abc", "z"), vals = FALSE)
greml(c("a|b", "Q"), c("a", "b", "z"), vals = FALSE)
greml(c("a|b", "Q"), c("bq", "z"), vals = FALSE)
greml(c("a|b", "Q"), c("bq", "z"), vals = TRUE)

# compare greml (above) to gremlr() (here)
gremlr(c("AB"), c("ab", "ab", "abc", "z"), vals = TRUE, ignore.case = FALSE)
gremlr(c("ab"), c("ab", "ab", "abc", "z"), vals = FALSE)
gremlr(c("ab", "Q"), c("ab", "ab", "abc", "z"), vals = FALSE)
gremlr(c("a|b", "Q"), c("a", "b", "abc", "z"), vals = FALSE)
gremlr(c("a|b", "Q"), c("a", "b", "z"), vals = FALSE)
gremlr(c("a|b", "Q"), c("bq", "z"), vals = FALSE)

Description

gremlr accepts two character vectors of strings and, for each element of the second vector, determines whether that element matches any of the patterns supplied via any of the elements of the first vector.

Usage

gremlr(patterns, x, ignore.case = TRUE, vals = FALSE)

Arguments

Details

This function accepts a character vector of text substring patterns or regular expressions (patterns argument), and searches another character vector (x argument) to determine for each element of x, whether that element is a match (in the sense of base::grepl()) for any pattern element of of patterns. If vals = TRUE (default is FALSE), each matched x element is returned; if vals = FALSE, a vector of named logical values equal in length to x is returned, indicating for each x element whether it contains any text substring or pattern found in any element of patterns (TRUE if so, FALSE if not), with the names corresponding to the elements of the x vector. Used internally by various labelr functions. If ignore.case = TRUE (the default), neither vector is treated case-sensitively (both are coerced to lower-case before other operations).

Used internally by various labelr functions Note that this is the same search and syntax that is performed by greml(gremlr is "greml in reverse"), except that, whereas greml returns matches in terms of the patterns argument, gremlr returns matches in terms of x argument.

Value

a vector, either character (if vals = TRUE) or logical (if vals = FALSE).

Examples

# search for "AB" (case-sensitively) anywhere in subsequent vector
gremlr(c("AB"), c("ab", "ab", "abc", "z"), vals = TRUE, ignore.case = FALSE)
# character(0)

# search for "AB" (non-case-sensitively; the default) anywhere in next vector
gremlr(c("AB"), c("ab", "ab", "abc", "z"), vals = TRUE, ignore.case = TRUE)
# [1] "ab"  "ab"  "abc"

# other searches
gremlr(c("AB"), c("ab", "ab", "abc", "z"), vals = TRUE, ignore.case = FALSE)
gremlr(c("ab"), c("ab", "ab", "abc", "z"), vals = FALSE)
gremlr(c("ab", "Q"), c("ab", "ab", "abc", "z"), vals = FALSE)
gremlr(c("a|b", "Q"), c("a", "b", "abc", "z"), vals = FALSE)
gremlr(c("a|b", "Q"), c("a", "b", "z"), vals = FALSE)
gremlr(c("a|b", "Q"), c("bq", "z"), vals = FALSE)

# compare gremlr (above) to greml() (here)
greml(c("AB"), c("ab", "ab", "abc", "z"), vals = TRUE, ignore.case = FALSE)
greml(c("ab"), c("ab", "ab", "abc", "z"), vals = FALSE)
greml(c("ab", "Q"), c("ab", "ab", "abc", "z"), vals = FALSE)
greml(c("a|b", "Q"), c("a", "b", "abc", "z"), vals = FALSE)
greml(c("a|b", "Q"), c("a", "b", "z"), vals = FALSE)
greml(c("a|b", "Q"), c("bq", "z"), vals = FALSE)

Description

Determine whether a specific variable of a data.frame has value labels associated with it that were added using add_val_labs() or add_val1().

Usage

has_avl_labs(data, var)

h11l(data, var)

hql(data, var)

Arguments

Details

h11l is a compact alias for has_avl_labs: they do the same thing, and the former is easier to type

Value

A 1L logical.

Examples

# add val labs to multiple variables at once
# make a "Likert"-type fake data set to demo
# note, by default, add_val_labs() "vars" arg will do partial matching
# in this case, we catch all vars with "y" in their name, except "y3"
set.seed(272)
dflik <- make_likert_data(scale = 1:7)
vals2label <- 1:7
labs2use <- c(
  "VSD",
  "SD",
  "D",
  "N",
  "A",
  "SA",
  "VSA"
)

dflik <- add_val_labs(
  data = dflik, vars = c("y"), # note the vars args
  not.vars = "y3",
  vals = vals2label,
  labs = labs2use,
  partial = TRUE
)

has_avl_labs(dflik, y1) # TRUE

has_avl_labs(dflik, y3) # FALSE, see not.vars arg above

Description

has_decv determines whether a vector has decimal values, using all values for smaller vectors and using a non-random sample of observations for larger vectors.

Usage

has_decv(x, sample.after = 1000)

Arguments

Details

This function is used by core labelr functions to detect vectors that are bad candidates for one-to-one value labeling (as implemented by, e.g., add_val_labs).

Value

a 1L vector indicating whether x has decimal values.

Examples

set.seed(123)
x1 <- runif(10)
x2 <- as.character(sample(c(1:20), 10, replace = TRUE))
x3 <- sample(letters, size = 10, replace = TRUE)
df <- data.frame(x1, x2, x3)
head(df, 3)
sapply(df, class)
class(df$x2)

df <- as_num(df)
head(df, 3)
sapply(df, class)

sapply(mtcars, is.double)
sapply(mtcars, is.numeric)
sapply(mtcars, is.integer)
sapply(mtcars, has_decv)

Description

Determine whether a specific variable of a data.frame has many-to-one-style value labels associated with it (i.e., via add_m1_lab() or add1m1()).

Usage

has_m1_labs(data, var)

hm1l(data, var)

Arguments

Details

hm1l is a compact alias for has_m1_labs: they do the same thing, and the former is easier to type

Value

A 1L logical.

Examples

# add many-to-one style labels for "carb" and one-to-one style for "am"
df <- mtcars

df <- add_m1_lab(df,
  vars = "carb",
  vals = 1:3,
  lab = "<=3",
  max.unique.vals = 10
)

df <- add_m1_lab(df,
  vars = "carb",
  vals = c(4, 6, 8),
  lab = ">=4",
  max.unique.vals = 10
)

df <- add_val_labs(df,
  vars = "am",
  vals = c(0, 1),
  labs = c("autom", "manu"),
  max.unique.vals = 10
)

has_m1_labs(df, carb) # TRUE, carb has m1-style value labels

has_val_labs(df, am) # TRUE, am does have value labels

has_m1_labs(df, am) # FALSE, am's value labels are not not m1-style labels

Description

Determine whether a specific variable of a data.frame has value labels associated with it that were added using add_quant_labs() or add_quant1().

Usage

has_quant_labs(data, var)

Arguments

Details

hql is a compact alias for has_quant_labs: they do the same thing, and the former is easier to type

Value

A 1L logical.

Examples

# copy mtcars to mt2 and assign various types of value labels
mt2 <- mtcars

# add 1-to-1 value labels
mt2 <- add_val_labs(
  data = mt2,
  vars = "am",
  vals = c(0, 1),
  labs = c("automatic", "manual")
)

has_val_labs(mt2, am) # TRUE, it does
has_m1_labs(mt2, am) # FALSE, they are NOT add_m1_lab()-style
has_quant_labs(mt2, am) # FALSE, they are NOT add_quant_labs() -style

# add many-to-1 value labels
mt2 <- add_m1_lab(
  data = mt2,
  vars = "gear",
  vals = 4:5,
  lab = "4+"
)

has_val_labs(mt2, gear) # TRUE, it does
has_m1_labs(mt2, gear) # TRUE, they ARE add_m1_lab()-style
has_quant_labs(mt2, gear) # FALSE, they NOT not add_quant_labs() -style

# add quartile-based numerical range value labels
mt2 <- add_quant_labs(
  data = mt2,
  vars = "disp",
  qtiles = 4
)

has_val_labs(mt2, disp) # TRUE, it does
has_m1_labs(mt2, disp) # FALSE, they are NOT add_m1_lab()-style
has_quant_labs(mt2, disp) # TRUE, they ARE add_quant_labs() -style

Description

Determine whether a specific variable of a data.frame has value labels associated with it.

Usage

has_val_labs(data, var, type = "any")

hvl(data, var, type = "any")

Arguments

Details

hvl is a compact alias for has_val_labs: they do the same thing, and the former is easier to type

Value

A 1L logical.

Examples

# add val labs to multiple variables at once
# make a "Likert"-type fake data set to demo
# note, by default, add_val_labs() "vars" arg will do partial matching
# in this case, we catch all vars with "y" in their name, except "y3"
set.seed(272)
dflik <- make_likert_data(scale = 1:7)
vals2label <- 1:7
labs2use <- c(
  "VSD",
  "SD",
  "D",
  "N",
  "A",
  "SA",
  "VSA"
)

dflik <- add_val_labs(
  data = dflik, vars = c("y"), # note the vars args
  not.vars = "y3",
  vals = vals2label,
  labs = labs2use,
  partial = TRUE
)

has_val_labs(dflik, y1) # TRUE

has_val_labs(dflik, y3) # FALSE, see not.vars arg above

Description

headl accepts a labelr value-labeled data.frame and returns the first n value-labeled rows of that data.frame

Usage

headl(data, n = 6L)

Arguments

Details

Whereas utils::head returns the first n rows of a data.frame, headl does the same thing, substituting value labels for values wherever the former exist. See also taill and somel.

Value

a data.frame.

Examples

# make toy demographic (gender, raceth, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function
# let's add variable VALUE labels for variable "raceth"
df <- add_val_labs(df,
  vars = "raceth", vals = c(1:7),
  labs = c("White", "Black", "Hispanic", "Asian", "AIAN", "Multi", "Other"),
  max.unique.vals = 50
)

# let's add variable VALUE labels for variable "gender"
# note that, if we are labeling a single variable, we can use add_val1()
# distinction between add_val1() and add_val_labs() will become more meaningful
# when we get to our Likert example
df <- add_val1(
  data = df, gender, vals = c(0, 1, 2, 3, 4),
  labs = c("M", "F", "TR", "NB", "Diff-Term"), max.unique.vals = 50
)

head(df) # utils::head
headl(df) # same, but with value labels in place of values

Description

init_labs pre-populates a data.frame with "placeholder" labelr label meta- data, which will be overwritten if/when you explicitly assign your own preferred label attributes.

Usage

init_labs(data, max.unique.vals = 5000)

Arguments

Details

init_labs is used inside other labelr functions but is not intended for interactive use at the console.

Value

a data.frame with initial placeholder labelr meta-data added.

Examples

# make toy demographic (gender, race, etc.) data set
set.seed(555)
df <- make_demo_data(n = 1000) # another labelr:: function
df2 <- init_labs(df) # df2 is not df
get_all_lab_atts(df) # this is df; is not df2
get_all_lab_atts(df2) # this is df2

Description

Check all (or specified) columns of a data.frame for the presence of "irregular" values (e.g., NA, Inf, NaN) and, if found, replace them with NA (or some other specified value).

Usage

irregular2(
  data,
  vars = NULL,
  to = NA,
  nan.include = TRUE,
  inf.include = TRUE,
  special = c("NA", "NAN", "INF", "-INF")
)

Arguments

Details

For purposes of irregular2, irregular values consist of: NA values, other arbitrary values you specify, and (by default): NaN, Inf, -Inf, and character variants of same (i.e., upper, lower, or mixed-case variants of "NA","NAN", "INF","-INF"). This function converts all such values to NA (or some other specified value).

Value

a data.frame identical to data, with exception that irregular values have been converted to the value specified in "to" argument (NA, by default).

Examples

set.seed(123)
x <- c(NA, Inf, -Inf, NaN, runif(6))
y <- c("a", "inf", "NaN", NA, sample(letters, 6, replace = TRUE))
df <- data.frame(x, y)

head(df, 10)

df_1 <- irregular2(df)

head(df_1, 10)

df_2 <- irregular2(df, vars = "x", to = ";-)")

head(df_2)

Description

Check a vector for the presence of "irregular" values (e.g., NA) and, if found, replace with some other (single) user-specified value.

Usage

irregular2v(
  x,
  to = 99,
  nan.include = TRUE,
  inf.include = TRUE,
  special = c("NA", "NAN", "INF", "-INF"),
  other = NULL
)

Arguments

Details

For purposes of irregular2v, irregular values consist of: NA values, other arbitrary values you specify, and (by default): NaN, Inf, -Inf, and character variants of same (i.e., upper, lower, or mixed-case variants of "NA","NAN", "INF","-INF"). This function is used insider core labelr functions to manage such values, but the typical labelr user will have no explicit need to use it as part of an interactive session.

Value

a vector identical to x, with exception that NA (and other irregular) values have been converted to the value specified in "to" argument.

Examples

set.seed(123)
x <- c(NA, Inf, -Inf, NaN, runif(6))
x
x1 <- irregular2v(x, to = 33)
x1

set.seed(123)
x1 <- c(NA, Inf, -Inf, NaN, runif(6))
x
x1 <- irregular2v(x, to = 33, nan.include = TRUE, inf.include = FALSE)
x1

set.seed(123)
x <- c(NA, "INF", "in", "nan", "NA", sample(letters, 5))
x
x1 <- irregular2v(x, to = "<-X->")
x1

Description

is_numable determines whether a character vector can be coerced to numeric without generating new NA values.

Usage

is_numable(x, nan2na = TRUE, inf2na = TRUE)

Arguments

Details

Core labelr functions coerce integers to characters and back, which is_numable facilitates.

Value

a 1L (scalar) logical vector.

Examples

set.seed(123)
x1 <- runif(10)
x2 <- as.character(sample(c(1:20), 10, replace = TRUE))
x2_num_test <- is_numable(x2)
x2_num_test
x3 <- sample(LETTERS, 10, replace = TRUE)
x3_num_test <- is_numable(x3)
x3_num_test

Description

lab_int_to_factor converts a value-labeled integer variable to a factor, using labelr value labels as factor level labels and returning the modified data.frame.

Usage

lab_int_to_factor(data, var, ordered = FALSE)

int2f(data, var, ordered = FALSE)

Arguments

Details

Note 1: int2f is a compact alias for lab_int_to_factor: they do the same thing, and the former is easier to type.

Note 2: This function can be used to produce ordered factors but will not do so by default (see argument ordered).

Note 3: This function's effects are NOT straightforwardly "undone" by factor_to_lab_int() See the latter's documentation for more information and an example demonstration.

Value

a data.frame.

Examples

class(iris[["Species"]])

iris_sp_int <- factor_to_lab_int(iris, Species)
class(iris_sp_int[["Species"]])

get_val_labs(iris_sp_int, "Species")
iris_sp_fac <- lab_int_to_factor(iris_sp_int, Species)

class(iris_sp_fac[["Species"]])

levels(iris_sp_fac[["Species"]])

# copy data.frame mtcars to mt2
mt2 <- mtcars

# add value labels to mtcars$carb and assign data.frame to object mt2
mt2 <- add_val_labs(
  data = mt2,
  vars = "carb",
  vals = c(1, 2, 3, 4, 6, 8),
  labs = c(
    "1c", "2c", # a tad silly, but these val labels will demo the principle
    "3c", "4c",
    "6c", "8c"
  )
)

# carb as labeled integer
class(mt2$carb)
levels(mt2$carb)
head(mt2$carb, 3)
lm(mpg ~ carb, data = mt2)
(adj_r2_int <- summary(lm(mpg ~ carb, data = mt2))$adj.r.squared)
AIC(lm(mpg ~ carb, data = mt2))

# carb as factor
carb_fac <- mt2 # copy mt2 to new data.frame carb_fac
carb_fac <- lab_int_to_factor(carb_fac, carb) # alias int2f() also works
class(carb_fac$carb)
levels(carb_fac$carb)
head(carb_fac$carb, 3)
lm(mpg ~ carb, data = carb_fac)
(adj_r2_fac <- summary(lm(mpg ~ carb, data = carb_fac))$adj.r.squared)
AIC(lm(mpg ~ carb, data = carb_fac))