Usage guide

For narrative topics (when to call apply, saving, axes helpers, labels, Jupyter, and API stability), see the Guides entries in the left-hand toctree.

Installation

Install SignalPlot into your environment:

pip install signalplot

Or, from a clone of the repository in editable mode:

pip install -e .

Quick start

The basic pattern is:

1. Import Matplotlib and SignalPlot.

2. Call signalplot.apply() once.

3. Use plain Matplotlib to create figures.

4. Save with signalplot.save() or plt.savefig (after patching).

import matplotlib.pyplot as plt
import signalplot as sp

sp.apply()

x = [1, 2, 3, 4]
y = [2, 3, 2.5, 4]

fig, ax = plt.subplots()
ax.plot(x, y)
ax.set_title("Example series")

sp.finish(ax)
sp.save("example.png")
plt.show()

Direct labels and events

SignalPlot prefers direct labels and simple, explicit event markers over heavy legends and decorations.

import numpy as np
import matplotlib.pyplot as plt
import signalplot as sp

sp.apply()

x = np.arange(0, 36)
y = np.cumsum(np.random.default_rng(0).normal(size=x.size))

fig, ax = plt.subplots()
ax.plot(x, y)

sp.direct_label(ax, x[-1], y[-1], "Series A", dx=0.5)
sp.event_line(ax, x=18, text="Policy change")
sp.finish(ax)

sp.save("direct_label_event.png")
plt.show()

Honest bar charts

Bar charts should start at zero to preserve scale honesty. Use force_bar_zero to enforce this when needed.

import matplotlib.pyplot as plt
import signalplot as sp

sp.apply()

categories = ["Residential", "Commercial", "Industrial"]
values = [120, 150, 95]

fig, ax = plt.subplots()
ax.bar(categories, values, color="0.6")
ax.set_title("Average demand by sector")

sp.force_bar_zero(ax)
sp.finish(ax)

sp.save("bar_honest_scale.png")
plt.show()