ai4s-research / publication-figures

Publication Figures and Tables

Make generated figures publication-grade and on-system by default. Every
figure you produce with matplotlib must use the bundled Open Science style, so a
figure in a report and a stat tile in the app read as one design system.
When a paper/survey skill or target venue specifies its own publication palette
and physical type scale, that more specific standard overrides this palette;
the final-size, collision, and figure-form rules below still apply.

Apply the style (always, before plotting)

The style file openscience.mplstyle sits next to this SKILL.md. Load it by
absolute path at the top of any figure script:

import matplotlib.pyplot as plt
from pathlib import Path

# This skill's directory — the style ships beside SKILL.md.
STYLE = Path(__file__).resolve().parent / "openscience.mplstyle" if "__file__" in dir() else None
# In a notebook/agent cell, use the skill's deployed path directly:
plt.style.use(str(STYLE)) if STYLE and STYLE.exists() else plt.style.use("default")

If you cannot resolve the path, set the palette inline (same hexes as below).

Choose a paper-appropriate form

• Use matplotlib/seaborn for quantitative evidence; use a purpose-built
  TikZ/SVG/PDF schematic for a method or architecture; use scientific image
  panels only with source, crop, scale, and processing provenance.

• Do not use Mermaid, PlantUML, generic flowchart/mind-map output, diagram-editor
  screenshots, or notebook/UI screenshots as a final paper figure. They may be
  scratch aids only. Graphviz is acceptable only when the graph itself is the
  analysed data, not as a shortcut for a generic process diagram.

• Every figure must make evidence, a mechanism, or an experimental design easier
  to understand. Decorative roadmaps, funnels, icon collages, and stock process
  diagrams do not belong in a paper.

The shared palette (single source of truth)

These are the exact hues the app's native charts use. Assign categorical series
in this fixed order — never a different order, never a cycled 9th hue.

Sequential (magnitude, one hue light→dark): `#cde2fb #9ec5f4 #6da7ec #3987e5
#256abf #184f95 #104281`. Diverging: blue ↔ red with a neutral gray midpoint.

Rules (from the app's dataviz standard)

• One y-axis. Never two scales on one plot — use two charts or index to a
  common base.

• **Categorical color = identity, assigned in slot order; sequential = one hue
  by magnitude; diverging = two hues + gray midpoint.** Never a rainbow.

• Thin marks, recessive chrome: 2px lines, ≥6pt markers, hairline y-grid
  only, no top/right spines (the style sets these).

• Label selectively — the endpoint or the extreme, never a number on every
  point. A legend is present for ≥2 series; a single series needs none (the
  title names it).

• Text stays in ink, never the series color. Identity comes from the mark.

• Fit by design, not tiny type. Size for the final column/page first. When
  labels compete for space, enlarge the canvas, wrap/shorten labels, show fewer
  ticks, move the legend, use a horizontal chart, or split panels. Do not shrink
  any text below 7 pt at final size.

• No collisions. Labels, ticks, legends, annotations, watermarks, panel
  letters, and data marks may not overlap or be clipped. Use constrained layout
  where appropriate, but always inspect the rendered result; an automatic
  layout call is not proof.

• Save clean: plt.savefig(path, bbox_inches="tight") (the style sets dpi).

Keep paper tables readable

• Design every table for its final column or page width. Body text must remain at
  least 8 pt at final size.

• Resolve an over-wide table in this order: shorten or wrap headings and move
  units/details into the caption or notes; use flexible text columns and aligned
  numeric columns; split the table or move secondary columns to an appendix; use
  landscape for a genuinely wide appendix table; reduce cell padding last.

• Do not solve width by scaling the entire table until it fits. If scaling would
  make text smaller than 8 pt, redesign or split the table.

• Keep precision purposeful, repeat units once, and avoid dense vertical rules.

• Render the containing PDF or page to an image at the intended output size and
  inspect it. A table fails if it crosses margins, clips content, overlaps text,
  or is readable only by zooming.

Final-size inspection

For PDF output, rasterize the actual final artifact before delivery:

pdftoppm -png -r 180 paper.pdf /tmp/paper-check/page

Inspect every page containing a generated figure or table. Source dimensions,
tight_layout, constrained_layout, and a successful compile are not evidence
that the rendered result is readable.

Checklist before returning a figure or table

1. Style applied (palette + chrome from openscience.mplstyle).
2. Series colors assigned in slot order; ≤8 series (else group into "Other").
3. Single y-axis; legend iff ≥2 series; axis labels + units present.
4. Figure form is appropriate for a paper; no Mermaid/PlantUML/generic diagram.

5. Table fits by structure rather than tiny type; final body text is at least
   8 pt.

6. Final PDF/page was rasterized and visually inspected: readable text, no
   overlap, clipping, or margin overflow.

7. Saved to the workspace and referenced by path so it surfaces as an artifact.