lusca 0.1.1

A Jupyter magic command for creating reproducible matplotlib figures.

lusca

lusca is a Python library for creating reproducible matplotlib figures using Jupyter magic commands.

Often, you want to use Jupyter for experiments but may not want to rerun the entire notebook to recreate plots. Additionally, saving data and figures is essential for artifact generation and reproducibility.

📊 %%mplfreeze Command

The %%mplfreeze magic command:

• Captures the data used in your plots and saves it in a compressed NPZ file.
• Automatically exports your figures in multiple useful formats.
• Creates 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.
• Leverages lusca's built-in stylesheet.

Once you're satisfied with your plot, add the %%mplfreeze command to the cell.

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

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

Example

1. Import and load the magic command

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

2. Some data

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

3. Plot + save

%%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. The generated plots are saved in docs/figs/ with the following structure:

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

Installation

Install lusca directly from GitHub:

pip install -e git+https://github.com/evmckinney9/lusca#egg=lusca

Note

If you are using VS Code, you can set the workspace root as the default directory for saving figures by adding the following setting to your settings.json file. Otherwise, output paths will be relative to the notebook location.

"jupyter.notebookFileRoot": "${workspaceFolder}"