lusca

pip install lusca

lusca is a Python library for creating reproducible matplotlib figures using Jupyter magic commands. You often want to use Jupyter for experiments without rerunning the entire notebook to recreate a plot, and saving data alongside figures is essential for artifact generation and reproducibility.

%%mplfreeze

%%mplfreeze <name> [vars ...] [--outdir DIR]

• <name>: Base name for outputs (folder + files).
• [vars ...]: Variable names to save into the NPZ file.
• [--outdir DIR]: Parent output directory (default: docs/figs).

The magic command:

• Captures the data used in your plots and saves it in a compressed NPZ file.
• Exports your figures in PDF, PNG, and SVG.
• Generates a minimal standalone script that reproduces the figure.
• Snapshots Python/package versions and the git commit into <name>.meta.json.
• Statically checks the cell for unsaved free names before writing anything, then runs the generated replot in a subprocess to confirm the bundle actually reproduces the figure - if %%mplfreeze succeeds, the replot is guaranteed to work.
• Applies lusca's built-in stylesheet.

Example

import matplotlib.pyplot as plt
import numpy as np
import lusca
%load_ext lusca

x_data = np.linspace(-10, 10, 100)
sine = np.sin(x_data)
cosine = np.cos(x_data)

%%mplfreeze trig_demo x_data sine cosine
with plt.style.context("lusca"):
    fig, ax = plt.subplots(1, 1, figsize=(3.5, 2.6), sharey=True)
    ax.plot(x_data, sine, label="Sine")
    ax.plot(x_data, cosine, label="Cosine")
    plt.show()

An example notebook is available in src/demo.ipynb. Generated plots are saved under docs/figs/:

name_stamp/
    name.npz             # saved variables
    name.pdf             # exported figure
    name.png
    name.svg
    name.meta.json       # python/package versions + git commit
    replot_name.py       # standalone replot script