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, BarChart, Hist, Hist2D, and Image;
• optional JSON text files used to populate titles, axis labels, and legend labels.

Installation

On Unix-like systems:

1. Clone the repository.

2. Move into the project directory.

3. Install the package:

   pip install .

4. Import it in Python:

   import plotter

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
    ├── blueprint.txt
    ├── 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 scatter_plots, line_plots, bar_charts, histograms, histograms_2d, and images.
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.

Example

import numpy as np
import plotter as p


def f(x):
    return x**2


# datasets to plot
x = np.linspace(-5, 5, num=50)
y = x**2
y_err = np.full(50, 0.5)
x_err = np.full(50, 0.2)
categories = np.array([0.0, 1.0, 2.0])
heights = np.array([2.0, 4.0, 3.0])

with p.Canvas("example.json", rows_cols=(1, 2), show=False) as canvas:
    canvas.setup(0)
    canvas.setup(1)

    p.ScatterPlot(x, y, y_err, x_err).draw(canvas, label="data")
    p.LinePlot(x, f, wider=(0.01, 0.01)).draw(canvas, label=r"$f(x)=x^2$")
    p.BarChart(categories, heights).draw(canvas, plot_n=1, label="counts")

Available Drawables

• ScatterPlot: scatter plots with optional x/y error bars.
• LinePlot: function plots or explicit x/y line plots.
• BarChart: bar charts with optional y-error bars.
• Hist: one-dimensional histograms.
• Hist2D: two-dimensional histograms with colorbars.
• Image: grayscale or RGB(A) image rendering.

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

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.