The Viewer: Viz

Viz, from plesty.lib.monitor, is an experiment’s viewer: a window that shows a run’s data as plots, and redraws them as the run goes on. An experiment module usually ships one, in a file of its own such as plesty/pol_pl/viz.py, so that anyone can watch its runs. The layers of a viewer shows where it sits.

A viewer

# power_viz.py
import sys

from plesty.lib.monitor import Line, Viz

viz = Viz("Power scan", experiment="powerscan")


@viz.plot("Power")
def power(data):
    return [Line(x=data.column("wavelength_nm"), y=data.column("power_w"),
                 x_label="Wavelength (nm)", y_label="Power (W)")]


if __name__ == "__main__":
    sys.exit(viz.main())

Viz takes:

Argument	Meaning
title	the window’s title
experiment=	the experiment name whose runs to show, as in the run ids (powerscan_…). Several names are allowed, for an experiment that was renamed. None shows the newest run of any experiment.
run_root=	where to look for runs. A relative path is taken inside the shared disk when PLESTY_DATA is set (see Data on a Shared Disk); by default the shared disk itself, or runs without one.
reads=	a function that turns a row naming a file into the numbers inside it; see reads: rows that name a file

Add plots with @viz.plot("Title") over a function, or viz.add_plot(plot) for a plot object; Plots and Drawables explains both. @viz.plot also takes weight=, the plot’s share of the window when the panels are first laid out, and name=, the key the window’s layout is remembered under (the title by default).

Starting it

viz.main() gives the viewer a command line with two subcommands. monitor needs the gui extra; render needs the gui and record extras (see Install).

python power_viz.py monitor                      # a window following the newest run
python power_viz.py monitor --replay 2           # play a finished run back, 2 rows per refresh
python power_viz.py monitor --record demo.mp4    # also record the window to a video
python power_viz.py render --run powerscan_20260925-101534   # the run as a video, no window

render draws without a screen, so it also works on a computer without one, and stops by itself when the run’s data is used up.

A replayed run can be held: Replay ▸ Pause, or the space bar, stops the plots where they are, and the same again resumes them. Panels can still be moved and closed while it is paused. A live run has no such menu. Code that builds its own window calls the window’s pause() and resume(), and offer_pause() adds the menu.

Option	For	Meaning
--run RUN_ID	both	the run to show; the newest by default
--run-root FOLDER	both	where to look for runs, instead of the viewer’s run_root
--data-root FOLDER	both	where this computer sees the shared disk, instead of PLESTY_DATA
--interval-ms MS	both	how often the plots are redrawn; 500 by default
--record-fps FPS	both	the frame rate of a recorded video; 10 by default
--replay [ROWS]	monitor	play a finished run back instead of following it live, ROWS rows per refresh (1 if no number is given)
--record PATH	monitor	record the window to a video, saved when the window closes
--rows ROWS	render	rows added per video frame; 1 by default
--out PATH	render	where to save the video; <run id>.mp4 next to the run folder by default

--help works without the gui extra, so the options can be read on any computer.

Showing it inside another window

viz.view(run) builds the viewer’s window content for run without showing it, and returns it for another program to place in its own window, such as a console that shows the runs it started. It is not refreshing yet: call its start() once it is in place. Pass remember_layout=False there: the arrangement inside another window is not the viewer’s own. Shell Framework explains the window it returns.