Package {rbin}


Type: Package
Title: Tools for Binning Data
Version: 0.3.0
Description: Manually bin data using weight of evidence and information value. Includes other binning methods such as equal length, quantile and winsorized. Options for combining levels of categorical data are also available. Dummy variables can be generated based on the bins created using any of the available binning methods. References: Siddiqi, N. (2006) <doi:10.1002/9781119201731>.
License: MIT + file LICENSE
URL: https://github.com/rsquaredacademy/rbin, https://rbin.rsquaredacademy.com
BugReports: https://github.com/rsquaredacademy/rbin/issues
Depends: R (≥ 3.3)
Imports: data.table (≥ 1.9.4), ggplot2, stats, utils
Suggests: covr, graphics, knitr, miniUI, rmarkdown, rstudioapi, shiny, testthat (≥ 3.1.7), tibble, vdiffr
VignetteBuilder: knitr
Encoding: UTF-8
LazyData: true
Config/testthat/edition: 3
Config/roxygen2/version: 8.1.1
NeedsCompilation: no
Packaged: 2026-11-18 07:53:26 UTC; DELL
Author: Aravind Hebbali [aut, cre]
Maintainer: Aravind Hebbali <aravindhebbali@rsquaredacademy.com>
Repository: CRAN
Date/Publication: 2026-11-19 11:20:22 UTC

rbin package

Description

Tools for binning data.

Details

See the README on GitHub

Author(s)

Maintainer: Aravind Hebbali aravindhebbali@rsquaredacademy.com

Authors:

See Also

Useful links:


Bank marketing data set

Description

The data is related with direct marketing campaigns of a Portuguese banking institution. The marketing campaigns were based on phone calls. Often, more than one contact to the same client was required, in order to access if the product (bank term deposit) would be ('yes') or not ('no') subscribed.

Usage

mbank

Format

A tibble with 4521 rows and 17 variables:

age

age of the client

job

type of job

marital

marital status

education

education level of the client

default

has credit in default?

balance

average yearly balance, in euros

housing

has housing loan?

loan

has personal loan?

contact

contact communication type

day

last contact day of the month

month

last contact month of year

duration

last contact duration, in seconds

campaign

number of contacts performed during this campaign and for this client

pdays

number of days that passed by after the client was last contacted from a previous campaign

previous

number of contacts performed before this campaign and for this client

poutcome

outcome of the previous marketing campaign

y

has the client subscribed a term deposit?

Source

[Moro et al., 2014] S. Moro, P. Cortez and P. Rita. A Data-Driven Approach to Predict the Success of Bank Telemarketing. Decision Support Systems, Elsevier, 62:22-31, June 2014


Bin continuous data

Description

Manually bin continuous data using weight of evidence.

Usage

rbinAddin(data = NULL)

Arguments

data

A data.frame or tibble, or the name of one. When NULL (the default), the current editor selection is used as the initial data name.

Examples

## Not run: 
rbinAddin(data = mbank)

## End(Not run)


Custom binning

Description

Manually combine categorical variables using weight of evidence.

Usage

rbinFactorAddin(data = NULL)

Arguments

data

A data.frame or tibble, or the name of one. When NULL (the default), the current editor selection is used as the initial data name.

Examples

## Not run: 
rbinFactorAddin(data = mbank)

## End(Not run)


Create dummy variables

Description

Create dummy variables from bins.

Usage

rbin_create(data, predictor, bins)

Arguments

data

A data.frame or tibble.

predictor

Bare column name, character name, or variable holding a character name in data. The numeric variable for which dummies must be created.

bins

An object of class rbin_manual, rbin_quantiles, rbin_equal_length, rbin_winsorize or rbin_equal_freq.

Details

Missing predictor values produce missing indicators; the separate missing-value bin is not turned into a dummy column. Winsorized objects apply their fitted clamp before assigning intervals. Older saved winsorized objects without clamp metadata must be fitted again. Equal-frequency bins keep ties together and use their stored value intervals for scoring. Gaps go to the preceding group, with boundaries at the next group's minimum. Dummy names describe these scoring intervals, which extend beyond the training range.

Value

data with one indicator column per bin, appended in bin order. Every bin defined when the bins were created is represented, even when the data passed here has no observation in that bin.

Examples

k <- rbin_manual(mbank, y, age, c(29, 39, 56))
rbin_create(mbank, age, k)


Equal frequency binning

Description

Bin continuous data using the equal frequency binning method.

Usage

rbin_equal_freq(data = NULL, response = NULL, predictor = NULL, bins = 10)

## S3 method for class 'rbin_equal_freq'
plot(x, print_plot = TRUE, ...)

Arguments

data

A data.frame or tibble.

response

Bare column name, character name, or variable holding a character name in data. A binary variable coded as 0/1, a logical variable, or a two-level factor/character. For a two-level factor the first level is treated as 0 and the second as 1. A character response is sorted in byte (C-locale) order: uppercase before lowercase, ASCII before accented characters; use a factor to choose the event level. The second value is the event. Rows with a missing response are dropped with a warning.

predictor

Bare column name, character name, or variable holding a character name in data. A numeric predictor variable.

bins

Number of bins.

x

An object of class rbin_equal_freq.

print_plot

logical; if TRUE, prints the plot else returns a plot object.

...

further arguments passed to or from other methods.

Details

Groups have approximately equal sizes and never split tied values. For each k = 1, ..., bins - 1, take the smallest observed value whose cumulative count reaches k * n / bins, where n is the number of non-missing predictors (the type-1 empirical quantile). All observations equal to that value stay in the lower group. The next distinct observed value is the scoring cut. Repeated cuts and cuts beyond the maximum are omitted; a message reports the requested and actual numbers of non-missing bins when fewer bins result. No bin is empty. Without ties, group sizes differ by at most one observation.

Both the top-level and table lower_cut/upper_cut fields contain the actual left-closed, right-open scoring intervals. The first and last intervals extend to negative and positive infinity; gaps go to the preceding group. rbin_create() reproduces the non-missing training counts using these intervals. Missing predictor values form a separate final group, and the equal frequency groups are built from non-missing values only. As with other numeric methods, missing predictors produce missing dummy indicators.

Value

A list of class rbin_equal_freq with the following elements: bins, a data.frame with one row per group (plus a final row for missing values when present); method; vars; lower_cut; and upper_cut.

Examples

bins <- rbin_equal_freq(mbank, y, age, 10)
bins

# plot
plot(bins)


Equal length binning

Description

Bin continuous data using the equal length binning method.

Usage

rbin_equal_length(
  data = NULL,
  response = NULL,
  predictor = NULL,
  bins = 10,
  include_na = TRUE
)

## S3 method for class 'rbin_equal_length'
plot(x, print_plot = TRUE, ...)

Arguments

data

A data.frame or tibble.

response

Bare column name, character name, or variable holding a character name in data. A binary variable coded as 0/1, a logical variable, or a two-level factor/character. For a two-level factor the first level is treated as 0 and the second as 1. A character response is sorted in byte (C-locale) order: uppercase before lowercase, ASCII before accented characters; use a factor to choose the event level. The second value is the event. Rows with a missing response are dropped with a warning.

predictor

Bare column name, character name, or variable holding a character name in data. A numeric predictor; non-missing values must be finite with absolute value up to 1e300.

bins

Number of bins.

include_na

logical; if TRUE, a separate bin is created for missing values.

x

An object of class rbin_equal_length.

print_plot

logical; if TRUE, prints the plot else returns a plot object.

...

further arguments passed to or from other methods.

Value

A list of class rbin_equal_length with the following elements: bins, a data.frame with one row per interval (including empty intervals) and a final row for missing values when present; method; vars; lower_cut; and upper_cut.

Examples

bins <- rbin_equal_length(mbank, y, age, 10)
bins

# plot
plot(bins)



Factor binning

Description

Weight of evidence and information value for categorical data.

Usage

rbin_factor(data = NULL, response = NULL, predictor = NULL, include_na = TRUE)

## S3 method for class 'rbin_factor'
plot(x, print_plot = TRUE, ...)

Arguments

data

A data.frame or tibble.

response

Bare column name, character name, or variable holding a character name in data. A binary variable coded as 0/1, a logical variable, or a two-level factor/character. For a two-level factor the first level is treated as 0 and the second as 1. A character response is sorted in byte (C-locale) order: uppercase before lowercase, ASCII before accented characters; use a factor to choose the event level. The second value is the event. Rows with a missing response are dropped with a warning.

predictor

Bare column name, character name, or variable holding a character name in data. A categorical predictor variable. Factor (including ordered), character, numeric, logical, Date and POSIXct columns are supported. Distinct values form distinct groups.

include_na

logical; if TRUE, a separate bin is created for missing values.

x

An object of class rbin_factor.

print_plot

logical; if TRUE, prints the plot else returns a plot object.

...

further arguments passed to or from other methods.

Details

Both response and predictor accept bare column names, character names, or variables holding character names. Groups and cumulative counts follow first appearance, with missing values last. Factor levels and the ordered class are preserved; an explicit NA level is a valid category, distinct from a missing factor code. It precedes the final missing-code group and is retained when include_na = FALSE. Numeric NaN and NA share a missing-value group. If a literal "NA" category or an explicit NA level is present, the genuine missing group displays as "(missing)" in printed summaries and plots. Stored typed labels, explicit NA levels and ordered classes are preserved.

Value

A list of class rbin_factor with the following elements: bins, a data.frame with one row per observed level (plus a final row for missing values when present); method; and vars.

Examples

bins <- rbin_factor(mbank, y, education)
bins

# plot
plot(bins)


Combine levels

Description

Manually combine levels of categorical data.

Usage

rbin_factor_combine(data, var, new_var, new_name)

Arguments

data

A data.frame or tibble.

var

Bare or character name of a factor or character column in data.

new_var

A character vector containing the names of levels to combine. An NA selects both an explicit NA level and missing factor codes.

new_name

Name of the combined level.

Details

Levels are matched exactly, not as regular expressions. Only the selected levels are renamed; other levels are left untouched even when their names contain the selected name as a substring. Unselected explicit NA levels and missing codes are preserved, as is the ordered class. A combined level takes the position of its first selected level; a new level for missing codes alone is appended at the end.

Value

A data.frame with the predictor's levels combined. The predictor keeps its original position among the columns.

Examples

upper <- c("secondary", "tertiary")
out <- rbin_factor_combine(mbank, education, upper, "upper")
table(out$education)

out <- rbin_factor_combine(mbank, education, c("secondary", "tertiary"), "upper")
table(out$education)


Create dummy variables

Description

Create dummy variables for categorical data.

Usage

rbin_factor_create(data, predictor)

Arguments

data

A data.frame or tibble.

predictor

Bare column name, character name, or variable holding a character name in data. It can be a factor or a character variable; character variables are converted to a factor first, so the levels are sorted.

Details

Indicator columns are derived from the factor codes, so a factor with an explicit NA level gets a real indicator column (for example g_NA) and not a column of missings. A missing factor code that is not a level produces missing indicators. Generated names never overwrite existing columns: a collision is made unique by appending a suffix.

Value

A data.frame with the original columns preserved and one indicator column per level, appended at the end.

Examples

upper <- c("secondary", "tertiary")
out <- rbin_factor_combine(mbank, education, upper, "upper")
rbin_factor_create(out, education)


Manual binning

Description

Bin continuous data manually.

Usage

rbin_manual(
  data = NULL,
  response = NULL,
  predictor = NULL,
  cut_points = NULL,
  include_na = TRUE
)

## S3 method for class 'rbin_manual'
plot(x, print_plot = TRUE, ...)

Arguments

data

A data.frame or tibble.

response

Bare column name, character name, or variable holding a character name in data. A binary variable coded as 0/1, a logical variable, or a two-level factor/character. For a two-level factor the first level is treated as 0 and the second as 1. A character response is sorted in byte (C-locale) order: uppercase before lowercase, ASCII before accented characters; use a factor to choose the event level. The second value is the event. Rows with a missing response are dropped with a warning.

predictor

Bare column name, character name, or variable holding a character name in data. A numeric predictor variable.

cut_points

Cut points for binning.

include_na

logical; if TRUE, a separate bin is created for missing values.

x

An object of class rbin_manual.

print_plot

logical; if TRUE, prints the plot else returns a plot object.

...

further arguments passed to or from other methods.

Details

Cut points are open upper bounds: intervals are left closed and right open, [lower, upper). Supply nine cut points for ten bins; the last bin has no upper bound. For an integer predictor, a cut at 37 includes integers through 36. For continuous data, that cut includes every value below 37, including 36.5; choose the continuous boundary directly.

Value

A list of class rbin_manual with the following elements: bins, a data.frame with one row per interval (including empty intervals) and a final row for missing values when present; method; vars; lower_cut; and upper_cut.

Examples

bins <- rbin_manual(mbank, y, age, c(29, 31, 34, 36, 39, 42, 46, 51, 56))
bins

# plot
plot(bins)


Quantile binning

Description

Bin continuous data using quantiles.

Usage

rbin_quantiles(
  data = NULL,
  response = NULL,
  predictor = NULL,
  bins = 10,
  include_na = TRUE
)

## S3 method for class 'rbin_quantiles'
plot(x, print_plot = TRUE, ...)

Arguments

data

A data.frame or tibble.

response

Bare column name, character name, or variable holding a character name in data. A binary variable coded as 0/1, a logical variable, or a two-level factor/character. For a two-level factor the first level is treated as 0 and the second as 1. A character response is sorted in byte (C-locale) order: uppercase before lowercase, ASCII before accented characters; use a factor to choose the event level. The second value is the event. Rows with a missing response are dropped with a warning.

predictor

Bare column name, character name, or variable holding a character name in data. A numeric predictor variable. Infinite values are supported when the computed cut points are numbers; interpolation producing NA or NaN cut points errors.

bins

Number of bins.

include_na

logical; if TRUE, a separate bin is created for missing values.

x

An object of class rbin_quantiles.

print_plot

logical; if TRUE, prints the plot else returns a plot object.

...

further arguments passed to or from other methods.

Value

A list of class rbin_quantiles with the following elements: bins, a data.frame with one row per interval (including empty intervals) and a final row for missing values when present; method; vars; lower_cut; and upper_cut.

Examples

bins <- rbin_quantiles(mbank, y, age, 10)
bins

# plot
plot(bins)


Winsorized binning

Description

Bin continuous data using winsorized method.

Usage

rbin_winsorize(
  data = NULL,
  response = NULL,
  predictor = NULL,
  bins = 10,
  include_na = TRUE,
  winsor_rate = 0.05,
  min_val = NULL,
  max_val = NULL,
  type = 7,
  remove_na = TRUE
)

## S3 method for class 'rbin_winsorize'
plot(x, print_plot = TRUE, ...)

Arguments

data

A data.frame or tibble.

response

Bare column name, character name, or variable holding a character name in data. A binary variable coded as 0/1, a logical variable, or a two-level factor/character. For a two-level factor the first level is treated as 0 and the second as 1. A character response is sorted in byte (C-locale) order: uppercase before lowercase, ASCII before accented characters; use a factor to choose the event level. The second value is the event. Rows with a missing response are dropped with a warning.

predictor

Bare column name, character name, or variable holding a character name in data. A numeric predictor; non-missing values must be finite. The values used to compute the cut points (after winsorizing) must have absolute value up to 1e300.

bins

Number of bins.

include_na

logical; if TRUE, a separate bin is created for missing values.

winsor_rate

A value from 0.0 to 0.5.

min_val

the low border, all values being lower than this will be replaced by this value. The default is set to the 5 percent quantile of predictor.

max_val

the high border, all values being larger than this will be replaced by this value. The default is set to the 95 percent quantile of predictor.

type

an integer between 1 and 9 selecting one of the nine quantile algorithms detailed in quantile() to be used.

remove_na

logical; if TRUE, missing values are removed while calculating quantiles. If FALSE, retained predictor values must not be missing; use TRUE to retain a separate missing-value bin.

x

An object of class rbin_winsorize.

print_plot

logical; if TRUE, prints the plot else returns a plot object.

...

further arguments passed to or from other methods.

Value

A list of class rbin_winsorize with the following elements: bins, a data.frame with one row per interval (including empty intervals) and a final row for missing values when present; method; vars; lower_cut; upper_cut; and clamp, the fitted minimum and maximum used when scoring new data (absent if all predictor values are missing).

Examples

bins <- rbin_winsorize(mbank, y, age, 10, winsor_rate = 0.05)
bins

# plot
plot(bins)