Manuel Raimann
e359392a00
Add a `visualization` feature flag that generates self-contained HTML reports with interactive Plotly.js charts for offline visualization of optimization results. Charts include optimization history, slice plots, parallel coordinates, parameter importance, trial timeline, and intermediate values (learning curves).
459 lines
15 KiB
Rust
459 lines
15 KiB
Rust
//! HTML report generation for optimization visualization.
|
|
//!
|
|
//! Generates self-contained HTML files with embedded Plotly.js charts
|
|
//! for offline visualization of optimization results.
|
|
|
|
use core::fmt::Write as _;
|
|
use std::collections::BTreeMap;
|
|
use std::path::Path;
|
|
|
|
use crate::distribution::Distribution;
|
|
use crate::param::ParamValue;
|
|
use crate::parameter::ParamId;
|
|
use crate::sampler::CompletedTrial;
|
|
use crate::types::{Direction, TrialState};
|
|
|
|
/// Generate an HTML report with interactive Plotly.js charts.
|
|
///
|
|
/// Creates a self-contained HTML file at `path` containing:
|
|
/// - **Optimization history**: Objective value vs trial number with best-so-far line
|
|
/// - **Slice plots**: Objective value vs each parameter (1D scatter)
|
|
/// - **Parallel coordinates**: Multi-parameter relationship view
|
|
/// - **Trial timeline**: Duration index of each trial (horizontal bar)
|
|
/// - **Intermediate values**: Learning curves per trial (if pruning data available)
|
|
/// - **Parameter importance**: Bar chart (if enough completed trials)
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Returns an I/O error if the file cannot be created or written.
|
|
pub fn generate_html_report(
|
|
study: &crate::Study<f64>,
|
|
path: impl AsRef<Path>,
|
|
) -> std::io::Result<()> {
|
|
let trials = study.trials();
|
|
let direction = study.direction();
|
|
let importance = study.param_importance();
|
|
|
|
let html = build_html(&trials, direction, &importance);
|
|
std::fs::write(path, html)
|
|
}
|
|
|
|
fn build_html(
|
|
trials: &[CompletedTrial<f64>],
|
|
direction: Direction,
|
|
importance: &[(String, f64)],
|
|
) -> String {
|
|
let mut html = String::with_capacity(8192);
|
|
|
|
let dir_label = match direction {
|
|
Direction::Minimize => "Minimize",
|
|
Direction::Maximize => "Maximize",
|
|
};
|
|
|
|
// Collect parameter metadata.
|
|
let param_info = collect_param_info(trials);
|
|
let has_intermediate = trials.iter().any(|t| !t.intermediate_values.is_empty());
|
|
|
|
let _ = write!(
|
|
html,
|
|
r#"<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Optimization Report</title>
|
|
<script src="https://cdn.plot.ly/plotly-2.35.2.min.js"></script>
|
|
<style>
|
|
* {{ margin: 0; padding: 0; box-sizing: border-box; }}
|
|
body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
|
|
background: #f5f6fa; color: #2c3e50; padding: 24px; }}
|
|
h1 {{ text-align: center; margin-bottom: 8px; font-size: 1.8em; }}
|
|
.subtitle {{ text-align: center; color: #7f8c8d; margin-bottom: 24px; }}
|
|
.chart {{ background: #fff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.08);
|
|
margin-bottom: 24px; padding: 16px; }}
|
|
.chart-title {{ font-size: 1.1em; font-weight: 600; margin-bottom: 8px; }}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1>Optimization Report</h1>
|
|
<p class="subtitle">{dir_label} · {n} trials</p>
|
|
"#,
|
|
n = trials.len(),
|
|
);
|
|
|
|
// Optimization history chart.
|
|
html.push_str("<div class=\"chart\"><div class=\"chart-title\">Optimization History</div><div id=\"history\"></div></div>\n");
|
|
write_history_chart(&mut html, trials, direction);
|
|
|
|
// Slice plots.
|
|
if !param_info.is_empty() {
|
|
html.push_str("<div class=\"chart\"><div class=\"chart-title\">Slice Plots</div><div id=\"slices\"></div></div>\n");
|
|
write_slice_charts(&mut html, trials, ¶m_info);
|
|
}
|
|
|
|
// Parallel coordinates.
|
|
if param_info.len() >= 2 {
|
|
html.push_str("<div class=\"chart\"><div class=\"chart-title\">Parallel Coordinates</div><div id=\"parcoords\"></div></div>\n");
|
|
write_parallel_coordinates(&mut html, trials, ¶m_info, direction);
|
|
}
|
|
|
|
// Parameter importance.
|
|
if !importance.is_empty() {
|
|
html.push_str("<div class=\"chart\"><div class=\"chart-title\">Parameter Importance</div><div id=\"importance\"></div></div>\n");
|
|
write_importance_chart(&mut html, importance);
|
|
}
|
|
|
|
// Trial timeline.
|
|
html.push_str("<div class=\"chart\"><div class=\"chart-title\">Trial Timeline</div><div id=\"timeline\"></div></div>\n");
|
|
write_timeline_chart(&mut html, trials);
|
|
|
|
// Intermediate values.
|
|
if has_intermediate {
|
|
html.push_str("<div class=\"chart\"><div class=\"chart-title\">Intermediate Values</div><div id=\"intermediate\"></div></div>\n");
|
|
write_intermediate_chart(&mut html, trials);
|
|
}
|
|
|
|
html.push_str("</body>\n</html>\n");
|
|
html
|
|
}
|
|
|
|
/// Metadata about each parameter seen across trials.
|
|
struct ParamMeta {
|
|
label: String,
|
|
#[allow(dead_code)]
|
|
dist: Option<Distribution>,
|
|
}
|
|
|
|
/// Collect parameter labels and distributions across all trials.
|
|
fn collect_param_info(trials: &[CompletedTrial<f64>]) -> BTreeMap<ParamId, ParamMeta> {
|
|
let mut info: BTreeMap<ParamId, ParamMeta> = BTreeMap::new();
|
|
for trial in trials {
|
|
for &id in trial.params.keys() {
|
|
info.entry(id).or_insert_with(|| {
|
|
let label = trial
|
|
.param_labels
|
|
.get(&id)
|
|
.cloned()
|
|
.unwrap_or_else(|| id.to_string());
|
|
let dist = trial.distributions.get(&id).cloned();
|
|
ParamMeta { label, dist }
|
|
});
|
|
}
|
|
}
|
|
info
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Chart generators
|
|
// ---------------------------------------------------------------------------
|
|
|
|
fn write_history_chart(html: &mut String, trials: &[CompletedTrial<f64>], direction: Direction) {
|
|
let complete: Vec<_> = trials
|
|
.iter()
|
|
.filter(|t| t.state == TrialState::Complete)
|
|
.collect();
|
|
if complete.is_empty() {
|
|
return;
|
|
}
|
|
|
|
let mut ids = Vec::with_capacity(complete.len());
|
|
let mut vals = Vec::with_capacity(complete.len());
|
|
let mut best_vals = Vec::with_capacity(complete.len());
|
|
let mut best = complete[0].value;
|
|
for t in &complete {
|
|
ids.push(t.id);
|
|
vals.push(t.value);
|
|
best = match direction {
|
|
Direction::Minimize => best.min(t.value),
|
|
Direction::Maximize => best.max(t.value),
|
|
};
|
|
best_vals.push(best);
|
|
}
|
|
|
|
let _ = write!(
|
|
html,
|
|
r##"<script>
|
|
Plotly.newPlot("history", [
|
|
{{ x: {ids:?}, y: {vals:?}, mode: "markers", name: "Objective", type: "scatter",
|
|
marker: {{ color: "#3498db", size: 6 }} }},
|
|
{{ x: {ids:?}, y: {best_vals:?}, mode: "lines", name: "Best so far", type: "scatter",
|
|
line: {{ color: "#e74c3c", width: 2 }} }}
|
|
], {{ xaxis: {{ title: "Trial" }}, yaxis: {{ title: "Objective Value" }},
|
|
margin: {{ t: 10 }}, legend: {{ x: 1, xanchor: "right", y: 1 }} }},
|
|
{{ responsive: true }});
|
|
</script>
|
|
"##,
|
|
);
|
|
}
|
|
|
|
fn write_slice_charts(
|
|
html: &mut String,
|
|
trials: &[CompletedTrial<f64>],
|
|
param_info: &BTreeMap<ParamId, ParamMeta>,
|
|
) {
|
|
let complete: Vec<_> = trials
|
|
.iter()
|
|
.filter(|t| t.state == TrialState::Complete)
|
|
.collect();
|
|
if complete.is_empty() {
|
|
return;
|
|
}
|
|
|
|
let n_params = param_info.len();
|
|
let cols = if n_params <= 2 { n_params } else { 2 };
|
|
let rows = n_params.div_ceil(cols);
|
|
|
|
// Build subplot titles and data.
|
|
let mut subplot_titles = Vec::new();
|
|
let mut traces = String::new();
|
|
for (i, (id, meta)) in param_info.iter().enumerate() {
|
|
subplot_titles.push(format!("\"{}\"", escape_js(&meta.label)));
|
|
|
|
let mut x_vals = Vec::new();
|
|
let mut y_vals = Vec::new();
|
|
for t in &complete {
|
|
if let Some(pv) = t.params.get(id) {
|
|
x_vals.push(param_value_to_f64(pv));
|
|
y_vals.push(t.value);
|
|
}
|
|
}
|
|
|
|
let subplot_idx = i + 1;
|
|
let xa = if subplot_idx == 1 {
|
|
"x".to_string()
|
|
} else {
|
|
format!("x{subplot_idx}")
|
|
};
|
|
let ya = if subplot_idx == 1 {
|
|
"y".to_string()
|
|
} else {
|
|
format!("y{subplot_idx}")
|
|
};
|
|
let _ = write!(
|
|
traces,
|
|
r##"{{ x: {x_vals:?}, y: {y_vals:?}, mode: "markers", type: "scatter",
|
|
xaxis: "{xa}", yaxis: "{ya}",
|
|
marker: {{ color: "#3498db", size: 5 }}, showlegend: false }},"##,
|
|
);
|
|
}
|
|
|
|
let _ = write!(
|
|
html,
|
|
r#"<script>
|
|
Plotly.newPlot("slices", [{traces}],
|
|
{{ grid: {{ rows: {rows}, columns: {cols}, pattern: "independent" }},
|
|
annotations: [{annotations}],
|
|
margin: {{ t: 30 }}, showlegend: false }},
|
|
{{ responsive: true }});
|
|
</script>
|
|
"#,
|
|
annotations = build_subplot_annotations(&subplot_titles, rows, cols),
|
|
);
|
|
}
|
|
|
|
fn write_parallel_coordinates(
|
|
html: &mut String,
|
|
trials: &[CompletedTrial<f64>],
|
|
param_info: &BTreeMap<ParamId, ParamMeta>,
|
|
direction: Direction,
|
|
) {
|
|
let complete: Vec<_> = trials
|
|
.iter()
|
|
.filter(|t| t.state == TrialState::Complete)
|
|
.collect();
|
|
if complete.is_empty() {
|
|
return;
|
|
}
|
|
|
|
let mut dimensions = String::new();
|
|
|
|
// Add objective value as the first dimension.
|
|
let obj_vals: Vec<f64> = complete.iter().map(|t| t.value).collect();
|
|
let _ = write!(
|
|
dimensions,
|
|
r#"{{ label: "Objective", values: {obj_vals:?} }},"#,
|
|
);
|
|
|
|
// Add each parameter as a dimension.
|
|
for (id, meta) in param_info {
|
|
let vals: Vec<f64> = complete
|
|
.iter()
|
|
.map(|t| t.params.get(id).map_or(f64::NAN, param_value_to_f64))
|
|
.collect();
|
|
let _ = write!(
|
|
dimensions,
|
|
r#"{{ label: "{label}", values: {vals:?} }},"#,
|
|
label = escape_js(&meta.label),
|
|
);
|
|
}
|
|
|
|
// Color by objective value: green = good, red = bad.
|
|
let (cmin, cmax) = min_max(&obj_vals);
|
|
let colorscale = match direction {
|
|
Direction::Minimize => r##"[[0,"#2ecc71"],[1,"#e74c3c"]]"##,
|
|
Direction::Maximize => r##"[[0,"#e74c3c"],[1,"#2ecc71"]]"##,
|
|
};
|
|
|
|
let _ = write!(
|
|
html,
|
|
r#"<script>
|
|
Plotly.newPlot("parcoords", [{{
|
|
type: "parcoords",
|
|
line: {{ color: {obj_vals:?}, colorscale: {colorscale},
|
|
cmin: {cmin}, cmax: {cmax}, showscale: true }},
|
|
dimensions: [{dimensions}]
|
|
}}], {{ margin: {{ t: 10 }} }}, {{ responsive: true }});
|
|
</script>
|
|
"#,
|
|
);
|
|
}
|
|
|
|
fn write_importance_chart(html: &mut String, importance: &[(String, f64)]) {
|
|
let names: Vec<_> = importance.iter().map(|(n, _)| format!("\"{n}\"")).collect();
|
|
let values: Vec<f64> = importance.iter().map(|(_, v)| *v).collect();
|
|
|
|
let _ = write!(
|
|
html,
|
|
r##"<script>
|
|
Plotly.newPlot("importance", [{{
|
|
x: {values:?}, y: [{names}], type: "bar", orientation: "h",
|
|
marker: {{ color: "#9b59b6" }}
|
|
}}], {{ xaxis: {{ title: "Importance (|Spearman correlation|)" }},
|
|
yaxis: {{ automargin: true }}, margin: {{ t: 10, l: 120 }} }},
|
|
{{ responsive: true }});
|
|
</script>
|
|
"##,
|
|
names = names.join(","),
|
|
);
|
|
}
|
|
|
|
fn write_timeline_chart(html: &mut String, trials: &[CompletedTrial<f64>]) {
|
|
let mut ids = Vec::with_capacity(trials.len());
|
|
let mut colors = Vec::with_capacity(trials.len());
|
|
let mut labels = Vec::with_capacity(trials.len());
|
|
|
|
for t in trials {
|
|
ids.push(format!("\"Trial {}\"", t.id));
|
|
let (color, label) = match t.state {
|
|
TrialState::Complete => ("#2ecc71", "Complete"),
|
|
TrialState::Pruned => ("#f39c12", "Pruned"),
|
|
TrialState::Failed => ("#e74c3c", "Failed"),
|
|
TrialState::Running => ("#3498db", "Running"),
|
|
};
|
|
colors.push(format!("\"{color}\""));
|
|
labels.push(format!("\"{label}\""));
|
|
}
|
|
|
|
// Use trial index as a proxy for duration (no wallclock data available).
|
|
let indices: Vec<usize> = (0..trials.len()).collect();
|
|
|
|
let _ = write!(
|
|
html,
|
|
r#"<script>
|
|
Plotly.newPlot("timeline", [{{
|
|
y: [{ids}], x: {indices:?}, type: "bar", orientation: "h",
|
|
text: [{labels}], textposition: "auto",
|
|
marker: {{ color: [{colors}] }}
|
|
}}], {{ xaxis: {{ title: "Trial Index" }}, yaxis: {{ automargin: true, autorange: "reversed" }},
|
|
margin: {{ t: 10, l: 80 }}, showlegend: false }},
|
|
{{ responsive: true }});
|
|
</script>
|
|
"#,
|
|
ids = ids.join(","),
|
|
colors = colors.join(","),
|
|
labels = labels.join(","),
|
|
);
|
|
}
|
|
|
|
fn write_intermediate_chart(html: &mut String, trials: &[CompletedTrial<f64>]) {
|
|
let trials_with_iv: Vec<_> = trials
|
|
.iter()
|
|
.filter(|t| !t.intermediate_values.is_empty())
|
|
.collect();
|
|
if trials_with_iv.is_empty() {
|
|
return;
|
|
}
|
|
|
|
let mut traces = String::new();
|
|
for t in &trials_with_iv {
|
|
let steps: Vec<u64> = t.intermediate_values.iter().map(|(s, _)| *s).collect();
|
|
let values: Vec<f64> = t.intermediate_values.iter().map(|(_, v)| *v).collect();
|
|
let color = match t.state {
|
|
TrialState::Pruned => "#f39c12",
|
|
_ => "#3498db",
|
|
};
|
|
let _ = write!(
|
|
traces,
|
|
r#"{{ x: {steps:?}, y: {values:?}, mode: "lines+markers", name: "Trial {id}",
|
|
line: {{ color: "{color}", width: 1 }}, marker: {{ size: 3 }} }},"#,
|
|
id = t.id,
|
|
);
|
|
}
|
|
|
|
let _ = write!(
|
|
html,
|
|
r#"<script>
|
|
Plotly.newPlot("intermediate", [{traces}],
|
|
{{ xaxis: {{ title: "Step" }}, yaxis: {{ title: "Intermediate Value" }},
|
|
margin: {{ t: 10 }}, showlegend: true }},
|
|
{{ responsive: true }});
|
|
</script>
|
|
"#,
|
|
);
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Helpers
|
|
// ---------------------------------------------------------------------------
|
|
|
|
#[allow(clippy::cast_precision_loss)]
|
|
fn param_value_to_f64(pv: &ParamValue) -> f64 {
|
|
match *pv {
|
|
ParamValue::Float(v) => v,
|
|
ParamValue::Int(v) => v as f64,
|
|
ParamValue::Categorical(v) => v as f64,
|
|
}
|
|
}
|
|
|
|
fn escape_js(s: &str) -> String {
|
|
s.replace('\\', "\\\\")
|
|
.replace('"', "\\\"")
|
|
.replace('\n', "\\n")
|
|
}
|
|
|
|
fn min_max(vals: &[f64]) -> (f64, f64) {
|
|
let mut mn = f64::INFINITY;
|
|
let mut mx = f64::NEG_INFINITY;
|
|
for &v in vals {
|
|
if v < mn {
|
|
mn = v;
|
|
}
|
|
if v > mx {
|
|
mx = v;
|
|
}
|
|
}
|
|
(mn, mx)
|
|
}
|
|
|
|
/// Build Plotly annotation objects to act as subplot titles.
|
|
#[allow(clippy::cast_precision_loss)]
|
|
fn build_subplot_annotations(titles: &[String], rows: usize, cols: usize) -> String {
|
|
let mut anns = Vec::new();
|
|
for (i, title) in titles.iter().enumerate() {
|
|
let row = i / cols;
|
|
let col = i % cols;
|
|
// Compute x/y anchor in paper coordinates.
|
|
let x = if cols == 1 {
|
|
0.5
|
|
} else {
|
|
(f64::from(u32::try_from(col).unwrap_or(0))) / (cols as f64 - 1.0)
|
|
};
|
|
let y = 1.0 - (f64::from(u32::try_from(row).unwrap_or(0))) / (rows as f64).max(1.0) + 0.02;
|
|
anns.push(format!(
|
|
r#"{{ text: {title}, x: {x:.3}, y: {y:.3}, xref: "paper", yref: "paper",
|
|
showarrow: false, font: {{ size: 12 }} }}"#,
|
|
));
|
|
}
|
|
anns.join(",")
|
|
}
|