tern (version 0.9.11)

df_explicit_na: Encode categorical missing values in a data frame

Description

This is a helper function to encode missing entries across groups of categorical variables in a data frame.

Usage

df_explicit_na(
  data,
  omit_columns = NULL,
  char_as_factor = TRUE,
  logical_as_factor = FALSE,
  na_level = "",
  factor_as_factor = FALSE,
  factor_level_method = c("sort_auto", "sort_radix", "data"),
  factor_level_last_pattern = NULL
)

Value

A data.frame with the chosen modifications applied.

Arguments

data

(data.frame)
data set.

omit_columns

(character)
names of variables from data that should not be modified by this function.

char_as_factor

(flag)
whether to convert character variables in data to factors.

logical_as_factor

(flag)
whether to convert logical variables in data to factors.

na_level

(string)
string used to replace all NA or empty values inside non-omit_columns columns.

factor_as_factor

(flag)
whether to re-encode existing factor variables using factor_level_method. When FALSE (default), existing factor levels are preserved as-is (original behavior).

factor_level_method

(string)
method used to order factor levels when converting character or logical variables (or existing factors when factor_as_factor = TRUE). One of:

"sort_auto"

sort(unique(x)) — default R sort, locale-aware (default). Preserves the original behavior of this function.

"sort_radix"

sort(unique(x), method = "radix") — byte-order (ASCII) sort. Unlike "sort_auto", this is not locale-sensitive: uppercase letters always sort before lowercase. On data where all values share the same case (e.g. all-caps ADaM variables) the two methods produce identical results.

"data"

unique(x) — levels in order of first appearance in the data.

factor_level_last_pattern

(string or NULL)
regular expression. Any factor levels matching this pattern are moved to the end (before na_level). NULL (default) disables this behaviour. Note: this parameter only takes effect when factor levels are being re-encoded (i.e. for character/logical columns with char_as_factor/logical_as_factor, or for existing factor columns with factor_as_factor = TRUE). Existing factor columns where factor_as_factor = FALSE are not affected.

Details

Missing entries are those with NA or empty strings and will be replaced with a specified value. If factor variables include missing values, the missing value will be inserted as the last level. Similarly, in case character or logical variables should be converted to factors with the char_as_factor or logical_as_factor options, the missing values will be set as the last level.

See Also

sas_na() and explicit_na() for other missing data helper functions.

Examples

my_data <- data.frame(
  u = c(TRUE, FALSE, NA, TRUE),
  v = factor(c("A", NA, NA, NA), levels = c("Z", "A")),
  w = c("A", "B", NA, "C"),
  x = c("D", "E", "F", NA),
  y = c("G", "H", "I", ""),
  z = c(1, 2, 3, 4),
  stringsAsFactors = FALSE
)

# Example 1
# Encode missing values in all character or factor columns.
df_explicit_na(my_data)
# Also convert logical columns to factor columns.
df_explicit_na(my_data, logical_as_factor = TRUE)
# Encode missing values in a subset of columns.
df_explicit_na(my_data, omit_columns = c("x", "y"))

# Example 2
# Here we purposefully convert all `M` values to `NA` in the `SEX` variable.
# After running `df_explicit_na` the `NA` values are encoded as `` but they are not
# included when generating `rtables`.
adsl <- tern_ex_adsl
adsl$SEX[adsl$SEX == "M"] <- NA
adsl <- df_explicit_na(adsl)

# If you want the `Na` values to be displayed in the table use the `na_level` argument.
adsl <- tern_ex_adsl
adsl$SEX[adsl$SEX == "M"] <- NA
adsl <- df_explicit_na(adsl, na_level = "Missing Values")

# Example 3
# Numeric variables that have missing values are not altered. This means that any `NA` value in
# a numeric variable will not be included in the summary statistics, nor will they be included
# in the denominator value for calculating the percent values.
adsl <- tern_ex_adsl
adsl$AGE[adsl$AGE < 30] <- NA
adsl <- df_explicit_na(adsl)

# Example 4: Control factor level ordering
# Use radix sort to match SAS PROC SORT behavior.
df_explicit_na(my_data, factor_level_method = "sort_radix")
# Use data order (first appearance).
df_explicit_na(my_data, factor_level_method = "data")

# Example 5: Move matching levels to the end
# Levels matching "^Other" are placed last (before na_level).
df_explicit_na(my_data, factor_level_last_pattern = "^Other")