# Plots and Drawables

A **plot** is one panel of a viewer: a title, and a function that is given the run's
data (see [The Run's Data: RunData](run_data.md)) and returns what to draw. What it
returns is a list of **drawables**: lines, points, images, numbers or text. Everything
between the data and the drawables is yours to compute.

## Three ways to write a plot

**A function**, for most plots. `@viz.plot("Title")` adds it to the viewer (see
[The Viewer: Viz](viz.md)):

```python
@viz.plot("Spectral map", weight=3)
def spectral_map(data):
    return [Image(z=data.stack("counts"), y=data.column("hwp_deg"), scale="sqrt",
                  y_label="Plate angle (deg)")]
```

The decorator returns the function unchanged, so it can still be called directly,
for example in a test (see [Testing a Viewer](../testing/viewer.md)).

**A `Plot` subclass**, when a plot has to remember something from one refresh to the
next, such as a line it is tracking or a running baseline:

```python
from plesty.lib.monitor import Plot


class FineStructure(Plot):
    title = "Fine structure"

    def draw(self, data):
        ...


viz.add_plot(FineStructure())
```

**A widget of your own**, when the panel is not a plot at all: a table of the rows,
an image browser, a row of readouts. Override `Plot.build()` and return any Qt widget;
`draw()` is then never called.

## The drawables

| Drawable | Draws |
|---|---|
| `Line(x, y, width=, marker=)` | a curve |
| `Scatter(x, y, size=)` | points |
| `Image(z, x=, y=, scale=)` | a 2-D array as a colour map, with a colour bar; `scale="sqrt"` makes weak features visible next to strong ones |
| `Scalar(value, unit=)` | a single number, shown large |
| `Text(text)` | a line of text in the plot |

All are in `plesty.lib.monitor`. Each also takes `label` (its name in the legend),
`color`, `x_label` and `y_label`. `color` is a name from the PLESTY palette, one of
`cyan`, `violet`, `mint`, `amber`, `rose` and `blue`, never a colour code, so every
viewer looks the same.

The values and the style of a drawable are given together, in one call, and a plot
can return a different number of drawables from one refresh to the next.

A plot that returns an empty list draws empty axes. That is normal at the start of a
run, before the first row is saved.

The same drawables make the figures in an analyzer's report (see
[Reports](../analysis/reports.md)), so a plot on screen and a figure in a
report are written the same way.