# KPI card

> Dashboard component reference for the KPI card, its mini-chart and distribution, window statistics, retention and every editor property.

The **KPI card** writes one numeric point large, with an optional mini-chart under it and
optional statistics of the displayed window beside it. The card collects its own samples
through the station's live-series collector, so it opens onto a filled window instead of
an empty drawing. When the point has no reading the card shows the gap mark (—) and no
unit; the declared bands tint the reading by where it falls, and a reading no band claims
takes no colour at all.

## Data {#data}

| Property | What it does | Values | Default |
|---|---|---|---|
| Address | Rooted Logic address of the numeric point shown. The field suggests from the live point list, filtered to numeric points, and shows the point's current reading once named. | address | empty |

## Format {#format}

| Property | What it does | Values | Default |
|---|---|---|---|
| Unit | Optional unit suffix written beside the value. | text | empty |
| Decimals | Fixed decimal places for the readouts (the headline, the statistics and the difference alike). | 0 to 15 | blank uses the station's preference |
| Digits | How many places the headline reserves before the decimal separator; a reading past it is marked (`####`) with the whole of itself in the tooltip. | 1 to 15 | blank reserves 5 |
| Type size | Whether the cell decides the type size or the operator states it. | As big as the cell affords · A size I state | As big as the cell affords |
| Points | The stated size, drawn literally in any cell. Only shown in the stated mode. | 9 to 144 | 12 |
| Reads as | How the readouts are written out. | Number · Percentage · Duration | Number |
| The value counts | What one unit of the value means while the format is a duration. | Seconds · Milliseconds · Minutes | Seconds |
| Show min | Writes the displayed window's minimum on the stats row. | on / off | on |
| Show max | Writes the displayed window's maximum. | on / off | on |
| Show avg | Writes the displayed window's average. | on / off | off |
| Show the difference from the reference | Writes how far the reading is from the declared reference, as `Δ` under the value, with the reference itself in the tooltip. It says nothing while no reference is declared: a difference against nothing is not a reading. | on / off | off |

The statistics and the difference are second readings of the same value, written with the
card's own declaration; they stay at the card's small size whatever the headline's type
size is.

## Mini-chart {#mini-chart}

| Property | What it does | Values | Default |
|---|---|---|---|
| Draws | What the card draws under the reading. The value, its quality and the band it falls in are the same whichever is drawn. | A line over the window · The distribution of the samples · Nothing | A line over the window |
| Classes | How many equal classes the distribution cuts the observed range into. Only shown for the distribution. | 2 to 40 | 10 |
| Over (samples) | How many of the newest collected samples the distribution counts. It frames the distribution the way the window frames the sparkline; more than the buffer holds counts what is there, because the classes are of observed readings and of nothing else. | 2 to 20,000 | 120 |
| Accent | Where the mini-chart's colour comes from. Identity, not meaning: the bands keep the last word over the classes of a distribution. | The ordinary ink · A color · A color point | The ordinary ink |
| Light / Dark | The accent as a light and dark pair, both stated because the running theme decides which half is on screen. Only shown while the accent is a color. | `#RRGGBB` each | `#5470C6` both |
| Color point | Rooted Logic address of a Color point the accent follows. Only shown while the accent is a color point. | address | empty |

A distribution counts only good, finite samples, so bad quality reads as fewer samples
counted, exactly as it reads as a hole in a line. When every counted sample read the same
value there is one class holding all of them. The card captions the distribution with
what it counted.

## History {#history}

Two different knobs, the same as on the [Line chart](component-line-chart): the window is
what the card frames, the retention is what the station keeps behind it. Samples live in
memory; restarting the application starts the collection over.

| Property | What it does | Values | Default |
|---|---|---|---|
| Keep | What the retention numbers mean. | just the window · a stretch of time · a number of samples | just the window |
| Keep for (s) | The stretch kept while retention is a stretch of time. | 5 to 604,800 (7 days) | 600 |
| Keep (samples) | The count kept while retention is a number of samples. | 2 to 20,000 | 2,000 |

The station grants retention inside three ceilings: 20,000 samples per point, 60,000 per
component and 200,000 for the station as a whole. A retention a ceiling could not grant
whole is said on the card itself, not only in the editor, so an operator on a view-only
client never reads a shorter history with nothing to explain it. When the station's own
ceiling is already spent, the card collects nothing at all and says so: "The station is
already keeping all the history it allows, so this series collects nothing. Shorten the
retention of another chart to make room.".

## Advanced {#advanced}

A collapsed section for the two fields most cards never touch.

| Property | What it does | Values | Default |
|---|---|---|---|
| Window s | The rolling window the sparkline and the statistics cover. | 5 to 86,400 (1 day) | 60 |
| Sample ms | The card's own sampling cadence. | 100 (the sweep) to 3,600,000 (1 h) | 500 |

## Scale {#scale}

The shared **Scale** section declares the bands and the reference.

- Each **band** covers everything up to its bound, from where the band above it ended;
  the tone (Neutral, Information, Success, Caution, Critical) tints the headline, and a
  worded band writes its name on the stats row — the one thing the colour cannot say.
- The **reference** is what the difference is measured against: nothing, a fixed value,
  or a point that moves with the recipe.