driedfigs

Preserve your matplotlib figures with their data for reproducible research.

driedfigs makes it effortless to save the data behind your matplotlib plots alongside your figures, ensuring complete reproducibility for academic publications.

Why driedfigs?

When you publish research papers with figures, reviewers and readers often want to see the underlying data. Manually extracting and organizing this data is tedious and error-prone. driedfigs automatically captures the data passed to matplotlib plotting functions and saves it in a structured format.

Key Features

• Zero effort reproducibility: Automatically capture plot data with minimal code changes
• Publication-ready: Save data alongside figures for complete transparency
• Non-intrusive: Works with existing matplotlib code - just add name parameters
• Flexible: Supports most matplotlib plotting functions (plot, scatter, contour, etc.)
• Simple API: Just two main functions - start_figure() and save_figuredata()

Installation

pip install driedfigs

For xarray support (automatic conversion of DataArrays to numpy):

pip install driedfigs[xarray]

Quick Start

import driedfigs as df
import matplotlib.pyplot as plt
import numpy as np

# 1. Start capturing data for a figure
fig_data = df.start_figure("example_plot")

# 2. Create plots with the 'name' parameter to identify each artist
x = np.linspace(0, 10, 100)
plt.plot(x, np.sin(x), name="sin_wave")
plt.scatter([1, 2, 3], [0.5, 0.8, 1.2], name="data_points")

# 3. Save the data
df.save_figuredata("./data/example_plot.pkl")

# 4. Save the figure (using standard matplotlib)
plt.savefig("./figures/example_plot.pdf")

This creates:

• ./figures/example_plot.pdf (the figure, saved normally)
• ./data/example_plot.pkl (the captured data)

How It Works

driedfigs hooks into matplotlib's plotting functions to capture the data you pass to them:

1. Install hooks (automatic on first use): Wraps matplotlib functions to intercept data
2. Name your plots: Add name="identifier" to capture that plot's data
3. Save the data: Call save_figuredata() to persist the captured data
4. Save your figure: Use matplotlib's normal savefig() to save the visualization

Detailed Usage

Basic Workflow

import driedfigs as df
import matplotlib.pyplot as plt

# Start a new figure
fig_data = df.start_figure("my_analysis", verbose=True)

# Make plots - use 'name' to capture data
plt.plot(x_data, y_data, name="raw_data")
plt.plot(x_model, y_model, '--', name="model_fit")

# Save the data
df.save_figuredata("./data/my_analysis.pkl")

# Save the figure (standard matplotlib)
plt.savefig("./figures/my_analysis.pdf")
plt.savefig("./figures/my_analysis.png", dpi=300)

Loading Saved Data

import pickle

# Load the saved data
with open("data/my_analysis.pkl", "rb") as f:
    data = pickle.load(f)

# Access specific plot data
raw_data = data["raw_data"]  # Returns tuple of args passed to plt.plot
x, y = raw_data[0], raw_data[1]

Supported Matplotlib Functions

pyplot functions:

plot, scatter, bar, hist, imshow, contour, contourf, pcolormesh, fill_between, errorbar, boxplot, violin, pie, polar, loglog, semilogx, semilogy

Axes methods:

plot, scatter, bar, hist, imshow, contour, contourf, pcolormesh, fill_between, errorbar, boxplot, violin

Managing Multiple Figures

# Create separate figure data objects
fig1 = df.start_figure("figure_1")
plt.plot(x1, y1, name="data1")
fig1.save("./data/figure1.pkl")  # Use the .save() method

fig2 = df.start_figure("figure_2")
plt.plot(x2, y2, name="data2")
fig2.save("./data/figure2.pkl")

Real-World Example

import driedfigs as df
import matplotlib.pyplot as plt
import numpy as np

# Simulate some research data
time = np.linspace(0, 10, 100)
measurement = np.sin(time) + np.random.normal(0, 0.1, 100)
model = np.sin(time)

# Start capturing
df.start_figure("experiment_results")

# Create publication-quality plot
plt.figure(figsize=(10, 6))
plt.plot(time, measurement, 'o', alpha=0.5, label="Measurements", name="raw_measurements")
plt.plot(time, model, '-', linewidth=2, label="Model", name="theoretical_model")
plt.xlabel("Time (s)")
plt.ylabel("Signal (V)")
plt.legend()
plt.title("Experimental Results vs. Theoretical Model")

# Save the data for reproducibility
df.save_figuredata("./manuscript/data/experiment_results.pkl")

# Save the figure
plt.savefig("./manuscript/figures/experiment_results.pdf")
plt.savefig("./manuscript/figures/experiment_results.png", dpi=300)

# Now you can upload ./manuscript/ with your paper submission!

Tips for Reproducible Research

1. Name everything: Use descriptive names for all plots you want to preserve
2. Organize by figure: Create one driedfigs capture per figure in your paper
3. Include data with submissions: Upload the .pkl files alongside your manuscript
4. Document your workflow: Add a README explaining how to load and use the data
5. Version control: Commit both code and data files to git (if reasonable size)

API Reference

Main Functions

• start_figure(name, verbose=False): Begin capturing data for a new figure

  • Returns a FigureData instance
  • Automatically installs hooks on first use

• save_figuredata(output_path, figuredata=None): Save captured data to a pickle file

  • If figuredata is None, uses the currently active FigureData

FigureData Class

• save(output_path): Save this figure's data to file
• figure_name: Name of the figure
• figure_data: Dictionary mapping artist names to their data
• is_active: Whether this FigureData is currently active

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests on GitHub.

License

MIT License - see LICENSE file for details.

Citation

If you use driedfigs in your research, please cite:

@software{driedfigs,
  author = {Davis, Charles},
  title = {driedfigs: Preserve matplotlib figure data for reproducible research},
  year = {2025},
  url = {https://github.com/cmdavis4/driedfigs}
}

---

Made with care for reproducible science 🔬📊