FigRecipe API Reference

The full public surface of figrecipe is documented inline below via automodule. The __all__ declaration in figrecipe/__init__.py is the single source of truth for what appears here; do NOT add explicit autofunction / autoclass directives below — Sphinx already discovers them through automodule :members: and a second declaration triggers duplicate object description warnings (treated as errors on PR builds).

figrecipe - Record and reproduce matplotlib figures.

A lightweight library for capturing matplotlib plotting calls and reproducing figures from saved recipes.

Usage

>>> import figrecipe as fr
>>> fig, ax = fr.subplots()
>>> ax.plot(x, y, id='my_data')
>>> fr.save(fig, 'recipe.yaml')

Examples

Recording a figure:

>>> import figrecipe as fr
>>> import numpy as np
>>>
>>> x = np.linspace(0, 10, 100)
>>> y = np.sin(x)
>>>
>>> fig, ax = fr.subplots()
>>> ax.plot(x, y, color='red', linewidth=2, id='sine_wave')
>>> ax.set_xlabel('Time')
>>> ax.set_ylabel('Amplitude')
>>> fr.save(fig, 'my_figure.yaml')

Reproducing a figure:

>>> fig, ax = fr.reproduce('my_figure.yaml')
>>> plt.show()

Notes

Submodules:

• fr.utils: Unit conversions, font checks, low-level recipe access

• fr.styles: Axis helpers, spine management, plot styling functions

• fr.viz: Diagram and graph visualization utilities

>>> from figrecipe import utils
>>> utils.mm_to_inch(25.4)  # Unit conversions

>>> from figrecipe import styles
>>> styles.hide_spines(ax)  # Spine management

figrecipe.subplots(nrows=1, ncols=1, axes_width_mm=None, axes_height_mm=None, margin_left_mm=None, margin_right_mm=None, margin_bottom_mm=None, margin_top_mm=None, space_w_mm=None, space_h_mm=None, style=None, apply_style_mm=True, panel_labels=None, **kwargs)

Create a figure with recording-enabled axes.

This is a drop-in replacement for plt.subplots() that wraps the returned figure and axes with recording capabilities.

Supports mm-based layout control for publication-quality figures.

Parameters:

• nrows (int) – Number of rows and columns of subplots.

• ncols (int) – Number of rows and columns of subplots.

• axes_width_mm (Optional[float]) – Axes dimensions in mm.

• axes_height_mm (Optional[float]) – Axes dimensions in mm.

• margin_left_mm (Optional[float]) – Left/right margins in mm.

• margin_right_mm (Optional[float]) – Left/right margins in mm.

• margin_bottom_mm (Optional[float]) – Bottom/top margins in mm.

• margin_top_mm (Optional[float]) – Bottom/top margins in mm.

• space_w_mm (Optional[float]) – Horizontal/vertical spacing between axes in mm.

• space_h_mm (Optional[float]) – Horizontal/vertical spacing between axes in mm.

• style (Optional[Dict[str, Any]]) – Style configuration dictionary.

• apply_style_mm (bool) – If True (default), apply loaded style to axes.

• panel_labels (Optional[bool]) – If True, add panel labels (A, B, C, …).

• **kwargs – Additional arguments passed to plt.subplots().

Return type:

Tuple[RecordingFigure, Union[RecordingAxes, NDArray]]

Returns:

• fig (RecordingFigure) – Wrapped figure object.

• axes (RecordingAxes or ndarray) – Wrapped axes.

figrecipe.save(fig, path, save_recipe=True, include_data=True, data_format='csv', csv_format='separate', validate=True, validate_mse_threshold=100.0, validate_error_level='error', validate_axis_range_alignment=True, validate_axis_range_alignment_error_level='warning', verbose=True, dpi=None, image_format=None, facecolor=None, save_hitmap=False, save_editable=False)

Save a figure as image and recipe. Unified API with fig.savefig().

Parameters:

• fig (Union[RecordingFigure, Figure]) – The figure to save.

• path (Union[str, Path]) – Output path (.png, .pdf, .svg, .yaml, etc.)

• save_recipe (bool) – If True (default), save YAML recipe alongside the image.

• include_data (bool) – If True (default), save large arrays to separate files.

• data_format (Literal['csv', 'npz', 'inline']) – Format for data files: ‘csv’, ‘npz’, or ‘inline’.

• csv_format (Literal['single', 'separate']) – CSV structure: ‘separate’ (default) or ‘single’ (scitex-compatible).

• validate (bool) – If True (default), validate reproducibility after saving.

• validate_mse_threshold (float) – Maximum acceptable MSE for validation (default: 100).

• validate_error_level (str) – How to handle failures: ‘error’, ‘warning’, or ‘debug’.

• validate_axis_range_alignment (bool) – If True (default), run the runtime axis_range_alignment check on the rendered figure. Catches the autoscale-with- different-data case that the static STX-FIG001 lint misses.

• validate_axis_range_alignment_error_level (str) – Dispatch level for the axis-range-alignment check: ‘warning’ (default), ‘error’, or ‘debug’ (silent).

• verbose (bool) – If True (default), print save status.

• dpi (Optional[int]) – DPI for image output.

• image_format (Optional[str]) – Image format when path is YAML.

• facecolor (Optional[str]) – Background color. When opaque, patches are made visible.

• save_hitmap (bool) – If True (default), save hitmap image for GUI editor element selection.

• save_editable (bool) – If True, write the editable-figure JSON (schema scitex.plt.figure.editable) to <stem>.json next to the image. Default False — opt in for the GUI / web editor.

Returns:

If save_recipe=True: (image_path, yaml_path, ValidationResult or None) If save_recipe=False: (image_path, None, None)

Return type:

tuple

figrecipe.reproduce(path, calls=None, skip_decorations=False, apply_style=True)

Reproduce a figure from a recipe file or bundle.

Parameters:

• path (Union[str, Path]) – Path to recipe. Supports multiple formats: - .yaml/.yml file: Direct recipe file - .png/.jpg/etc: Image with associated .yaml - Directory: Bundle containing recipe.yaml - .zip: ZIP bundle (both old recipe.yaml format and new spec.json format)

• calls (Optional[List[str]]) – If provided, only reproduce these specific call IDs.

• skip_decorations (bool) – If True, skip decoration calls.

• apply_style (bool) – If True (default), apply saved style.

Return type:

Tuple[Figure, Union[Axes, List[Axes]]]

Returns:

• fig (matplotlib.figure.Figure) – Reproduced figure.

• axes (Axes or list of Axes) – Reproduced axes.

figrecipe.load(path, calls=None, skip_decorations=False, apply_style=True)

Reproduce a figure from a recipe file or bundle.

Parameters:

• path (Union[str, Path]) – Path to recipe. Supports multiple formats: - .yaml/.yml file: Direct recipe file - .png/.jpg/etc: Image with associated .yaml - Directory: Bundle containing recipe.yaml - .zip: ZIP bundle (both old recipe.yaml format and new spec.json format)

• calls (Optional[List[str]]) – If provided, only reproduce these specific call IDs.

• skip_decorations (bool) – If True, skip decoration calls.

• apply_style (bool) – If True (default), apply saved style.

Return type:

Tuple[Figure, Union[Axes, List[Axes]]]

Returns:

• fig (matplotlib.figure.Figure) – Reproduced figure.

• axes (Axes or list of Axes) – Reproduced axes.

figrecipe.compose(sources, layout=None, canvas_size_mm=None, width_mm=None, gap_mm=2.0, dpi=300, panel_labels=False, label_style='uppercase', caption=None, panel_captions=None, max_whitespace_frac=None, **kwargs)

Compose a new figure from multiple sources (recipes or raw images).

Supports three modes automatically detected from sources/layout format:

1. Grid-based: sources={(row, col): path} Uses layout=(nrows, ncols) for subplot grid.

2. Mm-based: sources={path: {“xy_mm”: (x, y), “size_mm”: (w, h)}} Uses canvas_size_mm for precise positioning.

3. Tiled (row-justified, whitespace-free): layout=[[“A”,”B”,”C”],[“D”]] (or the multiline string “A B CnD”) with sources={“A”: path, …}. Each panel keeps its true aspect ratio; within a row all panels share one common height and sit edge-to-edge (only gap_mm between) so there is no whitespace, and every row spans the same width so the right edge is never ragged. The first layout row is rendered on top.

Parameters:

• sources (Dict[Any, Any]) – One of: - Grid-based: {(row, col): source_path} mapping positions to sources - Mm-based: {source_path: {“xy_mm”: (x, y), “size_mm”: (w, h)}} - Tiled: {label: source} keyed by the string labels used in layout

• layout (Union[Tuple[int, int], str, List[List[str]], None]) –

  • (nrows, ncols) for grid-based composition (auto-detected if omitted).

  • list of rows of labels ([["A","B"],["C"]]) or a multiline string ("A B\nC") for tiled composition.

• canvas_size_mm (Optional[Tuple[float, float]]) – (width_mm, height_mm) for mm-based composition. Required for mm-based mode.

• width_mm (Optional[float]) – Overall content width (mm) for TILED composition. When omitted the default width is the widest row at its true content size, i.e. max over rows of (sum of true panel widths + (k-1)*gap_mm). Ignored by grid/mm modes.

• gap_mm (float) – Gap between panels in mm (gutter; tiled mode uses it as the edge-to-edge spacing, and gap_mm=0 makes panels share edges exactly).

• dpi (int) – DPI for the output figure.

• panel_labels (bool) – If True, add panel labels (A, B, C…) to each panel.

• label_style (str) – ‘uppercase’, ‘lowercase’, or ‘numeric’.

• caption (Optional[str]) – Figure-level caption text. Rendered on the figure and persisted in the recipe so it survives save→reproduce.

• panel_captions (Optional[List[str]]) – Per-panel caption texts. When provided, panel labels (A, B, C…) are placed with the corresponding caption text on each panel.

• max_whitespace_frac (Optional[float]) – Refuse the composite when more than this fraction of the canvas is blank — e.g. 0.4 raises above 40% whitespace, naming the measured figure and the largest empty regions. Omitted (the default) measures without enforcing: a composite over half blank warns, nothing raises. Enforcement is opt-in because a raising default would break every existing sparse composite at once.

• **kwargs – Additional arguments passed to figure creation.

Return type:

Tuple[RecordingFigure, Union[RecordingAxes, NDArray, List[RecordingAxes]]]

Returns:

• fig (RecordingFigure) – Composed figure (editable, recordable).

• axes (RecordingAxes, ndarray, or list) – Axes of the composed figure.

Examples

Grid-based composition:

>>> fig, axes = fr.compose(
...     layout=(1, 2),
...     sources={
...         (0, 0): "panel_a.yaml",
...         (0, 1): "panel_b.yaml",
...     }
... )

Composition with figure-level caption:

>>> fig, axes = fr.compose(
...     layout=(2, 2),
...     sources={
...         (0, 0): "a.yaml", (0, 1): "b.yaml",
...         (1, 0): "c.yaml", (1, 1): "d.yaml",
...     },
...     caption="Figure 1. Four-condition comparison (n=3).",
... )

Mm-based free-form composition:

>>> fig, axes = fr.compose(
...     canvas_size_mm=(180, 120),
...     sources={
...         "panel_a.yaml": {"xy_mm": (0, 0), "size_mm": (85, 55)},
...         "panel_b.yaml": {"xy_mm": (90, 0), "size_mm": (85, 55)},
...         "panel_c.yaml": {"xy_mm": (0, 60), "size_mm": (175, 55)},
...     }
... )

Tiled (row-justified, whitespace-free) composition:

>>> fig, axes = fr.compose(
...     layout=[["A", "B", "C"], ["D"]],
...     sources={"A": "a.yaml", "B": "b.yaml",
...              "C": "c.yaml", "D": "d.yaml"},
...     width_mm=180, gap_mm=1.0,
... )

figrecipe.align_panels(fig, panels, mode, reference=None)

Align multiple panels to a reference panel.

Parameters:

• fig (RecordingFigure) – The figure containing the panels.

• panels (List[Tuple[int, int]]) – List of (row, col) positions to align.

• mode (Union[str, AlignmentMode]) – Alignment mode: ‘left’, ‘right’, ‘top’, ‘bottom’, ‘center_h’, ‘center_v’, ‘axis_x’, ‘axis_y’.

• reference (Optional[Tuple[int, int]]) – Reference panel position. If None, uses first panel.

Return type:

None

Examples

>>> import figrecipe as fr
>>> fig, axes = fr.subplots(2, 2)
>>> # Align left column panels to left edge
>>> fr.align_panels(fig, [(0, 0), (1, 0)], mode="left")

figrecipe.distribute_panels(fig, panels, direction='horizontal', spacing_mm=None)

Distribute panels evenly with optional fixed spacing.

Parameters:

• fig (RecordingFigure) – The figure containing the panels.

• panels (List[Tuple[int, int]]) – List of (row, col) positions to distribute.

• direction (str) – ‘horizontal’ or ‘vertical’.

• spacing_mm (Optional[float]) – Fixed spacing in mm. If None, distribute evenly within current bounds.

Return type:

None

Examples

>>> import figrecipe as fr
>>> fig, axes = fr.subplots(1, 3)
>>> # Distribute evenly
>>> fr.distribute_panels(fig, [(0, 0), (0, 1), (0, 2)])
>>> # With fixed 5mm spacing
>>> fr.distribute_panels(fig, [(0, 0), (0, 1), (0, 2)], spacing_mm=5)

figrecipe.align_smart(fig, panels=None)

Automatically align panels in a compact grid layout.

Works like human behavior: 1. Detect grid structure (nrows, ncols) 2. Place panels from top-left to bottom-right 3. Calculate minimum rectangle to cover all content in each row/column 4. Unify row heights and column widths 5. Use space effectively with theme margins and spacing

Uses margin and spacing values from the loaded SCITEX theme: - margins.left_mm, margins.right_mm, margins.top_mm, margins.bottom_mm - spacing.horizontal_mm, spacing.vertical_mm

Parameters:

• fig (RecordingFigure) – The figure containing the panels.

• panels (Optional[List[Tuple[int, int]]]) – Specific panels to align. If None, aligns all panels.

Return type:

None

Examples

>>> import figrecipe as fr
>>> fig, axes = fr.subplots(2, 2)
>>> # ... add plots ...
>>> fr.align_smart(fig)  # Align all panels using theme settings

figrecipe.empty_cells(layout, sources)

Blank (row, col) cells of a GRID compose (deterministic fast path).

For grid composition (layout=(nrows, ncols) with sources keyed by (row, col)), returns the cells with no source = {all cells} - set(sources keys), sorted row-major. When layout is omitted it is inferred from the max present (row, col). Returns [] for non-grid (tiled/mm) layouts — those are whitespace-free by construction and have no grid-cell concept.

Return type:

List[Tuple[int, int]]

figrecipe.layout_report(fig)

Structured, machine-readable layout of a composed figure.

Returns a dict with: mode (grid/mm/tiled when known), canvas_mm, panels (per-panel *_frac/*_mm box + aspect), empty_regions (maximal blank rectangles), and coverage_frac (fraction of the canvas covered by panels). An agent reads this to propose panel target sizes for a tight, no-stretch re-tiling.

Return type:

Dict[str, Any]

figrecipe.auto_tile_layout(aspects, width_mm, height_mm=None, gap_mm=1.0)

Bin-pack panel aspect ratios into a tight layout for build_tiled_sources.

Parameters:

• aspects (Dict[str, float]) – {label: w/h} – each panel’s TRUE aspect ratio. Never a size to target; only a ratio the packer must preserve exactly.

• width_mm (float) – Overall content width W of the figure in mm (same role as build_tiled_sources’s width_mm).

• height_mm (float) – Target overall canvas height in mm. When given, the packer searches row-counts and picks the one whose resulting total height is closest to height_mm without exceeding it (falling back to the closest overall if every candidate exceeds it). When omitted, the packer instead MINIMISES wasted canvas area (the width_mm x total_height bounding box minus the summed true panel areas) – the canonical packing-efficiency objective.

• gap_mm (float) – Gutter between adjacent panels (both within a row and between rows), same convention as build_tiled_sources.

Return type:

Tuple[List[List[str]], Dict[str, Tuple[float, float]], Tuple[float, float]]

Returns:

• layout (list of list of str) – Row-list of labels, ready to hand to build_tiled_sources (or fr.compose) verbatim.

• sizes_mm (dict) – {label: (width_mm, height_mm)} – the target size each panel should be RE-AUTHORED/re-plotted at. Every panel’s w/h here equals aspects[label] exactly (to floating-point precision): this function only ever proposes geometry, it never stretches or upscales a panel.

• canvas_size_mm (tuple) – (width_mm, total_height_mm) of the resulting canvas.

Notes

For each candidate row-count n_rows (searched over 1..len(aspects)) labels are greedily partitioned by _greedy_partition() (largest aspect first, into whichever row has the smallest running aspect-sum – this keeps row heights close to parity). Each row is then sized by the SAME formula build_tiled_sources uses (see figrecipe._composition._tile._row_height_mm): row height h_r = (width_mm - (k-1) * gap_mm) / sum(row aspects), panel width w_i = aspect_i * h_r. Row order (top-to-bottom) and each row’s internal label order follow assignment order and are never reshuffled afterwards.

figrecipe.gui(source=None, style=None, port=5050, host='127.0.0.1', open_browser=True, hot_reload=False, working_dir=None, desktop=False)

Launch interactive GUI editor for figure styling.

Parameters:

• source (RecordingFigure, str, Path, or None) – Either a live RecordingFigure object, path to a .yaml recipe file, or None to create a new blank figure.

• style (str or dict, optional) – Style preset name or style dict.

• port (int) – Django server port (default: 5050).

• host (str) – Host to bind server (default: “127.0.0.1”, use “0.0.0.0” for Docker).

• open_browser (bool) – Whether to open browser automatically (default: True).

• hot_reload (bool) – Enable hot reload (default: False).

• working_dir (str or Path, optional) – Working directory for file browser (default: directory containing source).

• desktop (bool) – Launch as native desktop window using pywebview (default: False). Requires: pip install figrecipe[desktop]

Returns:

Final style overrides after editing session.

Return type:

dict

figrecipe.crop(input_path, output_path=None, margin_mm=1.0, margin_px=None, overwrite=False, verbose=False, return_offset=False)

Crop a figure image to its content area with a specified margin.

Parameters:

• input_path (str or Path) – Path to the input image.

• output_path (str or Path, optional) – Path to save the cropped image.

• margin_mm (float, optional) – Margin in millimeters (default: 1.0mm).

• margin_px (int, optional) – Margin in pixels (overrides margin_mm if provided).

• overwrite (bool, optional) – Whether to overwrite the input file (default: False)

• verbose (bool, optional) – Whether to print detailed information (default: False)

• return_offset (bool, optional) – If True, also return crop offset info dict (default: False)

Returns:

Path to the saved cropped image. If return_offset=True, returns (path, offset_dict).

Return type:

Path or tuple

figrecipe.info(path)

Get information about a recipe without reproducing.

Return type:

Dict[str, Any]

figrecipe.validate(path, mse_threshold=100.0)

Validate that a saved recipe can reproduce its original figure.

Parameters:

• path (Union[str, Path]) – Path to .yaml recipe file.

• mse_threshold (float) – Maximum acceptable MSE for validation to pass (default: 100).

Returns:

Detailed comparison results.

Return type:

ValidationResult

figrecipe.extract_data(path)

Extract data arrays from a saved recipe.

Returns:

Nested dictionary: {call_id: {‘x’: array, ‘y’: array, …}}

Return type:

Dict[str, Dict[str, Any]]

figrecipe.add_qr_to_figure(fig, metadata, position='bottom-right', size=0.08)

Add a minimal QR code to a matplotlib figure.

Parameters:

• fig (matplotlib.figure.Figure) – Target figure to overlay onto.

• metadata (dict) – Payload to encode. If "url" is absent, "https://scitex.ai" is added so the QR resolves to something even when consumers don’t provide one.

• position (str) – One of "bottom-right", "bottom-left", "top-right", "top-left". Unknown values fall back to "bottom-right".

• size (float) – Relative size of the QR overlay (fraction of figure width).

Returns:

The same figure, with a QR overlay axes added. If the optional qrcode / Pillow dependencies are not installed, the figure is returned unmodified and a warning is logged.

Return type:

matplotlib.figure.Figure

figrecipe.add_figure_caption(fig, caption, *, figure_label=None, style='scientific', position='bottom', width_ratio=0.9, font_size='small', wrap_width=80, align='justify', pad_mm=2.0, save_to_file=False, file_path=None)

Add a figure caption.

The caption text is stripped of Markdown formatting (bold/italic) so it renders cleanly in matplotlib. The caption is also recorded on fig.record.caption so it survives save→reproduce round-trip.

Parameters:

• fig (Any) – The figure to add caption to.

• caption (str) – The caption text (Markdown formatting is automatically stripped).

• figure_label (Optional[str]) – Custom figure label (e.g. “Figure 1”). Auto-generated if None.

• style (str) – Caption style: “scientific”, “nature”, “ieee”, “apa”.

• position (str) – Caption position: “bottom” (default) or “top”.

• width_ratio (float) – Width of caption relative to figure width.

• font_size (Union[str, int]) – Font size for caption text.

• wrap_width (int) – Character width for text wrapping.

• align (str) – Caption alignment: “justify” (default), “left”, or “center”. “justify” spans the full content width with the last line left-aligned.

• pad_mm (float) – Gap (mm) between the caption band and the axes / figure edge.

• save_to_file (bool) – Whether to also save caption to a separate file.

• file_path (Optional[str]) – Path for caption file.

Returns:

The rendered caption text (Markdown-stripped).

Return type:

str

figrecipe.add_panel_captions(fig, axes, panel_captions, *, main_caption='', figure_label=None, panel_style='letter_bold', position='top_left', font_size='medium', offset=(0.02, 0.98))

Add panel captions (A, B, C, etc.) to subplot panels.

Panel labels are rendered with Markdown-stripped text so they display cleanly in matplotlib.

Parameters:

• fig (Any) – The figure containing panels.

• axes (Any) – Axes objects for each panel.

• panel_captions (Union[List[str], Dict[str, str]]) – Caption text for each panel.

• main_caption (str) – Main figure caption (optional, auto-attached).

• figure_label (Optional[str]) – Figure label for the main caption.

• panel_style (str) – Panel label style: “letter_bold”, “letter_italic”, “number”.

• position (str) – Panel label position: “top_left”, “top_right”, etc.

• font_size (Union[str, int]) – Font size for panel labels.

• offset (Tuple[float, float]) – Position offset for panel labels.

Returns:

Dictionary mapping panel labels to full caption text.

Return type:

Dict[str, str]

figrecipe.set_manuscript_mode(on=True)

Enable/disable manuscript mode process-wide.

Return type:

None

figrecipe.manuscript_mode(on=True)

Context manager that sets manuscript mode for the enclosed block.

figrecipe.is_manuscript_mode()

True when manuscript mode is active (explicit flag OR env var).

Return type:

bool

figrecipe.panel_label(ax, label, loc='upper left', offset=(-0.1, 1.05), fontsize=10, fontweight='bold', text_color='black', **kwargs)

Place a single panel label (A, B, C, etc.) on one axes.

Parameters:

• ax (Any) – The axes to annotate.

• label (str) – The panel label text (e.g. ‘A’, ‘B’, ‘(1)’).

• loc (str) – Location hint: ‘upper left’ (default), ‘upper right’, ‘lower left’, ‘lower right’.

• offset (Tuple[float, float]) – (x, y) offset in axes coordinates. Default (-0.1, 1.05).

• fontsize (float) – Font size in points (default 10).

• fontweight (str) – Font weight (default ‘bold’).

• text_color (str) – Text color (default ‘black’).

• **kwargs – Additional arguments passed to ax.text().

Returns:

The created text annotation.

Return type:

Any

class figrecipe.Figz(path)

Bases: object

Multi-panel figure bundle (.fig.zip).

Manages a ZIP file containing:

manifest.json - bundle type declaration spec.json - figure spec with panel list style.json - figure dimensions and theme panels/ - .plt.zip panel bundles

Example

>>> figz = Figz.create("Figure1.fig.zip", "Figure1")
>>> figz.add_panel("A", pltz_path)
>>> figz.add_panel("B", pltz_bytes)

__init__(path)

classmethod create(path, name, size_mm=None)

Create a new empty .fig.zip bundle.

Parameters:

• path (Union[str, Path]) – Output path (should end in .fig.zip).

• name (str) – Figure name / ID.

• size_mm (Optional[Dict]) – Canvas size e.g. {“width_mm”: 170, “height_mm”: 120}.

Returns:

Loaded Figz instance.

Return type:

Figz

save()

Save spec/style changes back to bundle.

Return type:

None

add_panel(label, pltz_source, position=None, size=None)

Add a .plt.zip panel to this figure.

Parameters:

• label (str) – Panel label (e.g., “A”, “B”).

• pltz_source (Union[bytes, str, Path]) – Panel bytes or path to a .plt.zip file.

• position (Optional[Dict]) – Panel position e.g. {“x_mm”: 5, “y_mm”: 5}.

• size (Optional[Dict]) – Panel size e.g. {“width_mm”: 80, “height_mm”: 68}.

Return type:

None

add_panel_from_png(label, png_bytes, plot_type='image', position=None, size=None, hitmap_bytes=None, hitmap_color_map=None, data_csv=None)

Create a .plt.zip bundle from PNG bytes and embed it as a panel.

Convenience wrapper around add_panel() for the common case of adding a pre-rendered PNG image as a panel.

Parameters:

• label (str) – Panel label (e.g., “A”, “B”).

• png_bytes (bytes) – PNG image data.

• plot_type (str) – Plot type label stored in the panel’s spec.json (default: “image”).

• position (Optional[Dict]) – Panel position e.g. {“x_mm”: 5, “y_mm”: 5}.

• size (Optional[Dict]) – Panel size e.g. {“width_mm”: 80, “height_mm”: 68}.

Return type:

None

remove_panel(label)

Remove a panel (rebuilds ZIP).

Parameters:

label (str) – Panel label to remove.

Return type:

None

get_panel(label)

Extract panel as Pltz instance (via temp file).

Note: The caller is responsible for cleaning up the temp file (accessible via the returned Pltz instance’s .path attribute).

Parameters:

label (str) – Panel label.

Returns:

Loaded Pltz instance for the panel.

Return type:

Pltz

get_panel_pltz(panel_id)

Get panel as raw bytes.

Parameters:

panel_id (str) – Panel label.

Returns:

Raw .plt.zip bytes, or None if panel not found.

Return type:

Optional[bytes]

list_panel_ids()

List panel labels in order.

Returns:

Panel labels.

Return type:

List[str]

get_panel_data(panel_id)

Get panel’s CSV data as DataFrame.

Parameters:

panel_id (str) – Panel label.

Return type:

DataFrame or None

render_preview()

Return preview of first panel as PNG bytes.

Return type:

Optional[bytes]

class figrecipe.Pltz(path)

Bases: object

Single-plot bundle (.plt.zip).

Thin wrapper around figrecipe’s existing bundle functions: - load_bundle() - save_bundle() - reproduce_bundle()

Bundle structure (inside ZIP):

{stem}/
    spec.json    # WHAT to plot (semantic specification)
    style.json   # HOW it looks (appearance settings)
    data.csv     # Raw data
    recipe.yaml  # Reproducible recipe
    exports/
        figure.png

__init__(path)

classmethod from_png(png_bytes, path, plot_type='image', spec=None, style=None, hitmap_bytes=None, hitmap_color_map=None, data_csv=None)

Create a .plt.zip bundle wrapping a pre-rendered PNG image.

Useful when a figure is rendered externally (e.g., from a gallery template) and needs to be stored as a figrecipe bundle.

Parameters:

• png_bytes (bytes) – PNG image data.

• path (Union[str, Path]) – Output path for the .plt.zip file.

• plot_type (str) – Plot type label stored in spec.json (default: “image”).

• spec (Optional[dict]) – Additional spec entries (default: {}).

• style (Optional[dict]) – Style entries (default: {}).

Returns:

Loaded Pltz instance wrapping the saved bundle.

Return type:

Pltz

classmethod create(path, fig)

Save a RecordingFigure as a .plt.zip bundle.

Parameters:

• path (Union[str, Path]) – Output path. If it doesn’t end in .zip, .zip is appended.

• fig (RecordingFigure) – Figure created with figrecipe.subplots().

Returns:

Loaded Pltz instance wrapping the saved bundle.

Return type:

Pltz

get_preview()

Read pre-rendered preview PNG from bundle.

Returns:

PNG bytes, or None if no preview image is stored.

Return type:

Optional[bytes]

render_preview()

Reproduce figure and render to PNG bytes.

Returns:

PNG bytes, or None on failure.

Return type:

Optional[bytes]

save()

Save spec/style changes back to bundle in-place.

Updates spec.json and style.json inside the ZIP without re-rendering the figure.

Return type:

None

update_preview()

Re-render and update preview PNG in bundle.

Return type:

None

reproduce()

Reproduce figure from bundle.

Returns:

(fig, axes) reproduced from bundle.

Return type:

Tuple[Any, Any]

figrecipe.save_bundle(fig, path, dpi=None, image_formats=None, save_hitmap=False, verbose=True)

Save figure as a layered bundle (ZIP format).

Bundle structure inside ZIP:

spec.json      # WHAT (semantic specification)
style.json     # HOW (appearance settings)
data.csv       # DATA (immutable source data)
recipe.yaml    # Reproducible recipe (for fr.reproduce())
exports/
    figure.png
    figure_hitmap.png   # only if save_hitmap=True

Parameters:

• fig (RecordingFigure) – The figure to save.

• path (Union[str, Path]) – Output path (.zip will be added if not present).

• dpi (Optional[int]) – DPI for exports (default from style or 300).

• image_formats (Optional[list]) – Image formats to export (default: [‘png’]).

• save_hitmap (bool) – Whether to save the per-pixel hitmap PNG used by the GUI editor for diff visualisation (default: False). Hitmap rendering is expensive and the typical save() caller doesn’t need it; opt in with save_hitmap=True when persisting bundles for the editor.

• verbose (bool) – Whether to print status (default: True).

Returns:

Path to saved ZIP bundle.

Return type:

Path

figrecipe.load_bundle(path)

Load bundle components from ZIP file.

Parameters:

path (Union[str, Path]) – Path to bundle ZIP file.

Returns:

(spec, style, data) where data is DataFrame or None.

Return type:

Tuple[Dict[str, Any], Dict[str, Any], Optional[DataFrame]]

figrecipe.reproduce_bundle(path, apply_style=True)

Reproduce figure from bundle.

Parameters:

• path (Union[str, Path]) – Path to bundle (ZIP file or directory).

• apply_style (bool) – Whether to apply saved style (default: True).

Returns:

(fig, axes) reproduced from bundle.

Return type:

tuple

figrecipe.load_style(style='SCITEX', dark=False, background=None)

Load style configuration and apply it globally.

After calling this function, subsequent subplots() calls will automatically use the loaded style (fonts, colors, theme, etc.).

Parameters:

• style (str, Path, bool, or None) – One of: - “SCITEX” / “FIGRECIPE”: Scientific publication style (default) - “MATPLOTLIB”: Vanilla matplotlib defaults - Path to custom YAML file: “/path/to/my_style.yaml” - None or False: Unload style (reset to matplotlib defaults)

• dark (bool, optional) – If True, apply dark theme transformation (default: False). Equivalent to appending “_DARK” to preset name.

• background (str, optional) – Override default background color. E.g., ‘white’ for opaque figures. Sets theme.light.figure_bg and theme.light.axes_bg. Use ‘transparent’ for transparent background.

Returns:

Style configuration with dot-notation access. Returns None if style is unloaded.

Return type:

DotDict or None

Examples

>>> import figrecipe as fr

>>> # Load scientific style (default)
>>> fr.load_style()
>>> fr.load_style("SCITEX")  # explicit

>>> # Load with white background (override transparent default)
>>> fr.load_style("SCITEX", background='white')

>>> # Load dark theme
>>> fr.load_style("SCITEX_DARK")
>>> fr.load_style("SCITEX", dark=True)  # equivalent

>>> # Reset to vanilla matplotlib
>>> fr.load_style(None)    # unload
>>> fr.load_style(False)   # unload
>>> fr.load_style("MATPLOTLIB")  # explicit vanilla

>>> # Access style values
>>> style = fr.load_style("SCITEX")
>>> style.axes.width_mm
40

figrecipe.unload_style()

Unload the current style and reset to matplotlib defaults.

After calling this, subsequent subplots() calls will use vanilla matplotlib behavior without FigRecipe styling.

Examples

>>> import figrecipe as fr
>>> fr.load_style("SCITEX")  # Apply scientific style
>>> fig, ax = fr.subplots()  # Styled
>>> fr.unload_style()        # Reset to matplotlib defaults
>>> fig, ax = fr.subplots()  # Vanilla matplotlib

figrecipe.list_presets()

List available style presets.

Returns:

Names of available presets.

Return type:

list of str

Examples

>>> import figrecipe as ps
>>> ps.list_presets()
['MINIMAL', 'PRESENTATION', 'SCIENTIFIC']

class figrecipe.Diagram(title=None, width_mm=170.0, height_mm=120.0, padding_mm=10.0, gap_mm=None)

Bases: object

Builder for rich box-and-arrow diagrams with mm-based coordinates.

__init__(title=None, width_mm=170.0, height_mm=120.0, padding_mm=10.0, gap_mm=None)

add_box(id, title, subtitle=None, content=None, emphasis='normal', shape='rounded', x_mm=None, y_mm=None, width_mm=None, height_mm=None, fill_color=None, border_color=None, title_color=None, padding_mm=5.0, margin_mm=0.0, node_class=None, state=None, language=None, bullet=None)

Add a rich text box. See BoxSpec for node_class/state/language/bullet.

Return type:

Diagram

add_container(id, title=None, children=None, emphasis='muted', x_mm=None, y_mm=None, width_mm=None, height_mm=None, fill_color=None, border_color=None, title_loc='upper center', direction='row', container_gap_mm=8.0, container_padding_mm=8.0, equalize_heights=True, equalize_widths=True)

Add a container. equalize_heights/widths: match children in row/column.

Return type:

Diagram

add_arrow(source, target, source_anchor='auto', target_anchor='auto', source_dx=0.0, source_dy=0.0, target_dx=0.0, target_dy=0.0, label=None, style='solid', color=None, curve=0.0, linewidth_mm=0.5, label_offset_mm=None, margin_mm=None)

Add an arrow connecting two boxes.

Return type:

Diagram

add_icon(id, source, x_mm, y_mm, width_mm=8.0, height_mm=8.0, color=None, opacity=1.0)

Add an icon (SVG/PNG or built-in: warning/check/cross/info/lock).

Return type:

Diagram

validate_containers()

Check every container fully encloses its declared children.

Return type:

None

validate_no_overlap()

Check that no two boxes overlap each other.

Return type:

None

auto_layout(layout='lr', margin_mm=15.0, box_size_mm=None, gap_mm=10.0, avoid_overlap=True, justify='space-between', align_items='center')

Automatically position boxes. See _layout for details.

Return type:

Diagram

_auto_box_height(box)

Compute box height from content when height_mm is not specified.

Return type:

float

_finalize_canvas_size()

Compute canvas height from element positions when height_mm=None.

Return type:

None

_get_anchor(pos, anchor)

Get absolute position of an anchor point on the visual box edge.

Return type:

Tuple[float, float]

_auto_anchor(src, tgt)

Determine best anchor points automatically.

Return type:

Tuple[str, str]

render(ax=None, auto_fix=False, auto_curve=True)

Render. auto_fix=True resolves violations; auto_curve=False skips R7.

Return type:

Tuple[Figure, Axes]

save(path, dpi=200, save_recipe=True, save_hitmap=False, save_debug=True, watermark=False)

Render, crop, and save. watermark=True adds ‘Plotted by scitex.ai’.

Return type:

Path

render_to_file(path, dpi=200, save_recipe=True, save_hitmap=False, save_debug=True, watermark=False)

Render, crop, and save. watermark=True adds ‘Plotted by scitex.ai’.

Return type:

Path

to_dict()

Convert diagram to dictionary for serialization.

Return type:

Dict[str, Any]

classmethod from_dict(data)

Create Diagram from dictionary (recipe reproduction).

Return type:

Diagram

class figrecipe.StatResult(p_value, method=None, statistic=None, statistic_name='t', dof=None, effect_size=None, effect_name='d', ci=None, ci_level=95, n=None, n_subjects=None, n_unit='', n_subjects_unit='', extras=<factory>)

Bases: object

A completed statistical test, ready to be rendered onto a figure.

Only p_value is structurally required — a result with no p-value is not a test result at all. The other five doctrine fields are optional at the type level but their absence is reported by missing_fields() and warned about at render time, because “incomplete but loud” is more useful than “complete or TypeError”: a producer that genuinely cannot supply a CI (e.g. a permutation test) should still be able to render, with the gap visible.

Parameters:

• p_value (float) – The p-value of the test.

• method (Optional[str]) – Human-readable test name, e.g. "Welch's t-test". Rendered upright.

• statistic (Optional[float]) – The test statistic’s value.

• statistic_name (str) – Symbol for the test statistic ("t", "F", "U", "chi2", …).

• dof (Union[float, int, Sequence[float], None]) – Degrees of freedom; a scalar renders t(338), a pair renders F(2, 57).

• effect_size (Optional[float]) – The effect size’s value.

• effect_name (str) – Symbol for the effect size ("d", "r", "eta2", …).

• ci (Optional[Tuple[float, float]]) – Confidence interval around the estimate.

• ci_level (int) – Confidence level as a percentage. Default 95.

• n (Optional[int]) – Number of observations (windows / trials / samples) — lowercase n.

• n_subjects (Optional[int]) – Number of subjects — capital N. Keep distinct from n: collapsing the two hides the unit of statistical independence from the reader.

• n_unit (str) – Optional units, e.g. "windows" / "patients".

• n_subjects_unit (str) – Optional units, e.g. "windows" / "patients".

Examples

>>> result = StatResult(
...     p_value=0.0004, method="Pearson correlation",
...     statistic=5.1, statistic_name="t", dof=338,
...     effect_size=0.42, effect_name="r", ci=(0.21, 0.60),
...     n=340, n_subjects=12,
... )
>>> result.stars
'***'
>>> "Pearson correlation" in result.annotation()
True

p_value: float

method: str | None = None

statistic: float | None = None

statistic_name: str = 't'

dof: float | int | Sequence[float] | None = None

effect_size: float | None = None

effect_name: str = 'd'

ci: Tuple[float, float] | None = None

ci_level: int = 95

n: int | None = None

n_subjects: int | None = None

n_unit: str = ''

n_subjects_unit: str = ''

extras: Mapping[str, Any]

property stars: str

Significance stars for this p-value.

missing_fields()

Names of the doctrine’s six fields that this result cannot render.

Return type:

list

annotation(sep=', ', precision=3, stars=False, require_complete=True)

Render the six-stat annotation string, with italic statistical symbols.

Parameters:

• sep (str) – Separator between fields. Pass ",\n" to wrap onto two lines when a panel is too narrow for one.

• precision (int) – Decimal places for the p-value before it collapses to < 0.001.

• stars (bool) – Prepend the significance stars on their own line. The stars are a convenience for the reader, never a substitute for the p-value — the exact number is always rendered alongside them.

• require_complete (bool) – Warn (never raise) when any of the six doctrine fields is absent. Set False when the missing fields genuinely live in the caption instead.

Returns:

e.g. "$N$ = 12, $n$ = 340, Pearson correlation, $t$(338) = 5.10, $p$ < 0.001, $r$ = 0.42, 95% CI [0.21, 0.60]"

Return type:

str

classmethod from_mapping(mapping)

Build a StatResult from a producer’s result dict — the adapter seam.

This is how scitex-stats (or scipy, or a stored results table) hands a test result to figrecipe without either side importing the other. Common key spellings are accepted. Keys that match nothing are preserved verbatim in extras rather than dropped, so a producer whose schema drifts leaves a trace instead of vanishing into a silently-incomplete annotation — and the render-time completeness warning still names whatever field went missing.

Raises:

KeyError – If no p-value key is present — that is not a test result.

Return type:

StatResult

__init__(p_value, method=None, statistic=None, statistic_name='t', dof=None, effect_size=None, effect_name='d', ci=None, ci_level=95, n=None, n_subjects=None, n_unit='', n_subjects_unit='', extras=<factory>)

figrecipe.hints_for(figure_type)

Return the hint for figure_type, or None when there is no entry yet.

None means “the registry has nothing to say”, NOT “this figure type is wrong”. Most plot types have no entry – the table is a short list of cases that came up, not a closed world. Callers must treat None as silence.

Return type:

Optional[FigureTypeHint]

figrecipe.known_figure_types()

Figure types the registry has an entry for, aliases included.

Return type:

List[str]

class figrecipe.ComparisonGeometry(*values)

Bases: str, Enum

How a comparison between two conditions is drawn on this figure type.

BRACKET_ABOVE = 'bracket_above'

A horizontal bracket spanning the two categories, above the data.

The default for categorical plots (bar, box, violin): the x positions are discrete, so a bracket has two unambiguous endpoints to span.

INLINE_TEXT = 'inline_text'

No bracket – the statistic is written as text in the plot area.

For plots with no discrete categories to span (a scatter, a correlation): the comparison is not between two x positions, it is a property of the whole cloud, so a bracket would point at nothing.

COLORBAR_ANNOTATION = 'colorbar_annotation'

Significance is carried by the image itself (e.g. a mask or contour).

A heatmap has no free space to run a bracket through, and a cell-by-cell test produces one statistic per cell, not one per pair – so significance is shown by marking the cells, with the method and correction named in the caption.

figrecipe.build_spec(params)

Convert a parameter dict to a figrecipe spec dict.

Parameters:

params (dict) – Flat parameter dict. Required key: kind. For XY plots: x, y (comma-separated floats or strings). For distributions: data, data2 .. data6, labels. For pie: data, labels. For heatmap: data, nrows, ncols. Optional: color, title, xlabel, ylabel, width, height, yerr.

Returns:

Figrecipe-compatible spec.

Return type:

dict

Raises:

ValueError – If required parameters are missing or kind is unsupported.

figrecipe.build_spec_from_csv(csv_path, params)

Build a figrecipe spec from a CSV file path and parameters.

Uses figrecipe’s native data_file + column name resolution.

Parameters:

• csv_path (Union[str, Path]) – Path to the CSV file.

• params (dict) – Flat parameter dict. Required: kind. For XY: x_col, y_col. For distributions: data_col. For pie: data_col, labels_col. For heatmap: data_col.

Returns:

Figrecipe-compatible spec.

Return type:

dict

Raises:

ValueError – If required parameters are missing or kind is unsupported.

figrecipe.render_spec_to_bytes(spec, *, dpi=300, fmt='png', facecolor='white')

Render a figrecipe spec dict to image bytes.

Parameters:

• spec (dict) – Figrecipe-compatible spec dict (as produced by build_spec).

• dpi (int) – Output resolution (default 300).

• fmt (Literal['png', 'pdf', 'svg']) – Image format: "png", "pdf", or "svg" (default "png").

• facecolor (str) – Background colour (default "white").

Returns:

Encoded image bytes.

Return type:

bytes

figrecipe.from_stats_plot_spec(spec)

Create a recorded figure from a scitex-stats.plot-spec document.

Parameters:

spec (Dict[str, Any]) – Stats plot spec (schema scitex-stats.plot-spec, version 1).

Returns:

Save with figrecipe.save() to get the PNG plus editable YAML.

Return type:

(RecordingFigure, RecordingAxes)

Examples

>>> fig, ax = figrecipe.from_stats_plot_spec(spec)
>>> figrecipe.save(fig, "ttest.png")

figrecipe.termplot(*args)

Plot y (and optional x) values in the terminal using termplotlib.

Parameters:

*args – Either (y,) — plotted against its indices — or (x, y, ...) where extra positional arguments are ignored.

Returns:

Displays the plot in the terminal.

Return type:

None

figrecipe.draw_graph(ax, G, *, layout='spring', pos=None, seed=42, node_size=100, node_color='#3498db', node_alpha=0.8, node_shape='o', node_edgecolors='white', node_linewidths=0.34, edge_width=0.34, edge_color='gray', edge_alpha=0.5, edge_style='solid', arrows=None, arrowsize=10, arrowstyle='-|>', connectionstyle='arc3,rad=0.0', labels=False, font_size=6, font_color='black', font_weight='normal', font_family='sans-serif', colormap='viridis', vmin=None, vmax=None, **layout_kwargs)

Draw a NetworkX graph on matplotlib axes.

Parameters:

• ax (Axes) – The axes to draw on.

• G (networkx.Graph) – The graph to draw.

• layout (str) – Layout algorithm: ‘spring’, ‘circular’, ‘kamada_kawai’, ‘shell’, ‘spectral’, ‘random’, ‘planar’, ‘spiral’, ‘hierarchical’.

• pos (Optional[Dict]) – Pre-computed node positions {node: (x, y)}.

• seed (int) – Random seed for layout reproducibility.

• node_size (Union[str, Callable, float]) – Node sizes. Can be attribute name, callable (node, data) -> size, or scalar.

• node_color (Union[str, Callable, Any]) – Node colors. Can be attribute name, callable, color name, or array.

• node_alpha (float) – Node transparency.

• node_shape (str) – Node marker shape.

• edge_width (Union[str, Callable, float]) – Edge widths. Can be attribute name, callable (u, v, data) -> width, or scalar.

• edge_color (Union[str, Callable, Any]) – Edge colors.

• edge_alpha (float) – Edge transparency.

• arrows (Optional[bool]) – Draw arrows for directed graphs. Auto-detected if None.

• arrowsize (float) – Arrow head size for directed edges.

• labels (Union[bool, Dict, str]) – Node labels. True for node IDs, dict for custom labels, str for attribute name.

• font_size (float) – Label font size (default 6pt for scitex).

• colormap (str) – Matplotlib colormap for numeric node colors.

• **layout_kwargs – Additional kwargs passed to layout algorithm.

Returns:

Dictionary with ‘pos’, ‘node_collection’, ‘edge_collection’.

Return type:

Dict[str, Any]

figrecipe.smart_align(fig, panels=None)

Automatically align panels in a compact grid layout.

Works like human behavior: 1. Detect grid structure (nrows, ncols) 2. Place panels from top-left to bottom-right 3. Calculate minimum rectangle to cover all content in each row/column 4. Unify row heights and column widths 5. Use space effectively with theme margins and spacing

Uses margin and spacing values from the loaded SCITEX theme: - margins.left_mm, margins.right_mm, margins.top_mm, margins.bottom_mm - spacing.horizontal_mm, spacing.vertical_mm

Parameters:

• fig (RecordingFigure) – The figure containing the panels.

• panels (Optional[List[Tuple[int, int]]]) – Specific panels to align. If None, aligns all panels.

Return type:

None

Examples

>>> import figrecipe as fr
>>> fig, axes = fr.subplots(2, 2)
>>> # ... add plots ...
>>> fr.align_smart(fig)  # Align all panels using theme settings

figrecipe.edit(source=None, style=None, port=5050, host='127.0.0.1', open_browser=True, hot_reload=False, working_dir=None, desktop=False)

Launch interactive GUI editor for figure styling.

Parameters:

• source (RecordingFigure, str, Path, or None) – Either a live RecordingFigure object, path to a .yaml recipe file, or None to create a new blank figure.

• style (str or dict, optional) – Style preset name or style dict.

• port (int) – Django server port (default: 5050).

• host (str) – Host to bind server (default: “127.0.0.1”, use “0.0.0.0” for Docker).

• open_browser (bool) – Whether to open browser automatically (default: True).

• hot_reload (bool) – Enable hot reload (default: False).

• working_dir (str or Path, optional) – Working directory for file browser (default: directory containing source).

• desktop (bool) – Launch as native desktop window using pywebview (default: False). Requires: pip install figrecipe[desktop]

Returns:

Final style overrides after editing session.

Return type:

dict

figrecipe.export_editable(fig, title='', description='', include_full_paths=False, simplify_threshold=0.5)

Export a matplotlib figure with geometry data for interactive editing.

This produces a Schema v0.3 compliant dictionary with axes-local pixel coordinates for all visual elements, suitable for shape-based hit testing.

Parameters:

• fig (matplotlib.figure.Figure or scitex.plt.FigureWrapper) – The figure to export

• title (str) – Optional title for the figure metadata

• description (str) – Optional description for the figure metadata

• include_full_paths (bool) – If True, include full (unsimplified) paths for lines. Default False.

• simplify_threshold (float) – Maximum pixel error for path simplification. Default 0.5.

Returns:

Schema v0.3 compliant dictionary with structure: - scitex_schema: “scitex.plt.figure.editable” - scitex_schema_version: “0.3.0” - figure: {size_px, dpi, …} - axes: {ax_id: {bbox_px, …}, …} - elements: {elem_id: {geometry_px, style, …}, …} - statistics: {} (placeholder for stats integration) - data: {} (placeholder for linked data) - output: {} (rendering metadata)

Return type:

Dict[str, Any]

figrecipe.enable_svg()

Manually enable SVG format for Jupyter notebook display.

Call this if figures appear pixelated in notebooks.

Examples

>>> import figrecipe as fr
>>> fr.enable_svg()  # Enable SVG rendering
>>> fig, ax = fr.subplots()  # Now renders as crisp SVG

figrecipe.apply_style(ax, style=None)

Apply mm-based styling to an axes.

Parameters:

• ax (matplotlib.axes.Axes) – Target axes to apply styling to.

• style (dict or DotDict, optional) – Style configuration. If None, uses default FIGRECIPE_STYLE.

Returns:

Trace line width in points.

Return type:

float

Examples

>>> import figrecipe as ps
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> trace_lw = ps.apply_style(ax)
>>> ax.plot(x, y, lw=trace_lw)

figrecipe.signature(image_path=None, recipe_path=None)

Compute verification signature for a saved figure.

Parameters:

• image_path (Union[str, Path, None]) – Path to the saved image file.

• recipe_path (Union[str, Path, None]) – Path to the saved recipe YAML file.

Returns:

Signature with keys: image_hash, recipe_hash, image_path, recipe_path.

Return type:

Dict[str, Any]

figrecipe.caption_with_signature(caption, image_path=None, recipe_path=None, style='short')

Append verification signature to a figure caption.

Parameters:

• caption (str) – Original caption text.

• image_path (Union[str, Path, None]) – Path to the saved image.

• recipe_path (Union[str, Path, None]) – Path to the saved recipe YAML.

• style (str) – ‘short’ (default): hash only. ‘full’: includes “Generated by figrecipe” prefix.

Returns:

Caption with appended signature.

Return type:

str

Recording Wrappers (internal)

These classes back the public subplots() return value. They live under figrecipe._wrappers rather than the top-level namespace, so they’re documented here separately.

class figrecipe._wrappers.RecordingFigure(fig, recorder, axes)

Bases: FigureTextMixin

Wrapper around matplotlib Figure that manages recording.

Parameters:

• fig (Figure) – The underlying matplotlib figure.

• recorder (Recorder) – The recorder instance.

• axes (Union[RecordingAxes, List[RecordingAxes]]) – Wrapped axes objects.

Examples

>>> import figrecipe as ps
>>> fig, ax = ps.subplots()
>>> ax.plot([1, 2, 3], [4, 5, 6])
>>> ps.save(fig, "my_figure.yaml")

__init__(fig, recorder, axes)

_on_draw_finalize(event)

Apply figrecipe finalize hooks once per figure lifetime.

Run-once: setting a new locator marks the canvas stale, which on the inline notebook backend triggers another draw and a SECOND inline render of the same figure. We only need to finalize once per figure — cache the flag and short-circuit on subsequent draws.

Re-entrancy guard: finalize_ticks may swap a locator, which on some backends triggers another draw and would recurse. The flag breaks the loop.

property fig: Figure

Get the underlying matplotlib figure.

property axes: List[List[RecordingAxes]]

Get axes as 2D array.

property dpi

Proxy dpi to underlying figure.

Needed as a class-level descriptor so matplotlib’s _setattr_cm can do getattr(type(obj), ‘dpi’) during savefig/print_figure.

draw(renderer)

Proxy draw to underlying figure.

Needed as a class-level method so matplotlib’s _setattr_cm can do getattr(type(obj), ‘draw’) during _get_renderer.

property flat: List[RecordingAxes]

Get flattened list of all axes.

property record: FigureRecord

Get the figure record.

_get_style_fontsize(key, default)

Get fontsize from loaded style.

Return type:

float

_get_style_fontweight(key, default)

Get a font WEIGHT string from the loaded style’s fonts block.

Sibling of _get_style_fontsize for weight-valued keys (e.g. panel_label_weight) so the weight is a style-owned field, not a hardcoded code default. Falls back to default when no style is loaded or the key is absent (older styles), so behaviour is unchanged.

Return type:

str

_get_resolved_font_family()

Resolve the font family LIST the active style pins on the body.

Returns the same chain the style applier gives the axis labels, ticks and title – the requested font (or its available fallback) followed by the CJK face when one exists – so the auto panel labels render in the SAME faces, glyph for glyph. A bare string here was the one path left that could not fall back for CJK, and it made the panel labels disagree with the body whenever a CJK face was installed. None when nothing can be resolved.

Return type:

Optional[List[str]]

_get_theme_text_color(default='black')

Get text color from loaded style’s theme settings.

Return type:

str

colorbar(mappable, ax=None, **kwargs)

Add a colorbar and record it for reproduction.

ax may be a single axes OR a list/array of axes (a shared colorbar that steals space from several panels, e.g. fig.colorbar(im, ax=axes.ravel().tolist())). An explicit cax=<axes> (the colorbar is drawn into a caller-provided axes) and a standalone ScalarMappable are also handled. Every source axes is recorded in ax_keys; the colorbar’s resolved geometry is captured later at SAVE time (see _capture_colorbar_geometry) so reproduction can pin it exactly. Recording logic lives in _figure_colorbar to keep this module within the per-file line budget.

Return type:

Any

add_panel_labels(labels=None, loc='upper left', offset=(-0.1, 1.05), fontsize=None, fontweight=None, **kwargs)

Add panel labels (A, B, C, D, etc.) to multi-panel figures.

Parameters:

• labels (Optional[List[str]]) – Custom labels. If None, uses uppercase letters (A, B, C, …).

• loc (str) – Location hint: ‘upper left’ (default), ‘upper right’, ‘lower left’, ‘lower right’.

• offset (Tuple[float, float]) – (x, y) offset in axes coordinates from the corner. Default is (-0.1, 1.05) for upper left positioning.

• fontsize (Optional[float]) – Font size in points. If None, uses style’s panel_label_pt or 10.

• fontweight (Optional[str]) – Font weight. If None, uses the style’s panel_label_weight (SCITEX: ‘bold’), falling back to ‘bold’.

• **kwargs – Additional arguments passed to ax.text().

Returns:

The matplotlib Text objects created.

Return type:

List[Any]

Examples

>>> fig, axes = fr.subplots(2, 2)
>>> fig.add_panel_labels()  # Adds A, B, C, D
>>> fig.add_panel_labels(['i', 'ii', 'iii', 'iv'])  # Custom labels
>>> fig.add_panel_labels(loc='upper right', offset=(1.05, 1.05))

set_title_metadata(title)

Set figure title metadata (not rendered, stored in recipe).

This is for storing a publication/reference title for the figure, separate from suptitle which is rendered on the figure.

Parameters:

title (str) – The figure title for publication/reference.

Returns:

Self for method chaining.

Return type:

RecordingFigure

Examples

>>> fig, ax = fr.subplots()
>>> fig.set_title_metadata("Effect of temperature on reaction rate")
>>> fig.set_caption("Figure 1. Reaction rates measured at various temperatures.")

set_caption(caption)

Set figure caption metadata (not rendered, stored in recipe).

This is for storing a publication caption for the figure, typically used in scientific papers (e.g., “Fig. 1. Description…”).

Parameters:

caption (str) – The figure caption text.

Returns:

Self for method chaining.

Return type:

RecordingFigure

Examples

>>> fig, ax = fr.subplots()
>>> fig.set_caption("Figure 1. Temperature dependence of reaction rates.")

property title_metadata: str | None

Get the figure title metadata.

property caption: str | None

Get the figure caption metadata.

set_stats(stats)

Set figure-level statistics metadata (not rendered, stored in recipe).

Parameters:

stats (Dict[str, Any]) – Statistics dictionary (comparisons, summary, correction_method, alpha).

Return type:

RecordingFigure

property stats: Dict[str, Any] | None

Get the figure-level statistics metadata.

generate_caption(style='publication', template=None)

Generate caption from stored stats. Styles: publication, brief, detailed.

Return type:

str

__getattr__(name)

Delegate attribute access to underlying figure.

Return type:

Any

savefig(fname, save_recipe=True, include_data=True, data_format='csv', csv_format='separate', validate=True, validate_mse_threshold=100.0, validate_error_level='error', verbose=True, dpi=None, image_format=None, facecolor=None, save_hitmap=False, **kwargs)

Save figure — equivalent to fr.save(). Same DPI, crop, recipe.

Returns (image_path, yaml_path, result). **kwargs passed to matplotlib savefig for file-like objects.

save_recipe(path, include_data=True, data_format='csv', csv_format='separate')

Save the recording recipe to YAML.

Parameters:

• path (Union[str, Path]) – Output path for the recipe file.

• include_data (bool) – If True, save array data alongside recipe.

• data_format (Literal['csv', 'npz', 'inline']) – Format for data files: ‘csv’ (default), ‘npz’, or ‘inline’.

• csv_format (Literal['single', 'separate']) – CSV structure: ‘separate’ (default) or ‘single’ (scitex-compatible).

Return type:

Path

class figrecipe._wrappers.RecordingAxes(ax, recorder, position=(0, 0))

Bases: RecordingAxesMethods, AxesStyleMixin, SciTexMixin, DiagramMixin, ScatterLabelsMixin

Wrapper around matplotlib Axes that records all calls.

This wrapper intercepts calls to plotting methods and records them for later reproduction.

Parameters:

• ax (Axes) – The underlying matplotlib axes.

• recorder (Recorder) – The recorder instance to log calls to.

• position (Tuple[int, int]) – (row, col) position in the figure grid.

Examples

>>> import figrecipe as ps
>>> fig, ax = ps.subplots()
>>> ax.plot([1, 2, 3], [4, 5, 6], color='red', id='my_line')
>>> # The call is recorded automatically

__init__(ax, recorder, position=(0, 0))

property ax: Axes

Get the underlying matplotlib axes.

property position: Tuple[int, int]

Get axes position in grid.

__getattr__(name)

Intercept attribute access to wrap methods.

Return type:

Any

embed(source, bounds=None, *, ax_key=None, track=True, id=None)

Embed a recipe or diagram as a managed sub-panel that round-trips.

source may be a recipe path, image, FigureRecord, diagram recipe, composed multi-panel recipe, or (source, ax_key). bounds is an axes-fraction [x, y, w, h] (defaults to the whole axes). Returns the embedded inset RecordingAxes (or a list for a multi-panel source).

__dir__()

Return list of attributes for tab completion.

Exposes all matplotlib plotting and decoration methods alongside figrecipe’s custom methods and properties.

_create_recording_wrapper(method_name, method)

Create a wrapper function that records the call.

_create_bar_wrapper()

Create wrapper for bar() with SCITEX error bar styling.

_create_boxplot_wrapper()

Create wrapper for boxplot() with patch_artist=True default.

_create_stem_wrapper()

Create wrapper for stem() that accepts color kwarg.

_create_legend_wrapper()

Build the legend() wrapper that handles SCITEX styling + figrecipe loc extensions + recording. Implementation lives in _legend_wrapper.py so this file stays focused.

set_caption(caption)

Set panel caption metadata (not rendered, stored in recipe).

Return type:

RecordingAxes

property panel_caption: str | None

Get the panel caption metadata.

set_stats(stats)

Set panel-level statistics metadata (not rendered, stored in recipe).

Return type:

RecordingAxes

property stats: Dict[str, Any] | None

Get the panel-level statistics metadata.

_no_record()

Context manager to temporarily disable recording (internal).

_record_seaborn_call(func_name, args, kwargs, data_arrays, call_id=None)

Record a seaborn plotting call.

Return type:

None

property figure

property xaxis

property yaxis

get_xlim()

get_ylim()

get_xlabel()

get_ylabel()

get_title()

property caption: str | None

Get the panel caption metadata.

generate_panel_caption(label=None, style='publication')

Generate a caption for this panel from stats metadata.

Return type:

str