API reference¶

Top-level module¶

class signalplot.SaveDefaults(dpi=300, bbox_inches='tight', facecolor='white', edgecolor='white')¶

Bases: object

Defaults for saving figures.

These map directly onto Matplotlib’s savefig parameters and are installed into rcParams by apply().

Parameters:

dpi (int)
bbox_inches (str)
facecolor (str)
edgecolor (str)

bbox_inches: str = 'tight'¶

dpi: int = 300¶

edgecolor: str = 'white'¶

facecolor: str = 'white'¶

signalplot.accent_point(ax, x, y, *, label=None, color=None, size=30.0, zorder=3, **kwargs)¶

Highlight a single point with the accent color.

Optionally add a short text label offset slightly from the point.

Return type:

Axes

Parameters:

ax (Axes)
x (float)
y (float)
label (str | None)
color (str | None)
size (float)
zorder (int)
kwargs (Any)

signalplot.add_range_frame(ax, x_data=None, y_data=None)¶

Shorten axes spines so they span only the data range.

This is adapted from the older range-frame helper and keeps the spines visually tied to the data instead of the full axis domain.

Return type:

Axes

Parameters:

ax (Axes)
x_data (Iterable[float] | None)
y_data (Iterable[float] | None)

signalplot.apply(*, font_family='sans-serif', base_fontsize=10, figure_dpi=100, save=SaveDefaults(dpi=300, bbox_inches='tight', facecolor='white', edgecolor='white'))¶

Apply SignalPlot rcParams defaults.

Call this once near the start of your script or notebook:

Return type:

None

Parameters:

font_family (str)
base_fontsize (int)
figure_dpi (int)
save (SaveDefaults)

>>> import signalplot as sp
>>> sp.apply()

signalplot.band(ax, x, low, high, *, color='0.9', edgecolor='none', alpha=1.0, label=None, zorder=1, **kwargs)¶

Draw a filled band between low and high around a series.

This is useful for confidence intervals, prediction bands, or uncertainty regions.

Return type:

Axes

Parameters:

ax (Axes)
x (Sequence[float])
low (Sequence[float])
high (Sequence[float])
color (str)
edgecolor (str)
alpha (float)
label (str | None)
zorder (int)
kwargs (Any)

signalplot.direct_label(ax, x, y, text, *, dx=0.0, dy=0.0, use_accent=False, ha='left', va='center', **kwargs)¶

Place a direct label near a data point.

Typical use is to label the last point of a line instead of using a legend.

Return type:

Axes

Parameters:

ax (Axes)
x (float)
y (float)
text (str)
dx (float)
dy (float)
use_accent (bool)
ha (str)
va (str)
kwargs (Any)

signalplot.emphasize_last(ax, x, y, *, size=30.0, **kwargs)¶

Emphasize a final point in a series using the accent color.

Return type:

Axes

Parameters:

ax (Axes)
x (float)
y (float)
size (float)
kwargs (Any)

signalplot.event_line(ax, x, *, text=None, y_text=0.9, color=None, linewidth=1.0, linestyle='--', **kwargs)¶

Draw a vertical event marker with optional label.

x can be a numeric value or datetime, consistent with axvline. If 0 <= y_text <= 1, it is treated as a fraction of the data y-span. Otherwise it is interpreted directly in data coordinates.

Return type:

Axes

Parameters:

ax (Axes)
x (Any)
text (str | None)
y_text (float)
color (str | None)
linewidth (float)
linestyle (str)
kwargs (Any)

signalplot.figure(*, nrows=1, ncols=1, figsize=None, sharex=False, sharey=False, constrained_layout=True)¶

Create a SignalPlot-styled figure.

This is a light wrapper around matplotlib.pyplot.subplots() that chooses sensible defaults for analytical figures and returns the figure plus axes.

Return type:

Tuple[Figure, Union[Axes, Sequence[Axes]]]

Parameters:

nrows (int)
ncols (int)
figsize (Tuple[float, float] | None)
sharex (bool)
sharey (bool)
constrained_layout (bool)

signalplot.finish(ax)¶

Apply final cosmetic tweaks to an axes.

Currently this is a thin alias of tidy_axes so that examples using either name remain valid.

Return type:: Axes
Parameters:: ax (Axes)

signalplot.force_bar_zero(ax)¶

Force bar chart y-axis to start at zero, preserving honest scale.

Return type:: Axes
Parameters:: ax (Axes)

signalplot.note(ax, x, y, text, **kwargs)¶

Attach a short note with a simple arrow, avoiding legends.

Return type:

Axes

Parameters:

ax (Axes)
x (float)
y (float)
text (str)
kwargs (Any)

signalplot.patch_pyplot(defaults=None)¶

Patch matplotlib.pyplot.savefig to inject SignalPlot defaults.

After calling this once, plain plt.savefig(“x.png”) will receive the configured defaults unless the caller overrides them.

Return type:: None
Parameters:: defaults (Mapping[str, Any] | None)

signalplot.save(path, *, dpi=None, bbox_inches=None, facecolor=None, edgecolor=None, **kwargs)¶

Save the current figure with SignalPlot defaults unless overridden.

After apply(), this is equivalent to plt.savefig(path) but makes the intended contract explicit and still allows overrides:

sp.save(“figure.png”) sp.save(“hi_res.png”, dpi=600)

Return type:

None

Parameters:

path (str)
dpi (int | None)
bbox_inches (str | None)
facecolor (str | None)
edgecolor (str | None)
kwargs (Any)

signalplot.savefig(path, **kwargs)¶

Alias for save to match Matplotlib naming.

This makes the cookbook sketches that use signalplot.savefig(…) work without change.

Return type:

None

Parameters:

path (str)
kwargs (Any)

signalplot.small_multiples(count, *, ncols=3, sharex=True, sharey=False, figsize=None)¶

Create a grid of small-multiple axes.

Returns the figure and a flat sequence of axes, already styled with tidy_axes().

Return type:

Tuple[Figure, Sequence[Axes]]

Parameters:

count (int)
ncols (int)
sharex (bool)
sharey (bool)
figsize (Tuple[float, float] | None)

signalplot.style_bar_plot(ax, *, horizontal=False)¶

Style bar charts with alternating light fills and clean edges.

Return type:

Axes

Parameters:

ax (Axes)
horizontal (bool)

signalplot.style_line_plot(ax, *, emphasize_last=False)¶

Apply a restrained hierarchy of line styles to an axes.

Return type:

Axes

Parameters:

ax (Axes)
emphasize_last (bool)

signalplot.style_scatter_plot(ax)¶

Style scatter collections with neutral points.

Return type:: Axes
Parameters:: ax (Axes)

signalplot.tidy_axes(ax)¶

Clean up axes spines and ticks to follow the style contract.

Return type:: Axes
Parameters:: ax (Axes)