diff --git a/data/contract_docs/contract.md b/data/contract_docs/contract.md index 4243d841a..db7059913 100644 --- a/data/contract_docs/contract.md +++ b/data/contract_docs/contract.md @@ -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 :-). diff --git a/data/contract_docs/heatmap.md b/data/contract_docs/heatmap.md new file mode 100644 index 000000000..8f55365db --- /dev/null +++ b/data/contract_docs/heatmap.md @@ -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: + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Type: Time +

+ Name: Time +

+ 		+ Type: Number +

+ Name: +

+

+ Labels: {"le": "10"} +

+ 		+ Type: Number +

+ Name: +

+

+ Labels: {"le": "20"} +

+ 		+ Type: Number +

+ Name: +

+

+ Labels: {"le": "+Inf"} +

+
1653416391000678
1653416391000678
1653416391000678
+ + +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:** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Type: Time +

+ Name: xMax|xMin|x +

+ 		+ Type: Number +

+ Name: yMax|yMin|y +

+ 		+ Type: Number +

+ Name: Count +

+ 		+ Type: Number +

+ Name: Total +

+ 		+ Type: Number +

+ Name: Speed +

+
1653416391000100111
1653416391000200222
1653416391000300333
1653416392000100444
1653416392000200555
1653416392000300666
+ +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: + + + + + + + + + + + + + + + + + + + + + + + + +
+ Type: Time +

+ Name: xMin +

+ 		+ Type: Time +

+ Name: xMax +

+ 		+ Type: Number +

+ Name: yMin +

+ 		+ Type: Number +

+ Name: yMax +

+ 		+ Type: Number +

+ Name: Value +

+
165341639100016534163920001002001
165341639200016534163930002004002
+ +* 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