API reference

Both estimators are scikit-learn compatible, with fit, then predict / predict_proba methods. Parameters are documented below; for guidance on which ones to tweak, see Parameters.

ChimeraBoostRegressor

ChimeraBoostRegressor(
    n_estimators=2000,
    learning_rate=None,
    depth=None,
    l2_leaf_reg=1.0,
    max_bins=128,
    subsample=1.0,
    colsample=None,
    cat_smoothing=1.0,
    cat_n_permutations=4,
    early_stopping_rounds=None,
    loss="RMSE",
    alpha=0.5,
    min_child_weight=1.0,
    thread_count=None,
    random_state=None,
    verbose=False,
    ordered_boosting=False,
    cat_combinations=None,
    leaf_estimation_iterations=1,
    linear_leaves=None,
    linear_lambda=1.0,
    cross_features=None,
    selection_rounds=100,
    early_stopping=True,
    validation_fraction=0.2,
    n_ensembles=None,
    ensemble_n_jobs=-1,
    max_samples=0.8,
    cat_features=None,
    quantize_gradients=True,
)

Bases: RegressorMixin, BaseEstimator

Gradient boosted oblivious trees for regression.

A scikit-learn compatible regressor supporting squared-error, absolute-error, and quantile losses, native categorical features, sample weights, bagging, and exact SHAP attributions.

Parameters:

Name	Type	Description	Default
n_estimators	int	Maximum number of boosting rounds (trees). With early_stopping on, this is an upper bound and the best round is selected automatically.	2000
learning_rate	float or None	Shrinkage applied to each tree. None resolves to 0.1 when early stopping is active.	None
depth	int or None	Depth of each oblivious tree; a depth-d tree makes d splits. None resolves to 6 for squared-error/absolute-error losses, and to 4 for loss="Quantile" -- estimating an extreme conditional quantile from a leaf needs more samples per leaf than estimating a mean, so deep trees overfit the tails and the predicted quantiles collapse toward the median. Raise to 8-10 for large, interaction-heavy problems; set it explicitly to override the per-loss default.	None
l2_leaf_reg	float	L2 regularization on leaf values.	1.0
max_bins	int	Histogram bins per numeric feature.	128
subsample	float	Row subsampling fraction per tree. Below 1.0, rows are drawn by Minimum Variance Sampling (gradient-weighted, unbiased) rather than uniformly.	1.0
colsample	float or None	Fraction of features eligible for each tree. None resolves to 1.0 for a single model and to the bagged-member default 0.85 inside n_ensembles > 1 fits (see member_params_).	None
cat_smoothing	float	Prior strength for ordered target statistics; higher shrinks rare categories harder toward the global mean. Must be > 0 -- it is the Bayesian pseudocount in the encoder denominator, so 0 is undefined.	1.0
cat_n_permutations	int	Number of random orderings averaged by the ordered target encoder.	4
early_stopping_rounds	int or None	Rounds without validation improvement before stopping. None becomes 50 when early stopping is active.	None
loss	(RMSE, MAE, Quantile)	Training objective. Set the level with alpha for "Quantile".	"RMSE"
alpha	float	Quantile level for loss="Quantile" (e.g. 0.9 for the 90th percentile).	0.5
min_child_weight	float	Minimum total hessian required on each side of a split.	1.0
thread_count	int or None	numba thread count. None or -1 uses all detected cores.	None
random_state	int or None	Seed for reproducibility (deterministic for a fixed thread_count).	None
verbose	bool	Print per-round train and validation metrics.	False
ordered_boosting	bool	Use the leave-one-out leaf training step instead of plain Newton updates.	False
cat_combinations	bool or None	Add all pairwise categorical-by-categorical features. None enables them automatically only when the data is entirely categorical (where the interaction columns help without crowding out numeric splits); set True/False to force it on/off.	None
leaf_estimation_iterations	int	Newton refinement steps per leaf.	1
linear_leaves	bool or None	Fit a ridge linear model per leaf over the numeric split features instead of a constant value, adding local slope where step leaves underfit. Leaves with too few rows fall back to a constant. Not available with MAE or quantile loss. None (the default) = validation-selected: both variants are fit and the one with the lower validation loss is kept (~2x fit time; requires an early-stopping split or eval_set, RMSE loss, and >= 1000 rows — otherwise constant leaves are used). Set True/False to force one variant and skip the double fit.	None
linear_lambda	float	Ridge penalty on per-leaf linear slopes; larger is closer to a constant.	1.0
quantize_gradients	bool	Run the split search on quantized gradients/hessians packed into integer histograms (LightGBM-style quantized training, ~15-bit): ~20-25% faster fits at benchmark-flat accuracy. Leaf values always use the exact float gradients; the rounding noise touches only split selection and is deterministic for a fixed random_state. False restores exact float64 histograms.	True
cross_features	bool or None	Numeric interaction columns. None (the default) and True refit with difference and product columns for the pairs of the top numeric features of the base fit and keep whichever model reaches the lower validation loss (cross_features_selected_ records the outcome, cross_pairs_ the columns kept); applies to RMSE loss with >= 2000 rows and >= 2 numeric features, and is skipped otherwise. False turns it off. Oblivious trees can only staircase a numeric interaction such as x_i < x_j; a cross column makes it a single split. Costs up to ~2x fit time when the refit runs.	None
selection_rounds	int or None	Round budget for the internal selection fits. The constant/linear-leaf variants and the pre-cross base fit run at most this many rounds (auditions, judged on their best validation loss within the budget); the winning candidate continues to full early stopping, and the audition winner is refit in full only when the cross-augmented model loses or cross features do not apply. An audition that early-stops before the budget is the full fit already (no extra cost). None runs every variant to full early stopping instead (the pre-0.15 behavior, ~1.5x slower fits); an audition can occasionally pick a different variant than full fits would.	100
early_stopping	bool	Hold out a validation split and stop when its score stops improving.	True
validation_fraction	float	Validation fraction used when early_stopping is on and no eval_set is passed to fit.	0.2
n_ensembles	int or None	Number of bagged members. None or 1 trains a single model; >= 2 averages independent members, each fit on its own random row sample (max_samples, without replacement by default).	None
ensemble_n_jobs	int	Worker processes fitting ensemble members concurrently, each on an equal share of the thread budget (same total cores as a single fit; models are identical either way, wall-clock 1.2-2x faster). -1 sizes the pool from the budget, capped at n_ensembles; 1 fits members sequentially, each with the full budget.	-1
max_samples	float	Fraction of rows each ensemble member trains on, drawn WITHOUT replacement ("subagging"). The default 0.8 beats the classic bootstrap on strength and fit time (a full-size bootstrap holds only ~0.63n unique rows at n rows of compute). 1.0 restores the classic full-size with-replacement bootstrap. Unsampled rows are each member's early-stopping eval set either way.	0.8
cat_features	list of int or str, or None	Default categorical columns, given as integer positions and/or column names (names resolved against the DataFrame at fit). Used when fit is called without its own cat_features (the fit argument overrides). Provided as a constructor argument so GridSearchCV/Pipeline can carry it.	None

Attributes:

Name	Type	Description
feature_importances_	ndarray of shape (n_features,)	Split-gain importance per input feature, normalized to sum to 1.
best_iteration_	int	Number of trees retained after early stopping.
expected_value_	float	SHAP baseline (mean prediction over the background); set after calling shap_values.
estimators_	list or None	Fitted members when n_ensembles > 1, otherwise None.
member_params_	dict	Bagged-mode member defaults that were auto-applied (params the user left on auto resolve to tuned member values inside a bag; explicit values always win). Set only when n_ensembles > 1.
quantile_offset_	float	Split-conformal correction added to every prediction when loss="Quantile" and a validation split was available: the conformal order statistic of the validation residuals, restoring the nominal coverage that learning-rate shrinkage of the per-leaf quantile steps otherwise starves. 0.0 for other losses or without a validation set.
linear_leaves_selected_	bool or None	With linear_leaves=None, whether the linear-leaf variant won the validation selection. None when no selection took place.

Source code in chimeraboost/sklearn_api.py

def __init__(self, n_estimators=2000, learning_rate=None, depth=None,
             l2_leaf_reg=1.0, max_bins=128, subsample=1.0, colsample=None,
             cat_smoothing=1.0, cat_n_permutations=4,
             early_stopping_rounds=None,
             loss="RMSE", alpha=0.5, min_child_weight=1.0, thread_count=None,
             random_state=None, verbose=False, ordered_boosting=False,
             cat_combinations=None, leaf_estimation_iterations=1,
             linear_leaves=None, linear_lambda=1.0, cross_features=None,
             selection_rounds=100,
             early_stopping=True, validation_fraction=0.2,
             n_ensembles=None, ensemble_n_jobs=-1, max_samples=0.8,
             cat_features=None, quantize_gradients=True):
    self.n_estimators = n_estimators
    self.learning_rate = learning_rate
    self.depth = depth
    self.l2_leaf_reg = l2_leaf_reg
    self.max_bins = max_bins
    self.subsample = subsample
    self.colsample = colsample
    self.cat_smoothing = cat_smoothing
    self.cat_n_permutations = cat_n_permutations
    self.early_stopping_rounds = early_stopping_rounds
    self.cat_features = cat_features
    self.loss = loss
    self.alpha = alpha
    self.min_child_weight = min_child_weight
    self.thread_count = thread_count
    self.random_state = random_state
    self.verbose = verbose
    self.ordered_boosting = ordered_boosting
    self.cat_combinations = cat_combinations
    self.leaf_estimation_iterations = leaf_estimation_iterations
    self.linear_leaves = linear_leaves
    self.linear_lambda = linear_lambda
    self.cross_features = cross_features
    self.selection_rounds = selection_rounds
    self.early_stopping = early_stopping
    self.validation_fraction = validation_fraction
    self.n_ensembles = n_ensembles
    self.ensemble_n_jobs = ensemble_n_jobs
    self.max_samples = max_samples
    self.quantize_gradients = quantize_gradients

validation_history_ property

validation_history_

Per-round validation loss recorded during fit (RMSE-space loss for regression), as a list whose length is the number of rounds run. Empty when no eval_set / early-stopping split was available; for a bagged model (n_ensembles > 1) a list of the members' histories.

fit

fit(
    X,
    y,
    cat_features=None,
    eval_set=None,
    groups=None,
    sample_weight=None,
    callbacks=None,
)

Fit the model.

Parameters:

Name	Type	Description	Default
X	array - like	Training data.	required
y	array - like	Training data.	required
cat_features	list of int or str, or None	Columns to treat as categoricals, given as integer positions and/or column names (names resolved against the DataFrame). Falls back to the cat_features constructor argument when not given here; passing it here overrides the constructor value. (The constructor form lets GridSearchCV/Pipeline carry it, which a fit-only kwarg can't.)	None
eval_set	(X_val, y_val) tuple or None	Explicit validation set. When provided, automatic splitting is skipped regardless of the early_stopping setting.	None
groups	array-like of shape (n_samples,) or None	Group labels for the samples (e.g. df['subject_id']). When supplied and early_stopping triggers an automatic split, groups are kept intact across the train/validation boundary using GroupShuffleSplit.	None
sample_weight	array-like of shape (n_samples,) or None	Per-sample weights. Normalized to mean 1 internally. Applied throughout: the gradient/leaf fit, the categorical target encoder, the quantile bin borders, and the early-stopping metric on an automatically split (or bagged out-of-bag) validation set, so a zero-weight row never influences the model. An explicitly passed eval_set carries no weights and is scored unweighted.	None
callbacks	callable or list of callable, or None	Per-round fit hooks cb(iteration, train_loss, val_loss, model); a callback returning True requests an early stop. Used for live validation-curve capture and instrumentation. Not supported with n_ensembles > 1 (members fit in parallel worker processes).	None

Source code in chimeraboost/sklearn_api.py

def fit(self, X, y, cat_features=None, eval_set=None, groups=None,
        sample_weight=None, callbacks=None):
    """Fit the model.

    Parameters
    ----------
    X, y : array-like
        Training data.
    cat_features : list of int or str, or None
        Columns to treat as categoricals, given as integer positions and/or
        column names (names resolved against the DataFrame). Falls back to the
        ``cat_features`` constructor argument when not given here; passing it
        here overrides the constructor value. (The constructor form lets
        ``GridSearchCV``/``Pipeline`` carry it, which a fit-only kwarg can't.)
    eval_set : (X_val, y_val) tuple or None
        Explicit validation set.  When provided, automatic splitting is
        skipped regardless of the *early_stopping* setting.
    groups : array-like of shape (n_samples,) or None
        Group labels for the samples (e.g. ``df['subject_id']``).  When
        supplied and *early_stopping* triggers an automatic split, groups
        are kept intact across the train/validation boundary using
        ``GroupShuffleSplit``.
    sample_weight : array-like of shape (n_samples,) or None
        Per-sample weights.  Normalized to mean 1 internally.  Applied
        throughout: the gradient/leaf fit, the categorical target encoder,
        the quantile bin borders, and the early-stopping metric on an
        automatically split (or bagged out-of-bag) validation set, so a
        zero-weight row never influences the model.  An explicitly passed
        ``eval_set`` carries no weights and is scored unweighted.
    callbacks : callable or list of callable, or None
        Per-round fit hooks ``cb(iteration, train_loss, val_loss, model)``;
        a callback returning True requests an early stop. Used for live
        validation-curve capture and instrumentation. Not supported with
        ``n_ensembles > 1`` (members fit in parallel worker processes).
    """
    cat_features = _resolve_cat_features(self, cat_features)
    cat_features = _resolve_cat_feature_names(cat_features, X)
    _validate_hyperparams(self)
    y = _validate_fit_input(self, X, y, cat_features, sample_weight,
                            classification=False)
    if eval_set is not None:
        _check_eval_set(eval_set, self.n_features_in_)
    if self.n_ensembles and self.n_ensembles > 1:
        if callbacks is not None:
            raise ValueError(
                "callbacks are not supported with n_ensembles > 1.")
        self.estimators_ = _fit_bagged(self, X, y, cat_features, eval_set,
                                       groups, sample_weight)
        return self
    self.estimators_ = None
    return self._fit_single(X, y, cat_features, eval_set, groups,
                            sample_weight, callbacks)

staged_predict

staged_predict(X)

Yield the prediction after each successive tree (the conformal quantile offset, a post-fit constant, is included in every stage so the final stage equals predict).

Source code in chimeraboost/sklearn_api.py

def staged_predict(self, X):
    """Yield the prediction after each successive tree (the conformal
    quantile offset, a post-fit constant, is included in every stage so the
    final stage equals ``predict``)."""
    _check_predict_input(self, X)
    if self.estimators_ is not None:
        raise NotImplementedError("staged_predict is not defined for a "
                                  "bagged ensemble (n_ensembles > 1).")
    for staged in self.model_.staged_predict_raw(X):
        yield staged + self.quantile_offset_

shap_values

shap_values(X, X_background=None)

Exact interventional TreeSHAP contributions to the predicted target.

Returns an array of shape (n_samples, n_features) whose rows sum to predict(X) - expected_value_, where expected_value_ (set as an attribute by this call) is the mean prediction over the background. Each entry is a feature's signed additive contribution to the prediction; linear-leaf slopes are included exactly. Averaged across the bag when n_ensembles > 1 (the bag prediction is the members' mean, so the averaged attribution stays exact). X_background overrides the reference distribution (default: a sample of the training data).

Source code in chimeraboost/sklearn_api.py

def shap_values(self, X, X_background=None):
    """Exact interventional TreeSHAP contributions to the predicted target.

    Returns an array of shape ``(n_samples, n_features)`` whose rows sum to
    ``predict(X) - expected_value_``, where ``expected_value_`` (set as an
    attribute by this call) is the mean prediction over the background. Each
    entry is a feature's signed additive contribution to the prediction;
    linear-leaf slopes are included exactly. Averaged across the bag when
    ``n_ensembles > 1`` (the bag prediction is the members' mean, so the
    averaged attribution stays exact). ``X_background`` overrides the
    reference distribution (default: a sample of the training data)."""
    _check_predict_input(self, X)
    if self.estimators_ is not None:
        out = [m.model_.shap_values(X, background=X_background)
               for m in self.estimators_]
        # Fold each member's conformal quantile offset into the baseline so
        # rows still sum to predict(X) - expected_value_.
        self.expected_value_ = float(np.mean(
            [b + m.quantile_offset_ for m, (_, b) in zip(self.estimators_, out)]))
        return np.mean([p for p, _ in out], axis=0)
    phi, base = self.model_.shap_values(X, background=X_background)
    # The conformal quantile offset is a constant shift; it belongs to the
    # baseline, keeping rows summing to predict(X) - expected_value_.
    self.expected_value_ = base + self.quantile_offset_
    return phi

ChimeraBoostClassifier

ChimeraBoostClassifier(
    n_estimators=2000,
    learning_rate=None,
    depth=6,
    l2_leaf_reg=1.0,
    max_bins=128,
    subsample=1.0,
    colsample=None,
    cat_smoothing=1.0,
    cat_n_permutations=4,
    early_stopping_rounds=None,
    min_child_weight=None,
    thread_count=None,
    random_state=None,
    verbose=False,
    ordered_boosting=False,
    cat_combinations=None,
    leaf_estimation_iterations=None,
    linear_leaves=None,
    linear_lambda=1.0,
    cross_features=None,
    selection_rounds=100,
    early_stopping=True,
    validation_fraction=0.2,
    n_ensembles=None,
    ensemble_n_jobs=-1,
    max_samples=0.8,
    cat_features=None,
    quantize_gradients=True,
)

Bases: ClassifierMixin, BaseEstimator

Gradient boosted oblivious trees for classification.

A scikit-learn compatible classifier. Uses binary logloss for 2 classes and softmax for 3 or more, chosen automatically. predict_proba is temperature scaled on the validation split for calibrated probabilities.

Parameters:

Name	Type	Description	Default
n_estimators	int	Maximum number of boosting rounds (trees). With early_stopping on, this is an upper bound and the best round is selected automatically.	2000
learning_rate	float or None	Shrinkage applied to each tree. None resolves to 0.1 when early stopping is active.	None
depth	int	Depth of each oblivious tree; a depth-d tree makes d splits.	6
l2_leaf_reg	float	L2 regularization on leaf values.	1.0
max_bins	int	Histogram bins per numeric feature.	128
subsample	float	Row subsampling fraction per tree (Minimum Variance Sampling below 1.0).	1.0
colsample	float or None	Fraction of features eligible for each tree. None resolves to 1.0 for a single model and to the bagged-member default 0.85 inside n_ensembles > 1 fits (see member_params_).	None
cat_smoothing	float	Prior strength for ordered target statistics. Must be > 0 (a Bayesian pseudocount in the encoder denominator; 0 is undefined).	1.0
cat_n_permutations	int	Number of random orderings averaged by the ordered target encoder.	4
early_stopping_rounds	int or None	Rounds without validation improvement before stopping. None becomes 50 when early stopping is active.	None
min_child_weight	float or None	Minimum total hessian on each side of a split. None resolves to a size-adaptive value: a full veto below ~500 rows, off above ~2000.	None
thread_count	int or None	numba thread count. None or -1 uses all detected cores.	None
random_state	int or None	Seed for reproducibility (deterministic for a fixed thread_count).	None
verbose	bool	Print per-round train and validation metrics.	False
ordered_boosting	bool	Use the leave-one-out leaf training step instead of plain Newton updates.	False
cat_combinations	bool or None	Add all pairwise categorical-by-categorical features. None enables them automatically only when the data is entirely categorical (where the interaction columns help without crowding out numeric splits); set True/False to force it on/off.	None
leaf_estimation_iterations	int or None	Extra Newton refinement steps per leaf. None is the auto default and resolves to 3, which helps small and categorical-heavy binary fits. Refinement only applies to the plain constant-leaf path: it is inert while linear_leaves is active (default-on for binary ≥ ~1000 rows, where the per-leaf ridge already fits the second-order-optimal leaf) and is not implemented for multiclass. An explicitly-set value that will be ignored on the path about to run warns.	None
linear_leaves	bool or None	Fit a ridge linear model per leaf over the numeric split features instead of a constant. None enables it for binary classification and disables it for multiclass (where it is unsupported). Below ~1000 rows it falls back to constant leaves.	None
linear_lambda	float	Ridge penalty on per-leaf linear slopes; larger is closer to a constant.	1.0
quantize_gradients	bool	Run the split search on quantized gradients/hessians packed into integer histograms (LightGBM-style quantized training, ~15-bit): ~20-25% faster fits at benchmark-flat accuracy. Leaf values always use the exact float gradients; the rounding noise touches only split selection and is deterministic for a fixed random_state. False restores exact float64 histograms.	True
cross_features	bool or None	Numeric interaction columns. None (the default) refits the model with difference and product columns for the pairs of the top numeric features of the base fit and keeps whichever model reaches the lower validation loss (cross_features_selected_ records the outcome, cross_pairs_ the columns kept); needs >= 2000 rows and >= 2 numeric features. Binary judges on binary log loss, multiclass on softmax log loss. False turns it off. Costs up to ~2x fit time when the refit runs.	None
selection_rounds	int or None	Round budget for the pre-cross base fit when the cross-features refit will run. The base fit is an audition capped at this many rounds; the candidates are judged on their best validation loss within the budget, the winner continues to full early stopping, and the base is refit in full only if the augmented model loses after being truncated by the cap. None runs the base fit to full early stopping instead (the pre-0.15 behavior).	100
early_stopping	bool	Hold out a stratified validation split and stop when it stops improving. StratifiedGroupKFold is used when groups is passed to fit.	True
validation_fraction	float	Validation fraction used when early_stopping is on and no eval_set is passed to fit.	0.2
n_ensembles	int or None	Number of bagged members. None or 1 trains a single model; >= 2 soft-votes the calibrated probabilities of members, each fit on its own random row sample (max_samples, without replacement by default).	None
ensemble_n_jobs	int	Worker processes fitting ensemble members concurrently, each on an equal share of the thread budget (same total cores as a single fit; models are identical either way, wall-clock 1.2-2x faster). -1 sizes the pool from the budget, capped at n_ensembles; 1 fits members sequentially, each with the full budget.	-1
max_samples	float	Fraction of rows each ensemble member trains on, drawn WITHOUT replacement ("subagging"). The default 0.8 beats the classic bootstrap on strength and fit time (a full-size bootstrap holds only ~0.63n unique rows at n rows of compute). 1.0 restores the classic full-size with-replacement bootstrap. Unsampled rows are each member's early-stopping eval set either way.	0.8
cat_features	list of int or str, or None	Default categorical columns, given as integer positions and/or column names (names resolved against the DataFrame at fit). Used when fit is called without its own cat_features (the fit argument overrides). Provided as a constructor argument so GridSearchCV/Pipeline can carry it.	None

Attributes:

Name	Type	Description
classes_	ndarray	Class labels, in the column order of predict_proba.
feature_importances_	ndarray of shape (n_features,)	Split-gain importance per input feature, normalized to sum to 1.
best_iteration_	int	Number of trees retained after early stopping.
temperature_	float	Fitted calibration temperature; > 1 means raw scores were over-confident.
expected_value_	float	SHAP baseline (binary only); set after calling shap_values.
estimators_	list or None	Fitted members when n_ensembles > 1, otherwise None.
member_params_	dict	Bagged-mode member defaults that were auto-applied (params the user left on auto resolve to tuned member values inside a bag; explicit values always win). Set only when n_ensembles > 1.

Source code in chimeraboost/sklearn_api.py

def __init__(self, n_estimators=2000, learning_rate=None, depth=6,
             l2_leaf_reg=1.0, max_bins=128, subsample=1.0, colsample=None,
             cat_smoothing=1.0, cat_n_permutations=4,
             early_stopping_rounds=None,
             min_child_weight=None, thread_count=None, random_state=None,
             verbose=False, ordered_boosting=False,
             cat_combinations=None, leaf_estimation_iterations=None,
             linear_leaves=None, linear_lambda=1.0, cross_features=None,
             selection_rounds=100,
             early_stopping=True, validation_fraction=0.2,
             n_ensembles=None, ensemble_n_jobs=-1, max_samples=0.8,
             cat_features=None, quantize_gradients=True):
    self.n_estimators = n_estimators
    self.learning_rate = learning_rate
    self.depth = depth
    self.l2_leaf_reg = l2_leaf_reg
    self.max_bins = max_bins
    self.subsample = subsample
    self.colsample = colsample
    self.cat_smoothing = cat_smoothing
    self.cat_n_permutations = cat_n_permutations
    self.early_stopping_rounds = early_stopping_rounds
    self.cat_features = cat_features
    self.min_child_weight = min_child_weight
    self.thread_count = thread_count
    self.random_state = random_state
    self.verbose = verbose
    self.ordered_boosting = ordered_boosting
    self.cat_combinations = cat_combinations
    self.leaf_estimation_iterations = leaf_estimation_iterations
    self.linear_leaves = linear_leaves
    self.linear_lambda = linear_lambda
    self.cross_features = cross_features
    self.selection_rounds = selection_rounds
    self.early_stopping = early_stopping
    self.validation_fraction = validation_fraction
    self.n_ensembles = n_ensembles
    self.ensemble_n_jobs = ensemble_n_jobs
    self.max_samples = max_samples
    self.quantize_gradients = quantize_gradients

validation_history_ property

validation_history_

Per-round validation loss recorded during fit (binary or softmax log loss), as a list whose length is the number of rounds run. Empty when no eval_set / early-stopping split was available; for a bagged model (n_ensembles > 1) a list of the members' histories.

fit

fit(
    X,
    y,
    cat_features=None,
    eval_set=None,
    groups=None,
    sample_weight=None,
    callbacks=None,
)

Fit the model.

Parameters:

Name	Type	Description	Default
X	array - like	Training data.	required
y	array - like	Training data.	required
cat_features	list of int or str, or None	Columns to treat as categoricals, given as integer positions and/or column names (names resolved against the DataFrame). Falls back to the cat_features constructor argument when not given here; passing it here overrides the constructor value. (The constructor form lets GridSearchCV/Pipeline carry it, which a fit-only kwarg can't.)	None
eval_set	(X_val, y_val) tuple or None	Explicit validation set with original class labels. When provided, automatic splitting is skipped.	None
groups	array-like of shape (n_samples,) or None	Group labels (e.g. df['subject_id']). When supplied and early stopping triggers an automatic split, StratifiedGroupKFold keeps groups intact and class proportions balanced across the split.	None
sample_weight	array-like of shape (n_samples,) or None	Per-sample weights. Normalized to mean 1 internally. Applied throughout: the gradient/leaf fit, the categorical target encoder, the quantile bin borders, and the early-stopping metric on an automatically split (or bagged out-of-bag) validation set, so a zero-weight row never influences the model. An explicitly passed eval_set carries no weights and is scored unweighted.	None
callbacks	callable or list of callable, or None	Per-round fit hooks cb(iteration, train_loss, val_loss, model); a callback returning True requests an early stop. Used for live validation-curve capture and instrumentation. Not supported with n_ensembles > 1 (members fit in parallel worker processes).	None

Source code in chimeraboost/sklearn_api.py

def fit(self, X, y, cat_features=None, eval_set=None, groups=None,
        sample_weight=None, callbacks=None):
    """Fit the model.

    Parameters
    ----------
    X, y : array-like
        Training data.
    cat_features : list of int or str, or None
        Columns to treat as categoricals, given as integer positions and/or
        column names (names resolved against the DataFrame). Falls back to the
        ``cat_features`` constructor argument when not given here; passing it
        here overrides the constructor value. (The constructor form lets
        ``GridSearchCV``/``Pipeline`` carry it, which a fit-only kwarg can't.)
    eval_set : (X_val, y_val) tuple or None
        Explicit validation set with original class labels.  When provided,
        automatic splitting is skipped.
    groups : array-like of shape (n_samples,) or None
        Group labels (e.g. ``df['subject_id']``).  When supplied and early
        stopping triggers an automatic split, ``StratifiedGroupKFold`` keeps
        groups intact and class proportions balanced across the split.
    sample_weight : array-like of shape (n_samples,) or None
        Per-sample weights.  Normalized to mean 1 internally.  Applied
        throughout: the gradient/leaf fit, the categorical target encoder,
        the quantile bin borders, and the early-stopping metric on an
        automatically split (or bagged out-of-bag) validation set, so a
        zero-weight row never influences the model.  An explicitly passed
        ``eval_set`` carries no weights and is scored unweighted.
    callbacks : callable or list of callable, or None
        Per-round fit hooks ``cb(iteration, train_loss, val_loss, model)``;
        a callback returning True requests an early stop. Used for live
        validation-curve capture and instrumentation. Not supported with
        ``n_ensembles > 1`` (members fit in parallel worker processes).
    """
    cat_features = _resolve_cat_features(self, cat_features)
    cat_features = _resolve_cat_feature_names(cat_features, X)
    _validate_hyperparams(self)
    y = _validate_fit_input(self, X, y, cat_features, sample_weight,
                            classification=True)
    if eval_set is not None:
        _check_eval_set(eval_set, self.n_features_in_)
        # Bag members are exempt: their OOB eval set may legitimately hold
        # a rare label their row sample missed, and the parent aligns
        # member probability columns to the global class set.
        if not getattr(self, "_is_bag_member", False):
            _check_eval_labels(eval_set, y)
    if self.n_ensembles and self.n_ensembles > 1:
        if callbacks is not None:
            raise ValueError(
                "callbacks are not supported with n_ensembles > 1.")
        # Fix the global class set up front: a member's bootstrap may miss a
        # rare class, and predict_proba aligns each member's columns to this.
        yarr = np.asarray(y)
        self.classes_ = np.unique(yarr)
        self.n_classes_ = self.classes_.size
        if self.n_classes_ < 2:
            raise ValueError(
                f"Need at least 2 classes; got {self.n_classes_} class(es).")
        self._multiclass = self.n_classes_ > 2
        self.estimators_ = _fit_bagged(self, X, yarr, cat_features, eval_set,
                                       groups, sample_weight)
        return self
    self.estimators_ = None
    return self._fit_single(X, y, cat_features, eval_set, groups,
                            sample_weight, callbacks)

shap_values

shap_values(X, X_background=None)

Exact interventional TreeSHAP contributions in LOG-ODDS (margin) space.

Binary only. Returns an array of shape (n_samples, n_features) whose rows sum to raw_log_odds(X) - expected_value_ (pre-temperature), with expected_value_ set as an attribute. Each entry is a feature's signed contribution to the log-odds of the positive class; linear-leaf slopes are included exactly. Averaged across the bag when n_ensembles > 1 (an additive surrogate for the soft-voted probability). Multiclass is not supported yet. X_background overrides the reference distribution.

Source code in chimeraboost/sklearn_api.py

def shap_values(self, X, X_background=None):
    """Exact interventional TreeSHAP contributions in LOG-ODDS (margin) space.

    Binary only. Returns an array of shape ``(n_samples, n_features)`` whose
    rows sum to ``raw_log_odds(X) - expected_value_`` (pre-temperature), with
    ``expected_value_`` set as an attribute. Each entry is a feature's signed
    contribution to the log-odds of the positive class; linear-leaf slopes are
    included exactly. Averaged across the bag when ``n_ensembles > 1`` (an
    additive surrogate for the soft-voted probability). Multiclass is not
    supported yet. ``X_background`` overrides the reference distribution."""
    _check_predict_input(self, X)
    members = self.estimators_ if self.estimators_ is not None else None
    if (members is not None and getattr(members[0], "_multiclass", False)) \
            or (members is None and self._multiclass):
        raise NotImplementedError(
            "shap_values is not supported for multiclass classification yet.")
    if members is not None:
        out = [m.model_.shap_values(X, background=X_background)
               for m in members]
        self.expected_value_ = float(np.mean([b for _, b in out]))
        return np.mean([p for p, _ in out], axis=0)
    phi, base = self.model_.shap_values(X, background=X_background)
    self.expected_value_ = base
    return phi