hmbp 0.2.1__tar.gz

hmbp-0.2.1/.github/workflows/pypi.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for setuptools-scm versioning
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: List artifacts
+        run: ls -la dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses trusted publishing - no API token needed
+        # Configure at: https://pypi.org/manage/account/publishing/

hmbp-0.2.1/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+figures/
+.claude/
+hmbp/_version.py

hmbp-0.2.1/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: hmbp
+Version: 0.2.1
+Summary: Simple matplotlib and PGFPlots plotting with consistent, publication-ready styling
+Author: hmblair
+License: MIT
+Project-URL: Homepage, https://github.com/hmblair/hmbp
+Project-URL: Repository, https://github.com/hmblair/hmbp
+Keywords: plotting,matplotlib,pgfplots,latex,visualization,data-science
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# hmbp
+
+A simple matplotlib wrapper with consistent, publication-ready styling.
+
+## Installation
+
+```bash
+pip install hmbp
+```
+
+## Style
+
+- Font: Helvetica
+- Colormap: RdPu (primary), PiYG (secondary/diverging)
+- 400 DPI output
+- Consistent sizing: title 15pt, labels 14pt, ticks 13pt, legend 12pt
+
+## Usage
+
+```python
+import hmbp
+
+fig, ax = hmbp.new_figure()
+hmbp.line_plot(y_values, x_values, label="Model A")
+hmbp.set_labels("Title", "X Label", "Y Label")
+hmbp.save("output.png")
+```
+
+## Available Functions
+
+| Function | Description |
+|----------|-------------|
+| `line_plot` | Line with optional fill and smoothing |
+| `multi_line_plot` | Multiple lines on same axes with smoothing |
+| `scatter_plot` | Scatter with optional color mapping |
+| `histogram` | Color-mapped histogram |
+| `histogram_overlay` | Overlaid histograms for comparison |
+| `bar_plot` | Vertical/horizontal bars |
+| `box_plot` | Box plot distributions |
+| `violin_plot` | Violin plot distributions |
+| `heatmap` | 2D heatmap with colorbar |
+| `line_plot_with_error` | Line with shaded error region |
+| `confusion_matrix` | Annotated confusion matrix |
+| `roc_curve` | ROC curve with AUC |
+| `precision_recall_curve` | PR curve with AP |
+| `residual_plot` | Regression residuals |
+| `learning_curve` | Train/val learning curves |
+| `metric_comparison` | Horizontal bar comparison |
+| `volcano_plot` | Volcano plot for differential analysis |
+
+## Smoothing
+
+Line plots support EMA smoothing for noisy data (e.g., training curves):
+
+```python
+# smooth=0.9 means 90% weight on previous value (heavy smoothing)
+hmbp.quick_line(noisy_loss, smooth=0.9, path="smoothed.png")
+hmbp.quick_lines([y1, y2], labels=["A", "B"], smooth=0.8, path="comparison.png")
+```
+
+## Helpers
+
+- `new_figure(figsize)` - Create figure and axes
+- `set_labels(title, xlabel, ylabel)` - Apply labels
+- `save(path, fig, close)` - Save with auto-legend
+
+## Quick API
+
+Single-call functions that create, label, and save in one step:
+
+```python
+import hmbp
+
+hmbp.quick_histogram(data, title="Scores", xlabel="Value", path="hist.png")
+hmbp.quick_bar(values, labels, title="Comparison", ylabel="F1", path="bars.png")
+hmbp.quick_confusion_matrix(cm, class_names=["A", "B"], path="cm.png")
+```
+
+Available: `quick_line`, `quick_lines`, `quick_scatter`, `quick_histogram`, `quick_histogram_overlay`, `quick_bar`, `quick_heatmap`, `quick_confusion_matrix`, `quick_roc`, `quick_volcano`
+
+## PGFPlots Output
+
+Generate LaTeX figures using PGFPlots for direct inclusion in papers:
+
+```python
+import hmbp.pgfplots as pgf
+
+# Step-by-step
+pgf.new_figure()
+pgf.line_plot(y, x=x, label="Data", marker="*")
+pgf.set_labels(title="Results", xlabel="Time", ylabel="Value")
+pgf.save("figure.tex")  # Creates .tex and .pdf
+
+# Quick API
+pgf.quick_bar(values, labels, title="Comparison", path="bars.tex")
+pgf.quick_histogram(data, title="Distribution", path="hist.tex")
+```
+
+Features:
+- Outputs both `.tex` and compiled `.pdf` files
+- Helvetica font, clean axis styling, y-major grids
+- Supports `line_plot`, `multi_line_plot`, `bar_plot`, `histogram`
+- Log scale via `new_figure(ymode='log')`
+
+Requires a LaTeX distribution with `lualatex` or `pdflatex`.

hmbp-0.2.1/README.md

@@ -0,0 +1,105 @@
+# hmbp
+
+A simple matplotlib wrapper with consistent, publication-ready styling.
+
+## Installation
+
+```bash
+pip install hmbp
+```
+
+## Style
+
+- Font: Helvetica
+- Colormap: RdPu (primary), PiYG (secondary/diverging)
+- 400 DPI output
+- Consistent sizing: title 15pt, labels 14pt, ticks 13pt, legend 12pt
+
+## Usage
+
+```python
+import hmbp
+
+fig, ax = hmbp.new_figure()
+hmbp.line_plot(y_values, x_values, label="Model A")
+hmbp.set_labels("Title", "X Label", "Y Label")
+hmbp.save("output.png")
+```
+
+## Available Functions
+
+| Function | Description |
+|----------|-------------|
+| `line_plot` | Line with optional fill and smoothing |
+| `multi_line_plot` | Multiple lines on same axes with smoothing |
+| `scatter_plot` | Scatter with optional color mapping |
+| `histogram` | Color-mapped histogram |
+| `histogram_overlay` | Overlaid histograms for comparison |
+| `bar_plot` | Vertical/horizontal bars |
+| `box_plot` | Box plot distributions |
+| `violin_plot` | Violin plot distributions |
+| `heatmap` | 2D heatmap with colorbar |
+| `line_plot_with_error` | Line with shaded error region |
+| `confusion_matrix` | Annotated confusion matrix |
+| `roc_curve` | ROC curve with AUC |
+| `precision_recall_curve` | PR curve with AP |
+| `residual_plot` | Regression residuals |
+| `learning_curve` | Train/val learning curves |
+| `metric_comparison` | Horizontal bar comparison |
+| `volcano_plot` | Volcano plot for differential analysis |
+
+## Smoothing
+
+Line plots support EMA smoothing for noisy data (e.g., training curves):
+
+```python
+# smooth=0.9 means 90% weight on previous value (heavy smoothing)
+hmbp.quick_line(noisy_loss, smooth=0.9, path="smoothed.png")
+hmbp.quick_lines([y1, y2], labels=["A", "B"], smooth=0.8, path="comparison.png")
+```
+
+## Helpers
+
+- `new_figure(figsize)` - Create figure and axes
+- `set_labels(title, xlabel, ylabel)` - Apply labels
+- `save(path, fig, close)` - Save with auto-legend
+
+## Quick API
+
+Single-call functions that create, label, and save in one step:
+
+```python
+import hmbp
+
+hmbp.quick_histogram(data, title="Scores", xlabel="Value", path="hist.png")
+hmbp.quick_bar(values, labels, title="Comparison", ylabel="F1", path="bars.png")
+hmbp.quick_confusion_matrix(cm, class_names=["A", "B"], path="cm.png")
+```
+
+Available: `quick_line`, `quick_lines`, `quick_scatter`, `quick_histogram`, `quick_histogram_overlay`, `quick_bar`, `quick_heatmap`, `quick_confusion_matrix`, `quick_roc`, `quick_volcano`
+
+## PGFPlots Output
+
+Generate LaTeX figures using PGFPlots for direct inclusion in papers:
+
+```python
+import hmbp.pgfplots as pgf
+
+# Step-by-step
+pgf.new_figure()
+pgf.line_plot(y, x=x, label="Data", marker="*")
+pgf.set_labels(title="Results", xlabel="Time", ylabel="Value")
+pgf.save("figure.tex")  # Creates .tex and .pdf
+
+# Quick API
+pgf.quick_bar(values, labels, title="Comparison", path="bars.tex")
+pgf.quick_histogram(data, title="Distribution", path="hist.tex")
+```
+
+Features:
+- Outputs both `.tex` and compiled `.pdf` files
+- Helvetica font, clean axis styling, y-major grids
+- Supports `line_plot`, `multi_line_plot`, `bar_plot`, `histogram`
+- Log scale via `new_figure(ymode='log')`
+
+Requires a LaTeX distribution with `lualatex` or `pdflatex`.

hmbp-0.2.1/examples/sample_pgfplots.py

@@ -0,0 +1,152 @@
+"""
+Sample PGFPlots figures demonstrating the hmbp.pgfplots module.
+
+This script generates .tex files and compiles them to PDF.
+Requires a LaTeX distribution with lualatex or pdflatex.
+"""
+
+import numpy as np
+from pathlib import Path
+
+import hmbp.pgfplots as pgf
+
+# Output directory
+OUTPUT_DIR = Path(__file__).parent.parent / "figures" / "pgfplots"
+OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def line_plot_example():
+    """Generate a line plot with markers."""
+    x = np.array([0, 1, 2, 3, 4, 5])
+    y = np.array([1.2, 2.5, 1.8, 4.2, 3.5, 5.1])
+
+    pgf.new_figure()
+    pgf.line_plot(y, x=x, label="Measurements", marker="*")
+    pgf.set_labels(
+        title="Sample Line Plot",
+        xlabel="Time (s)",
+        ylabel="Value",
+    )
+    pdf = pgf.save(OUTPUT_DIR / "line_plot.tex")
+    print(f"Line plot: {pdf or 'tex only'}")
+
+
+def multi_line_example():
+    """Generate a plot with multiple lines."""
+    x = np.linspace(0, 10, 20)
+    y1 = np.sin(x)
+    y2 = np.cos(x)
+    y3 = np.sin(x) * 0.5
+
+    pgf.new_figure()
+    pgf.multi_line_plot(
+        [y1, y2, y3],
+        x=x,
+        labels=["sin(x)", "cos(x)", "0.5 sin(x)"],
+        marker="*",
+    )
+    pgf.set_labels(
+        title="Trigonometric Functions",
+        xlabel="x",
+        ylabel="y",
+    )
+    pdf = pgf.save(OUTPUT_DIR / "multi_line.tex")
+    print(f"Multi-line plot: {pdf or 'tex only'}")
+
+
+def bar_chart_example():
+    """Generate a bar chart."""
+    values = np.array([23, 45, 12, 67, 34])
+    labels = ["A", "B", "C", "D", "E"]
+
+    pgf.new_figure()
+    pgf.bar_plot(values, labels, color="purple")
+    pgf.set_labels(
+        title="Category Comparison",
+        xlabel="Category",
+        ylabel="Count",
+    )
+    pdf = pgf.save(OUTPUT_DIR / "bar_chart.tex")
+    print(f"Bar chart: {pdf or 'tex only'}")
+
+
+def histogram_example():
+    """Generate a histogram."""
+    np.random.seed(42)
+    data = np.random.normal(loc=5, scale=2, size=500)
+
+    pgf.new_figure()
+    pgf.histogram(data, bins=15, color="purple")
+    pgf.set_labels(
+        title="Distribution",
+        xlabel="Value",
+        ylabel="Count",
+    )
+    pdf = pgf.save(OUTPUT_DIR / "histogram.tex")
+    print(f"Histogram: {pdf or 'tex only'}")
+
+
+def log_scale_example():
+    """Generate a line plot with logarithmic y-axis."""
+    x = np.array([1, 2, 3, 4, 5, 6])
+    y = np.array([10, 100, 1000, 5000, 20000, 100000])
+
+    pgf.new_figure(ymode="log")
+    pgf.line_plot(y, x=x, label="Exponential Growth", marker="square*")
+    pgf.set_labels(
+        title="Logarithmic Scale",
+        xlabel="Step",
+        ylabel="Value",
+    )
+    pdf = pgf.save(OUTPUT_DIR / "log_scale.tex")
+    print(f"Log scale plot: {pdf or 'tex only'}")
+
+
+def quick_api_example():
+    """Demonstrate quick API functions."""
+    # Quick line plot
+    y = [1, 3, 2, 5, 4, 6]
+    pdf = pgf.quick_line(
+        y,
+        title="Quick Line",
+        xlabel="X",
+        ylabel="Y",
+        path=OUTPUT_DIR / "quick_line.tex",
+    )
+    print(f"Quick line: {pdf or 'tex only'}")
+
+    # Quick bar chart
+    pdf = pgf.quick_bar(
+        [10, 25, 15, 30],
+        ["Q1", "Q2", "Q3", "Q4"],
+        title="Quarterly Results",
+        xlabel="Quarter",
+        ylabel="Revenue",
+        path=OUTPUT_DIR / "quick_bar.tex",
+    )
+    print(f"Quick bar: {pdf or 'tex only'}")
+
+    # Quick histogram
+    np.random.seed(123)
+    data = np.random.exponential(scale=2, size=300)
+    pdf = pgf.quick_histogram(
+        data,
+        bins=12,
+        title="Exponential Distribution",
+        xlabel="Value",
+        path=OUTPUT_DIR / "quick_histogram.tex",
+    )
+    print(f"Quick histogram: {pdf or 'tex only'}")
+
+
+if __name__ == "__main__":
+    print("Generating PGFPlots examples...\n")
+
+    line_plot_example()
+    multi_line_example()
+    bar_chart_example()
+    histogram_example()
+    log_scale_example()
+    quick_api_example()
+
+    print(f"\nOutput directory: {OUTPUT_DIR}")

hmbp-0.2.1/examples/sample_plots.py

@@ -0,0 +1,167 @@
+"""Generate sample plots to demonstrate the hmbp plotting module."""
+
+import numpy as np
+import hmbp
+
+np.random.seed(42)
+
+# 1. Line plot
+fig, ax = hmbp.new_figure()
+x = np.linspace(0, 10, 100)
+hmbp.line_plot(np.sin(x), x, label="Model A")
+hmbp.line_plot(np.cos(x), x, label="Model B", cmap=hmbp.CMAP_ALT)
+hmbp.set_labels("Training Loss Over Time", "Epoch", "Loss")
+hmbp.save("figures/01_line_plot.png")
+
+# 2. Scatter plot
+fig, ax = hmbp.new_figure()
+x = np.random.randn(200)
+y = 0.5 * x + np.random.randn(200) * 0.3
+hmbp.scatter_plot(x, y, c=y, label="Samples")
+hmbp.set_labels("Feature Correlation", "Feature A", "Feature B")
+hmbp.save("figures/02_scatter_plot.png")
+
+# 3. Histogram
+fig, ax = hmbp.new_figure()
+data = np.concatenate([np.random.randn(500), np.random.randn(300) + 3])
+hmbp.histogram(data, bins=40)
+hmbp.set_labels("Score Distribution", "Score", "Count")
+hmbp.save("figures/03_histogram.png")
+
+# 4. Bar plot
+fig, ax = hmbp.new_figure()
+models = ["Random Forest", "XGBoost", "Neural Net", "SVM", "LogReg"]
+scores = [0.92, 0.95, 0.91, 0.88, 0.85]
+hmbp.bar_plot(scores, models)
+hmbp.set_labels("Model Comparison", "", "F1 Score")
+hmbp.save("figures/04_bar_plot.png")
+
+# 5. Box plot
+fig, ax = hmbp.new_figure()
+data = [np.random.randn(100) + i * 0.5 for i in range(4)]
+hmbp.box_plot(data, ["Model A", "Model B", "Model C", "Model D"])
+hmbp.set_labels("Score Distribution by Model", "", "Score")
+hmbp.save("figures/05_box_plot.png")
+
+# 6. Violin plot
+fig, ax = hmbp.new_figure()
+data = [np.random.randn(100) * (i + 1) * 0.3 for i in range(4)]
+hmbp.violin_plot(data, ["Small", "Medium", "Large", "XL"])
+hmbp.set_labels("Prediction Variance by Model Size", "", "Prediction Error")
+hmbp.save("figures/06_violin_plot.png")
+
+# 7. Heatmap (correlation matrix)
+fig, ax = hmbp.new_figure()
+corr = np.random.randn(6, 6)
+corr = (corr + corr.T) / 2
+np.fill_diagonal(corr, 1)
+features = ["feat_1", "feat_2", "feat_3", "feat_4", "feat_5", "feat_6"]
+hmbp.heatmap(corr, xticklabels=features, yticklabels=features,
+             colorbar_label="Correlation", center_zero=True, annot=True)
+hmbp.set_labels("Feature Correlation Matrix", "", "")
+hmbp.save("figures/07_heatmap.png")
+
+# 8. Line plot with error
+fig, ax = hmbp.new_figure()
+x = np.arange(10)
+y = np.exp(-x * 0.3) + 0.1
+yerr = 0.05 + 0.02 * np.random.randn(10)
+hmbp.line_plot_with_error(y, np.abs(yerr), x, label="Mean +/- Std")
+hmbp.set_labels("Convergence with Uncertainty", "Iteration", "Loss")
+hmbp.save("figures/08_line_with_error.png")
+
+# 9. Confusion matrix
+fig, ax = hmbp.new_figure()
+cm = np.array([[85, 10, 5], [8, 82, 10], [4, 12, 84]])
+hmbp.confusion_matrix(cm, class_names=["Cat", "Dog", "Bird"], normalize=True)
+hmbp.set_labels("Classification Results", "", "")
+hmbp.save("figures/09_confusion_matrix.png")
+
+# 10. ROC curve
+fig, ax = hmbp.new_figure()
+fpr1 = np.linspace(0, 1, 100)
+tpr1 = np.sqrt(fpr1)  # Good model
+tpr2 = fpr1 ** 2 + fpr1 * 0.5  # Mediocre model
+tpr2 = np.clip(tpr2, 0, 1)
+hmbp.roc_curve(fpr1, tpr1, auc=0.92, label="XGBoost")
+hmbp.roc_curve(fpr1, tpr2, auc=0.71, label="Baseline", cmap=hmbp.CMAP_ALT)
+hmbp.set_labels("ROC Comparison", "", "")
+hmbp.save("figures/10_roc_curve.png")
+
+# 11. Precision-Recall curve
+fig, ax = hmbp.new_figure()
+recall = np.linspace(0, 1, 100)
+precision1 = 1 - 0.3 * recall ** 2
+precision2 = 1 - 0.6 * recall
+hmbp.precision_recall_curve(precision1, recall, ap=0.89, label="Model A")
+hmbp.precision_recall_curve(precision2, recall, ap=0.72, label="Model B", cmap=hmbp.CMAP_ALT)
+hmbp.set_labels("Precision-Recall Comparison", "", "")
+hmbp.save("figures/11_pr_curve.png")
+
+# 12. Residual plot
+fig, ax = hmbp.new_figure()
+y_pred = np.linspace(0, 10, 100)
+y_true = y_pred + np.random.randn(100) * 0.5
+hmbp.residual_plot(y_true, y_pred)
+hmbp.set_labels("Residual Analysis", "", "")
+hmbp.save("figures/12_residual_plot.png")
+
+# 13. Learning curve
+fig, ax = hmbp.new_figure()
+sizes = np.array([100, 200, 500, 1000, 2000, 5000])
+train_scores = np.column_stack([
+    0.99 - 0.1 * np.exp(-sizes / 500) + np.random.randn(6) * 0.01
+    for _ in range(5)
+])
+val_scores = np.column_stack([
+    0.85 + 0.1 * (1 - np.exp(-sizes / 1000)) + np.random.randn(6) * 0.02
+    for _ in range(5)
+])
+hmbp.learning_curve(train_scores, val_scores, sizes, metric_name="Accuracy")
+hmbp.set_labels("Learning Curve", "", "")
+hmbp.save("figures/13_learning_curve.png")
+
+# 14. Metric comparison
+fig, ax = hmbp.new_figure()
+metrics = {
+    "Accuracy": 0.94,
+    "Precision": 0.91,
+    "Recall": 0.88,
+    "F1": 0.89,
+    "AUC": 0.96
+}
+hmbp.metric_comparison(metrics)
+hmbp.set_labels("Model Metrics", "", "")
+hmbp.save("figures/14_metric_comparison.png")
+
+# 15. Histogram overlay
+fig, ax = hmbp.new_figure()
+data1 = np.random.randn(500) * 0.8
+data2 = np.random.randn(500) * 1.2 + 1.5
+data3 = np.random.randn(500) * 0.6 + 3
+hmbp.histogram_overlay([data1, data2, data3], labels=["MLP", "Attention", "Ground Truth"], bins=30)
+hmbp.set_labels("Score Distributions by Model", "Score", "Count")
+hmbp.save("figures/15_histogram_overlay.png")
+
+# 16. Multi-line plot with noisy data and smoothing
+fig, ax = hmbp.new_figure()
+x = np.arange(100)
+y1 = np.exp(-x * 0.03) + np.random.randn(100) * 0.08
+y2 = np.exp(-x * 0.025) * 0.9 + np.random.randn(100) * 0.08
+y3 = np.exp(-x * 0.035) * 1.1 + np.random.randn(100) * 0.08
+hmbp.multi_line_plot([y1, y2, y3], x, labels=["Adam", "SGD", "AdamW"], smooth=0.9)
+hmbp.set_labels("Training Loss Comparison (Smoothed)", "Epoch", "Loss")
+hmbp.save("figures/16_multi_line.png")
+
+# 17. Raw vs smoothed comparison
+import matplotlib.pyplot as plt
+fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
+x = np.arange(100)
+y = np.exp(-x * 0.03) + np.random.randn(100) * 0.15
+hmbp.line_plot(y, x, label="Raw", ax=ax1, fill=False)
+hmbp.set_labels("Raw Training Curve", "Epoch", "Loss", ax=ax1)
+hmbp.line_plot(y, x, label="Smoothed (0.9)", ax=ax2, fill=False, smooth=0.9)
+hmbp.set_labels("EMA Smoothed (weight=0.9)", "Epoch", "Loss", ax=ax2)
+hmbp.save("figures/17_smoothing_comparison.png")
+
+print("Generated 17 sample plots in figures/")