zabgrab.services.plotting

What to plot: numeric series grouped by units, split where nothing was fetched.

This module decides the content of a plot; zabgrab.ui.plot draws it with matplotlib. Keeping the two apart means the rules (which items can be plotted, where lines break) are tested without matplotlib.

Functions

plot_spec(series, coverage, ui, *[, title, ...])

Work out what to plot.

Classes

Axis(units[, lines])	A vertical axis, shared by the series with the same units.
Line(label[, segments])	One series on an axis.
PlotSpec(axes[, title, log_y])	Everything to draw.
Segment(times, values[, low, high])	A run of points drawn as one connected line.

class zabgrab.services.plotting.Segment(times, values, low=None, high=None)

Bases: object

A run of points drawn as one connected line.

Parameters:

• times (list[float])

• values (list[float])

• low (list[float] | None)

• high (list[float] | None)

times

POSIX seconds.

Type:

list of float

values

The line’s values: raw values, or the hourly average.

Type:

list of float

low, high

The hourly minimum and maximum, drawn as a band around the line (trends only, when both were fetched).

Type:

list of float or None

class zabgrab.services.plotting.Line(label, segments=<factory>)

Bases: object

One series on an axis.

Parameters:

• label (str)

• segments (list[Segment])

label

The legend entry, host: name [units].

Type:

str

segments

The connected runs of points; lines break between them.

Type:

list of Segment

class zabgrab.services.plotting.Axis(units, lines=<factory>)

Bases: object

A vertical axis, shared by the series with the same units.

Parameters:

• units (str)

• lines (list[Line])

units

The units of every line on the axis (empty for none).

Type:

str

lines

The series drawn on this axis.

Type:

list of Line

class zabgrab.services.plotting.PlotSpec(axes, title='', log_y=False)

Bases: object

Everything to draw.

Parameters:

• axes (list[Axis])

• title (str)

• log_y (bool)

axes

One axis per distinct unit, in the order the units first appear.

Type:

list of Axis

title

The figure title (may be empty).

Type:

str

log_y

Whether the vertical axes use a log scale.

Type:

bool

zabgrab.services.plotting.plot_spec(series, coverage, ui, *, title='', log_y=False)

Work out what to plot.

Parameters:

• series (sequence of Series) – The data, e.g. a merged dataset’s series.

• coverage (sequence of (float, float)) – The time ranges that were fetched, sorted and not overlapping (POSIX seconds). Lines break between ranges, so gaps nobody fetched aren’t drawn as if the data were continuous, while sparse data inside a fetched range is still joined up.

• ui (UI) – Warns about text items that are left out.

• title (str, optional) – The figure title.

• log_y (bool, optional) – Use log scales for the vertical axes. Lines with values of zero or less, which can’t be shown on them, are warned about.

Returns:

PlotSpec – One axis per unit, each with a line per numeric series.

Raises:

ZabgrabError – If there’s nothing numeric to plot (no series, or only text items).

Return type:

PlotSpec