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 |
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. |
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.
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. |
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 |
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+) |
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.