craft-scientific-figures

name

craft-scientific-figures

description

Create, redesign, or audit publication-ready scientific figures with deterministic Python, especially Matplotlib and NetworkX. Use for journal or conference plots, directed-network diagrams, theory schematics, multi-panel figures, IEEE-width redraws, vector export, visual hierarchy, color-accessibility, and final-size figure QA. Trigger when exact data, equations, topology, geometry, or scientific meaning must be preserved; do not use generative imagery for quantitative evidence.

Craft Scientific Figures

Create figures that communicate one scientific claim at their final publication size. Preserve exact data and mathematical semantics, use editable vector output, and keep the source script reproducible.

Workflow

1. Inspect the source figure, manuscript context, caption, data, and target venue. Treat source data as read-only and write derived artifacts separately.
2. Write a short figure contract before coding:
   • one-sentence claim;
   • exact quantitative figure or conceptual schematic;
   • intended audience and target single- or double-column width;
   • panel map and reading order;
   • must-preserve data, topology, labels, symbols, and equations;
   • semantic encodings for color, shape, line style, and arrow direction;
   • source and provenance for every visual element.
3. Apply the exactness gate:
   • Use deterministic local Python for measured values, axes, equations, graph topology, directed edges, scientific geometry, and theory diagrams.
   • Never fabricate data or alter topology for visual convenience.
   • Do not use generative raster imagery as quantitative evidence.
4. Build the figure with explicit hierarchy. Prefer small multiples or a clear panel sequence. For small semantic networks, use fixed coordinates instead of an automatic layout.
5. Export editable PDF and SVG, plus a high-resolution PNG, from the same script.
6. Render and inspect the figure at final manuscript size. Run the automated checks, then visually verify clipping, overlaps, arrow direction, line visibility, grayscale meaning, and caption consistency.

Read references/design-rules.md for the figure contract, IEEE dimensions, network-diagram rules, and visual QA checklist. Read references/sources.md when provenance, third-party inspiration, or licensing matters.

Python Tools

Use scripts/science_style.py as a reusable style/export module:

from science_style import apply_ieee_style, export_figure, figure_size

apply_ieee_style()
fig, ax = plt.subplots(figsize=figure_size("double", aspect=0.38))
# draw deterministically
export_figure(fig, output_dir / "figure_01", dpi=600)

Run the figure QA tool after export:

python scripts/figure_qa.py --stem path/to/figure_01 --expected-width-in 7.16 --min-dpi 300

The QA script checks file presence, PDF page size, raster density, and basic grayscale range. It does not prove semantic correctness; visual inspection remains required.

Design Requirements

• Lead with the claim, not decorative styling.
• Use a restrained, color-vision-safe palette and redundant non-color encoding.
• Keep text horizontal and readable at final size; avoid legends when direct labeling is clearer.
• Match mathematical symbols and graph orientation exactly to the manuscript.
• Use visual weight to distinguish evidence, mechanism, and annotation.
• Remove repeated labels, unexplained colors, shadows, gradients, and chart junk.
• For directed networks, make source/sink boundaries, feedback cycles, SCC membership, and arrow direction unmistakable.
• Do not rely on tight_layout to repair a poorly specified diagram; reserve margins deliberately and inspect curved arrows after export.

Deliverables

Return:

• the figure contract;
• a reproducible Python source file;
• vector PDF and SVG;
• a high-resolution PNG preview;
• a concise QA report, including any judgment that still requires human verification.