Skip to content

Commit

Permalink
Contract: add heatmap format docs (#507)
Browse files Browse the repository at this point in the history 
* add heatmap type

* add heatmap type

* rename contract.md

* rename contract.md

* yMin/yMax/y

* timeseries wide

* add numeric long

* DataPlane: Update heatmap docs (#554)

* rename README to contract

* update docs for scanline uniform cells and difference between sparse and scanlines

* remove readme will change this later

* change numeric many to numeric multi

* change numeric many to numeric multi

* change numeric many to numeric multi

Co-authored-by: Brendan O'Handley <brendan.ohandley@grafana.com>
Co-authored-by: bohandley <brendan.ohandley@gmail.com>
  • Loading branch information
@ryantxu @bohandley
3 people committed Nov 9, 2022
1 parent 74f14da commit 4438c11
Show file tree
Hide file tree
Showing 2 changed files with 247 additions and 0 deletions.
15 changes: 15 additions & 0 deletions data/contract_docs/contract.md
View file
Expand Up @@ -14,6 +14,21 @@ There are logical **_kinds_** (like Time Series Data, Numeric, Histogram, etc),

A **_data type_** definition or declaration in this framework includes both a kind and format. For example, "TimeSeriesWide" is: kind: "Time Series", format: "Wide".

* [Time series](./timeseries.md)
* [Wide](./timeseries.md#time-series-wide-format-timeserieswide)
* [Long](./timeseries.md#time-series-long-format-timeserieslong-sql-like)
* [Multi](./timeseries.md#time-series-multi-format-timeseriesmulti)
* [Numeric](./numeric.md)
* [Wide](./numeric.md#numeric-wide-format-numericwide)
* [Multi](./numeric.md#numeric-multi-format-numericmulti)
* [Long](./numeric.md#numeric-many-format-numericlong)
* [Heatmap](./heatmap.md)
* [Buckets](./heatmap.md#heatmap-buckets-heatmapbuckets)
* [Scanlines](./heatmap.md#heatmap-scanlines-heatmapscanlines)
* [Sparse](./heatmap.md#heatmap-sparse-heatmapsparse)



## Dimensional Set Based Kinds

Within a data type (kind+format), there can be multiple **_items_** of data that are uniquely identified. This forms a **_set_** of data items. For example, in the numeric kind there can be a set of numbers, or, in the time series kind, a set of time series-es :-).
Expand Down
232 changes: 232 additions & 0 deletions data/contract_docs/heatmap.md
View file
@@ -0,0 +1,232 @@
# Heatmap

Status: EARLY Draft/Proposal

Heatmaps are used to show the magnitude of a phenomenon as color in two dimensions. The variation in color
may give visual cues about how the phenomenon is clustered or varies over space.


## Heatmap buckets (HeatmapBuckets)

The first field represents the X axis, the rest of the fields indicate rows in the heatmap.
The true numeric range of each bucket can be indicated using an "le" label. When absent,
The field display is used for the bucket label.

Example:

<table>
<tr>
<td>
<strong>Type: Time</strong>
<p>
<strong>Name: Time</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: </strong>
</p>
<p>
<strong>Labels: {"le":<em> "10"</em>}</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: </strong>
</p>
<p>
<strong>Labels: {"le":<em> "20"</em>}</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: </strong>
</p>
<p>
<strong>Labels: {"le":<em> "+Inf"</em>}</strong>
</p>
</td>
</tr>
<tr>
<td>1653416391000</td>
<td>6</td>
<td>7</td>
<td>8</td>
</tr>
<tr>
<td>1653416391000</td>
<td>6</td>
<td>7</td>
<td>8</td>
</tr>
<tr>
<td>1653416391000</td>
<td>6</td>
<td>7</td>
<td>8</td>
</tr>
</table>


Note: [Timeseries wide](./timeseries.md#time-series-wide-format-timeserieswide) can be used directly
as heatmap-buckets, in this case each value field becomes a row in the heatmap.


## Heatmap scanlines (HeatmapScanlines)

In this format, each row in the frame indicates the value of a single cell in a heatmap.
There exists a row for every cell in the heatmap.

**Example:**

<table>
<tr>
<td>
<strong>Type: Time</strong>
<p>
<strong>Name: xMax|xMin|x</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: yMax|yMin|y</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: Count</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: Total</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: Speed</strong>
</p>
</td>
</tr>
<tr>
<td>1653416391000</td>
<td>100</td>
<td>1</td>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>1653416391000</td>
<td>200</td>
<td>2</td>
<td>2</td>
<td>2</td>
</tr>
<tr>
<td>1653416391000</td>
<td>300</td>
<td>3</td>
<td>3</td>
<td>3</td>
</tr>

<tr>
<td>1653416392000</td>
<td>100</td>
<td>4</td>
<td>4</td>
<td>4</td>
</tr>
<tr>
<td>1653416392000</td>
<td>200</td>
<td>5</td>
<td>5</td>
<td>5</td>
</tr>
<tr>
<td>1653416392000</td>
<td>300</td>
<td>6</td>
<td>6</td>
<td>6</td>
</tr>
</table>

This format requires uniform cell sizing. The size of the cell is defined by the columns in each row that are chosen as the xMax|xMin|x and the yMax|yMin|y. We can see that the Number column(yMax|yMin|y) increases by 100(each cell is roughly 100 higher than the previous cell on the y axis) for each row containing a similar Time value(these stacked cells all have roughly the same location along the x axis). This produces a uniform cell size.

Note that multiple "value" fields can included to represent multiple dimensions within the same cell.
The first value field is used in the display, unless explicilty configured

The field names for yMax|yMin|y indicate the aggregation period or the supplied values.
* yMax: the values are from the bucket below
* yMin: the values are from to bucket above
* y: the values are in the middle of the bucket


## Heatmap sparse (HeatmapSparse)

This format is simplar to Heatmap scanlines, except that each cell is independent from its adjacent values.
Unlike scanlines, this allows resolutions to change over time. Where scanline has uniformity of cells over time, heatmap sparse allows for variability of cells along the x axis(Time).

Example:


<table>
<tr>
<td>
<strong>Type: Time</strong>
<p>
<strong>Name: xMin</strong>
</p>
</td>
<td>
<strong>Type: Time</strong>
<p>
<strong>Name: xMax</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: yMin</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: yMax</strong>
</p>
</td>
<td>
<strong>Type: Number</strong>
<p>
<strong>Name: Value</strong>
</p>
</td>
</tr>
<tr>
<td>1653416391000</td>
<td>1653416392000</td>
<td>100</td>
<td>200</td>
<td>1</td>
</tr>
<tr>
<td>1653416392000</td>
<td>1653416393000</td>
<td>200</td>
<td>400</td>
<td>2</td>
</tr>
</table>

* For high resolution with many gaps, this will require less space
* This format is much less optomized for fast render and lookup than the uniform "scanlines" approach

0 comments on commit 4438c11

Please sign in to comment.