Viewing a Run

A viewer shows a run’s data as plots while the measurement goes on, and can play a finished run back or save it as a video. It lives in plesty.lib.monitor.

A viewer only reads the run folder (see Where a Measurement’s Data Goes). It never talks to a device or to the experiment program, and writes nothing back. So a viewer can be opened, closed and opened again in the middle of an eight-hour run, and any number of them can watch the same run, without affecting the measurement.

The layers of a viewer

From the bottom up:

Layer	What it does	Who writes it
the run folder	holds records.jsonl, one line per finished step, and the files in raw/ that records name (see The run folder)	the experiment and its devices
reader	follows records.jsonl, reading only the lines added since the last refresh; live, or replaying a finished run a few lines at a time	internal
RunData	keeps every row read so far and answers questions about them (latest, column, stack, where, …). One per run, shared by every plot. Its reads= function turns a row that names a file into the numbers inside that file, once per row.	internal; you write only reads=
Plot	a title and draw(data): given the RunData, returns what to draw	you
drawables	Line, Scatter, Image, Scalar, Text: the only things a plot can return, each carrying its values and its style together	you choose them
renderer	draws the drawables with pyqtgraph, in one docked panel per plot, or offscreen when saving a video	internal
Viz	the viewer as a whole: finds the run, opens the window, holds the plots, and refreshes them	you create it, once

So a viewer names three things: the Viz, its plots, and what the plots draw.

When something goes wrong

A plot that raises an error does not stop the others: its panel shows the error in its title bar, and the rest of the window goes on. The same holds for reads=: a row whose file cannot be read yet just lacks its extra fields.

In this chapter

Page	Covers
The Viewer: Viz	creating a viewer, and starting it to watch, replay or save a video
The Run’s Data: RunData	what a plot can ask about the run, and reading files that rows name
Plots and Drawables	the three ways to write a plot, and what it can draw
Ready-Made Plots	spectra, spectral maps and series that need no code of your own
Testing a Viewer	testing plots without a window
Shell Framework	the window around the plots, device control panels, themes and recording