Visualization And Report Generation

Use the report CLI when you want stable saved artifacts. Use the plotting helpers when you want ad hoc analysis inside Python.

Stable report entry points

python -m zeroproofml.report benchmark results/benchmarks/<domain>/<run_dir> --html-report
python -m zeroproofml.report bundle path/to/bundle_dir
python -m zeroproofml.report training-log runs/scm_train_metrics.jsonl

Those three modes cover the maintained reporting surfaces:

  • benchmark: refreshes RUN_REPORT.md, optional RUN_REPORT.html, per-seed distribution plots, and baseline-delta plots when paired stats are present
  • bundle: writes VALIDATION_REPORT.md plus bundle summary artifacts
  • training-log: writes a Markdown summary plus <stem>_REPORT_metrics.svg

If Plotly is installed through zeroproofml[interactive], the training-log path also writes <stem>_REPORT.html.

What the report CLI is for

Prefer the CLI when you need artifacts that can be checked into a run directory, attached to release notes, or handed to operators. Bundle and benchmark report regeneration also discover nearby saved sidecars so the report stays tied to the artifact directory rather than the local machine. Benchmark reports always include metric means and per-seed distribution figures; when aggregated/paired_stats.json contains baseline deltas, they also include figures/baseline_delta.svg.

Direct plotting helpers

zeroproofml.utils.viz is the lightweight plotting layer for notebooks and one-off analysis. Useful strict-inference and deployment plots include:

  • plot_denominator_hist(...)
  • plot_tau_infer_sweep(...)
  • plot_tau_train_sweep(...)
  • plot_2d_mask_map(...)
  • plot_3d_mask_map(...)
  • plot_workspace_rate_heatmaps(...)
  • plot_route_to_solver_overlay(...)
  • plot_fallback_route_timeline(...)
  • plot_monitoring_batch_summary(...)

These helpers are intentionally experimental; the stable contract is the saved artifact format produced by the report CLI.

Composability Figure Packs

For downstream composability experiments, the maintained saved-artifact path is zeroproofml.downstream_pipeline.write_downstream_pipeline_visualization_pack(...). It writes composability_figure_pack/ with:

  • DOWNSTREAM_PIPELINE_STAGE_SUMMARY.json and .csv
  • stage_transition_diagram.svg
  • failure_propagation_diagram.svg
  • corruption_sensitivity_curves.svg
  • manifest.json

Use the pack when you need per-stage transition diagrams or failure-propagation evidence without rebuilding plots in a notebook.

Live telemetry and CSV exports

For ROS 2 dashboards, the companion workspace publishes a stable numeric telemetry vector on telemetry_topic and can flatten the same data into named CSV columns through write_visualization_telemetry_csv(...). Use that path when Foxglove, PlotJuggler, or another live dashboard should consume the strict-inference rates without parsing custom messages.