plesty.lib.monitor.plots

What a view draws, and the one shape every view is expressed in.

A plot is a title and a function from RunData to a list of drawables. That is the whole contract:

@viz.plot("Spectrum")
def spectrum(data):
    row = data.latest
    return [Line(row["wavelength"], row["counts"],
                 x_label="Wavelength (nm)", y_label="Counts")]

What is fixed is only how a result is expressed — five kinds of drawable, which is the vocabulary a renderer can draw. What is free is everything computed on the way to one: fit it, filter it, stack it, annotate it. The contract constrains the output and nothing else, which is what lets an experiment draw something nobody anticipated without asking for a new kind.

A drawable carries its own style. There is no declaration to keep matched against it. The two used to be separate — a spec declared once, values keyed to it per update — which bought the renderer the right to build its items once, and cost the developer a string correspondence across two methods that nothing checked. The renderer now reuses its items by position and rebuilds when the shape changes, which is an optimisation it can make for itself.

Three ways in, one contract. A function for the ordinary case; a Plot subclass when a view has to remember something between ticks; and Plot.build() for a view that is not a plot at all — a table, an image browser — which hands back a widget and draws nothing.

Attributes

`COLORS`
`SCALES`
`Drawing`
`DrawFunc`

Exceptions

PlotError

Raised when a plot declares something that cannot be drawn.

Classes

`Drawable`	One element of a plot: what to draw, and how it should look.
`Line`	A curve through `(x, y)`.
`Scatter`	Points at `(x, y)`, drawn without a line between them.
`Image`	A 2-D block of values, drawn as a map with a colour bar.
`Scalar`	A single number, shown large.
`Text`	A line of text placed in the plot — a result, a warning, a caption.
`Plot`	One view of a run: a title, and what to draw from the run's data.
`FunctionPlot`	A plot written as a function — what `Viz.plot()` wraps.

Functions

shape_of(→ tuple[Any, Ellipsis])

Return what about a drawing decides how it is built.

Module Contents

plesty.lib.monitor.plots.COLORS: tuple[str, Ellipsis] = ('cyan', 'violet', 'mint', 'amber', 'rose', 'blue')

plesty.lib.monitor.plots.SCALES: tuple[str, Ellipsis] = ('linear', 'sqrt')

exception plesty.lib.monitor.plots.PlotError

Bases: ValueError

Raised when a plot declares something that cannot be drawn.

Initialize self. See help(type(self)) for accurate signature.

class plesty.lib.monitor.plots.Drawable

One element of a plot: what to draw, and how it should look.

Variables:

label – Legend label. One starting with _ stays out of the legend, as in matplotlib — for a trace the legend would only repeat, such as a fitted curve in the colour of its points.
color – A token from COLORS.
x_label – Axis label including the unit, "Wavelength (nm)".
y_label – Axis label including the unit.

kind: ClassVar[str] = 'drawable'

label: str = ''

color: str = 'cyan'

x_label: str = ''

y_label: str = ''

__post_init__() → None

Check the colour token.

Raises:: PlotError – If the colour is not one the theme defines.
Return type:: None

class plesty.lib.monitor.plots.Line

Bases: Drawable

A curve through (x, y).

Variables:

x – Sample positions.
y – Sample values.
width – Line width.
marker – Draw a point marker at every sample as well.

kind: ClassVar[str] = 'line'

x: Any = None

y: Any = None

width: float = 1.5

marker: bool = False

class plesty.lib.monitor.plots.Scatter

Bases: Drawable

Points at (x, y), drawn without a line between them.

Variables:

x – Sample positions.
y – Sample values.
size – Marker size.

kind: ClassVar[str] = 'scatter'

x: Any = None

y: Any = None

size: float = 8.0

class plesty.lib.monitor.plots.Image

Bases: Drawable

A 2-D block of values, drawn as a map with a colour bar.

Variables:

z – The values, shape (rows, columns).
x – Positions of the columns, for the axis.
y – Positions of the rows, for the axis.
scale – "linear", or "sqrt" — colours follow the square root of the value, so features ten times weaker than the strongest still stand out from the background. The bar stays labelled in the image’s own values.

kind: ClassVar[str] = 'image'

z: Any = None

x: Any = None

y: Any = None

scale: str = 'linear'

__post_init__() → None

Check the colour token and the colour scale.

Raises:: PlotError – If the scale is not one the renderer knows.
Return type:: None

class plesty.lib.monitor.plots.Scalar

Bases: Drawable

A single number, shown large.

Variables:

value – The number.
unit – Shown after it.

kind: ClassVar[str] = 'scalar'

value: float | None = None

unit: str = ''

class plesty.lib.monitor.plots.Text

Bases: Drawable

A line of text placed in the plot — a result, a warning, a caption.

Variables:: text – What to show.

kind: ClassVar[str] = 'text'

text: str = ''

plesty.lib.monitor.plots.Drawing

plesty.lib.monitor.plots.DrawFunc

class plesty.lib.monitor.plots.Plot(title: str = '', *, name: str = '', weight: float | None = None, area: str = '')

Bases: abc.ABC

One view of a run: a title, and what to draw from the run’s data.

Subclass this when a view has to remember something between ticks — a line tracker, a running baseline. For a view that is a pure function of the data, plot() takes the function directly and there is no class to write.

Variables:

title – What the view is called, on its dock tab.
name – Stable identifier, used as the layout key so an arrangement survives a restart; defaults to the title.
weight – Relative size when the panels are first laid out.
area – Which side of the window it starts on — one of DOCK_AREAS. Views sharing an area are stacked in one column, so this is how a viewer says which of its plots belong side by side. The operator can drag them anywhere afterwards, and the arrangement is remembered.

Parameters:

title (str)
name (str)
weight (Optional[float])
area (str)

Name the view.

Parameters:

title (str) – Overrides the class attribute.
name (str) – Layout key; defaults to the title.
weight (Optional[float]) – Overrides the class attribute.
area (str) – Overrides the class attribute.

title: str = ''

name: str = ''

weight: float = 1.0

area: str = 'right'

abstractmethod draw(data: Any) → Drawing

Return what to draw, given everything the run has produced.

Called on every tick, on the GUI thread. It should be a projection of the data and nothing else — no device is reachable from here and none should be: watching never disturbs measuring.

Parameters:: data (Any) – The run’s RunData.
Returns:: The drawables, in the order they should be layered.
Return type:: Drawing

build() → Any

Return a widget for this view instead of a plot, or None.

The escape hatch. A view that is not a plot at all — a table of the committed rows, an image browser, a strip of readouts — returns its own widget here and ignores draw(). Anything Qt can show is allowed; the dock does not care what is inside it.

Returns:: None by default, meaning “draw me as a plot”.
Return type:: Any

__repr__() → str

Return <ClassName 'title'>.

Return type:: str

class plesty.lib.monitor.plots.FunctionPlot(func: DrawFunc, title: str = '', *, name: str = '', weight: float | None = None)

Bases: Plot

A plot written as a function — what Viz.plot() wraps.

Not usually built by hand: decorating a function with plot() makes one of these.

Wrap func as a plot.

Parameters:

func (DrawFunc) – Takes the run’s data, returns drawables.
title (str) – What the view is called; defaults to the function’s name with underscores as spaces.
name (str) – Layout key.
weight (Optional[float]) – Relative size.

func

draw(data: Any) → Drawing

Call the wrapped function.

Parameters:: data (Any) – The run’s data.
Returns:: Whatever the function returned; () when it returned nothing, so a plot with nothing to show yet is empty rather than an error.
Return type:: Drawing

plesty.lib.monitor.plots.shape_of(drawing: Drawing) → tuple[Any, Ellipsis]

Return what about a drawing decides how it is built.

A renderer reuses its items while this is unchanged and rebuilds when it is not, which is what replaces the keys a plot used to have to declare.

Parameters:: drawing (Drawing) – The drawables returned by a plot.
Returns:: its kind, label, colour and scale.
Return type:: One entry per drawable