tide-binning 0.6.0__tar.gz

tide_binning-0.6.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+site/
+.ipynb_checkpoints/
+plots_review/

tide_binning-0.6.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 0.6.0 (2026-10-16)
+
+Complete rewrite. The greedy algorithm and its rules are unchanged: on the scenarios in
+`tests/golden`, the bins are identical to v0.5.0.
+
+### New
+- scikit-learn estimator: `get_params` / `set_params` / `clone`, `Pipeline`,
+  `cross_validate(params={"tide__periods": ...})`, metadata routing,
+  `get_feature_names_out`.
+- NaN / None / pd.NA / NaT are supported in features (bins key `None`).
+- `cat_values` and `missing_values` turn numeric codes such as `-999` into categories or
+  missing values, globally or per feature.
+- `trend` can be forced (`"pos"` / `"neg"`), globally or per feature.
+- `max_unique` / `n_quantiles` (defaults 1000 / 200): features with more than 1000 unique values
+  are split at 200 quantiles instead of every unique value. This is faster, and with many
+  periods the exact search often finds no split at all. Pass a large `max_unique` for v0.5 behaviour.
+- `user_bins`: apply your own bins (any shape), with a coverage warning.
+- `summary_` table; a warning when a feature collapses to one continuous bin.
+- `n_jobs` (parallel over features) and `verbose` (progress bar).
+- `plot()` returns the figures and accepts `show=False`.
+- Periods may be any sortable type and need not be sorted.
+
+### Fixed
+- `min_er_delta` is now also guaranteed for the last bin (it is merged otherwise).
+- `min_er_delta` no longer applies to the first bin (v0.5 required its event rate ≥ delta).
+- With `worst_bin` / `best_bin`, no split is made between the continuous part and the
+  attached missing values.
+- `cat_strategy="tide"` now guarantees all constraints: continuous bins merge only with
+  adjacent ones (their intervals become one), and their monotonicity is re-checked.
+  The missing bin takes part in the merge.
+- `transform` no longer mistakes values equal to a WoE for unknown values.
+- `stats_per` no longer duplicates rows on refit.
+- `"col_min"` / `"col_max"` bounds now use the next representable float instead of
+  `± 1e-8`, which failed for large values.
+
+### Changed (breaking)
+- WoE uses a symmetric epsilon, `ln((%nonevents + 1e-8) / (%events + 1e-8))`: a bin without
+  non-events no longer gets WoE = -inf and IV = inf. Other bins are unchanged up to ~1e-8.
+- `fit(X, y, per)` → `fit(X, y, periods)`; `reset` and `return_bins` were removed.
+- `handle_unknown` moved from `transform()` into the constructor (`set_params` changes it).
+- `transform` requires the same columns as `fit`; `xnames` and ndarray input were removed.
+- Attributes: `exog_bins` → `bins_`, `exog_woes` → `woes_`, `stats` → `stats_`,
+  `stats_per` → `stats_per_`; the stats tables have a new `bin_idx` column.
+- `missing_categories` → `missing_values`; `n_prebins` → `n_trend_bins`.
+- Bin labels (stats tables and plots) show integer bounds without decimals (`(18,25]`) and
+  other bounds with exactly 4 decimals (`(0.3400,1.1130]`). `bins_` keeps the full values.

tide_binning-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Leonid Garin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tide_binning-0.6.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: tide-binning
+Version: 0.6.0
+Summary: TIDE - Time Invariant Discretization Engine: time-stable binning for credit scorecards
+Project-URL: Homepage, https://github.com/leonidgarin/TIDE
+Project-URL: Issues, https://github.com/leonidgarin/TIDE/issues
+Author-email: Leonid Garin <leonidgarin97@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: binning,credit risk,information value,psi,scorecard,weight of evidence,woe
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: joblib>=1.3
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy>=1.9
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.80; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.80; extra == 'test'
+Requires-Dist: pytest-cov>=4; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# TIDE — Time Invariant Discretization Engine
+
+[![CI](https://github.com/leonidgarin/TIDE/actions/workflows/ci.yml/badge.svg)](https://github.com/leonidgarin/TIDE/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tide-binning.svg)](https://pypi.org/project/tide-binning/)
+[![Python](https://img.shields.io/pypi/pyversions/tide-binning.svg)](https://pypi.org/project/tide-binning/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+TIDE bins features for credit scorecards so that the bins are **stable over time**.
+In every period of the training data, as hard constraints:
+
+- the event rate is **monotonic** over the bins, in the **same direction** in all periods,
+  so WoE / event-rate curves of different bins never cross;
+- adjacent bins differ in event rate by at least `min_er_delta`;
+- every bin holds at least `min_sample_rate` of the period's rows and at least
+  `min_class_obs` events and non-events.
+
+It works on **mixed-type** columns, e.g. `age = [18, 44, np.nan, "special_category", -999]`,
+and encodes them with Weight of Evidence. It is a scikit-learn transformer.
+
+## Installation
+
+```bash
+pip install tide-binning
+```
+
+Requires Python ≥ 3.10. All dependencies (numpy, pandas, scipy, scikit-learn, matplotlib,
+joblib, tqdm) ship prebuilt wheels for Windows, macOS and Linux.
+
+## Quick start
+
+```python
+import pandas as pd
+from sklearn.linear_model import LogisticRegression
+from sklearn.metrics import roc_auc_score
+from tide import TIDE
+
+X = pd.DataFrame(...)          # features, may be mixed-type
+y = pd.Series(...)             # binary target, 0/1
+periods = pd.Series(...)       # e.g. application month: str, datetime, Period, int, ...
+
+binner = TIDE(cat_values=[-999])          # -999 is a category, not a number
+X_woe = binner.fit_transform(X, y, periods=periods)
+
+lr = LogisticRegression().fit(X_woe, y)
+print(roc_auc_score(y, lr.predict_proba(X_woe)[:, 1]))
+```
+
+## Results
+
+```python
+binner.summary_       # one row per feature: trend, n_bins, IV, max PSI, warnings
+binner.stats_         # per feature and bin: n_obs, event rate, WoE, IV
+binner.stats_per_     # per period, feature and bin: n_obs, event rate, PSI
+binner.bins_          # fitted bins (format below)
+binner.woes_          # {feature: {bin_idx: WoE}}
+binner.plot(["age"])  # bin sizes and event rates, event rate over time, PSI over time
+```
+
+## Bins format
+
+```python
+{"trend": "pos",
+ "bins": {0: {(-np.inf, 25.0): "cont", "special_category": "cat"},
+          1: {(25.0, 40.0): "cont"},
+          2: {(40.0, np.inf): "cont"},
+          3: {None: "missing"}}}       # None = NaN / None / pd.NA / NaT
+```
+
+Intervals are `(a, b]` for a positive trend and `[a, b)` for a negative trend, so a value
+that is unseen in training and lies between two borders always goes to the bin with the
+**higher** event rate.
+
+## Handling special values
+
+| You have | Use |
+|---|---|
+| NaN, None, pd.NA, NaT | missing automatically |
+| strings, bools | categories automatically |
+| numeric codes such as `-999` that mean "no data" | `missing_values=[-999]` |
+| numeric codes that are a category of their own | `cat_values=[-999]` |
+| different codes per feature | `{"age": [-1], "income": [-999]}` |
+
+`missing_strategy` (`"separate_bin"`, `"worst_bin"`, `"best_bin"`) and `cat_strategy`
+(`"separate_bin"`, `"chi-squared"`, `"tide"`) control how they are binned. With
+`cat_strategy="tide"`, all bins — continuous, categorical and missing — are merged until the
+stability constraints hold for all of them.
+
+## Your own bins
+
+```python
+binner = TIDE(user_bins={"age": {"trend": "pos", "bins": {
+    0: {(-np.inf, 25.0): "cont"},
+    1: {(25.0, 60.0): "cont"},
+    2: {(60.0, np.inf): "cont", None: "missing"},
+}}})
+```
+
+User bins are applied as given (U-shapes are fine); a warning lists training values that
+fall in no bin.
+
+## In production
+
+```python
+import pickle
+binner = pickle.load(open("binner.pkl", "rb"))
+binner.set_params(handle_unknown="worst")   # change how unseen values are treated, no refit
+X_woe = binner.transform(X_new)
+```
+
+`handle_unknown`: `"keep"` (leave the raw value), `"worst"` / `"best"` (lowest / highest
+WoE), `"missing_worst"` / `"missing_best"` (WoE of the missing bin, else lowest / highest).
+
+## scikit-learn
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.model_selection import cross_validate
+
+pipe = Pipeline([("tide", TIDE()), ("lr", LogisticRegression())])
+pipe.fit(X, y, tide__periods=periods)
+cross_validate(pipe, X, y, params={"tide__periods": periods}, scoring="roc_auc")
+```
+
+`get_params` / `set_params` / `clone`, `get_feature_names_out` and metadata routing
+(`TIDE().set_fit_request(periods=True)`) work as usual.
+
+## Performance
+
+`fit` works on per-period counts of the sorted unique values, so after one sort per
+feature its cost no longer depends on the number of rows. `n_jobs=-1` fits features in
+parallel. Measured on a 2-core laptop, 5,000,000 rows and 24 periods, per feature:
+
+| feature | fit | transform |
+|---|---|---|
+| integer, 100 unique values | ~1 s | ~0.5 s |
+| float, 1,000 unique | ~1 s | ~0.5 s |
+| float, all unique (undersampled to 200 quantiles) | ~5 s | ~0.5 s |
+| float, 530k unique (exact search, `max_unique=10**6`) | ~5 s | ~0.5 s |
+| mixed object column (numbers, strings, NaN) | ~3 s | ~2 s |
+
+Run `python benchmarks/bench_fit.py` to measure on your machine.
+
+## License
+
+MIT © Leonid Garin

tide_binning-0.6.0/README.md

@@ -0,0 +1,145 @@
+# TIDE — Time Invariant Discretization Engine
+
+[![CI](https://github.com/leonidgarin/TIDE/actions/workflows/ci.yml/badge.svg)](https://github.com/leonidgarin/TIDE/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tide-binning.svg)](https://pypi.org/project/tide-binning/)
+[![Python](https://img.shields.io/pypi/pyversions/tide-binning.svg)](https://pypi.org/project/tide-binning/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+TIDE bins features for credit scorecards so that the bins are **stable over time**.
+In every period of the training data, as hard constraints:
+
+- the event rate is **monotonic** over the bins, in the **same direction** in all periods,
+  so WoE / event-rate curves of different bins never cross;
+- adjacent bins differ in event rate by at least `min_er_delta`;
+- every bin holds at least `min_sample_rate` of the period's rows and at least
+  `min_class_obs` events and non-events.
+
+It works on **mixed-type** columns, e.g. `age = [18, 44, np.nan, "special_category", -999]`,
+and encodes them with Weight of Evidence. It is a scikit-learn transformer.
+
+## Installation
+
+```bash
+pip install tide-binning
+```
+
+Requires Python ≥ 3.10. All dependencies (numpy, pandas, scipy, scikit-learn, matplotlib,
+joblib, tqdm) ship prebuilt wheels for Windows, macOS and Linux.
+
+## Quick start
+
+```python
+import pandas as pd
+from sklearn.linear_model import LogisticRegression
+from sklearn.metrics import roc_auc_score
+from tide import TIDE
+
+X = pd.DataFrame(...)          # features, may be mixed-type
+y = pd.Series(...)             # binary target, 0/1
+periods = pd.Series(...)       # e.g. application month: str, datetime, Period, int, ...
+
+binner = TIDE(cat_values=[-999])          # -999 is a category, not a number
+X_woe = binner.fit_transform(X, y, periods=periods)
+
+lr = LogisticRegression().fit(X_woe, y)
+print(roc_auc_score(y, lr.predict_proba(X_woe)[:, 1]))
+```
+
+## Results
+
+```python
+binner.summary_       # one row per feature: trend, n_bins, IV, max PSI, warnings
+binner.stats_         # per feature and bin: n_obs, event rate, WoE, IV
+binner.stats_per_     # per period, feature and bin: n_obs, event rate, PSI
+binner.bins_          # fitted bins (format below)
+binner.woes_          # {feature: {bin_idx: WoE}}
+binner.plot(["age"])  # bin sizes and event rates, event rate over time, PSI over time
+```
+
+## Bins format
+
+```python
+{"trend": "pos",
+ "bins": {0: {(-np.inf, 25.0): "cont", "special_category": "cat"},
+          1: {(25.0, 40.0): "cont"},
+          2: {(40.0, np.inf): "cont"},
+          3: {None: "missing"}}}       # None = NaN / None / pd.NA / NaT
+```
+
+Intervals are `(a, b]` for a positive trend and `[a, b)` for a negative trend, so a value
+that is unseen in training and lies between two borders always goes to the bin with the
+**higher** event rate.
+
+## Handling special values
+
+| You have | Use |
+|---|---|
+| NaN, None, pd.NA, NaT | missing automatically |
+| strings, bools | categories automatically |
+| numeric codes such as `-999` that mean "no data" | `missing_values=[-999]` |
+| numeric codes that are a category of their own | `cat_values=[-999]` |
+| different codes per feature | `{"age": [-1], "income": [-999]}` |
+
+`missing_strategy` (`"separate_bin"`, `"worst_bin"`, `"best_bin"`) and `cat_strategy`
+(`"separate_bin"`, `"chi-squared"`, `"tide"`) control how they are binned. With
+`cat_strategy="tide"`, all bins — continuous, categorical and missing — are merged until the
+stability constraints hold for all of them.
+
+## Your own bins
+
+```python
+binner = TIDE(user_bins={"age": {"trend": "pos", "bins": {
+    0: {(-np.inf, 25.0): "cont"},
+    1: {(25.0, 60.0): "cont"},
+    2: {(60.0, np.inf): "cont", None: "missing"},
+}}})
+```
+
+User bins are applied as given (U-shapes are fine); a warning lists training values that
+fall in no bin.
+
+## In production
+
+```python
+import pickle
+binner = pickle.load(open("binner.pkl", "rb"))
+binner.set_params(handle_unknown="worst")   # change how unseen values are treated, no refit
+X_woe = binner.transform(X_new)
+```
+
+`handle_unknown`: `"keep"` (leave the raw value), `"worst"` / `"best"` (lowest / highest
+WoE), `"missing_worst"` / `"missing_best"` (WoE of the missing bin, else lowest / highest).
+
+## scikit-learn
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.model_selection import cross_validate
+
+pipe = Pipeline([("tide", TIDE()), ("lr", LogisticRegression())])
+pipe.fit(X, y, tide__periods=periods)
+cross_validate(pipe, X, y, params={"tide__periods": periods}, scoring="roc_auc")
+```
+
+`get_params` / `set_params` / `clone`, `get_feature_names_out` and metadata routing
+(`TIDE().set_fit_request(periods=True)`) work as usual.
+
+## Performance
+
+`fit` works on per-period counts of the sorted unique values, so after one sort per
+feature its cost no longer depends on the number of rows. `n_jobs=-1` fits features in
+parallel. Measured on a 2-core laptop, 5,000,000 rows and 24 periods, per feature:
+
+| feature | fit | transform |
+|---|---|---|
+| integer, 100 unique values | ~1 s | ~0.5 s |
+| float, 1,000 unique | ~1 s | ~0.5 s |
+| float, all unique (undersampled to 200 quantiles) | ~5 s | ~0.5 s |
+| float, 530k unique (exact search, `max_unique=10**6`) | ~5 s | ~0.5 s |
+| mixed object column (numbers, strings, NaN) | ~3 s | ~2 s |
+
+Run `python benchmarks/bench_fit.py` to measure on your machine.
+
+## License
+
+MIT © Leonid Garin

tide_binning-0.6.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tide-binning"
+dynamic = ["version"]
+description = "TIDE - Time Invariant Discretization Engine: time-stable binning for credit scorecards"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Leonid Garin", email = "leonidgarin97@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["binning", "scorecard", "credit risk", "weight of evidence", "woe", "information value", "psi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "numpy>=1.23",
+    "pandas>=2.0",
+    "scipy>=1.9",
+    "scikit-learn>=1.4",
+    "matplotlib>=3.7",
+    "joblib>=1.3",
+    "tqdm>=4.60",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-cov>=4", "hypothesis>=6.80"]
+docs = ["mkdocs>=1.6,<2", "mkdocs-material>=9.5", "mkdocstrings[python]>=0.25"]
+dev = ["tide-binning[test,docs]", "ruff>=0.6", "build>=1.0", "twine>=5"]
+
+[project.urls]
+Homepage = "https://github.com/leonidgarin/TIDE"
+Issues = "https://github.com/leonidgarin/TIDE/issues"
+
+[tool.hatch.version]
+path = "src/tide/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tide"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tide", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+filterwarnings = ["error::FutureWarning", "error::DeprecationWarning:tide.*"]
+
+[tool.coverage.run]
+source = ["tide"]
+branch = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "NPY", "PD", "RUF"]
+ignore = ["RUF001", "RUF002", "RUF003", "PD011", "B905"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B", "PD", "RUF007", "RUF059"]
+"benchmarks/*" = ["B", "PD"]

tide_binning-0.6.0/src/tide/__init__.py

@@ -0,0 +1,10 @@
+"""TIDE - Time Invariant Discretization Engine.
+
+Time-stable binning of mixed-type features for credit scorecards.
+"""
+
+from ._estimator import TIDE
+
+__version__ = "0.6.0"
+
+__all__ = ["TIDE", "__version__"]