# 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](../concepts/data_flow.md)). 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

![The layers of a viewer, from the run folder up to the window](../imgs/monitor_layers.svg)

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](../concepts/data_flow.md#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](viz.md) | creating a viewer, and starting it to watch, replay or save a video |
| [The Run's Data: RunData](run_data.md) | what a plot can ask about the run, and reading files that rows name |
| [Plots and Drawables](plots.md) | the three ways to write a plot, and what it can draw |
| [Ready-Made Plots](ready_made_plots.md) | spectra, spectral maps and series that need no code of your own |
| [Testing a Viewer](../testing/viewer.md) | testing plots without a window |
| [Shell Framework](ui.md) | the window around the plots, device control panels, themes and recording |