Plotter

A small Python library for drawing beautiful plots on top of matplotlib.

Description

Plotter wraps common plotting tasks in small drawable objects with sensible defaults. The library is still matplotlib-based, so it works best when the user is already somewhat familiar with the underlying plotting model.

The current design revolves around:

• a Canvas object, which owns the figure and axes and acts as a context manager;
• drawable objects such as ScatterPlot, LinePlot, FunctionPlot, BarChart, BoxPlot, RawHist, BinnedHist, RawHist2D, BinnedHist2D, and Image, plus an explicit Colorbar for the last three;
• optional JSON text files used to populate titles, axis labels, and legend labels.

Installation

From the project root, run pip install ., then import plotter in Python. See the Quickstart for the full setup.

Workspace Layout

Call plotter.setup_workspace() once in the directory where you want to work. This creates the files and folders used by the library:

plotter
├── img
├── log
│   └── plotter.log
├── text
│   └── text_example.json
└── utils
    ├── info
    ├── log_config.json
    └── style.mplstyle

These files have the following purposes:

1. plotter/img/ stores saved figures.
2. plotter/log/ stores log output.
3. plotter/text/ stores JSON files with plot titles, axis labels, and legend labels. A subplot entry can include title, x_label, y_label, and the label lists scatter_plots, line_plots, bar_charts, box_plots, and histograms. Image, RawHist2D, and BinnedHist2D take no labels.
4. plotter/utils/ stores bundled helper assets and configuration files.

Usage

Canvas is a context manager. That means the figure lifecycle is handled automatically: when the with block exits, Plotter finalizes the legend, saves the figure if requested, and shows or closes it depending on the canvas configuration.

import numpy as np
import plotter as p

p.setup_workspace()

x = np.linspace(-5, 5, num=50)
y = x**2

with p.Canvas("example.json", show=False) as canvas:
    canvas.setup()
    p.ScatterPlot(x, y, yerr=np.full(50, 0.5), xerr=np.full(50, 0.2)).draw(canvas, label="data")
    p.FunctionPlot(x, lambda values: values**2, wider=(0.01, 0.01)).draw(canvas, label=r"$f(x)=x^2$")

The Quickstart covers the JSON text-file format, custom layouts, and more.

Available Drawables

• ScatterPlot: scatter plots with optional x/y error bars.
• LinePlot: explicit x/y line plots.
• FunctionPlot: function plots over a (possibly widened/densified) domain.
• BarChart: bar charts with optional y-error bars.
• BoxPlot: groups of box-and-whisker plots.
• RawHist: one-dimensional histograms computed from raw sample data.
• BinnedHist: one-dimensional histograms drawn from already pre-computed bin values.
• RawHist2D: two-dimensional histograms computed from raw sample data (pair with Colorbar for a colorbar).
• BinnedHist2D: two-dimensional histograms drawn from already pre-computed bin values (pair with Colorbar for a colorbar).
• Image: grayscale or RGB(A) image rendering (pair with Colorbar for a colorbar).
• Colorbar: an explicit colorbar for an already-drawn RawHist2D, BinnedHist2D, or Image, attached to one subplot or shared across a row/column.

All drawable classes inherit from Drawable and implement a draw(canvas, ...) method.

Examples

The example/ directory contains runnable scripts showing the library in practice, including Colorbar and zoom-inset usage. See example/README.md for how to run them.

Documentation Website

The published documentation is available at https://lmarchetti02.github.io/plotter/.

The documentation site is built with Zensical from the Markdown files in docs/. The API reference pages are generated from the docstrings in plotter/.

To refresh the API pages and build the site locally:

uv run python tools/generate_api_docs.py
uv run zensical build

To preview the site:

uv run zensical serve

The GitHub Actions workflow in .github/workflows/deploy-docs.yml rebuilds the documentation and deploys the generated site/ directory to GitHub Pages on every push to main. The workflow can also be run manually from the Actions tab.

Images

License

See the LICENSE file for license rights and limitations.