figrecipe 0.21.0

Reproducible matplotlib wrapper with mm-precision layouts

FigRecipe

Reproducible scientific figures as first-class objects

FigRecipe is a framework for creating reproducible, editable, and publication-ready scientific figures.

Instead of treating figures as static images, FigRecipe treats them as structured objects — with explicit data, layout, and style — that can be reproduced, edited, and shared.

Part of SciTeX™.

🤖 MCP Server — AI Agents Can Create Figures

FigRecipe includes an MCP (Model Context Protocol) server, enabling AI agents like Claude to create, compose, and reproduce publication-ready figures autonomously.

📄 Full MCP Demo (PDF)

▶️ Click to watch video demo

# Add to your Claude Code MCP config
figrecipe mcp install

Why FigRecipe?

Most scientific figures are created by code, but cannot be reproduced once the code is lost or modified.

FigRecipe solves this by separating:

• What is plotted (data & semantics)
• How it is styled (layout, colors, typography)
• How it is edited (GUI or code)

This makes figures: reproducible · inspectable · editable after publication

Quick Start

pip install figrecipe

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")  # → figure.png + figure.yaml

Reopen and edit later:

fig, ax = fr.load("figure.png")
fr.gui(fig)  # Launch GUI editor

CLI:

figrecipe gui figure.png       # Launch GUI editor
figrecipe reproduce fig.yaml   # Recreate figure
figrecipe extract fig.yaml     # Extract plotted data
figrecipe --help-recursive     # Show all commands

Bundle Format (for sharing)

Save as a self-contained ZIP bundle with layered architecture:

fr.save(fig, "figure.zip")  # → Layered bundle

# Bundle contains:
# - spec.json   (WHAT: semantic specification)
# - style.json  (HOW: appearance settings)
# - data.csv    (DATA: immutable source)
# - exports/    (PNG, hitmap)

Load and reproduce from bundle:

spec, style, data = fr.load_bundle("figure.zip")
fig, ax = fr.reproduce_bundle("figure.zip")

Documentation

📚 Full Documentation on Read the Docs

• Plot Gallery — Visual examples of all plot types
• CLI Reference — Complete command-line reference
• MCP Specification — AI agent integration guide
• Style Reference — Style parameters and anatomy

What Makes FigRecipe Different?

🔹 Figures are first-class objects — Figures are not just images — they are structured, versionable artifacts.

🔹 Declarative, not imperative — You describe what the figure is, not just how to draw it.

🔹 GUI + Code coexist — The GUI is a frontend, not a black box. Everything is backed by a reproducible spec.

🔹 Millimeter-precise layout — Designed for journal figures, not dashboards.

🔹 MCP Server for AI agents — Let Claude and other AI agents create publication-ready figures autonomously.

Core Features

• Drop-in replacement for matplotlib.pyplot
• Fully reproducible figure recipes (.yaml)
• Publication-ready millimeter layout
• Interactive GUI editor
• Dark / light themes
• Works with existing matplotlib code

Save / Load Formats

fr.save(fig, "fig.png")     # fig.png + fig.yaml
fr.save(fig, "bundle/")     # directory bundle
fr.save(fig, "fig.zip")     # zip bundle

fr.load("fig.png")
fr.load("bundle/")
fr.load("fig.zip")

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

Style Presets

fr.list_presets()
fr.load_style("SCITEX")
fr.load_style("SCITEX_DARK")

Millimeter-based Layout

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

Figure Captions

fig.set_caption("Main figure description")
ax.set_caption("Panel A description")

Figure Composition

Combine multiple figures into publication-ready layouts:

import figrecipe as fr

# Grid-based layout (auto-arranged)
fr.compose(
    sources=["panel_a.png", "panel_b.png", "panel_c.png"],
    output_path="figure.png",
    layout="horizontal",  # or "vertical", "grid"
    gap_mm=5.0,
)

# Free-form mm-based positioning (precise control)
fr.compose(
    canvas_size_mm=(180, 120),
    sources={
        "panel_a.yaml": {"xy_mm": (0, 0), "size_mm": (80, 50)},
        "panel_b.yaml": {"xy_mm": (90, 0), "size_mm": (80, 50)},
        "panel_c.yaml": {"xy_mm": (0, 60), "size_mm": (170, 50)},
    },
    output_path="figure.png",
)

Key features:

• Auto panel labels (A, B, C...)
• Saves .compose.yaml recipe for future re-composition
• Edit positions later with fr.recompose()
• All layouts internally use mm-based positioning

Who Is This For?

FigRecipe is designed for researchers who:

• already use matplotlib or seaborn
• care about reproducibility and traceability
• want figures that survive revisions and collaboration
• are tired of re-writing plotting code

It is not meant to replace exploratory notebooks or quick plotting — it is meant to formalize results.

Style Granularity

FigRecipe provides millimeter-precise control over every visual element with the SCITEX style preset:

Includes statistical annotation brackets with significance stars (*, **, ***) for publication-ready comparisons.

Plot Gallery

FigRecipe supports 47 matplotlib plot types with publication-ready SCITEX styling:

Supported 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

Philosophy

A scientific figure is not an image. It is a structured representation of knowledge.

FigRecipe treats figures as first-class scientific objects.

---

AGPL-3.0 · [e-mail]