core: add interactive preview, auto-layout heuristics, crosshair option, and fan/violin uncertainty helpers

watsonryan · watsonryan · commit e22605886e46 · 2026-02-25T16:28:32.000Z
diff --git a/include/gnuplotpp/plot.hpp b/include/gnuplotpp/plot.hpp
@@ -65,6 +65,8 @@ struct FigureSpec {
   bool share_x = false;
   bool share_y = false;
   bool hide_inner_tick_labels = false;
+  bool auto_layout = true;
+  bool interactive_preview = false;
 };
 
 /** @brief Legend placement presets. */
@@ -127,6 +129,7 @@ struct AxesSpec {
   bool grid = false;
   bool legend = true;
   LegendSpec legend_spec{};
+  bool enable_crosshair = false;
 
   bool has_xlim = false;
   double xmin = 0.0;
diff --git a/include/gnuplotpp/statistics.hpp b/include/gnuplotpp/statistics.hpp
@@ -40,6 +40,30 @@ void percentile_band(const std::vector<std::vector<double>>& ensemble,
                      std::vector<double>& low,
                      std::vector<double>& high);
 
+/**
+ * @brief Build multiple percentile ribbons for fan-chart visualization.
+ * @param ensemble Row-major series vectors with equal length.
+ * @param quantiles Ascending quantiles in (0,1), e.g. {0.1,0.25,0.75,0.9}.
+ * @param lows Output low bands matching each ribbon.
+ * @param highs Output high bands matching each ribbon.
+ */
+void fan_chart_bands(const std::vector<std::vector<double>>& ensemble,
+                     const std::vector<double>& quantiles,
+                     std::vector<std::vector<double>>& lows,
+                     std::vector<std::vector<double>>& highs);
+
+/**
+ * @brief Approximate violin density profile.
+ * @param samples Input values.
+ * @param y_grid Output y positions.
+ * @param half_width Output normalized half-width density [0,1].
+ * @param points Number of y-grid points.
+ */
+void violin_profile(std::span<const double> samples,
+                    std::vector<double>& y_grid,
+                    std::vector<double>& half_width,
+                    std::size_t points = 120);
+
 /**
  * @brief Simple moving average.
  * @param y Input signal.
diff --git a/src/gnuplot_backend.cpp b/src/gnuplot_backend.cpp
@@ -375,6 +375,25 @@ void emit_typed_objects(std::ostream& os, const AxesSpec& axis_spec) {
   }
 }
 
+void emit_auto_layout(std::ostream& os, const FigureSpec& spec, const AxesSpec& axis_spec) {
+  if (!spec.auto_layout) {
+    return;
+  }
+  // Heuristic margins in character units for single-panel readability.
+  const std::size_t yl = axis_spec.ylabel.size();
+  const std::size_t y2l = axis_spec.y2label.size();
+  const std::size_t xl = axis_spec.xlabel.size();
+  const std::size_t tl = axis_spec.title.size();
+  const int lmargin = static_cast<int>(std::clamp<std::size_t>(8 + yl / 2, 8, 16));
+  const int rmargin = static_cast<int>(std::clamp<std::size_t>(4 + y2l / 2, 4, 14));
+  const int bmargin = static_cast<int>(std::clamp<std::size_t>(4 + xl / 10, 4, 8));
+  const int tmargin = static_cast<int>(std::clamp<std::size_t>(2 + tl / 18, 2, 6));
+  os << "set lmargin " << lmargin << "\n";
+  os << "set rmargin " << rmargin << "\n";
+  os << "set bmargin " << bmargin << "\n";
+  os << "set tmargin " << tmargin << "\n";
+}
+
 void emit_plot_body(std::ostream& os,
                     const Figure& fig,
                     const std::vector<std::vector<std::filesystem::path>>& data_files) {
@@ -422,6 +441,7 @@ void emit_plot_body(std::ostream& os,
   for (std::size_t axis_idx = 0; axis_idx < all_axes.size(); ++axis_idx) {
     const auto& axis = all_axes[axis_idx];
     const auto& axis_spec = axis.spec();
+    emit_auto_layout(os, spec, axis_spec);
 
     os << "unset title\n";
     os << "unset xlabel\n";
@@ -440,7 +460,12 @@ void emit_plot_body(std::ostream& os,
 
     const bool legend_enabled = axis_spec.legend && axis_spec.legend_spec.enabled;
     if (legend_enabled) {
-      os << "set key " << legend_position_token(axis_spec.legend_spec.position) << "\n";
+      LegendPosition legend_pos = axis_spec.legend_spec.position;
+      if (spec.auto_layout && axis.series().size() >= 4 &&
+          legend_pos == LegendPosition::TopRight) {
+        legend_pos = LegendPosition::OutsideRight;
+      }
+      os << "set key " << legend_position_token(legend_pos) << "\n";
       os << "set key maxcols " << std::max(1, axis_spec.legend_spec.columns) << "\n";
       os << "set key " << (axis_spec.legend_spec.opaque ? "opaque" : "noopaque") << "\n";
       os << "set key box linewidth " << (axis_spec.legend_spec.boxed ? "0.5" : "0.0") << "\n";
@@ -474,6 +499,12 @@ void emit_plot_body(std::ostream& os,
     if (axis_spec.grid || spec.style.grid) {
       os << "set grid xtics ytics linewidth 0.35 linecolor rgb '#e2e2e2'\n";
     }
+    if (axis_spec.enable_crosshair) {
+      os << "set mouse\n";
+      os << "set mxtics 4\n";
+      os << "set mytics 4\n";
+      os << "set grid mxtics mytics linewidth 0.25 linecolor rgb '#f0f0f0'\n";
+    }
     if (axis_spec.xlog) {
       os << "set logscale x\n";
     }
@@ -705,6 +736,19 @@ RenderResult GnuplotBackend::render(const Figure& fig, const std::filesystem::pa
     return result;
   }
 
+  if (fig.spec().interactive_preview) {
+    const auto preview_path = out_dir / "tmp" / "interactive_preview.gp";
+    std::ofstream preview_os(preview_path);
+    if (preview_os.is_open()) {
+      preview_os << "set encoding utf8\n";
+      preview_os << "set terminal qt persist\n";
+      emit_plot_body(preview_os, fig, data_files);
+      preview_os << "pause mouse close\n";
+    } else {
+      gnuplotpp::log::Warn("failed to write interactive preview script: ", preview_path.string());
+    }
+  }
+
   const std::string check_cmd = "command -v " + executable_ + " >/dev/null 2>&1";
   if (std::system(check_cmd.c_str()) != 0) {
     result.ok = false;
diff --git a/src/statistics.cpp b/src/statistics.cpp
@@ -84,6 +84,50 @@ void percentile_band(const std::vector<std::vector<double>>& ensemble,
   }
 }
 
+void fan_chart_bands(const std::vector<std::vector<double>>& ensemble,
+                     const std::vector<double>& quantiles,
+                     std::vector<std::vector<double>>& lows,
+                     std::vector<std::vector<double>>& highs) {
+  lows.clear();
+  highs.clear();
+  if (quantiles.size() < 2 || quantiles.size() % 2 != 0) {
+    return;
+  }
+  const std::size_t half = quantiles.size() / 2;
+  lows.resize(half);
+  highs.resize(half);
+  for (std::size_t i = 0; i < half; ++i) {
+    const double ql = quantiles[i];
+    const double qh = quantiles[quantiles.size() - 1 - i];
+    percentile_band(ensemble, ql, qh, lows[i], highs[i]);
+  }
+}
+
+void violin_profile(std::span<const double> samples,
+                    std::vector<double>& y_grid,
+                    std::vector<double>& half_width,
+                    std::size_t points) {
+  y_grid.clear();
+  half_width.clear();
+  if (samples.empty() || points < 2) {
+    return;
+  }
+  const auto [it_min, it_max] = std::minmax_element(samples.begin(), samples.end());
+  const double y_min = *it_min;
+  const double y_max = *it_max;
+  y_grid.resize(points);
+  for (std::size_t i = 0; i < points; ++i) {
+    y_grid[i] = y_min + (y_max - y_min) * static_cast<double>(i) / static_cast<double>(points - 1);
+  }
+  half_width = gaussian_kde(samples, y_grid);
+  const double peak = *std::max_element(half_width.begin(), half_width.end());
+  if (peak > 0.0) {
+    for (double& v : half_width) {
+      v /= peak;
+    }
+  }
+}
+
 std::vector<double> moving_average(std::span<const double> y, std::size_t window) {
   if (y.empty() || window == 0) {
     return {};
