Tune¶

class endgame.tune.OptunaOptimizer(estimator=None, param_space=None, metric='roc_auc', cv=5, n_trials=100, timeout=None, sampler='tpe', pruner='median', direction='maximize', n_jobs=1, random_state=None, verbose=False)[source]¶

Bases: EndgameEstimator

Automated hyperparameter optimization with Optuna.

Provides Bayesian optimization of model hyperparameters with competition-specific search spaces and pruning.

Parameters:

estimator (endgame or sklearn estimator) – Model to optimize.
param_space (Dict or str) – Parameter search space. If str, uses preset: - ‘lgbm_standard’, ‘lgbm_large’ - ‘xgb_standard’, ‘xgb_large’ - ‘catboost_standard’
metric (str or callable) – Optimization target: ‘roc_auc’, ‘log_loss’, ‘rmse’, etc.
cv (int or CV splitter, default=5) – Cross-validation strategy.
n_trials (int, default=100) – Number of optimization trials.
timeout (int, optional) – Maximum optimization time in seconds.
sampler (str, default='tpe') – Optuna sampler: ‘tpe’, ‘cmaes’, ‘random’.
pruner (str, default='median') – Early stopping: ‘median’, ‘hyperband’, ‘none’.
direction (str, default='maximize') – Optimization direction: ‘maximize’ or ‘minimize’.
n_jobs (int, default=1) – Parallel jobs for cross-validation.
random_state (int, optional) – Random seed.
verbose (bool, default=False) – Enable verbose output.

best_params_¶

Best hyperparameters found.

Type:: Dict[str, Any]

best_score_¶

Best validation score.

Type:: float

study_¶

Optuna study for further analysis.

Type:: optuna.Study

best_estimator_¶

Model fitted with best parameters.

Type:: estimator

Examples

>>> from endgame.tune import OptunaOptimizer
>>> from endgame.models import LGBMWrapper
>>> optimizer = OptunaOptimizer(
...     estimator=LGBMWrapper(),
...     param_space='lgbm_standard',
...     metric='roc_auc',
...     n_trials=100
... )
>>> result = optimizer.optimize(X, y)
>>> print(f"Best params: {result.best_params}")

optimize(X, y, groups=None, fit_params=None)[source]¶

Run hyperparameter optimization.

Parameters:

X (array-like) – Training features.
y (array-like) – Target values.
groups (array-like, optional) – Group labels for group-aware CV.
fit_params (dict, optional) – Additional parameters for estimator.fit().

Return type:

OptimizationResult

Returns:

OptimizationResult –

best_params: Dict
best_score: float
study: optuna.Study
all_trials: List[Dict]

get_param_importances()[source]¶

Get hyperparameter importances.

Return type:: WSGIEnvironment[Text, float]
Returns:: Dict[str, float] – Importance score for each hyperparameter.

plot_optimization_history()[source]¶: Plot optimization history.

plot_param_importances()[source]¶: Plot hyperparameter importances.

endgame.tune.get_lgbm_space(size='standard')[source]¶

Get LightGBM search space.

Parameters:: size (str, default='standard') – Space size: ‘standard’, ‘large’, ‘fast’.
Return type:: WSGIEnvironment[Text, WSGIEnvironment[Text, Any]]
Returns:: Dict – Search space configuration.

endgame.tune.get_xgb_space(size='standard')[source]¶

Get XGBoost search space.

Parameters:: size (str, default='standard') – Space size: ‘standard’, ‘large’.
Return type:: WSGIEnvironment[Text, WSGIEnvironment[Text, Any]]
Returns:: Dict – Search space configuration.

endgame.tune.get_catboost_space(size='standard')[source]¶

Get CatBoost search space.

Parameters:: size (str, default='standard') – Space size: ‘standard’, ‘large’.
Return type:: WSGIEnvironment[Text, WSGIEnvironment[Text, Any]]
Returns:: Dict – Search space configuration.

endgame.tune.get_space(name)[source]¶

Get a predefined search space by name.

Parameters:: name (str) – Space name: ‘lgbm_standard’, ‘xgb_standard’, etc.
Return type:: WSGIEnvironment[Text, WSGIEnvironment[Text, Any]]
Returns:: Dict – Search space configuration.
Raises:: ValueError – If space name is not found.