plotez 0.3.3

Mundane plotting done easy.

plotEZ

Mundane plotting made easy.

plotez is a Python library that simplifies common matplotlib plotting tasks with an intuitive API. Create complex plots with minimal boilerplate code.

Project Status

Item	Status
Latest version	v0.3.3
Python support	3.10 · 3.11 · 3.12
Test coverage	85%+
Type hints	PEP 561 compliant (py.typed)
Documentation	Read the Docs
Changelog	CHANGELOG
License	MIT

Features

• Simple API: Create complex plots with just a few lines of code
• Error Bar Plotting: Comprehensive error bar support with enhanced styling options
• Error Band Plotting: Shaded error band support via plot_errorband, plot_errorband_relative, and ErrorBandConfig
• Histogram & Density Plotting: plot_hist and plot_density with HistogramConfig / hgc
• Dual-Axis Support: Easy creation of dual y-axis or dual x-axis plots
• Multi-Panel Layouts: Flexible subplot arrangements with automatic labeling
• File Integration: Direct plotting from CSV files
• Extensive Customization: Full control over plot appearance via parameter classes
• Custom Exceptions: Domain-specific exceptions for clear, catchable error handling
• Early Input Validation: Clear ShapeError, DataLengthError, and EmptyDataError failures before matplotlib
• Type Safety: Complete type hints for better IDE support and type checking (PEP 561 compliant)
• Well Tested: Comprehensive test suite with 85%+ coverage

Installation

From PyPI

pip install plotez

From Source

git clone https://github.com/syedalimohsinbukhari/plotez.git
cd plotez
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

import numpy as np
from plotez import plot_xy

x = np.linspace(0, 10, 100)
y = np.sin(x)
plot_xy(x, y)

That's it. Three lines for a labeled plot.

Examples

Scientific Error Bars

import numpy as np
from plotez import plot_errorbar
from plotez.backend import ErrorPlotConfig

rng = np.random.default_rng(1234)

x = np.linspace(0, 10, 20)
y = np.sin(x)
y_err = 0.2 * rng.random(size=y.shape)

ep = ErrorPlotConfig(color="darkblue", marker="o", capsize=5, ecolor="red", markerfacecolor="lime")
plot_errorbar(x, y, y_err=y_err, errorbar_config=ep)

Professional error bars in a few lines of config. ecolor sets the error bar colour independently from the line colour.

---

Dual Y-Axis

import numpy as np
from plotez import plot_xyy

x = np.linspace(0, 10, 100)
y1 = np.sin(x)
y2 = np.exp(-x / 10)

plot_xyy(x, y1, y2, x_label="Time (s)", y1_label="Signal (V)", y2_label="Decay",
         data_labels=["Oscillation", "Envelope"])

Dual axes done right. No ax.twinx() gymnastics.

---

Multi-Panel Grid

import numpy as np
from plotez import n_plotter

x_data = np.linspace(0, 10, 100)
y_data = [np.sin(x_data), np.cos(x_data),
          np.tan(x_data / 5), x_data ** 2 / 100]

n_plotter(x_data, y_data, n_rows=2, n_cols=2)

Four plots, one function call.

---

Error Bands

Use ErrorBandConfig and LinePlotConfig for explicit, IDE-friendly configuration:

import numpy as np
from plotez import plot_errorband
from plotez.backend import ErrorBandConfig, LinePlotConfig

x = np.linspace(0, 10, 50)
y = np.sin(x)
y_lower = y - 0.2
y_upper = y + 0.2

band_config = ErrorBandConfig(color="darkblue", alpha=0.25)
plot_config = LinePlotConfig(color="gold", linewidth=2, linestyle="--",
                             marker="o", markersize=5, markeredgecolor="k")

plot_errorband(x, y, y_lower, y_upper,
               data_label="Measurement", band_config=band_config, line_config=plot_config)

The same result using the ebc / lpc shorthand aliases — familiar matplotlib parameter names, no class imports needed:

import numpy as np
from plotez import ebc, lpc, plot_errorband

x = np.linspace(0, 10, 50)
y = np.sin(x)
y_lower = y - 0.2
y_upper = y + 0.2

band_config = ebc(c="darkblue", alpha=0.25)
plot_config = lpc(c="gold", lw=2, ls="--", marker="o", ms=5, mec="k")

plot_errorband(x, y, y_lower, y_upper,
               data_label="Measurement", band_config=band_config, line_config=plot_config)

---

Full Customization

import numpy as np
from plotez import plot_xyy
from plotez.backend import LinePlotConfig

x = np.linspace(0, 10, 50)
y1, y2 = np.sin(x), np.cos(x)

config = LinePlotConfig(
    linestyle=["--", "-."],
    color=["crimson", "gold"],
    marker=["o", "s"],
    markersize=[8, 8],
    markeredgecolor=["black", "black"],
    _extra={"markevery": [5, 5]},
)

plot_xyy(x, y1, y2, plot_config=config)

Config classes for when defaults aren't enough. Use _extra to pass any matplotlib parameter not covered by the dataclass fields.

---

Histogram / Density

Use plot_hist with the hgc shorthand to configure and plot a histogram in one go. Switch to plot_density to get normalised probability density instead of raw counts — everything else stays the same. Both functions accept one 1D dataset per call.

import numpy as np
from plotez import hgc, plot_hist

rng = np.random.default_rng(42)
data = rng.normal(loc=0, scale=1, size=5000)

h_cfg = hgc(bins=40, color="steelblue", ec="white", alpha=0.8)
plot_hist(data, x_label="Value", y_label="Counts",
          plot_title="Histogram of Normal Distribution",
          data_label="Normal", hist_config=h_cfg)

Swap plot_hist for plot_density to get the probability density on the y-axis.

Development

Running Tests

pytest

With Coverage Report

pytest --cov=src/plotez --cov-report=html

Type Checking

mypy src/plotez

Building Documentation

cd docs
make html

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License – see LICENSE file for details.

Authors

• Syed Ali Mohsin Bukhari - [e-mail]

Links

• Repository: https://github.com/syedalimohsinbukhari/plotez
• Issues: https://github.com/syedalimohsinbukhari/plotez/issues