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
-------

.. py:class:: OptunaTrialResult

   Result from a single Optuna trial.

   **Methods:**

   .. py:method:: to_dict()

      Convert to dictionary.


.. py:class:: OptimizationResults

   Complete results from an optimization run.

   **Methods:**

   .. py:method:: to_dict()

      Convert to dictionary for JSON serialization.


.. py: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:**

   .. py:method:: __init__()

      Initialize optimizer.

   .. py:method:: set_dicom_info()

      Set DICOM volume/study information.

   .. py:method:: create_study()

      Create Optuna study with configured sampler and pruner.

   .. py:method:: suggest_params()

      Suggest parameters for a trial.

   .. py:method:: optimize()

      Run optimization.

   .. py:method:: get_param_importance()

      Compute parameter importance using FAnova.

   .. py:method:: report_intermediate()

      Report intermediate value for pruning.

   .. py:method:: get_best_params()

      Get best parameters found.

   .. py:method:: get_best_value()

      Get best objective value.

   .. py:method:: resume()

      Resume optimization from saved state.


Functions
---------

.. py:function:: to_dict()

   Convert to dictionary.

.. py:function:: to_dict()

   Convert to dictionary for JSON serialization.

.. py:function:: 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).

.. py:function:: create_study()

   Create Optuna study with configured sampler and pruner.
   
   Args:
       study_name: Optional study name. Defaults to config name.
   
   Returns:
       Created Optuna study.

.. py:function:: 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.

.. py:function:: 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.

.. py:function:: wrapped_objective()

   Wrapper that handles parameter suggestion and result recording.

.. py:function:: get_param_importance()

   Compute parameter importance using FAnova.
   
   Returns:
       Dictionary mapping parameter names to importance (0-1).

.. py:function:: 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.

.. py:function:: get_best_params()

   Get best parameters found.
   
   Returns:
       Best parameter dictionary.

.. py:function:: get_best_value()

   Get best objective value.
   
   Returns:
       Best value or None if no trials.

.. py:function:: resume()

   Resume optimization from saved state.
   
   Creates study with load_if_exists=True to continue from
   SQLite storage.

.. py:function:: 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.

.. py:function:: objective()