Интерпретация модели

Помощники для важности признаков, SHAP-значений и проверки настроек ранней остановки.

from catboost_utils.explain import feature_importance, shap_values, check_early_stopping

fi = feature_importance(model, X)
sv = shap_values(model, X)
check_early_stopping(model, eval_set=(X_val, y_val))

feature_importance возвращает DataFrame с именами колонок, отсортированный по убыванию. Имена ищутся в данных, потом в Pool, потом в model.feature_names_, и в крайнем случае это просто номера. Если на вход передан DataFrame, он автоматически превращается в Pool с правильными категориальными колонками — для этого используется model.get_cat_feature_indices().

shap_values возвращает DataFrame, где каждая колонка — признак, а последняя — expected_value (базовое значение модели). Если модель обучена так, что SHAP не сможет посчитаться (известная ошибка про «non-zero approx for zero-weight leaf»), бросается понятное CBXError с подсказкой. SHAP для multiclass пока не поддержан — для этого используйте оригинальный API CatBoost.

check_early_stopping бросает CBXError, если задан хотя бы один из параметров (od_type, od_wait, od_pval, early_stopping_rounds), но eval_set не передан. Без валидационной выборки ранняя остановка работать всё равно не будет, лучше узнать об этом до запуска fit.

catboost_utils.explain.importance.feature_importance

feature_importance(
    model: Any,
    data: Any | None = None,
    *,
    type: ImportanceType = "PredictionValuesChange",
    prettified: bool = True,
) -> pd.DataFrame | npt.NDArray[Any]

Return feature importances with feature names attached.

Parameters:

Name	Type	Description	Default
model	Any	a fitted CatBoost model (or CBXClassifier/CBXRegressor).	required
data	Any | None	pd.DataFrame, catboost.Pool, or None (for types that don't require it). "ShapValues", "LossFunctionChange", "Interaction" require non-None data and will raise CBXError if missing.	None
type	ImportanceType	CatBoost importance type.	'PredictionValuesChange'
prettified	bool	when True (default), return a sorted pd.DataFrame with columns ["feature", "importance"]. When False, return the raw ndarray from CatBoost.	True

Returns:

Type	Description
DataFrame | NDArray[Any]	DataFrame or ndarray depending on prettified.

Raises:

Type	Description
CBXError	when data is required but not provided, or when the underlying CatBoost call fails for a reason we recognize.

catboost_utils.explain.shap.shap_values

shap_values(model: Any, data: Any) -> pd.DataFrame

Compute SHAP values and return them as a named DataFrame.

Parameters:

Name	Type	Description	Default
model	Any	a fitted CatBoost / CBX model.	required
data	Any	pd.DataFrame or catboost.Pool — the rows to explain.	required

Returns:

Type	Description
DataFrame	DataFrame with one column per feature plus expected_value (the model
DataFrame	bias / base value) as the last column. Rows correspond to the input rows.

Raises:

Type	Description
CBXError	if data is None, if the model is multiclass (not supported in v0.1), or if CatBoost reports the well-known "non-zero approx for zero-weight leaf" misconfiguration.

catboost_utils.explain.early_stopping.check_early_stopping

check_early_stopping(
    model: Any, eval_set: Any | None = None
) -> None

Validate early-stopping configuration before fit().

Parameters:

Name	Type	Description	Default
model	Any	a CatBoost / CBX model instance.	required
eval_set	Any | None	the eval_set you intend to pass to fit().	None

Raises:

Type	Description
CBXError	when any early-stopping parameter is set but eval_set is missing.