Paper Figures

Paper Figures

A structured approach to producing publication-ready chart figures (PNG) from tabular data plus a natural-language description, using matplotlib.

When to Use This Skill

• User provides a CSV / dataframe / inline data and asks for a chart
• User describes a target figure in words and wants it rendered
• User mentions "figure", "plot", "chart", "visualize", "render" for a paper or experiment

Inputs and Output

Inputs the agent will receive:

• A data source: CSV file path, JSON, or inline table.
• A description: natural-language text specifying chart type, axes, title, colors, annotations, legend, scenarios, etc. Sometimes terse, sometimes a full paragraph. The description is the full specification — no reference image is provided.

Output (always):

• A standalone Python script plot.py that:
  • Loads the data from the provided source
  • Renders the figure with matplotlib
  • Saves a PNG via plt.savefig(..., dpi=300, bbox_inches="tight")
• The rendered plot.png next to it (the script is run and the PNG produced — do not stop at the script).

Verification artifacts (write when filesystem access is available):

• figure-spec.md — the compact figure specification extracted before coding.
• audit.md — the post-render audit checklist and any repairs made.
• final-status.md — one visible status label: PASSED, PASSED_WITH_WARNINGS, REPAIRED, or FAILED_NEEDS_HANDOFF.

Output directory:

• If the user specifies an output directory (e.g. "save to path/to/dir/"), write plot.py and plot.png inside that directory. Create the directory if it does not exist.
• If no directory is given, write to the current working directory.
• The two filenames are always plot.py and plot.png. Repeated runs on different inputs go to different directories, not different filenames — this keeps the script reference inside the PNG's neighbourhood stable and makes batch comparison easy.

Setup

Dependencies: pip install matplotlib pandas numpy scipy (also listed in requirements.txt at the skill root). Install into the environment the user is working in.

Core Workflow

Step 1: Plan Figure                      -> verify: description/data ambiguity handled
Step 2: Inspect the data
Step 3: Write figure-spec.md             -> verify: figure-spec.md has all required fields
Step 4: Pick the matplotlib idiom
Step 5: Apply publication-style defaults
Step 6: Write the script and run it      -> verify: plot.py runs and plot.png exists
Step 7: Audit the result                 -> verify: chart matches spec, data, and description;
                                            repair and re-audit until it does; final-status.md is honest

Treat the workflow as a small validation protocol, not a one-shot drawing task. The chart is done only after the audit passes or after you explicitly mark the remaining gap.

Status Labels

Use exactly one final status:

Do not award PASSED because the script ran. Running only proves the PNG exists; it does not prove the figure matches the request.

Step 1: Plan Figure

Before writing any code, identify from the description:

• Chart type (line, bar, scatter, pie, KDE, violin, bubble, tornado, ring, heatmap, …). If ambiguous, prefer the type explicitly named; otherwise infer from the axes/data shape.
• Axes: x-label, y-label, units, scale (linear/log), tick formatting. Watch for shared axes across subplots, twin axes (ax.twinx() / ax.twiny()) when two series share an x but have different y-units, and dual / broken axes when ranges span very different magnitudes.
• Title: use the title verbatim if quoted in the description.
• Series / categories: how many, names, ordering.
• Colors: any specific colors named (use them); otherwise apply the default palette.
• Annotations: legend, gridlines, reference lines, data labels.

If the description references quantities ("around 200", "just above 0"), use those as sanity checks against the CSV — descriptions are paraphrased, the CSV is authoritative.

A few patterns that show up repeatedly:

• Title context for cross-sections: if the data is a snapshot (a single year, a single experiment), put that context in the title itself — as a parenthetical, comma-separated suffix, or quoted prefix. Don't add a separate "subtitle" via fig.text or similar; matplotlib has no clean subtitle API and ad-hoc subtitles tend to drift in alignment and style.
• Distinguish multi-series, but don't double-encode: when there is more than one series, the reader must be able to tell them apart — via direct end-of-line labels, a legend, or distinct linestyles paired with a legend. Don't double up (legend AND end-of-line labels for the same series; legend entry AND on-plot text annotation for the same point or region), but don't drop everything either: producing multiple curves with no key is never acceptable.
• Don't drop data silently: every series and data point in the input must either appear in the plot or be acknowledged. If a value is off-scale, annotate it at the edge. If a whole series is omitted, the description must justify it. Silent omission is a defect — the reader cannot tell what's missing from the plot alone.
• Don't invent uninvited elements; do compute what the description asks for: plot exactly what the description asks for, but no more. Don't add legend entries, annotations, or visual elements the brief didn't request. Don't synthesise extra rows the data doesn't have, and don't compute inferred summaries or aggregations the description doesn't mention. But: derived statistics that the description does ask for (quartiles, means, smoothed curves, regression fits, density estimates, and similar) are required, not forbidden — compute them faithfully.

If the request has a blocking ambiguity that changes the chart semantics (for example, two possible y variables or an unclear unit conversion), ask one specific question. If the ambiguity is only stylistic, choose the simpler option and record it in figure-spec.md.

Step 2: Inspect the data

Read the first ~10 rows and the column names before writing the plot code. The description gives semantic intent; the CSV gives the structural truth. When they disagree about column names, trust the CSV.

For multi-series data, check whether the data is long-form (one row per (series, x, y)) or wide-form (one column per series). Pivot or melt as needed.

Step 3: Write figure-spec.md

Before coding, write a compact Markdown spec. It is the contract the audit will check. Use this shape:

# Figure Spec

- chart_type:
- data_sources:
- rows_in_scope:
- data_columns:
- x_axis:
  - field:
  - label:
  - unit:
  - scale:
  - range:
- y_axis:
  - field:
  - label:
  - unit:
  - scale:
  - range:
- additional_axes:
- series_or_categories:
- category_order:
- color_mapping:
- size_mapping:
- legend:
- required_annotations:
- forbidden_elements:
- layout_constraints:
- source_note:
- assumptions:

Rules:

• scale must be explicit for every numeric axis (linear, log, symlog, etc.).
• forbidden_elements must include visual elements that are tempting but not requested, such as regression lines, diagonal reference lines, all-point labels, extra size legends, or aggregation.
• category_order must preserve the description order when one is given. Otherwise preserve data order unless sorting is explicitly requested.
• If you derive a statistic, aggregation, fitted line, or smoothed curve, name the calculation under assumptions.

Step 4: Pick the matplotlib idiom

See references/chart-types.md for a per-type recipe (one short matplotlib snippet per supported chart type). Read it when you need the right idiom for an unfamiliar type, or to refresh on a tricky one (tornado, ring, KDE).

Step 5: Apply publication-style defaults

See references/publication-style.md for size, fonts, palette, DPI, and savefig conventions. Apply these every time unless the description explicitly contradicts them.

Step 6: Write the script and run it

• Write the script.
• Execute it with python plot.py.
• Confirm the PNG was produced.
• If the script errors, fix and re-run before reporting completion.

When scripts/validate_figure.py is available, run it after rendering (the script path is relative to this skill's directory):

python scripts/validate_figure.py --output-dir <output-dir> --spec <output-dir>/figure-spec.md