figrecipe 0.24.0

Reproducible matplotlib wrapper with mm-precision layouts

FigRecipe (scitex-plt)

Reproducible scientific figures as first-class objects

Full Documentation · pip install figrecipe

---

Reproducible, editable, publication-ready scientific figures. Part of SciTeX.

SciTeX users: pip install scitex[plt] includes FigRecipe. scitex.plt delegates to figrecipe — they share the same API.

Overview

FigRecipe treats recipe, data, and style as first-class attributes of every figure. This enables data governance and style editing without losing scientific rigor.

_{Created with Schematic Diagrams}

Styling

FigRecipe provides millimeter-precise control over every visual element. The SCITEX style preset is applied by default, producing publication-ready figures with standard matplotlib plotting.

Millimeter-based Layout

fig, ax = fr.subplots(
    axes_width_mm=60,
    axes_height_mm=40,
    margin_left_mm=15,
)

Style Presets

fr.load_style("SCITEX")       # Publication defaults
fr.load_style("SCITEX_DARK")  # Dark theme
fr.load_style("MATPLOTLIB")   # Pure Matplotlib

GUI Editor

For precise adjustments, GUI editor is available.

Migration from Matplotlib

Matplotlib-compatibility

FigRecipe is a drop-in replacement for matplotlib — just change your import:

# Before
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot(x, y)
plt.savefig("fig.png")

# After
import figrecipe as fr
fig, ax = fr.subplots()
ax.plot(x, y, id="my_trace")
fr.save(fig, "fig.png")  # → fig.png + fig.yaml + fig_data/

Systematic Migration

scitex-linter detects and auto-fixes matplotlib patterns into mm-based FigRecipe equivalents (check, format, python). It also works as a pre-commit hook, ensuring AI agents follow FigRecipe conventions.

Schematic Diagrams

Create publication-quality box-and-arrow schematics with mm-based coordinates. See Overview for an example output.

Usage & Validation Rules

s = fr.Schematic(title="EEG Analysis Pipeline", width_mm=170, height_mm=100)
s.add_box("raw", "Raw EEG", subtitle="64 ch", emphasis="muted")
s.add_box("filter", "Bandpass Filter", subtitle="0.5-45 Hz", emphasis="primary")
s.add_box("ica", "ICA", subtitle="Artifact removal", emphasis="primary")
s.add_arrow("raw", "filter")
s.add_arrow("filter", "ica")
s.auto_layout(layout="lr", gap_mm=15)

fig, ax = fr.subplots()
ax.schematic(s, id="pipeline")
fr.save(fig, "pipeline.png")

Available shapes: rounded (default), box, stadium, cylinder (database), document (paper), file (folder), codeblock (terminal window). Use node_class for semantic defaults: "code" → codeblock, "input" → cylinder, "claim" → document.

All rules are enforced automatically on render. Errors are collected and reported together:

Rule	Check	Severity
W	Width exceeds 185 mm (double-column max)	UserWarning
R1	Container must enclose all children	ValueError
R2	No two boxes may overlap	ValueError
R3	Container title must clear children (5 mm zone)	UserWarning
R4	Box text must fit within padded inner area	UserWarning
R5	Text-to-text margin >= 2 mm	ValueError
R6	Text-to-edge margin >= 2 mm	ValueError
R7	Arrow visible-length ratio >= 90%	ValueError
R8	Curved-arrow label on same side as arc	ValueError

When validation fails, figures are still saved with a _FAILED suffix for inspection.

Three Interfaces

🐍 Python API

Create and save — standard matplotlib API with auto-recording:

import figrecipe as fr
import numpy as np

fig, ax = fr.subplots()
ax.plot(np.sin(np.linspace(0, 10, 100)), id="sine")
fr.save(fig, "figure.png")  # Saves + validates pixel-identical reproduction

Output:

figure.png                # Publication-ready image
figure.yaml               # Reproducible recipe (validated on save)
figure_data/
  sine.csv                # Plot data (one CSV per trace)

Save / Load Formats — from recipe or bundle:

fr.save(fig, "fig.png")     # fig.png + fig.yaml
fr.save(fig, "fig.zip")     # self-contained zip bundle
fr.load("fig.png")          # reload from any format

Format	Save	Load
PNG / PDF / SVG	✓	✓
YAML	✓	✓
Directory / ZIP	✓	✓

Reproduce and edit — from recipe or bundle:

fig, ax = fr.reproduce("figure.yaml")
fr.gui(fig)  # Launch visual editor (at http://127.0.0.1:5050 by default)

Compose — multi-panel figures:

fr.compose(
    sources=["panel_a.yaml", "panel_b.yaml"],
    output_path="composed.png",
    layout="horizontal",
)

Statistics — significance brackets:

ax.add_stat_annotation(x1=0, x2=1, p_value=0.01, style="stars")

Full API reference

🖥️ CLI Commands

figrecipe --help-recursive            # Show all commands
figrecipe reproduce fig.yaml          # Recreate figure from recipe
figrecipe gui figure.png              # Launch visual editor
figrecipe validate fig.yaml           # Verify pixel-identical reproduction
figrecipe extract fig.yaml            # Extract plotted data as CSV
figrecipe compose a.yaml b.yaml       # Compose multi-panel figure
figrecipe crop figure.png             # Auto-crop whitespace
figrecipe info fig.yaml               # Show recipe metadata

Full CLI reference

🔧 MCP Server — for AI Agents

AI agents can create, compose, and reproduce publication-ready figures autonomously.

Tool	Description
plot	Create figure from declarative YAML spec
reproduce	Recreate figure from recipe
compose	Combine panels into multi-panel layout
crop	Auto-crop whitespace
info	Inspect recipe metadata
validate	Verify reproduction fidelity

# Install to Claude Code
figrecipe mcp install

Full MCP specification

47 matplotlib plot types supported

Category	Plot Types
Line & Curve	plot, step, fill, fill_between, fill_betweenx, errorbar, stackplot, stairs
Scatter & Points	scatter
Bar & Categorical	bar, barh
Distribution	hist, hist2d, boxplot, violinplot, ecdf
2D Image & Matrix	imshow, matshow, pcolor, pcolormesh, hexbin, spy
Contour & Surface	contour, contourf, tricontour, tricontourf, tripcolor, triplot
Spectral & Signal	specgram, psd, csd, cohere, angle_spectrum, magnitude_spectrum, phase_spectrum, acorr, xcorr
Vector & Flow	quiver, barbs, streamplot
Special	pie, stem, eventplot, loglog, semilogx, semilogy, graph

---

AGPL-3.0