richard-evans/figures

figures — publication-quality gnuplot figures

Turn a natural-language request plus one or more data files into a paper-ready PDF figure in the group house style. Handles the common magnetism figure types, selectable colour schemes, and journal vs presentation styling.

Prerequisites

• gnuplot (v6+) — the plotting engine. Renders PDF directly via pdfcairo.
• pdftoppm (poppler) — convert the output PDF to PNG so you can look at the figure and iterate. Always visually check the result.

How styles/colours are loaded — GNUPLOT_LIB (important)

Scripts load shared style files by bare name, e.g. load "nature.journal" and load "bluegold.colour". gnuplot finds these via the GNUPLOT_LIB search path. Always run gnuplot with GNUPLOT_LIB pointing at this skill's styles/ and colours/ directories:

SKILL_DIR below is the absolute path to this skill's own directory (the one containing this SKILL.md, e.g. ~/.claude/skills/figures if installed personally, or the repo path during development). Substitute the real path:

SKILL_DIR="/absolute/path/to/figures"      # dir containing this SKILL.md
export GNUPLOT_LIB="$SKILL_DIR/styles:$SKILL_DIR/colours"
gnuplot myfigure.gpl                        # run from the dir holding the data

Keeping the paths out of the scripts means a script is portable and a change to a style file propagates to every figure that loads it.

Workflow

1. Identify the figure type from the request (see references/figure-types.md): hysteresis M(H), magnetisation M(T), time series M(t), or other. Each type has a canonical example script to copy.
2. Inspect the data. Look at the file: strip comment lines (#), count columns, check ranges. Map which columns are x and y. VAMPIRE output files are plain whitespace-separated columns with # comment headers; if a VAMPIRE input file is alongside the data, its output: keywords define the column order — read it to label columns correctly. Otherwise treat the data as generic columns and confirm the mapping with the user if ambiguous.
3. Copy the matching example from examples/<type>/ as a starting point and adapt: data filenames, using columns, axis labels + units, axis limits (5 % beyond the first and last major tick at both ends, via padlo/padhi or lpadlo/lpadhi from the journal file, see references/conventions.md), legend labels, and any fit.
4. Choose the style and colour scheme (defaults below; honour any explicit request). Set them via the two load lines at the top of the script.
5. Render with GNUPLOT_LIB set, producing a PDF.
6. Look at the output: convert with pdftoppm -png -r 150 out.pdf preview and read the PNG. Check for clipped labels, legend overlap, tick density, colour contrast. Iterate on the script until it is clean.
7. Hand back the .gpl script and the PDF. The figure must be reproducible from the script + data alone.

Defaults

• Style: nature.journal (86 mm single-column, Helvetica, print-ready).
• Colour scheme: bluegold.colour (the house default).
• Output: PDF via pdfcairo, direct — never the EPS→PDF pipeline.

Styles (styles/)

File	Use
nature.journal	Default. Single-column width (86 mm) for a two-column journal; light bg, Helvetica.
inverted.journal	Dark grey background, light foreground — dark slides/web.
presentation.journal	Avenir Next, large canvas — projected talk slides.
presentation-dark.journal	Presentation style on a dark background.

Colour schemes (colours/)

Default: bluegold, used unless another scheme is requested. Sequential/perceptual (matplotlib and MATLAB families): viridis, magma, inferno, plasma, cividis (colour-blind safe), parula. Diverging: bluegold, skyrmion (navy → white → red, for signed quantities such as s_z), RdYlBu. Single-hue: purple. Rainbow: turbo (improved), jet (discouraged — not perceptually uniform). Each defines discrete series line styles ls 1–ls 8 plus a continuous pm3d palette. See references/colour-schemes.md for when to use each and light/dark pairing.

Figure types & examples

Canonical, annotated, runnable scripts live in examples/:

• examples/mvsH/MH.gpl — hysteresis loop M(H), zero-axis guides.
• examples/mvsT/mvsT.gpl — magnetisation M(T) with Curie–Bloch fit.
• examples/mvstime/mvstime.gpl — multi-curve demagnetisation time series (synthetic data, regenerate with make_data.py).
• examples/anisotropy-surface/3D.gpl — 3D energy surface: raster colour + vector axes composited inside gnuplot (small, fast PDFs; no external tools).

References

• references/conventions.md — the house figure rules (labels, units, ticks, legends, fits, enhanced-text syntax).
• references/figure-types.md — per-type recipe and column mapping.
• references/colour-schemes.md — scheme catalogue and selection guide.