scxpand.hyperopt.hyperopt_optimizer

scxpand.hyperopt.hyperopt_optimizer#

Hyperparameter optimization using Optuna with robust trial management.

Classes

HyperparameterOptimizer(model_type, data_path)

Robust hyperparameter optimizer using Optuna with enhanced trial management.
class scxpand.hyperopt.hyperopt_optimizer.HyperparameterOptimizer(model_type, data_path, study_name=None, storage_path='results/optuna_studies', score_metric='harmonic_avg/AUROC', seed_base=42, num_workers=0, config_path=None, resume=True, fail_fast=False, **param_overrides)#

Robust hyperparameter optimizer using Optuna with enhanced trial management.

Features: - Automatic cleanup of incomplete trials - Proper exception handling and categorization - Resume capability with duplicate prevention - Comprehensive logging and monitoring

__init__(model_type, data_path, study_name=None, storage_path='results/optuna_studies', score_metric='harmonic_avg/AUROC', seed_base=42, num_workers=0, config_path=None, resume=True, fail_fast=False, **param_overrides)#

Initialize the hyperparameter optimizer.

Parameters:

  • model_type (ModelType | str) – Type of model to optimize (MLP, SVM, etc.).

  • data_path (str | Path) – Path to the training data file.

  • study_name (str | None (default: None)) – Name for the Optuna study (auto-generated if None).

  • storage_path (str | Path (default: 'results/optuna_studies')) – Directory to store study results.

  • score_metric (str (default: 'harmonic_avg/AUROC')) – Metric to optimize (e.g., “harmonic_avg/AUROC”).

  • seed_base (int (default: 42)) – Base seed for reproducibility.

  • num_workers (int (default: 0)) – Number of parallel workers (0 for single-threaded).

  • config_path (str | None (default: None)) – Path to configuration file for parameter overrides.

  • resume (bool (default: True)) – Whether to resume existing study (False = start fresh).

  • fail_fast (bool (default: False)) – Whether to fail immediately on any exception (for testing).

  • **param_overrides – Additional parameter overrides.

create_study()#

Create or load an Optuna study based on the resume setting.

Return type:

Study

Returns:

The Optuna study object.

Raises:

ValueError – If study exists but resume=False.

objective(trial)#

Objective function for Optuna trials.

Parameters:

trial (Trial) – The Optuna trial object.

Return type:

float

Returns:

The trial score (higher is better) or -inf if failed.

print_results(study=None)#

Print optimization results.

Parameters:

study (Study | None (default: None)) – The study to print results for (loads existing if None).

Return type:

None

run_optimization(n_trials=100)#

Run the hyperparameter optimization.

Parameters:

n_trials (int (default: 100)) – Number of trials to run.

Return type:

Study

Returns:

The completed Optuna study.

Contents