Publication Chart Skill

Goal

Use this skill to turn research results into publication-grade figures and tables.

Primary production stack:

• pubfig>=0.3.0 JSON CLI for figures
• pubtab for publication tables

Default delivery chain:

1. identify the scientific communication goal,
2. decide figure / table / mixed deliverable,
3. choose the strongest representation,
4. route to pubfig, pubtab, or both,
5. generate a runnable route,
6. export paper-ready assets,
7. run publication QA,
8. propose revisions when needed.

Use this skill when

Trigger this skill for requests like:

• “make a publication-quality figure”
• “choose the right chart for these results”
• “turn these results into a paper-ready figure”
• “make a benchmark / ablation / calibration / forest / heatmap / scatter / line / bar figure”
• “make a benchmark / appendix / ablation table from Excel”
• “convert this Excel table into publication-ready LaTeX”
• “prepare one summary figure plus one companion table for the results section”
• “review and improve this scientific figure/table”
• “I already have a weak chart / screenshot / draft plot — make it publication-ready”
• “export panels for a paper figure”

Do not use this skill for

Do not use this skill when the task is mainly:

• manuscript prose writing,
• statistical testing without artifact design,
• raw exploratory analysis with no publication deliverable,
• Figma-first layout work before the figure or table content is solid.

Composite assembly is a secondary branch. Do not escalate ordinary figure tasks into panel/Figma workflows by default.

Primary contract

Inputs

Expect some combination of:

• the scientific communication goal,
• available data shape,
• venue or style constraints,
• whether the artifact is a figure, table, or mixed deliverable,
• optional assets such as code, spreadsheets, .tex, screenshots, or draft plots,
• whether the task is first-draft generation, publication-ready export, or review/revision.

Minimum useful outputs

A strong response should provide:

• the recommended artifact form,
• the recommended pubfig CLI / pubtab route,
• a minimal runnable JSON spec, CLI command, or code snippet,
• explicit output filenames and formats,
• a publication QA summary,
• a revision plan when the current artifact is weak.

Default workflow

0. Probe environment and task state

Before generating anything, identify:

• whether pubfig>=0.3.0 or pubtab is available,
• whether the user already has code, spreadsheets, .tex, screenshots, or draft plots,
• whether the deliverable is fresh generation or revision,
• whether the result needs visual pattern perception, exact value lookup, or both.

Keep this step light. Prefer the bundled helper script when runnable execution matters.

If a required dependency is missing, install it into the active environment first. The canonical pip commands are:

• python -m pip install --upgrade "pubfig>=0.3.0"
• python -m pip install --upgrade pubtab

When the bundled helper script is available, it is still the preferred route:

• python3 scripts/ensure_publication_tooling.py --require pubfig --json
• python3 scripts/ensure_publication_tooling.py --require pubtab --json

After installation:

• re-check availability,
• continue with the runnable workflow if install succeeds,
• otherwise degrade to a design/specification answer instead of failing.

For uv-managed and other fallback variants, see references/execution-and-verification.md.

1. Classify the task

Classify along these axes:

• artifact type — figure / table / mixed deliverable
• maturity — exploratory draft / publication-ready generation / revision
• structure — single panel / multi-panel / figure-plus-table package
• evidence mode — pattern perception / exact lookup / both

Do not jump into plotting before the communication target is clear.

2. Choose the representation

Choose the representation from the scientific claim, not from visual novelty.

Useful families:

• comparison — grouped scatter, bar, line comparison, benchmark summary, companion table
• ablation — grouped comparison, dumbbell, paired comparison, compact table
• distribution — box, violin, raincloud, histogram, density, ECDF, QQ
• relationship — scatter, bubble, contour2d, hexbin
• trend — line, area
• evaluation / diagnostic — calibration, ROC, PR, Bland–Altman, forest plot, volcano
• composition / hierarchy — UpSet, stacked ratio, donut, radial hierarchy, circular grouped or stacked bars
• table — benchmark table, ablation table, dataset summary, appendix table, error breakdown

Avoid weak defaults:

• avoid pie/donut when a bar or table communicates exact comparison better,
• avoid radar unless the claim is genuinely low-cardinality and profile-like,
• avoid 3D, decorative gradients, and style-only complexity,
• avoid forcing exact-value heavy results into a figure when a table is stronger.

For detailed task-to-chart rules, read references/chart-selection.md.

3. Map to the toolchain

Default mapping:

• Figures → pubfig>=0.3.0 JSON CLI by default
• Tables → pubtab
• Mixed deliverables → use both, with distinct communication roles

Route rules:

• prefer the pubfig JSON CLI for agent-generated figures,
• use pubfig Python API only when the user is explicitly working in a notebook/script or needs unsupported custom logic,
• prefer pubtab CLI for file-driven table workflows,
• keep figure and table responsibilities separate in mixed requests,
• treat panel export / composite assembly as optional downstream work.

For exact route selection and verification behavior, see:

• references/workflow.md
• references/execution-and-verification.md
• references/pubfig-recipes.md
• references/pubtab-recipes.md

4. Generate the smallest runnable artifact

Prefer the smallest production-ready route first:

• for figures: one figure.spec.json plus pubfig validate-spec and pubfig render,
• for tables: one pubtab route that produces a previewable .tex or rendered preview,
• for mixed requests: one figure route plus one table route, clearly separated.

Keep filenames and export formats explicit.

For figure-specific export patterns such as save_figure, batch_export, and export_panels, use references/pubfig-recipes.md.

5. Define the delivery contract

For every response, make these explicit when possible:

• the scientific claim the artifact supports,
• which artifact type was chosen and why,
• which part is handled by pubfig and which by pubtab,
• output filenames and formats,
• whether the artifact is draft / final / revision,
• what still needs user-provided data or manuscript context.

6. Run publication QA

After generation, check:

• title and legend density,
• axis labels and units,
• category ordering and baseline clarity,
• color accessibility and grayscale robustness,
• font and line-weight consistency,
• caption readiness,
• readability after downscaling,
• panel consistency for multi-panel exports,
• venue-fit issues such as width, crowding, or over-annotation.

The QA output must be concrete. Name the actual issue and the actual fix.

For a fuller checklist, see references/publication-qa-checklist.md.

7. Revise when the result is weak

Typical revisions include:

• switching chart family,
• removing chartjunk,
• reordering categories,
• moving exact values into a table,
• splitting a crowded panel,
• simplifying or strengthening the caption,
• changing export width,
• converting the deliverable from figure-first to table-first.

Missing dependency behavior

If pubfig>=0.3.0 or pubtab is unavailable:

• do not fail immediately,
• try the bundled install/probe route first,
• report the dependency state clearly,
• continue with the runnable workflow after a successful install,
• otherwise provide a design/specification answer with pseudocode or draft