Skip to contents

Apply Optimal Weight of Evidence (WoE) to a Categorical Feature

Source: R/ob_apply_woe_cat.R
ob_apply_woe_cat.Rd

Transforms a categorical feature into its corresponding Weight of Evidence (WoE) values using pre-computed binning results from an optimal binning algorithm (e.g., ob_categorical_cm).

Usage

ob_apply_woe_cat(
  obresults,
  feature,
  bin_separator = "%;%",
  missing_values = c("NA", "Missing", "")
)

Arguments

obresults

List output from an optimal binning function for categorical variables. Must contain elements bin (character vector of bin labels) and woe (numeric vector of WoE values). Bins may represent individual categories or merged groups separated by bin_separator.

feature

Character or factor vector of categorical values to be transformed. Automatically coerced to character if provided as factor.

bin_separator

Character string used to separate multiple categories within a single bin label (default: "%;%"). For example, a bin "A%;%B%;%C" contains categories A, B, and C.

missing_values

Character vector specifying which values should be treated as missing (default: c("NA", "Missing", "")). NA inputs and these values (after trimming surrounding whitespace) are scored with the missing-value bin: the first bin of obresults whose categories include one of them (the categorical binners store NA as the category "NA"), which is also the bin obwoe_sql and obwoe_apply use for missing values. A value that is itself a category of a bin (e.g. "NA") is scored with that bin. Without a missing-value bin they are scored as "Special" with WoE NA.

Value

A data frame with one row per element of feature and the columns feature (the input), bin (the label of the matched bin, or "Special"), woe (the bin's WoE; NA for "Special"), idbin (the bin's id; the number of bins plus one for "Special") and ismissing (1 for missing values and for categories not seen in obresults, 0 otherwise). Unseen categories are scored as "Special" without a warning.

Details

This function is typically used in a two-step workflow:

  1. Train binning on training data: bins <- ob_categorical_cm(feature_train, target_train)

  2. Apply WoE to new data: woe_test <- ob_apply_woe_cat(bins, feature_test)

Bin labels are split on bin_separator and each value of feature is matched against the resulting categories exactly, byte for byte, as obwoe_apply and obwoe_sql do. A category that appears in more than one bin label is scored with the first of those bins, as in the CASE expression generated by obwoe_sql. A value that only matches once leading and trailing whitespace is removed is still accepted, and a category whose own name contains bin_separator is recognised as a run of consecutive components of a bin label. Each distinct value is resolved once, so scoring takes \(O(n)\) hash lookups whatever the number of categories.

Examples

# \donttest{
# Mock data
train_data <- data.frame(
  category = c("A", "B", "A", "C", "B", "A"),
  default = c(0, 1, 0, 1, 0, 0)
)
test_data <- data.frame(
  category = c("A", "C", "B")
)

# Train binning on training set
train_bins <- ob_categorical_cm(
  feature = train_data$category,
  target = train_data$default
)

# Apply to test set
test_woe <- ob_apply_woe_cat(
  obresults = train_bins,
  feature = test_data$category
)

# Handle custom missing indicators
test_woe <- ob_apply_woe_cat(
  obresults = train_bins,
  feature = test_data$category,
  missing_values = c("NA", "Unknown", "N/A", "")
)
# }