Optimizer API

run_study

h2ml.optimization.optimizer.run_study(name, X, y, task='classification', metric=None, n_trials=50, n_splits=5, random_state=42, study_name=None, verbose=True, coords=None, spatial=None, n_hpo_repeats=1, fixed_params=None, y_true=None, inverse_fn=None, _splitter=None)

Run an Optuna hyperparameter optimization study for a registered model.

Parameters:

Name	Type	Description	Default
name	str	Model class name (e.g. 'RandomForestClassifier'). Must be registered in CLASSIFIER_OPT_PARAMS or REGRESSOR_OPT_PARAMS.	required
X	ndarray	Feature matrix as numpy array (n_samples, n_features).	required
y	ndarray	Target array (n_samples,).	required
task	str	'classification' or 'regression'.	'classification'
metric	Optional[str]	Scoring metric for the objective. Must be a key in CLF_METRICS (classification) or REG_METRICS (regression). Defaults to 'AUC' for classification, 'R2' for regression. All metrics are maximised internally (error metrics are negated).	None
n_trials	int	Total number of Optuna trials across all repeats (default 50). Divided evenly: trials_per_repeat = max(1, n_trials // n_hpo_repeats).	50
n_splits	int	CV folds inside each trial objective (default 5).	5
random_state	int	Base seed for reproducibility. Each repeat uses random_state + repeat_idx for both the TPE sampler and fold splitter (default 42).	42
study_name	Optional[str]	Optional Optuna study name for logging/storage.	None
verbose	bool	If True, log trial progress.	True
n_hpo_repeats	int	Number of independent HPO runs with different fold seeds (default 1). Each repeat draws fold splits from a different random seed, amortising the risk of an unlucky single split. The study with the highest best_value is returned.	1

Returns:

Type	Description
Study	optuna.Study with best_params, best_value, and full trial history.
Study	When n_hpo_repeats > 1, this is the repeat whose best_value was highest.

Raises:

Type	Description
KeyError	If the model is not registered.
ValueError	If the model is registered but disabled, or metric is invalid.

Example

study = run_study("RandomForestClassifier", X, y, task="classification") study.best_params {'n_estimators': 300, 'max_depth': 8, ...} study.best_value 0.923

Available metrics

Dict	Keys
CLF_METRICS	"AUC", "AUC_PR", "LogLoss", "F1", "Brier"
REG_METRICS	"R2", "MAE", "RMSE"

All metrics are maximised internally — error metrics (LogLoss, Brier, MAE, RMSE) are negated before optimisation and displayed with their natural (positive) values.