SnapShotPlot 📸📊

Capture Python code, Matplotlib plots, and HTML documentation in one step with automatic timestamping and organization.

Ever run into this?

"Cool plot... where's the code that made it?" "You made a mistake here, this other plot a few runs back was the correct one." "Uhh... I think I overwrote it... maybe version 12_final_final_really_final.py?"

Yeah. Same.

snapshotplot was born out of one too many late-night research plot reviews where the code was somewhere, but no one could say where. I got tired of asking "how did you generate this?" and getting blank stares.

This package automatically takes a snapshot of your code and the plot every time you run it—HTML, code, and image saved, timestamped, and organized like a sane person lives here.

You get reproducibility without thinking about it. Your future self (and your collaborators) will thank you.

Just wrap your code with the snapshot context manager and keep shipping.

Because science shouldn't involve detective work.

Features

• 🔄 Decorator & Context Manager Support: Use as @snapshot() or with snapshot():
• ⏰ Unified Timestamping: Single UTC timestamp per snapshot run
• 📁 Auto-Organization: Creates timestamped folders with all outputs
• 🎨 HTML Documentation: Beautiful, syntax-highlighted HTML with embedded plots
• 🔧 Zero Configuration: Works out of the box with sensible defaults
• 🚀 Non-Intrusive: Runs silently in the background

Quick Start

Installation

pip install snapshotplot

Basic Usage

As a Decorator

from snapshotplot import snapshot
import matplotlib.pyplot as plt
import numpy as np

@snapshot()
def create_sine_wave():
    x = np.linspace(0, 2*np.pi, 100)
    y = np.sin(x)
    plt.plot(x, y)
    plt.title("Sine Wave")
    plt.grid(True)
    plt.show()

As a Context Manager

from snapshotplot import snapshot
import matplotlib.pyplot as plt
import numpy as np

with snapshot():
    x = np.linspace(0, 10, 100)
    y = x**2
    plt.plot(x, y)
    plt.title("Quadratic Function")
    plt.xlabel("x")
    plt.ylabel("y = x²")
    plt.show()

Output Structure

Each snapshot creates a folder structure like this:

snapshot_<filename>/
├── 20241201_143022_123_code.py       # Raw source code
├── 20241201_143022_123_plot.png      # Saved plot image
└── 20241201_143022_123_snapshot.html # HTML documentation

The HTML file contains:

• Metadata: Filename, function name, timestamp
• Syntax-highlighted code: Your Python code with proper formatting
• Embedded plot: The matplotlib figure directly in the HTML
• Clean styling: Professional, readable layout

HTML Example

Here's what the generated HTML documentation looks like:

The output includes:

• Dark mode interface for easy reading
• Side-by-side layout with code and plot
• Syntax-highlighted Python code
• Embedded plot images
• Responsive design for mobile and desktop

Configuration Options

@snapshot(
    output_dir="my_snapshots",      # Custom output directory
    code_format="html",            # Code format in HTML
    title="My Analysis",           # Custom title for HTML
    author="Data Scientist",       # Author metadata
    notes="Important findings"     # Additional notes
)
def my_analysis():
    # Your code here
    pass

Advanced Usage

Custom Output Directory

@snapshot(output_dir="research_outputs")
def research_plot():
    # Your research code
    pass

With Metadata

@snapshot(
    title="Sales Analysis Q4",
    author="Analytics Team",
    notes="Key insights from quarterly data"
)
def sales_analysis():
    # Your analysis code
    pass

Context Manager with Configuration

with snapshot(output_dir="experiments", title="A/B Test Results"):
    # Your experimental code
    pass

Jupyter Notebook Integration

SnapshotPlot provides seamless integration with Jupyter notebooks through IPython magic commands, enabling you to capture and document your analysis workflow with zero overhead.

Quick Start

# 1. Load the extension (once per notebook)
%load_ext snapshotplot

# 2. Use cell magic to capture analysis
%%snapshot -t "Customer Analysis" -a "Data Science Team"
import matplotlib.pyplot as plt
import pandas as pd

# Your analysis code
df = pd.read_csv('data.csv')
plt.figure(figsize=(10, 6))
plt.hist(df['revenue'], bins=30)
plt.title('Revenue Distribution')
plt.show()

Magic Commands

Cell Magic (%%snapshot)

Capture an entire cell's code and output - the most common usage pattern:

%%snapshot -t "Market Segmentation" -a "Analytics Team" --tags ml clustering
import matplotlib.pyplot as plt
import numpy as np
from sklearn.cluster import KMeans

# Perform clustering analysis
data = np.random.rand(100, 2)
kmeans = KMeans(n_clusters=3)
clusters = kmeans.fit_predict(data)

# Visualize results
plt.figure(figsize=(8, 6))
plt.scatter(data[:, 0], data[:, 1], c=clusters, cmap='viridis')
plt.title('Customer Segments')
plt.xlabel('Feature 1')
plt.ylabel('Feature 2')
plt.colorbar(label='Cluster')
plt.show()

Line Magic (%snapshot)

Capture the previous cell's output - useful for retroactive documentation:

# First cell: Create your analysis
plt.figure(figsize=(10, 6))
plt.plot(time_series_data)
plt.title('Sales Trend Over Time')
plt.show()

# Second cell: Capture it with metadata
%snapshot -t "Q4 Sales Trend" -a "Sales Team" --tags quarterly sales --description "Shows strong growth in Q4"

Magic Command Arguments

All magic commands support comprehensive metadata and configuration options:

# Basic metadata
%%snapshot -t "Analysis Title" -a "Author Name" -n "Additional notes"

# Categorization and organization  
%%snapshot --tags experiment ml analysis --description "Detailed description" --collection research

# Custom output location
%%snapshot -o "custom_snapshots" --dpi 300

# Site integration (for static site generation)
%%snapshot --site "../my-blog" --collection "data-science" --auto-build

# Full example with all options
%%snapshot -t "Final Model Results" \
           -a "ML Team" \
           -n "Production model evaluation" \
           --tags model evaluation production \
           --description "Performance metrics for the final customer churn model" \
           --collection "ml-models" \
           --site "../research-blog" \
           --auto-commit \
           --auto-build

Context Manager

Use the notebook-aware context manager for programmatic control:

from snapshotplot import notebook_snapshot

# Basic usage
with notebook_snapshot(title="Experiment Results"):
    run_experiment()
    plot_results()
    plt.show()

# With full configuration
with notebook_snapshot(
    title="A/B Test Analysis",
    author="Product Team", 
    tags=["ab-test", "conversion"],
    collection="experiments",
    site="../product-blog"
):
    analyze_ab_test()
    plot_conversion_rates()
    plt.show()

Real-World Workflow

Here's how to integrate SnapshotPlot into a typical data science workflow:

# === NOTEBOOK SETUP ===
%load_ext snapshotplot
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns

# === EXPLORATORY DATA ANALYSIS ===
# Regular cells for exploration (no snapshot needed)
df = pd.read_csv('customer_data.csv')
df.info()
df.describe()

# === KEY INSIGHTS (Capture with snapshot) ===
%%snapshot -t "Customer Demographics Overview" -a "Data Science Team" --tags demographics eda
plt.figure(figsize=(12, 4))

plt.subplot(1, 3, 1)
df['age'].hist(bins=20)
plt.title('Age Distribution')

plt.subplot(1, 3, 2) 
df['income'].hist(bins=20)
plt.title('Income Distribution')

plt.subplot(1, 3, 3)
sns.countplot(data=df, x='segment')
plt.title('Customer Segments')

plt.tight_layout()
plt.show()

# === MODELING (More exploration) ===
from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

# === MODEL RESULTS (Capture with snapshot) ===
%%snapshot -t "Model Performance Evaluation" --tags modeling evaluation --collection research
from sklearn.metrics import classification_report, confusion_matrix
import seaborn as sns

# Evaluate model
y_pred = model.predict(X_test)

# Plot confusion matrix
plt.figure(figsize=(8, 6))
cm = confusion_matrix(y_test, y_pred)
sns.heatmap(cm, annot=True, fmt='d', cmap='Blues')
plt.title('Confusion Matrix')
plt.ylabel('Actual')
plt.xlabel('Predicted')
plt.show()

print("Classification Report:")
print(classification_report(y_test, y_pred))

# === FINAL INSIGHTS (Capture for presentation) ===
%%snapshot -t "Business Impact Analysis" -a "Data Science Team" \
           --description "Revenue impact of customer segmentation model" \
           --tags business-impact revenue --collection presentations \
           --site "../executive-dashboard" --auto-build

# Calculate business impact
plot_revenue_impact_by_segment()
plt.show()

Generated Output

Each snapshot creates three files with consistent naming:

Project/
├── my_analysis.ipynb
└── snapshot_my_analysis/
    ├── 20240718_143022_001_code.py      # Cell source code
    ├── 20240718_143022_001_plot.png     # Matplotlib figure
    ├── 20240718_143022_001_snapshot.html # HTML documentation
    ├── 20240718_143155_002_code.py      # Next snapshot
    ├── 20240718_143155_002_plot.png
    └── 20240718_143155_002_snapshot.html

HTML Documentation Features

The generated HTML documentation includes:

• Notebook Metadata: Name, kernel info, execution timestamp
• Syntax-Highlighted Code: Beautiful Python code formatting
• Embedded Plots: High-resolution matplotlib figures
• User Metadata: Title, author, tags, and notes
• Responsive Design: Mobile and desktop friendly