OptimalBinningWoE

Overview

OptimalBinningWoE is a high-performance R package for optimal binning and Weight of Evidence (WoE) transformation, designed for credit scoring, risk assessment, and predictive modeling applications.

Why OptimalBinningWoE?

Installation

# Install from CRAN (when available)
install.packages("OptimalBinningWoE")

# Or install the development version from GitHub
# install.packages("pak")
pak::pak("evandeilton/OptimalBinningWoE")

Quick Start

Basic Usage

library(OptimalBinningWoE)

# Create sample data
set.seed(123)
df <- data.frame(
  age = rnorm(1000, 45, 15),
  income = exp(rnorm(1000, 10, 0.5)),
  education = sample(c("HS", "BA", "MA", "PhD"), 1000, replace = TRUE),
  target = rbinom(1000, 1, 0.15)
)

# Automatic optimal binning with WoE calculation
result <- obwoe(
  data = df,
  target = "target",
  algorithm = "jedi", # Joint Entropy-Driven Information
  min_bins = 3,
  max_bins = 6
)

# View summary
print(result)

# Examine binning details
result$results$age

Integration with tidymodels

library(tidymodels)
library(OptimalBinningWoE)

# Create a preprocessing recipe with WoE transformation
rec <- recipe(default ~ ., data = credit_data) %>%
  step_obwoe(
    all_predictors(),
    outcome = "default",
    algorithm = "mob", # Monotonic Optimal Binning
    min_bins = 3,
    max_bins = tune(), # Tune the number of bins
    output = "woe"
  )

# Works seamlessly in ML workflows
workflow() %>%
  add_recipe(rec) %>%
  add_model(logistic_reg()) %>%
  fit(data = training_data)

Core Concepts

Weight of Evidence (WoE)

WoE quantifies the predictive power of each bin by measuring the log-odds ratio:

\[\text{WoE}_i = \ln\left(\frac{\text{Distribution of Goods}_i}{\text{Distribution of Bads}_i}\right)\]

Interpretation:

• WoE > 0: Lower risk than average (more “goods” than expected)
• WoE < 0: Higher risk than average (more “bads” than expected)
• WoE ≈ 0: Similar to population average

Information Value (IV)

IV measures the overall predictive power of a feature:

\[\text{IV} = \sum_{i=1}^{n} (\text{Dist. Goods}_i - \text{Dist. Bads}_i) \times \text{WoE}_i\]

Algorithm Reference

OptimalBinningWoE provides 36 algorithms optimized for different scenarios:

Universal Algorithms (Numerical & Categorical)

Numerical-Only Algorithms (20)

Categorical-Only Algorithms (16)

Algorithm Selection Guide

Key Functions

Example Workflow

library(OptimalBinningWoE)

# 1. Fit binning model on training data
model <- obwoe(
  data = train_data,
  target = "default",
  algorithm = "mob",
  min_bins = 3,
  max_bins = 5
)

# 2. View feature importance by IV
print(model$summary[order(-model$summary$total_iv), ])

# 3. Apply transformation
train_woe <- obwoe_apply(train_data, model)
test_woe <- obwoe_apply(test_data, model)

# 4. Compute performance metrics
gains <- obwoe_gains(model, feature = "income")
print(gains)
plot(gains, type = "ks")

Performance

OptimalBinningWoE is optimized for speed through:

• RcppEigen: Vectorized linear algebra operations
• Efficient algorithms: O(n log n) or better complexity
• Memory-conscious design: Streaming algorithms for large data

Typical performance on a standard laptop:

Documentation

• 📖 Package Vignette: Comprehensive guide with examples
• 📚 Function Reference: Complete API documentation
• 🐛 Issue Tracker: Report bugs or request features

Contributing

Contributions are welcome! Please see our Contributing Guidelines and Code of Conduct.

Citation

If you use OptimalBinningWoE in your research, please cite:

@software{optimalbinningwoe,
  author = {José Evandeilton Lopes},
  title = {OptimalBinningWoE: Optimal Binning and Weight of Evidence Framework for Modeling},
  year = {2026},
  url = {https://github.com/evandeilton/OptimalBinningWoE}
}

References

• Siddiqi, N. (2006). Credit Risk Scorecards: Developing and Implementing Intelligent Credit Scoring. John Wiley & Sons.
• Thomas, L. C., Edelman, D. B., & Crook, J. N. (2002). Credit Scoring and Its Applications. SIAM.
• Navas-Palencia, G. (2020). Optimal Binning: Mathematical Programming Formulation. arXiv:2001.08025.

License

MIT License © 2026 José Evandeilton Lopes