Optimal binning with multiclass target¶

class optbinning.MulticlassOptimalBinning(name='', prebinning_method='cart', solver='cp', max_n_prebins=20, min_prebin_size=0.05, min_n_bins=None, max_n_bins=None, min_bin_size=None, max_bin_size=None, monotonic_trend='auto', min_event_rate_diff=0, max_pvalue=None, max_pvalue_policy='consecutive', outlier_detector=None, outlier_params=None, user_splits=None, user_splits_fixed=None, special_codes=None, split_digits=None, mip_solver='bop', time_limit=100, verbose=False, **prebinning_kwargs)¶

Bases: optbinning.binning.binning.OptimalBinning

Optimal binning of a numerical variable with respect to a multiclass or multilabel target.

Note that the maximum number of classes is set to 100. To ease visualization of the binning table, a set of 100 maximally distinct colors is generated using the library glasbey.

Parameters

name (str, optional (default="")) – The variable name.
prebinning_method (str, optional (default="cart")) – The pre-binning method. Supported methods are “cart” for a CART decision tree, “quantile” to generate prebins with approximately same frequency and “uniform” to generate prebins with equal width. Method “cart” uses sklearn.tree.DecistionTreeClassifier.
solver (str, optional (default="cp")) – The optimizer to solve the optimal binning problem. Supported solvers are “mip” to choose a mixed-integer programming solver or “cp” to choose a constrained programming solver.
max_n_prebins (int (default=20)) – The maximum number of bins after pre-binning (prebins).
min_prebin_size (float (default=0.05)) – The fraction of mininum number of records for each prebin.
min_n_bins (int or None, optional (default=None)) – The minimum number of bins. If None, then min_n_bins is a value in [0, max_n_prebins].
max_n_bins (int or None, optional (default=None)) – The maximum number of bins. If None, then max_n_bins is a value in [0, max_n_prebins].
min_bin_size (float or None, optional (default=None)) – The fraction of minimum number of records for each bin. If None, min_bin_size = min_prebin_size.
max_bin_size (float or None, optional (default=None)) – The fraction of maximum number of records for each bin. If None, max_bin_size = 1.0.
monotonic_trend (str, array-like or None, optional (default="auto")) – The event rate monotonic trend. Supported trends are “auto”, “auto_heuristic” and “auto_asc_desc” to automatically determine the trend maximizing IV using a machine learning classifier, a list of monotonic trends combining “auto”, “auto_heuristic”, “auto_asc_desc”, “ascending”, “descending”, “concave”, “convex”, “peak”, “valley”, “peak_heuristic”, “valley_heuristic” and None, one for each class. If None, then the monotonic constraint is disabled.
min_event_rate_diff (float, optional (default=0)) –
The minimum event rate difference between consecutives bins.

New in version 0.17.0.
max_pvalue (float or None, optional (default=None)) – The maximum p-value among bins. The Z-test is used to detect bins not satisfying the p-value constraint.
max_pvalue_policy (str, optional (default="consecutive")) – The method to determine bins not satisfying the p-value constraint. Supported methods are “consecutive” to compare consecutive bins and “all” to compare all bins.
outlier_detector (str or None, optional (default=None)) – The outlier detection method. Supported methods are “range” to use the interquartile range based method or “zcore” to use the modified Z-score method.
outlier_params (dict or None, optional (default=None)) – Dictionary of parameters to pass to the outlier detection method.
user_splits (array-like or None, optional (default=None)) – The list of pre-binning split points.
user_splits_fixed (array-like or None (default=None)) – The list of pre-binning split points that must be fixed.
special_codes (array-like, dict or None, optional (default=None)) – List of special codes. Use special codes to specify the data values that must be treated separately.
split_digits (int or None, optional (default=None)) – The significant digits of the split points. If split_digits is set to 0, the split points are integers. If None, then all significant digits in the split points are considered.
mip_solver (str, optional (default="bop")) – The mixed-integer programming solver. Supported solvers are “bop” to choose the Google OR-Tools binary optimizer or “cbc” to choose the COIN-OR Branch-and-Cut solver CBC.
time_limit (int (default=100)) – The maximum time in seconds to run the optimization solver.
verbose (bool (default=False)) – Enable verbose output.
**prebinning_kwargs (keyword arguments) –
The pre-binning keywrord arguments.

New in version 0.6.1.

Notes

The parameter values max_n_prebins and min_prebin_size control complexity and memory usage. The default values generally produce quality results, however, some improvement can be achieved by increasing max_n_prebins and/or decreasing min_prebin_size.

The pre-binning refinement phase guarantee that no prebin has either zero counts of non-events or events by merging those pure prebins. Pure bins produce infinity WoE and event rates.

property binning_table¶

Return an instantiated binning table. Please refer to Binning table: multiclass target.

Returns: binning_table
Return type: MulticlassBinningTable.

property classes¶

List of classes.

Returns: classes
Return type: numpy.ndarray

fit(x, y, check_input=False)¶

Fit the optimal binning according to the given training data.

Parameters

x (array-like, shape = (n_samples,)) – Training vector, where n_samples is the number of samples.
y (array-like, shape = (n_samples,)) – Target vector relative to x.
check_input (bool (default=False)) – Whether to check input arrays.

Returns

self – Fitted optimal binning.

Return type

MulticlassOptimalBinning

fit_transform(x, y, metric='mean_woe', metric_special=0, metric_missing=0, show_digits=2, check_input=False)¶

Fit the optimal binning according to the given training data, then transform it.

Parameters

x (array-like, shape = (n_samples,)) – Training vector, where n_samples is the number of samples.
y (array-like, shape = (n_samples,)) – Target vector relative to x.
metric (str, optional (default="mean_woe")) – The metric used to transform the input vector. Supported metrics are “mean_woe” to choose the mean of Weight of Evidence (WoE), “weighted_mean_woe” to choose weighted mean of WoE using the number of records per class as weights, “indices” to assign the corresponding indices of the bins and “bins” to assign the corresponding bin interval.
metric_special (float or str (default=0)) – The metric value to transform special codes in the input vector. Supported metrics are “empirical” to use the empirical mean WoE or weighted mean WoE, and any numerical value.
metric_missing (float or str (default=0)) – The metric value to transform missing values in the input vector. Supported metrics are “empirical” to use the empirical mean WoE or weighted mean WoE, and any numerical value.
show_digits (int, optional (default=2)) – The number of significant digits of the bin column. Applies when metric="bins".
check_input (bool (default=False)) – Whether to check input arrays.

Returns

x_new – Transformed array.

Return type

numpy array, shape = (n_samples,)

get_params(deep=True)¶

Get parameters for this estimator.

Parameters: deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Returns: params – Parameter names mapped to their values.
Return type: dict

information(print_level=1)¶

Print overview information about the options settings, problem statistics, and the solution of the computation.

Parameters: print_level (int (default=1)) – Level of details.

read_json(path)¶

Read json file containing split points and set them as the new split points.

Parameters: path (The path of the json file.) –

set_params(**params)¶

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters: **params (dict) – Estimator parameters.
Returns: self – Estimator instance.
Return type: estimator instance

property splits¶

List of optimal split points.

Returns: splits
Return type: numpy.ndarray

property status¶

The status of the underlying optimization solver.

Returns: status
Return type: str

to_json(path)¶

Save optimal bins and/or splits points and transformation depending on the target type.

Parameters: path (The path where the json is going to be saved.) –

transform(x, metric='mean_woe', metric_special=0, metric_missing=0, show_digits=2, check_input=False)¶

Transform given data to mean Weight of Evidence (WoE) or weighted mean WoE using bins from the fitted optimal binning.

Parameters

x (array-like, shape = (n_samples,)) – Training vector, where n_samples is the number of samples.
metric (str, optional (default="mean_woe")) – The metric used to transform the input vector. Supported metrics are “mean_woe” to choose the mean of Weight of Evidence (WoE), “weighted_mean_woe” to choose weighted mean of WoE using the number of records per class as weights, “indices” to assign the corresponding indices of the bins and “bins” to assign the corresponding bin interval.
metric_special (float or str (default=0)) – The metric value to transform special codes in the input vector. Supported metrics are “empirical” to use the empirical mean WoE or weighted mean WoE, and any numerical value.
metric_missing (float or str (default=0)) – The metric value to transform missing values in the input vector. Supported metrics are “empirical” to use the empirical mean WoE or weighted mean WoE, and any numerical value.
show_digits (int, optional (default=2)) – The number of significant digits of the bin column. Applies when metric="bins".
check_input (bool (default=False)) – Whether to check input arrays.

Returns

x_new – Transformed array.

Return type

numpy array, shape = (n_samples,)