pickbuckets 0.5.0

Portable, human-readable bucketing rules for Python data workflows.

pickbuckets

Bucketing rules you can serialize, inspect, diff, and run anywhere.

pickbuckets turns raw numerical and categorical values into human-readable, versioned bucketing rules. Fit a rule with the full stack (pandas, Polars, scikit-learn), serialize it to JSON, and apply it in a plain-Python service with no runtime dependencies. The same rule produces identical results in training, batch scoring, online inference, and monitoring.

Portability in one example

Fit where the data lives; apply where the data doesn't.

# --- training environment (full stack available) ---
from pickbuckets import EqualFrequencyBucket

bucket = EqualFrequencyBucket(n_bins=4, duplicates="drop").fit(training_values)
payload = bucket.to_json()          # store this string anywhere

# --- serving environment (standard library only) ---
from pickbuckets import Rule
from pickbuckets.runtime import apply_rule

rule = Rule.from_json(payload)
codes = apply_rule(rule, [0, 5, 10, None])   # no pandas / Polars / sklearn

apply_rule is pure Python (optionally NumPy) and is verified by a CI job with pandas, Polars, and scikit-learn uninstalled.

Install

python -m pip install pickbuckets                 # dependency-free core
python -m pip install "pickbuckets[pandas]"
python -m pip install "pickbuckets[polars]"       # Python 3.10+
python -m pip install "pickbuckets[sklearn]"
python -m pip install "pickbuckets[plot]"
python -m pip install "pickbuckets[all]"
python -m pip install -e ".[dev,all]"             # development

Bucketers

Every bucketer fits to a single unified Rule and shares the same fit / transform / summary / to_json shape. transform() uses only the saved rule — never the training data.

Bucketer	Kind	What it does	Needs
EqualWidthBucket	numeric	Equal-width bins from min/max	core
EqualFrequencyBucket	numeric	Quantile (equal-frequency) bins	core
CustomBoundaryBucket	numeric	Manual, validated edges (supports ±inf)	core
RareCategoryBucket	categorical	Fold rare/unseen categories to a fallback	core
AutoBucket	mixed	One rule per column, dtype-driven dispatch	core
WoEBucket	supervised	WoE/IV with monotonic + min-bin-size constraints	core
ChiMergeBucket	supervised	Chi-square adjacent-bin merging	core
DecisionTreeBucket	supervised	Edges from a shallow decision tree	[sklearn]
ExternalSplitBucket	numeric	Import external splits (e.g. OptBinning)	core
StreamingEqualFrequencyBucket	numeric, experimental	Online/approximate quantile bins for out-of-core data	core

Plotting helpers (pickbuckets.plotting, behind [plot]) return matplotlib Axes for bucket counts, target rate, and WoE.

from pickbuckets import AutoBucket, EqualWidthBucket

frame = {"age": [18, 25, 34, 52, 70], "country": ["FR", "FR", "US", "DE", "DE"]}

auto = AutoBucket(
    n_bins=3,
    min_frequency=2,
    overrides={"age": EqualWidthBucket(n_bins=3, labels="interval")},
).fit(frame)
print(auto.transform(frame))

Configurable, serializable policies cover missing values (separate / most_frequent / propagate / error), numeric boundaries (clip / underflow_overflow / error), and unknown categories (other / missing / keep / error), each raising a clear typed exception.

Documentation

• Usage guide — worked examples for every bucketer and policy
• API reference — symbols, the Rule model, runtime, exceptions
• Integrations — pandas, Polars, and scikit-learn adapters
• Rule gallery — realistic portable JSON rules across ML use cases
• Benchmarks — reproducible speed and memory suite
• Changelog

When to use it

Use pickbuckets when ML buckets must be stable, reviewable, and identical across training, batch scoring, online inference, and monitoring — tabular preprocessing, feature-store transforms, score banding, drift slices, and governed models such as credit scoring, fraud, churn, pricing, and insurance risk. See the rule gallery for examples.

Development

ruff check .
mypy src/pickbuckets
pytest
python -m build

Contributions follow a few principles — keep the core import dependency-free, put integrations behind extras, fit once and transform from saved rules. See CONTRIBUTING.md.