Registry / ai-ml / optbinning

optbinning

JSON →
library0.21.0pypypi✓ verified 84d ago

OptBinning is a Python library for optimal binning, a data preprocessing technique used in machine learning to transform continuous or categorical features into discrete bins. It supports various binning algorithms, including optimal, isotonic, and tree-based methods, and facilitates scorecard development. The current version is 0.21.0, with a release cadence of typically a new minor version every 1-2 months, often including new features and bug fixes.

pip install optbinning
INSTALL
IMPORT
SIG · OPTBINNING
O
optbinning
ai-mlpythonv0.21.0
Install
21.9s avg
Import
7401ms
Disk
619MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.21.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 21.9s · import 7.401s · 556MB
619MB installed
● package 619MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OptimalBinning
from optbinning import OptimalBinning
BinningProcess
from optbinning import BinningProcess
Scorecard
from optbinning import Scorecard
OptimalBinningSklearn
from optbinning.optimal_binning import OptimalBinningSklearn
from optbinning import OptimalBinningSklearn
Subclass is in a submodule, not top-level.

This example demonstrates how to use `OptimalBinning` to discretize both numerical and categorical features for a binary target. It covers initialization, fitting the binning process, and transforming the data, finally printing the generated binning tables.

import numpy as np import pandas as pd from optbinning import OptimalBinning # Create dummy data np.random.seed(42) X = pd.DataFrame({ 'feature_1': np.random.rand(100) * 100, 'feature_2': np.random.randint(0, 5, 100), 'feature_3': np.random.normal(50, 10, 100), }) y = np.random.randint(0, 2, 100) # Binary target # Initialize and fit OptimalBinning for a continuous feature optb_num = OptimalBinning(name="feature_1", dtype="numerical", dtype_target="binary") optb_num.fit(X["feature_1"], y) # Transform the feature X["feature_1_binned"] = optb_num.transform(X["feature_1"]) # Print binning table print(f"Binning Table for feature_1:\n{optb_num.binning_table.build()}\n") # Example with a categorical feature optb_cat = OptimalBinning(name="feature_2", dtype="categorical", dtype_target="binary") optb_cat.fit(X["feature_2"], y) X["feature_2_binned"] = optb_cat.transform(X["feature_2"]) print(f"Binning Table for feature_2:\n{optb_cat.binning_table.build()}\n") # The transformed data print("Transformed DataFrame head:") print(X.head())
optbinning --version
Debug
Known issues
breakingOptBinning v0.20.1 introduced a specific constraint for the `ortools` dependency (`ortools<9.12`) to avoid incompatible changes in CP-SAT solver. Using `ortools` version 9.12 or higher will cause runtime errors.
fix
Ensure `ortools` is installed with a version less than 9.12. If you encounter issues, try `pip install 'ortools<9.12'`.
affects: >=0.20.1
gotchaThe `Scorecard.transform` method was added in OptBinning v0.21.0. If you are using an older version, this method will not exist, and you may need to manually apply transformations or update your library.
fix
Upgrade to OptBinning v0.21.0 or newer to use the `Scorecard.transform` method, or implement the transformation logic manually using `Scorecard.decision_function`.
affects: <0.21.0
gotchaPrior to OptBinning v0.19.0, the `transform` method might not preserve the `pandas.DataFrame` index. This could lead to misalignment issues if not handled carefully.
fix
Upgrade to OptBinning v0.19.0 or newer to ensure `pandas.DataFrame` indexes are preserved during transformation. If upgrading is not possible, explicitly manage index alignment after transformation.
affects: <0.19.0
gotchaThe handling and implementation of `sample_weight` have evolved across several versions (e.g., v0.17.0, v0.17.3, v0.21.0). Behavior might differ slightly or require specific checks depending on your OptBinning version.
fix
Always refer to the official documentation for your specific OptBinning version when working with `sample_weight` to understand its support and proper usage in `OptimalBinning` and `Scorecard` classes.
affects: <0.21.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ortools'
The `ortools` package, a required dependency for the underlying optimization solvers, is not installed or its version conflicts with OptBinning's requirements.
fix
Install the correct version of `ortools` by running `pip install 'ortools<9.12'` to satisfy OptBinning's dependency requirements.
AttributeError: 'Scorecard' object has no attribute 'transform'
Attempting to call the `transform` method on a `Scorecard` object in an OptBinning version older than 0.21.0, where this method did not exist.
fix
Upgrade OptBinning to version 0.21.0 or newer (`pip install --upgrade optbinning`). Alternatively, use `Scorecard.decision_function` if you need the scores for a specific dataset.
ValueError: Binning process not fitted. Call 'fit' or 'fit_transform' first.
The `transform` method was called on an `OptimalBinning` or `BinningProcess` object before the `fit` or `fit_transform` method was executed, meaning the binning rules have not been learned yet.
fix
Ensure that `binning_instance.fit(X, y)` or `binning_instance.fit_transform(X, y)` is called before attempting to call `binning_instance.transform(X)`.
TypeError: OptimalBinning.fit() missing 1 required positional argument: 'y'
The `fit` method for optimal binning classes (e.g., `OptimalBinning`) requires both features (X) and target (y) arguments, but 'y' was omitted.
fix
Provide both the feature series/array (X) and the target series/array (y) to the `fit` method, e.g., `optimal_binning_instance.fit(X['feature_name'], y)`.
Upgrade
Version history
0.21.0latest on PyPI · released Oct 26, 2025
Audit
Dependencies
pythonrequiredRequired Python version
ortoolsrequiredSolver dependency for optimal binning. Specific version required.
Agent activity
6 hits · last 30 days
node
6
Resources
optbinning — pip install optbinning · libregistry