visualizers

orchard.optimization.orchestrator.visualizers

Optuna Visualization Generation.

Creates interactive Plotly visualizations for study analysis:

• Optimization history (metric over trials)
• Parameter importance (feature importance for hyperparameters)
• Slice plots (1D parameter effects)
• Parallel coordinate plot (multi-dimensional view)

All functions handle missing dependencies (plotly) and plot generation failures gracefully with informative logging.

generate_visualizations(study, output_dir)

Generate and save all Optuna visualization plots.

Creates interactive HTML plots for study analysis. Skips generation if no completed trials exist or if plotly is not installed.

Parameters:

Name	Type	Description	Default
study	Study	Completed Optuna study with at least one successful trial	required
output_dir	Path	Directory to save HTML plot files (typically paths.figures)	required

Generated plots:

• optimization_history.html: Metric progression over trials
• param_importances.html: Hyperparameter importance ranking
• slice.html: Individual parameter effects
• parallel_coordinate.html: Multi-dimensional parameter view

Note

Requires plotly installation. Logs warning if not available.

Example

generate_visualizations(study, paths.figures)

Creates 4 .html files in paths.figures/

Source code in orchard/optimization/orchestrator/visualizers.py

def generate_visualizations(study: optuna.Study, output_dir: Path) -> None:
    """
    Generate and save all Optuna visualization plots.

    Creates interactive HTML plots for study analysis. Skips generation
    if no completed trials exist or if plotly is not installed.

    Args:
        study: Completed Optuna study with at least one successful trial
        output_dir: Directory to save HTML plot files (typically paths.figures)

    Generated plots:

    - ``optimization_history.html``: Metric progression over trials
    - ``param_importances.html``: Hyperparameter importance ranking
    - ``slice.html``: Individual parameter effects
    - ``parallel_coordinate.html``: Multi-dimensional parameter view

    Note:
        Requires plotly installation. Logs warning if not available.

    Example:
        >>> generate_visualizations(study, paths.figures)
        # Creates 4 .html files in paths.figures/
    """
    if not has_completed_trials(study):
        logger.warning("No completed trials. Skipping visualizations.")
        return

    try:
        from optuna.visualization import (
            plot_optimization_history,
            plot_parallel_coordinate,
            plot_param_importances,
            plot_slice,
        )

        plots = MappingProxyType(
            {
                "optimization_history": plot_optimization_history,  # pragma: no mutate
                "param_importances": plot_param_importances,  # pragma: no mutate
                "slice": plot_slice,  # pragma: no mutate
                "parallel_coordinate": plot_parallel_coordinate,  # pragma: no mutate
            }
        )

        for plot_name, plot_fn in plots.items():
            save_plot(study, plot_name, plot_fn, output_dir)  # type: ignore[arg-type]

    except ImportError:
        logger.warning(
            "plotly not installed. Skipping visualization generation. "
            "Install with: pip install plotly"
        )

save_plot(study, plot_name, plot_fn, output_dir)

Save a single Optuna visualization plot.

Wraps plot generation in exception handling to prevent failures from blocking the optimization pipeline.

Parameters:

Name	Type	Description	Default
study	Study	Optuna study instance	required
plot_name	str	Human-readable plot name (for logging)	required
plot_fn	Callable[..., Any]	Optuna plotting function (e.g., plot_optimization_history)	required
output_dir	Path	Directory for output HTML files	required

Example

from optuna.visualization import plot_optimization_history save_plot(study, "history", plot_optimization_history, Path("./figures"))

Source code in orchard/optimization/orchestrator/visualizers.py

def save_plot(
    study: optuna.Study, plot_name: str, plot_fn: Callable[..., Any], output_dir: Path
) -> None:
    """
    Save a single Optuna visualization plot.

    Wraps plot generation in exception handling to prevent failures
    from blocking the optimization pipeline.

    Args:
        study: Optuna study instance
        plot_name: Human-readable plot name (for logging)
        plot_fn: Optuna plotting function (e.g., plot_optimization_history)
        output_dir (Path): Directory for output HTML files

    Example:
        >>> from optuna.visualization import plot_optimization_history
        >>> save_plot(study, "history", plot_optimization_history, Path("./figures"))
    """
    try:
        # Conditional search spaces (e.g. focal_gamma only for criterion_type=="focal")
        # cause Optuna to log about "trials with missing parameters" in plots
        # like parallel_coordinate. This is expected and not actionable.
        # Optuna uses logging.warning() (not warnings.warn()), so we must
        # filter the exact child logger that emits the message — filters on
        # parent loggers do NOT propagate to children in Python's logging.
        _optuna_pc_logger = logging.getLogger("optuna.visualization._parallel_coordinate")
        _optuna_pc_logger.addFilter(_missing_params_filter)
        try:
            fig = plot_fn(study)
        finally:
            _optuna_pc_logger.removeFilter(_missing_params_filter)
        output_path = output_dir / f"{plot_name}.html"
        fig.write_html(str(output_path))  # pragma: no mutate
        logger.info("%s%s %-22s: %s", LogStyle.INDENT, LogStyle.ARROW, plot_name, output_path.name)
    except (ValueError, RuntimeError) as e:
        logger.warning("Failed to generate %s: %s", plot_name, e)