API Reference
Identical parameter set on ZoneBoostRegressor and
ZoneBoostClassifier, except calibrate
(classifier-only) and loss/quantile (regressor-only).
Parameters
| Parameter | Default | Description |
|---|
n_rounds | 300 | Maximum number of boosting rounds |
learning_rate | 0.1 | Shrinkage applied to each round's correction |
row_subsample | 0.7 | Fraction of rows sampled per round |
col_subsample | 0.7 | Fraction of columns sampled per round |
max_zones | 7 | Zone cap for continuous columns only — see the note in Continuous vs. Categorical Zones |
min_zone_frac | 0.02 | Minimum row fraction required on each side of a zone split |
categorical_features | None | Column names/indices to treat as nominal categories |
validation_fraction | 0.2 | Held-out fraction used to pick the best round count |
n_iter_no_change | None | Early-stopping patience, in rounds |
max_interaction_order | 2 | Set to 3 to enable an adaptive search for 3-way interactions — see Adaptive Interaction Order |
max_triple_interactions | 5 | Cap on how many 3-way terms a single round may add (only relevant when max_interaction_order=3) |
triple_min_gain | 0.05 | Minimum residual-explained evidence, relative to a candidate's strongest constituent pair, required to keep a 3-way interaction |
cross_fit_folds | 5 | Number of folds used to compute each round's training signal honestly — see Cross-Fitted Cell Means. Falls back to no cross-fitting if a round's row count is smaller than 2 folds |
shrinkage_m | 10.0 | Empirical-Bayes shrinkage strength — see Empirical Bayes Shrinkage |
learn_shrinkage_m | False | Estimate the shrinkage strength separately for main effects and pairs each round instead of using shrinkage_m for both; opt-in — see Empirical Bayes Shrinkage |
stacking_alpha | 0.01 | Lasso regularization strength for combining a round's terms — see Lasso Stacking |
monotonic_constraints | None | {column: +1 or -1} — forces a continuous column's main effect (and every interaction it participates in) to be non-decreasing/non-increasing; opt-in — see Monotonic Constraints |
max_pair_interactions | None | Cap on how many pairwise interactions a round keeps, ranked by importance; opt-in — see Pair Screening |
convexity_constraints | None | {column: +1 convex, -1 concave} — forces a continuous column's main effect onto a convex/concave sequence; main effects only, opt-in — see Global Shape Constraints |
strict_shape_constraints | False | Restricts Lasso-stacking weights to non-negative for every term a monotonic_constraints/convexity_constraints entry applies to, turning the per-round-only guarantee into an ensemble-level one; opt-in — see Ensemble-Level Guarantees |
bounded_effects | None | {column: (lower, upper)} — clips a continuous column's main effect to this range, per boosting round (not cumulatively); main effects only, opt-in — see Global Shape Constraints |
forbidden_interactions | None | List of 2-column name/index pairs that must never be fit as pairwise (or 3-way) interactions; opt-in — see Global Shape Constraints |
track_reliability | False | Record per-term support counts and cross-fold variability each round, consumed by explain(X, include_reliability=True) and evidence_report(X); opt-in — see Explanation Reliability and Evidence Report |
group_col | None | Regressor only. Column name/index to treat as a hierarchical grouping key: guarantees a (feature, group_col) pairwise interaction every round for every feature; opt-in — see Hierarchical Zones |
mondrian_col | None | Regressor only. Column name/index to stratify predict_interval's conformal margin by (Mondrian conformal), instead of one global margin for every row; independent of group_col; opt-in — see Prediction Intervals |
mondrian_min_group_size | 20 | Regressor only. A mondrian_col group with fewer calibration rows than this falls back to the global margin; ignored unless mondrian_col is set |
calibrate | False | Classifier only. Isotonic-recalibrate predict_proba; opt-in — see Probability Calibration |
calibration_fraction | 0.0 | Fraction held out in a dedicated calibration split, separate from validation_fraction; opt-in — see Honest Data Splits |
refit_on_full_data | False | Refit the deployed model on fit+validation data once best_n_rounds_ is chosen; requires calibration_fraction > 0 — see Honest Data Splits |
adaptive_boundary_smoothing | False | Learn a per-column, per-round hard-vs-smooth zone-lookup blend instead of always fully smooth; opt-in — see Adaptive Boundary Continuity |
boundary_shrinkage_m | 10.0 | Empirical-Bayes shrinkage strength toward full smoothness for adaptive_boundary_smoothing — see Adaptive Boundary Continuity |
loss | "squared_error" | Regressor only. "quantile" targets a conditional quantile — see Quantile Regression; "poisson"/"gamma"/"tweedie" target a log-link mean for right-skewed, non-negative targets, with an offset on fit/predict for exposure adjustment — see Actuarial Losses |
quantile | 0.5 | Regressor only. Target quantile level when loss="quantile" (ignored otherwise) — see Quantile Regression |
tweedie_power | 1.5 | Regressor only. Tweedie variance power when loss="tweedie" (ignored otherwise) — see Actuarial Losses |
trim_fraction | 0.0 | Robustify each main effect's own per-zone statistic against outlier rows via a trimmed mean instead of the plain mean; main effects only, opt-in, incompatible with loss="quantile" — see Robust Cell Statistics |
spline_zones | None | Regressor only. Column names/indices whose main effect is fit as a continuous piecewise-linear (linear spline) regression instead of a flat mean per zone; main effects only, opt-in, incompatible with loss="quantile"/trim_fraction > 0 — see Spline Zones |
spline_shrinkage_m | 1.0 | Regressor only. Ridge penalty strength (in per-column-standardized units) for a spline main effect's own slope/bend coefficients, fit jointly; only used for columns in spline_zones — see Spline Zones |
random_state | 42 | Seed for the validation split and subsampling |
fit also accepts two per-row (not constructor) parameters:
sample_weight (regressor only — a per-row weight affecting only how the
model learns, no corresponding predict argument; incompatible with
loss="quantile"/trim_fraction > 0 — see
Sample Weighting) and
offset (regressor only, loss in ("poisson","gamma","tweedie")
— see Actuarial Losses).
ZoneBoostRegressor Fitted Attributes
After fit, ZoneBoostRegressor exposes (among others):
rounds_ | One entry per boosting round, each a plain dict with keys "zone_info", "main_effects", "interactions", "triples" (empty unless max_interaction_order=3), "intercept"/"weights" (the round's fitted Lasso intercept and one weight per term — fitted_residual = intercept + contributions @ weights, in the same order main_effects/interactions/triples are themselves iterated), and "diagnostics" (None unless track_reliability=True or learn_shrinkage_m=True; otherwise each term's own row/cell counts and cross-fold standard deviation — see Explanation Reliability — and/or "learned_shrinkage_m", {"main": ..., "pair": ...} — see Empirical Bayes Shrinkage). Nothing hidden in an opaque object. |
best_n_rounds_ | The round count actually used by predict. |
val_rmse_ / train_rmse_ | RMSE after each round for loss="squared_error" (the default); mean pinball loss at quantile for loss="quantile"; mean deviance (sklearn.metrics.mean_poisson_deviance/mean_gamma_deviance/mean_tweedie_deviance) for "poisson"/"gamma"/"tweedie" — whichever loss is actually being minimized. |
categorical_features_ | The resolved set of categorical columns (declared ∪ auto-detected). |
monotonic_constraints_ | The resolved {column: +1 or -1} dict actually in effect (categorical columns dropped). |
convexity_constraints_ | The resolved {column: +1 or -1} convexity dict actually in effect (same resolution as monotonic_constraints_). |
bounded_effects_ | The resolved {column: (lower, upper)} dict actually in effect (categorical columns dropped). |
forbidden_interactions_ | The resolved set of 2-element column-name frozensets actually excluded from interaction discovery. |
spline_zones_ | The resolved set of column names actually fit as a continuous piecewise-linear main effect. See Spline Zones. |
group_col_ | The resolved column name for group_col (None if not set). See Hierarchical Zones. |
conformal_scores_ | Sorted absolute residuals on the held-out validation split at best_n_rounds_ — the nonconformity scores predict_interval draws its margin from (None if validation_fraction=0). See Prediction Intervals. |
mondrian_col_ / conformal_scores_by_group_ | Resolved column name for mondrian_col (None if not set); {group_value: sorted_scores_array} for every group with at least mondrian_min_group_size calibration rows (None unless mondrian_col was set). See Prediction Intervals. |
effect_overrides_ | Every edit made via edit_effect, in application order ([] until the first edit). See Audited Human Editing. |
evidence_card Signature
model.evidence_card(X=None) — a method on a fitted
ZoneBoostRegressor, returning a compact, JSON-serializable dict. See
Model Evidence Cards
for the full return-value reference.
| Parameter | Default | Description |
|---|
X | None | Optional; only needed for dataset_fingerprint and each term's mean_abs_contribution — every other section is available with no arguments |
ZoneBoostClassifier Fitted Attributes
ZoneBoostClassifier exposes the same categorical_features_ and monotonic_constraints_, plus:
classes_ | Distinct class labels seen during fit. |
multiclass_ | Whether native multinomial boosting (3+ classes) was used. |
booster_ (binary) | An internal log-odds booster with its own rounds_, best_n_rounds_, and calibrator_ (the fitted isotonic calibrator, or None if calibrate=False) — same plain-data structure as the regressor's. |
softmax_booster_ (3+ classes) | The single joint multinomial booster — see Native Multinomial Boosting. Has its own rounds_ (one entry per round, each a {class_index: round_dict} mapping), best_n_rounds_, n_classes_, and calibrators_ (a {class_index: IsotonicRegression} dict, or None if calibrate=False). |
ConformalizedQuantileRegressor Parameters
| Parameter | Default | Description |
|---|
estimator | None | Unfit ZoneBoostRegressor template supplying every tuning knob other than loss/quantile/calibration_fraction/random_state; None uses a plain ZoneBoostRegressor() — see Conformalized Quantile Regression (CQR) |
alpha | 0.1 | Miscoverage rate — e.g. 0.1 targets 90% coverage. The two internal quantile levels are alpha / 2 and 1 - alpha / 2 |
calibration_fraction | 0.2 | Fraction of rows held out purely for CQR calibration — genuinely separate from either quantile model's own internal validation split |
random_state | 42 | Seed for the calibration split and (via the two cloned estimators) their own internal splits/subsampling |
ConformalizedQuantileRegressor fitted attributes:
lo_ / hi_ | The two fitted ZoneBoostRegressor(loss="quantile", ...) instances, at levels alpha / 2 and 1 - alpha / 2. |
cqr_scores_ | Sorted CQR nonconformity scores on the calibration split — the margin predict_interval draws from. |
BootstrapStability Parameters
| Parameter | Default | Description |
|---|
estimator | None | Unfit ZoneBoostRegressor/ZoneBoostClassifier template; None uses a plain ZoneBoostRegressor(). Cloned and refit once per bootstrap resample — only random_state is overridden per clone — see Bootstrap Stability |
n_bootstrap | 30 | Number of bootstrap refits — real cost (n_bootstrap full model fits), kept modest by default |
alpha | 0.1 | Default miscoverage rate for every interval method (each method also accepts its own alpha override) |
random_state | 42 | Seed for the bootstrap resampling; each resample's cloned estimator gets its own derived seed |
BootstrapStability fitted attribute:
bootstrap_models_ — the n_bootstrap fitted clones, in
resampling order.
ZoneForest Parameters
| Parameter | Default | Description |
|---|
base_estimator | None | Unfit template exposing fit/predict/explain (typically a ZoneBoostRegressor); None uses a plain ZoneBoostRegressor(). Cloned and refit once per estimator — only random_state is overridden per clone — see ZoneForest |
n_estimators | 100 | Number of bootstrap resamples / fitted clones |
max_samples | 1.0 | Bootstrap draw size as a fraction of the training set, rows drawn with replacement (1.0 is the classic same-size bootstrap). Must be in (0, 1] |
max_features | 1.0 | Fraction of columns drawn without replacement for each estimator's own fixed column subset, drawn once at fit time. Must be in (0, 1]; base_estimator.group_col/mondrian_col are force-included regardless of this draw |
n_jobs | None | Passed to joblib.Parallel — None is sequential, -1 uses every core |
random_state | 42 | Seed for every bootstrap/column draw and each clone's own derived seed |
ZoneForest fitted attributes:
estimators_ | The n_estimators fitted clones, in resampling order. |
estimators_samples_ | Each estimator's own bootstrap row indices (into the original training X), same order as estimators_. |
estimators_features_ | Each estimator's own column subset (as column names), same order as estimators_. |
ZoneBoostTimeSeries Parameters
| Parameter | Default | Description |
|---|
base_estimator | None | Unfit ZoneBoostRegressor template; None uses a plain ZoneBoostRegressor(). Cloned and refit once per period — only random_state is overridden per clone — see ZoneBoostTimeSeries |
time_col | None | Required — the column (name, or index if X isn't a DataFrame) giving each row's timestamp, coerced via pandas.to_datetime |
freq | "Y" | A pandas offset alias controlling period granularity ("Y"/"Q"/"M"/...), forwarded to .dt.to_period(freq) |
window | "expanding" | "expanding" or "rolling" — see ZoneBoostTimeSeries. Raises ValueError otherwise |
min_periods | 2 | Dual meaning by window: minimum periods pooled for the first "expanding" fit, or the fixed window size for "rolling". Must be >= 1; raises ValueError if fewer than min_periods distinct periods exist at all |
random_state | 42 | Seed for each period's own derived clone seed |
ZoneBoostTimeSeries fitted attributes:
time_col_ | Resolved column name for time_col. |
feature_names_in_ | Every column actually fit on — time_col_ excluded. |
periods_ | Every distinct period observed, sorted, including any too early to have their own model. |
models_ | {period: fitted_model}, one entry per period from periods_[min_periods - 1] onward. |
comparisons_ | {(period_k, period_k_plus_1): compare_models(...)} for every consecutive fitted pair. |
drift_alerts_ | {(period_k, period_k_plus_1): flag_drift(...)}, only for a pair where the newer period's model has a calibrated conformal margin. |
ZoneBoostTimeSeries also exposes predict(X)/explain(X)/feature_importance(X) (each delegating to the most recent period's own fitted model) and stability_report() (a per-feature drift summary aggregated across every consecutive pair) — see ZoneBoostTimeSeries.
ZoneBoostSurvival Parameters
| Parameter | Default | Description |
|---|
estimator | None | Unfit ZoneBoostRegressor template supplying every tuning knob other than loss/random_state; None uses a plain ZoneBoostRegressor(). loss is always forced to "poisson" — see Zone-Native Survival Analysis |
n_intervals | 10 | Number of piecewise-constant hazard intervals, when breakpoints isn't given — cut points are quantiles of observed event times |
breakpoints | None | Explicit interval boundaries (must start at 0, strictly increasing); overrides n_intervals entirely when given |
random_state | 42 | Passed through to the underlying ZoneBoostRegressor |
ZoneBoostSurvival fitted attributes:
regressor_ | The fitted Poisson-loss ZoneBoostRegressor on the expanded person-period table — call explain()/feature_importance() directly on it for a transparent hazard decomposition. |
breakpoints_ | Interval boundaries actually used, ending in inf. |
max_duration_ | Largest observed duration at fit time — the default upper query time for predict_survival_function/predict_cumulative_hazard. |
ZoneProfileEncoder Parameters
| Parameter | Default | Description |
|---|
columns | None | Columns to encode; None encodes every column of X |
categorical_features | None | Columns to treat as categorical, in addition to auto-detected ones — same convention as ZoneBoostRegressor |
max_zones | 7 | Zone cap for continuous columns — see Parameters above |
min_zone_frac | 0.02 | Minimum row fraction required on each side of a zone split, for continuous columns |
min_zone_abs | 20 | Minimum absolute row count required on each side of a zone split, for continuous columns |
shrinkage | True | Empirical-Bayes-shrink each zone's raw mean toward the column's own grand mean; False emits the raw, unshrunk mean — see Zone Profile Encoder |
split_criterion | "variance" | "correlation" prefers a cut where a column's local relationship with y reverses sign over one that merely reduces variance — see Correlation-Aware Zone Boundaries |
random_state | 42 | Accepted for interface consistency; fitting is fully deterministic given X/y, so this is currently unused |
ZoneProfileEncoder fitted attributes:
zone_stats_ | Per-column zone boundaries/category map and per-zone counts/means/variances — every value plain inspectable data. |
columns_ | Columns actually encoded, in output order. |
DepthTransformer Parameters
| Parameter | Default | Description |
|---|
columns | None | Column group to compute joint depth over; None uses every numeric column of X (categorical columns auto-excluded; declaring one explicitly raises ValueError) |
group_name | None | Name used in the two emitted output columns; None joins the encoded column names with "_" |
ridge | 1e-6 | Added to the covariance matrix's diagonal before inverting, so a singular/ill-conditioned covariance degrades gracefully — see Depth Transformer |
random_state | 42 | Accepted for interface consistency; fitting is fully deterministic given X, so this is currently unused |
DepthTransformer fitted attributes:
columns_ | Columns actually encoded. |
mean_ | Fitted mean vector. |
covariance_ | Fitted, ridge-regularized covariance matrix. |
DepthCrowd Parameters
| Parameter | Default | Description |
|---|
columns | None | Input columns to treat as crowd experts; None uses every numeric column of X (categorical columns auto-excluded; declaring one explicitly raises ValueError). At least 2 columns are required |
rank_normalize | True | Convert each column to its percentile within that column's own fitted training distribution before aggregating; False uses raw input values directly — see Depth Crowd |
vote_threshold | 0.05 | An expert "votes" atypical when its (rank-normalized, if enabled) score is <= vote_threshold; calibrated for rank_normalize=True, needs raising substantially otherwise |
group_name | "crowd" | Prefix on every emitted output column |
DepthCrowd fitted attributes:
columns_ | Columns actually treated as experts, in fitted order. |
CategoricalDepthTransformer Parameters
| Parameter | Default | Description |
|---|
columns | None | The categorical/binary zone; None uses every auto-detected categorical column of X. Explicitly declaring a column is always accepted regardless of dtype (including bool/int-coded binary). At least 1 column is required |
group_name | None | Name used in the two emitted output columns; None joins the encoded column names with "_" |
random_state | 42 | Accepted for interface consistency; fitting is fully deterministic given X, so this is currently unused |
CategoricalDepthTransformer fitted attributes:
columns_ | Columns actually encoded, in fitted order. |
ConditionalZoneGrid Parameters
| Parameter | Default | Description |
|---|
columns | — | Exactly two continuous columns to grid jointly; required. Must not be categorical |
segment_columns | — | One or more columns whose distinct value combination defines a segment; required. Grouped by exact value, not zone-binned |
max_zones | 7 | Zone cap per column, per grid (segment or global) |
min_zone_frac | 0.02 | Minimum row fraction required on each side of a zone split |
min_zone_abs | 20 | Minimum absolute row count required on each side of a zone split |
min_segment_size | 50 | A segment with fewer training rows than this falls back to the global grid instead of fitting its own — see Conditional Zone Grid |
shrinkage | True | Empirical-Bayes-shrink each grid's own cell means toward that grid's own grand mean; False emits raw, unshrunk cell means |
split_criterion | "variance" | "correlation" prefers a cut where a column's local relationship with y reverses sign over one that merely reduces variance — see Correlation-Aware Zone Boundaries |
random_state | 42 | Accepted for interface consistency; fitting is fully deterministic given X/y, so this is currently unused |
ConditionalZoneGrid fitted attributes:
segment_grids_ | {segment_key: grid} for every segment that met min_segment_size. |
global_grid_ | The pooled fallback grid, fit on every row regardless of segment. |
ZoneFeatureSpace Parameters
| Parameter | Default | Description |
|---|
zone_profiles | True | True fits one ZoneProfileEncoder over every column of X; a list encodes only those columns; False disables it. Supervised — requires y at fit whenever enabled — see ZoneFeatureSpace |
categorical_features | None | Forwarded to the internal ZoneProfileEncoder only |
depth_scores | False | True fits one DepthTransformer over every numeric column; a list declares explicit groups (a plain list of columns = auto-named, a (name, columns) tuple = named); False disables it. Unsupervised |
categorical_depth_scores | False | Same shape as depth_scores, but CategoricalDepthTransformer over categorical/binary columns. Unsupervised |
conditional_grids | None | List of (col_a, col_b, segment_columns) triples, one ConditionalZoneGrid per triple — explicit only, never auto-discovered (see suggest_interactions). Supervised — requires y at fit whenever non-empty |
max_zones | 7 | Forwarded to every internal ZoneProfileEncoder/ConditionalZoneGrid |
min_zone_frac | 0.02 | Forwarded to every internal ZoneProfileEncoder/ConditionalZoneGrid |
min_zone_abs | 20 | Forwarded to every internal ZoneProfileEncoder/ConditionalZoneGrid |
min_segment_size | 50 | Forwarded to every internal ConditionalZoneGrid |
shrinkage | True | Forwarded to every internal ZoneProfileEncoder/ConditionalZoneGrid |
split_criterion | "variance" | Forwarded to every internal ZoneProfileEncoder/ConditionalZoneGrid — see Correlation-Aware Zone Boundaries |
depth_ridge | 1e-6 | Forwarded to every internal DepthTransformer as its own ridge parameter |
random_state | 42 | Forwarded to every internal transformer |
ZoneFeatureSpace fitted attribute: transformers_ (the
fitted sub-transformer instances, in output order). Methods beyond
fit/transform: explain(values) and
suggest_interactions(X, y, columns=None, top_k=10) — see
ZoneFeatureSpace.
LaplaceHistoryTransformer Parameters
| Parameter | Default | Description |
|---|
entity_col | — | Column in event_history/X identifying an event's owner; required |
time_col | — | Column in event_history giving each event's timestamp; required. Datetime-like columns convert to days since the Unix epoch; numeric columns are used as-is and must already share half_lives' unit |
half_lives | — | Positive half-lives, in the same unit as time_col; required. One amount-decay column per (value_column, half_life) pair, plus one event-count-decay column per half-life |
value_columns | None | Numeric columns in event_history to amount-decay; None/[] still emits the decay-weighted event count, a pure recency/frequency signal |
group_name | None | Prefix on every emitted output column, disambiguating multiple instances (e.g. one per event log) used together; None uses time_col |
random_state | 42 | Accepted for interface consistency; fitting/transforming are fully deterministic given their inputs, so this is currently unused |
fit(X, y=None, event_history=None) — event_history is
required. transform(X, asof_col=None, cutoff_date=None) — exactly one of
asof_col/cutoff_date is required — see Laplace History Transformer. No
fitted attributes beyond entity_col_/time_col_/value_columns_
— the per-entity event index is internal.
LLMZoneNamer Parameters
| Parameter | Default | Description |
|---|
client | None | Anything exposing .messages.create(...) with the Anthropic Messages API's response shape; None lazily constructs a bare anthropic.Anthropic() on first use — see LLM Zone Naming |
model | "claude-opus-4-8" | Model ID passed to messages.create |
max_tokens | 1024 | Passed to messages.create; scale up for large batches of zones |
No fitted attributes — name_zones(zone_summaries, context=None) is a
plain method call, not fit/transform.
compare_models Signature
compare_models(model_old, model_new, X_eval, y_eval=None) — a
top-level function, not a method, comparing two already-fitted
ZoneBoostRegressor instances on a shared evaluation dataset. See
Time-Based Drift
Comparison for the full return-value reference.
| Parameter | Default | Description |
|---|
model_old / model_new | — | Both already-fitted ZoneBoostRegressor instances (classifier not yet supported) |
X_eval | — | Shared evaluation data both models can score — every column either model needs, even if only one uses it |
y_eval | None | If given, adds performance_change (rmse_old/rmse_new) to the result |
flag_drift Signature
flag_drift(model_old, model_new, X_eval, y_eval=None, alpha=0.1) — a
top-level function that wraps compare_models with an active alert. See
Drift Threshold/Alert
Monitor for the full return-value reference.
| Parameter | Default | Description |
|---|
model_old / model_new | — | Both already-fitted ZoneBoostRegressor instances; model_new must have a non-None conformal_scores_ |
X_eval | — | Passed straight through to compare_models |
y_eval | None | Passed straight through to compare_models |
alpha | 0.1 | Miscoverage rate for the conformal margin — same parameter and meaning as predict_interval |
compile_to_sql Signature
compile_to_sql(model, table_name="input_table", score_alias="score",
offset_expr="0", include_evidence_card=False, dialect="sqlite") — a
top-level function, not a method, compiling an already-fitted
ZoneBoostRegressor to a single SQL SELECT statement. See
Compile to SQL Scorecard for
the full design, scope, and measured accuracy.
| Parameter | Default | Description |
|---|
model | — | An already-fitted ZoneBoostRegressor (classifier not supported) |
table_name | "input_table" | Source table name the generated SELECT reads from — must have one column per predictor, matching name and type |
score_alias | "score" | Output column alias for the computed prediction |
offset_expr | "0" | Raw SQL expression for the per-row offset term (only meaningful for loss in ("poisson","gamma","tweedie")) — e.g. "LN(exposure)"; offset is never a fitted attribute so this can't be inferred |
include_evidence_card | False | Prepend model.evidence_card()'s JSON as a leading SQL comment block |
dialect | "sqlite" | The only value currently accepted — clipping uses SQLite's scalar MIN/MAX idiom (also valid in DuckDB, MySQL 8+) |
zone_boxplot Signature
zoneboost.eda.zone_boxplot(X, y, column, n_zones=7, min_zone_frac=0.02,
min_zone_abs=20, split_criterion="variance", valid_range=None, plot=True,
ax=None) — a top-level function in the separate zoneboost.eda
subpackage (pip install zoneboost[eda]), not a method. See
zoneboost.eda (Optional) for the full
design.
| Parameter | Default | Description |
|---|
X | — | DataFrame or array-like of shape (n_samples, n_features) |
y | — | The outcome whose per-zone distribution is being compared |
column | — | The column (name, or index if X isn't a DataFrame) to zone |
n_zones | 7 | Forwarded as max_zones to adaptive_zone_boundaries; ignored for a categorical column |
min_zone_frac | 0.02 | Forwarded to adaptive_zone_boundaries; ignored for a categorical column |
min_zone_abs | 20 | Forwarded to adaptive_zone_boundaries; ignored for a categorical column |
split_criterion | "variance" | Forwarded to adaptive_zone_boundaries — see Correlation-Aware Zone Boundaries; ignored for a categorical column |
valid_range | None | Caller-declared (lower, upper) domain bound on column's own raw values; adds pct_business_invalid to the result when given. Raises ValueError for a categorical column |
plot | True | If True, also draws a boxplot via matplotlib (only import reached when True) and returns (stats, ax); if False, returns only stats |
ax | None | Draw onto this existing matplotlib.axes.Axes instead of creating a new figure; ignored if plot=False |
Returns stats (a DataFrame indexed by zone label, columns
count/mean/median/q1/q3/
iqr/outlier_count/outlier_frac, plus
pct_business_invalid when valid_range is given), or the tuple
(stats, ax) when plot=True.
drift_dashboard Signature
zoneboost.eda.drift_dashboard(model_old, model_new, X_eval, y_eval=None,
plot=True, top_n=15) — a top-level function in the separate
zoneboost.eda subpackage, wrapping compare_models with a
rendering layer. See zoneboost.eda
(Optional) for the full design.
| Parameter | Default | Description |
|---|
model_old / model_new | — | Both already-fitted ZoneBoostRegressor instances, forwarded as-is to compare_models |
X_eval | — | Forwarded to compare_models |
y_eval | None | Forwarded to compare_models; if given, the performance change is annotated on the figure |
plot | True | If True, also renders the multi-panel figure via matplotlib and returns (data, fig); if False, returns exactly compare_models's own dict |
top_n | 15 | Number of terms shown in the feature-importance-change panel, ranked by |change|; ignored if plot=False |
Returns data (exactly compare_models's own dict), or the
tuple (data, fig) when plot=True.
prediction_waterfall Signature
zoneboost.eda.prediction_waterfall(model, X, index=0, max_terms=None,
purify=False, plot=True, ax=None) — a top-level function in the separate
zoneboost.eda subpackage, not a method. See
zoneboost.eda (Optional) for the full
design.
| Parameter | Default | Description |
|---|
model | — | Already-fitted ZoneBoostRegressor or binary ZoneBoostClassifier. Raises ValueError for a multiclass classifier |
X | — | DataFrame or array-like of shape (n_samples, n_features); may hold more than one row — only row index is explained |
index | 0 | Positional row of X to explain |
max_terms | None | Cap on individual terms shown; None shows every term. When set, the smallest-magnitude excess terms fold into a single "other" row (summed) rather than being dropped — the waterfall still sums exactly to the prediction either way |
purify | False | Forwarded to model.explain(X, purify=purify) when the model's own explain accepts it (regressor only) — see Functional-ANOVA Purification |
plot | True | If True, also draws the waterfall via matplotlib and returns (table, ax); if False, returns only table |
ax | None | Draw onto this existing matplotlib.axes.Axes instead of creating a new figure; ignored if plot=False |
Returns table (one row per bar in waterfall order — "baseline"
first, every term sorted by |contribution| descending, an optional
"other" row, then "total" — columns contribution,
cumulative_start, cumulative_end), or the tuple
(table, ax) when plot=True.
signed_contribution_profile Signature
zoneboost.eda.signed_contribution_profile(model, X, feature, n_zones=7,
min_zone_frac=0.02, min_zone_abs=20, split_criterion="variance", purify=False,
plot=True, ax=None) — a top-level function in the separate
zoneboost.eda subpackage. See
zoneboost.eda (Optional) for the full
design.
| Parameter | Default | Description |
|---|
model | — | Already-fitted ZoneBoostRegressor or binary ZoneBoostClassifier. Raises ValueError for a multiclass classifier |
X | — | DataFrame or array-like of shape (n_samples, n_features) |
feature | — | The column (name, or index if X isn't a DataFrame) to profile. Must have appeared as its own main-effect term in explain(X) — raises ValueError otherwise |
n_zones | 7 | Forwarded as max_zones to adaptive_zone_boundaries; ignored for a categorical column |
min_zone_frac | 0.02 | Forwarded to adaptive_zone_boundaries; ignored for a categorical column |
min_zone_abs | 20 | Forwarded to adaptive_zone_boundaries; ignored for a categorical column |
split_criterion | "variance" | Forwarded to adaptive_zone_boundaries — see Correlation-Aware Zone Boundaries; ignored for a categorical column |
purify | False | Forwarded to model.explain(X, purify=purify) when the model's own explain accepts it (regressor only), before extracting feature's own contribution column |
plot | True | If True, also draws a bar chart via matplotlib and returns (table, ax); if False, returns only table |
ax | None | Draw onto this existing matplotlib.axes.Axes instead of creating a new figure; ignored if plot=False |
Returns table (indexed by zone label in natural — not magnitude —
order, columns count and mean_contribution), or the tuple
(table, ax) when plot=True.
explain / feature_importance purify Parameters
purify/purify_n_bins are parameters of the existing
explain/feature_importance methods, not a new function.
See Functional-ANOVA
Purification for the full explanation.
| Parameter | Default | Description |
|---|
purify | False | Moves any signal in a pairwise-interaction column that's really just a function of one constituent column alone into that column's own main effect; row sums (and predict) are unaffected — opt-in, real extra compute |
purify_n_bins | 10 | Quantile bins used to marginalize each pair's continuous constituent columns when purify=True (categorical columns always use exact categories); ignored otherwise |
Scope & Compatibility
This estimator targets practical scikit-learn compatibility —
get_params/set_params/clone, use inside a
Pipeline, and scoring via cross_val_score — rather than full
compliance with sklearn.utils.estimator_checks.check_estimator, which
checks many edge cases (e.g. sparse-matrix input) not exercised here.
