OptunaOptimizer

Optuna-powered parameter optimization for segmentation algorithms.

Provides smart parameter optimization using TPE (Tree-structured Parzen Estimator) sampling and HyperbandPruner for early stopping of poor trials.

See ADR-011 for architecture decisions.

Requires: pip install optuna

Classes

class OptunaTrialResult

Result from a single Optuna trial.

Methods:

to_dict()

Convert to dictionary.

class OptimizationResults

Complete results from an optimization run.

Methods:

to_dict()

Convert to dictionary for JSON serialization.

class OptunaOptimizer

Optuna-powered parameter optimization.

Uses TPE sampler for intelligent parameter suggestion and HyperbandPruner for early stopping of poor trials.

Example:

from OptimizationConfig import OptimizationConfig

config = OptimizationConfig.load(“configs/tumor_optimization.yaml”) optimizer = OptunaOptimizer(config)

def objective(params):

# Run segmentation with params… return dice_score

results = optimizer.optimize(objective) print(f”Best Dice: {results.best_trial.value}”)

Methods:

__init__()

Initialize optimizer.

set_dicom_info()

Set DICOM volume/study information.

create_study()

Create Optuna study with configured sampler and pruner.

suggest_params()

Suggest parameters for a trial.

optimize()

Run optimization.

get_param_importance()

Compute parameter importance using FAnova.

report_intermediate()

Report intermediate value for pruning.

get_best_params()

Get best parameters found.

get_best_value()

Get best objective value.

resume()

Resume optimization from saved state.

Functions

to_dict()

Convert to dictionary.

to_dict()

Convert to dictionary for JSON serialization.

set_dicom_info()

Set DICOM volume/study information.

Args:

dicom_info: Dictionary with DICOM UIDs (patient_id, study_instance_uid,

volume_series_uid, volume_name).

create_study()

Create Optuna study with configured sampler and pruner.

Args:

study_name: Optional study name. Defaults to config name.

Returns:

Created Optuna study.

suggest_params()

Suggest parameters for a trial.

Uses config’s parameter space to suggest values. Handles hierarchical parameters (algorithm-specific).

Args:

trial: Optuna trial object.

Returns:

Dictionary of suggested parameters.

optimize()

Run optimization.

Args:

objective: Objective function taking (trial, params) and returning metric. n_trials: Number of trials. Defaults to config value. timeout: Timeout in seconds. Defaults to config value. show_progress_bar: Whether to show progress bar. callbacks: Additional Optuna callbacks.

Returns:

OptimizationResults with all trial data.

wrapped_objective()

Wrapper that handles parameter suggestion and result recording.

get_param_importance()

Compute parameter importance using FAnova.

Returns:

Dictionary mapping parameter names to importance (0-1).

report_intermediate()

Report intermediate value for pruning.

Args:

trial: Current trial. step: Step number (e.g., stroke index). value: Intermediate metric value.

Returns:

True if trial should be pruned.

get_best_params()

Get best parameters found.

Returns:

Best parameter dictionary.

get_best_value()

Get best objective value.

Returns:

Best value or None if no trials.

resume()

Resume optimization from saved state.

Creates study with load_if_exists=True to continue from SQLite storage.

run_optimization_with_recipe()

Convenience function to run optimization with a recipe.

Args:

config_path: Path to YAML config file. recipe_path: Optional recipe path override. gold_standard_path: Optional gold standard path override.

Returns:

OptimizationResults.

objective()