{"id":8384,"library":"optbinning","title":"OptBinning","description":"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.","status":"active","version":"0.21.0","language":"en","source_language":"en","source_url":"https://github.com/guillermo-navas-palencia/optbinning","tags":["binning","feature-engineering","data-preprocessing","machine-learning","scorecard"],"install":[{"cmd":"pip install optbinning","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version","package":"python","optional":false},{"reason":"Solver dependency for optimal binning. Specific version required.","package":"ortools","optional":false}],"imports":[{"symbol":"OptimalBinning","correct":"from optbinning import OptimalBinning"},{"symbol":"BinningProcess","correct":"from optbinning import BinningProcess"},{"symbol":"Scorecard","correct":"from optbinning import Scorecard"},{"note":"Subclass is in a submodule, not top-level.","wrong":"from optbinning import OptimalBinningSklearn","symbol":"OptimalBinningSklearn","correct":"from optbinning.optimal_binning import OptimalBinningSklearn"}],"quickstart":{"code":"import numpy as np\nimport pandas as pd\nfrom optbinning import OptimalBinning\n\n# Create dummy data\nnp.random.seed(42)\nX = pd.DataFrame({\n    'feature_1': np.random.rand(100) * 100,\n    'feature_2': np.random.randint(0, 5, 100),\n    'feature_3': np.random.normal(50, 10, 100),\n})\ny = np.random.randint(0, 2, 100) # Binary target\n\n# Initialize and fit OptimalBinning for a continuous feature\noptb_num = OptimalBinning(name=\"feature_1\", dtype=\"numerical\", dtype_target=\"binary\")\noptb_num.fit(X[\"feature_1\"], y)\n\n# Transform the feature\nX[\"feature_1_binned\"] = optb_num.transform(X[\"feature_1\"])\n\n# Print binning table\nprint(f\"Binning Table for feature_1:\\n{optb_num.binning_table.build()}\\n\")\n\n# Example with a categorical feature\noptb_cat = OptimalBinning(name=\"feature_2\", dtype=\"categorical\", dtype_target=\"binary\")\noptb_cat.fit(X[\"feature_2\"], y)\nX[\"feature_2_binned\"] = optb_cat.transform(X[\"feature_2\"])\nprint(f\"Binning Table for feature_2:\\n{optb_cat.binning_table.build()}\\n\")\n\n# The transformed data\nprint(\"Transformed DataFrame head:\")\nprint(X.head())","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `ortools` is installed with a version less than 9.12. If you encounter issues, try `pip install 'ortools<9.12'`.","message":"OptBinning 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.","severity":"breaking","affected_versions":">=0.20.1"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":"<0.21.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.19.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"<0.21.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the correct version of `ortools` by running `pip install 'ortools<9.12'` to satisfy OptBinning's dependency requirements.","cause":"The `ortools` package, a required dependency for the underlying optimization solvers, is not installed or its version conflicts with OptBinning's requirements.","error":"ModuleNotFoundError: No module named 'ortools'"},{"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.","cause":"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.","error":"AttributeError: 'Scorecard' object has no attribute 'transform'"},{"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)`.","cause":"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.","error":"ValueError: Binning process not fitted. Call 'fit' or 'fit_transform' first."},{"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)`.","cause":"The `fit` method for optimal binning classes (e.g., `OptimalBinning`) requires both features (X) and target (y) arguments, but 'y' was omitted.","error":"TypeError: OptimalBinning.fit() missing 1 required positional argument: 'y'"}]}