plot-graph

name	plot-graph
description	Create polished SVG/PNG chart figures from experiment metrics, especially multi-panel bar charts for blog posts or reports. Use when asked to generate, revise, or verify a graph/plot/figure and visual correctness matters.

Plot Graph

Workflow

1. Use a plotting library.

• Prefer matplotlib, plotly, altair, or another real charting library.
• Do not hand-roll SVG geometry unless the chart itself requires custom vector logic.
• Do not use ImageMagick or Inkscape for normal chart export. Export SVG/PNG directly from the plotting library.

2. Choose the right metric before drawing.

• Do not mix incompatible metrics in one visual comparison.
• Separate single-worker throughput, aggregate throughput, wall-clock throughput, and token accounting.
• If a number is an estimate or probe result, label it as such in surrounding prose or the figure caption.
• If a metric is not comparable across models, either leave it out or use a separate panel with a clear label.

3. Make charts scannable.

• For multi-panel comparisons, keep one metric per panel.
• Use consistent model order across every panel.
• Keep the intended panel order explicit in source code. For example, if the narrative wants model-size context before throughput, place Parameters before Output tok/s rather than relying on whatever order the data file happens to use.
• Keep model names visible on the x-axis; do not add a redundant x-axis title.
• If every panel has a different y-scale, say so in the caption.
• Use a consistent highlight color for the best value in each panel and neutral gray for the others.
• Preserve units in titles or legends, for example Output tok/s, Parameters, Concurrency.

4. Choose the background deliberately.

• Before rendering, determine the target background. If the user has not specified one, ask whether they want light, dark, or a specific background color.
• For a specific background, accept a concrete color such as a hex value sampled from a reference page or brand asset.
• Keep the chart readable against that target: light backgrounds need dark text; dark backgrounds need light text.
• If using a dark chart block, make the main figure background match the target color, make the plot panels slightly lighter than the main background, and use muted-light grid/border colors.
• If the figure has rounded outer corners, make the outside corners transparent. Use display/physical units for the outer corner radius so corners stay circular rather than stretched by the figure aspect ratio.

5. Preserve geometry deliberately.

• If converting a one-row figure to a two-row figure, preserve the panel aspect ratio, not just the outer image dimensions.
• Use fixed physical panel dimensions when aspect ratio matters.
• Center incomplete rows instead of leaving them left-aligned.
• Add left/right padding inside each panel so edge bars do not touch the frame.
• Adjust spacing and bar width explicitly; do not rely on matplotlib defaults.
• Size the outer canvas to the chart content plus intentional margins. Do not leave large empty side gutters from an older wider layout.

6. Use robust visual details.

• Use rounded bar tops only if the corner radius is circular in display pixels. Data-unit rounding distorts with axis scaling.
• Keep the outer figure background transparent when the chart will sit in a page, but preserve the intended main chart block and plot panel backgrounds.
• Do not use savefig(..., transparent=True) if it makes axes patches transparent. Prefer fig.patch.set_alpha(0), ax.set_facecolor("#ffffff"), ax.patch.set_alpha(1), and normal savefig(...).
• Add a thin border around each plot area if the surrounding page background may vary.
• Derive y-axis upper bounds programmatically from data. A good default for bar charts is ymax = max_value / 0.9, so the tallest bar reaches 90% of the plot height.
• Keep only the useful y-axis tick labels. Often 0 is enough when bars are directly labeled.
• Put values above bars, and check labels do not collide with legends or panel borders.

7. Verify the rendered output.

• Always render both SVG and PNG when practical.
• Inspect the PNG visually before calling the chart finished.
• Check for label overlap, clipped bars, distorted aspect ratios, excessive whitespace, missing model labels, and stretched outer rounded corners.
• For transparent-corner figures, sample pixels in the rendered PNG: outer corners should be alpha 0, the main chart rectangle should match the target background, and panel interiors should match the chosen panel color.
• If possible, verify panel dimensions numerically when the user cares about aspect ratio.

Example Script

Use examples/render_comparison_chart.py as a starting point for blog-style multi-panel bar charts. It demonstrates:

• direct SVG/PNG export from matplotlib
• selectable light, dark, or custom target background
• transparent outer background outside an optional rounded chart block
• aspect-correct outer rounded corners
• bordered panels with theme-aware colors
• circular rounded bar tops
• data-derived y-limits with max bars at 90% height
• preserved panel aspect ratio in a 3-over-2 layout
• content-sized canvas with no stale side gutters
• visible x tick labels without redundant x-axis titles
• grouped bars for paired metrics such as per-worker and aggregate throughput