figrecipe 0.9.0

Reproducible matplotlib wrapper with mm-precision layouts

FigRecipe — Reproducible matplotlib figures with mm-precision layouts.

FigRecipe separates what is plotted (data) from how it is styled, storing both in a structured format. This enables reproducible figures with GUI editing while preserving scientific integrity, and allows AI integration in a scientifically rigorous manner. Ultimately, FigRecipe will bundle: (1) reproducible, style-editable figures, and (2) metadata such as statistical values—creating atomic, portable, and traceable scientific figure objects essential for automated research in the AI era.

FigRecipe is part of SciTeX™ (pending) – Research OS for reproducible science

---

Key Features

• ✅ Drop-in replacement for matplotlib.pyplot—minimal migration and learning cost
• ✅ All intermediate files use familiar formats (PNG/SVG/PDF/YAML/JSON)
• ✅ Import/Export to integrate with your existing workflow
• ✅ Millimeter-based layout (journal-ready)—difficult to achieve manually with matplotlib
• ✅ Publication-quality style presets
• ✅ Dark theme support (data colors preserved), with light theme export for journal compliance
• ✅ Research-focused features: automatic cropping, axis alignment, panel labels, and caption embedding
• ✅ Interactive GUI editor for manual adjustments

---

Examples

📓 View Demo Notebook on nbviewer (recommended)

Demo Videos — GUI Editor in action

Dark Mode	Change Color	Drag Panel

Move Legend	Undo/Redo	Toggle Theme

Hover Feedback	Edit Labels	Zoom Controls

Supported Plot Types — 46 matplotlib plot types in 9 categories

Line & Curve	Scatter	Distribution

Bar & Categorical	Contour & Surface	2D/Image/Matrix

Vector & Flow	Spectral & Signal	Special

Generate all plots: python examples/demo_plot_all.py

Installation

pip install figrecipe

# Optional extras
pip install figrecipe[seaborn]   # seaborn + pandas support
pip install figrecipe[imaging]   # image cropping (Pillow)
pip install figrecipe[all]       # all extras

# Optional: for PDF export from notebooks (SVG → PDF)
sudo apt install inkscape  # Linux
brew install inkscape      # macOS

Requirements: Python >= 3.9

Basic Usage

Recording & Saving

import figrecipe as fr
# import figrecipe.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)

fig, ax = fr.subplots() # or plt.subplots()
ax.plot(x, y, color='red', linewidth=2, id='sine_wave')
ax.set_xlabel('Time (s)')
ax.set_ylabel('Amplitude')

# Save image + recipe
img_path, yaml_path, result = fr.save(fig, 'figure.png')
# → creates: figure.png + figure.yaml

Supported I/O Formats — Save and load are fully symmetric

Save creates both image and recipe. Load finds recipe from any format:

# Save examples
fr.save(fig, 'figure.png')       # → figure.png + figure.yaml
fr.save(fig, 'figure.yaml')      # → figure.yaml + figure.png
fr.save(fig, 'figure_bundle/')   # → directory with recipe.yaml + figure.png
fr.save(fig, 'figure.zip')       # → ZIP containing recipe.yaml + figure.png

# Load examples (symmetric with save)
fig, ax = fr.load('figure.png')            # ← finds figure.yaml
fig, ax = fr.load('figure.yaml')           # ← direct
fig, ax = fr.load('figure_bundle/')        # ← finds recipe.yaml inside
fig, ax = fr.load('figure.zip')            # ← extracts recipe.yaml

# Edit also supports all formats
fr.edit('figure.png')  # Opens editor, finds figure.yaml

# Note: fr.reproduce() is an alias for fr.load()

Format	Save	Load	Notes
.png / .jpg / .jpeg	✓	✓	Creates/finds .yaml alongside
.pdf / .svg	✓	✓	Creates/finds .yaml alongside
.tif / .tiff	✓	✓	Creates/finds .yaml alongside
.yaml / .yml	✓	✓	Creates/finds image alongside
Directory (path/)	✓	✓	Bundle with recipe.yaml + image
.zip	✓	✓	ZIP bundle with recipe.yaml + image

Alternative save method:

fig.savefig('figure.png')                      # Same as fr.save()
fig.savefig('figure.png', save_recipe=False)   # Image only, no recipe

Reproducing a Figure

import figrecipe as fr

fig, ax = fr.reproduce('figure.yaml')  # Or .png, .pdf, directory/, .zip

Extracting Plotted Data

import figrecipe as fr

data = fr.extract_data('figure.yaml')
# {'sine_wave': {'x': array([...]), 'y': array([...])}}

Style Presets

fr.list_presets()
# ['MATPLOTLIB', 'SCITEX']

# Publication-quality preset (applied globally)
fr.load_style('SCITEX')
fig, ax = fr.subplots()

# Dark theme (UI-only, data colors preserved)
fr.load_style('SCITEX_DARK')
# or: fr.load_style('SCITEX', dark=True)

# Custom style
fr.load_style('/path/to/my_style.yaml')

See src/figrecipe/styles/presets/ for full examples.

Millimeter-Based Layout (Publication-Ready)

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

This guarantees consistent sizing across editors, exports, and journals.

Figure Legends (Scientific Captions)

Store publication-ready figure legends as metadata (not rendered on the figure):

fig, axes = fr.subplots(1, 2)

# Figure legend (main description)
fig.set_caption(
    "Comparison of treatment effects on neural activity. "
    "Data represent mean ± SEM."
)

# Panel legends (A, B, C, ...)
axes[0].set_caption("Representative traces from control condition")
axes[1].set_caption("Quantification across subjects (n=12)")

# Access captions
print(fig.caption)       # Figure legend
print(axes[0].caption)   # Panel A legend

# Auto-generate with statistics
fig.set_stats({"comparisons": [{"name": "A vs B", "p_value": 0.003}]})
full_legend = fig.generate_caption(style="publication")
# → "Comparison of... (A) Representative traces... (B) Quantification... A vs B (p=0.003)."

Captions are saved in the recipe YAML and displayed in the GUI editor's caption pane below the canvas—ready for copy-paste into manuscripts.

Interactive GUI Editor

import figrecipe as fr
import numpy as np

fig, ax = fr.subplots()
ax.plot(np.sin(np.linspace(0, 10, 100)))

# Launch browser-based editor
overrides = fr.edit(fig, port=5050)

# Returns style overrides when editor is closed (Ctrl+C)
# Apply overrides to future figures or save to custom YAML

The editor provides:

• Live preview with real-time style updates
• Theme switching between SCITEX/MATPLOTLIB presets
• Element selection with hover highlighting
• Property panels for Figure, Axis, Legend, and Labels
• Download in PNG, SVG, PDF formats
• Export updated recipe YAML

Axis Properties	Download Options	Dark Mode

Style Format (YAML) — Full preset example

# FIGRECIPE Style Preset (SCITEX)
axes:
  width_mm: 40
  height_mm: 28
  thickness_mm: 0.2

margins:
  left_mm: 1
  right_mm: 1
  bottom_mm: 1
  top_mm: 1

fonts:
  family: "Arial"
  axis_label_pt: 7
  tick_label_pt: 7
  title_pt: 8

lines:
  trace_mm: 0.2
  errorbar_mm: 0.2

ticks:
  length_mm: 0.8
  thickness_mm: 0.2
  direction: "out"

output:
  dpi: 300
  transparent: true
  format: "pdf"

theme:
  mode: "light"
  dark:
    text: "#d4d4d4"
    spine: "#d4d4d4"
  light:
    text: "black"
    spine: "black"

colors:
  palette:
    - [0, 128, 192]      # blue
    - [255, 70, 50]      # red
    - [20, 180, 20]      # green
# EOF

See src/figrecipe/styles/presets/ for complete examples.

API Overview

Import	Description
import figrecipe.pyplot as plt	Drop-in replacement of matplotlib.pyplot as plt
import figrecipe as fr	Import figrecipe package

Function
fr.subplots()	Create a recording-enabled figure
fr.save(fig, 'fig.png')	Save image + recipe
fr.reproduce('fig.yaml')	Reproduce figure from recipe
fr.extract_data('fig.yaml')	Extract plotted data
fr.info('fig.yaml')	Inspect recipe metadata
fr.edit(fig)	Launch interactive GUI editor
fr.load_style()	Load style preset (global)
fr.list_presets()	List available presets
fr.crop('fig.png')	Crop to content with mm margin
fig.set_caption(text)	Set figure legend (metadata)
ax.set_caption(text)	Set panel legend (metadata)

License

AGPL-3.0 See LICENSE

Contact

Yusuke Watanabe ([e-mail])