Soracom Lagoon
Heatmap Panel
The Heatmap Panel displays a data series as a histogram over time. Rather than simply plotting the raw value of a metric in a graph and seeing how the value changes over time, a heatmap allows you to sort each data point into different buckets based on its value, and visualize the frequency or how often a particular value occurs and how that frequency changes over time.
Compared to Histograms
When using the Graph Panel, you can set its Xaxis Mode to Histogram
. With this setting, each value in the data series will be sorted into different buckets together with other data points that have a similar value. The resulting panel will display the range of values (buckets) on the Xaxis, and the number of data points in each bucket along the Yaxis.
For example, consider a device that measures the water level of a river. The raw data can be plotted in a regular graph to see the height of the water at a particular time. However, due to daily tidal behavior, intermittent weather, and longterm seasonality, it may be difficult to identify trends by just looking at the raw data itself.
With a histogram, the water height data is organized into (for example) "low," "normal," and "high" buckets, allowing you to quickly visualize the number of times the water level was measured at each level. In this trivial example, you might expect the water level to be "low" 25% of the time, "normal" 50% of the time, and "high" 25% of the time. As your device collects more data, the histogram may begin to shift as rainfall results in more instances where the water level is measured as "high."
The limitation of a histogram is that it is a single representation of the distribution of all data points in a given time range, and therefore it is difficult to visualize how the distribution has changed over time. With a heatmap, the data is first divided into time buckets (such as 1day, 1week, 1month, or other time interval), and then the low/normal/high distribution is calculated for each interval.
When using a heatmap, the time intervals are arranged on the Xaxis, and the distribution is plotted on the Yaxis. Finally, rather than changing the "height" of each bucket to indicate the number of data points in the bucket, the color of the bucket is adjusted. This allows you to quickly understand the distribution of data points in a single time interval, and how that distribution changes over time.
Creating a Heatmap Panel

Click the Add panel button at the top of the dashboard.

From the list of available panels, select Heatmap.
The heatmap panel will be added to your dashboard.
Editing Panel Settings
To edit the heatmap panel settings, click the Panel Title, then select Edit.
General
The General tab lets you configure basic panel settings. Refer to the Lagoon Panels: General documentation for more information.
Metrics
The Metrics tab lets you configure the data series source. Refer to the Lagoon Panels: Metrics documentation for more information.
Axes
The Axes tab lets you configure the heatmap area and buckets.
Y Axis
 Unit  Add a unit to the Yaxis values, such as degrees for a temperature metric, percentage for a humidity metric, or length for a distance metric.
 Scale  The type of scale to use on the Yaxis.
 YMin and YMax  Specify the minimum and maximum values of the Yaxis. If blank, the Yaxis will be scaled automatically based on the data series.
 Decimals  The number of decimal places to show.
Buckets
 Y Axis  Configure the bucket settings for the Y axis (metric value).
 Buckets  The number of buckets the range of values should be divided into. For example, if your data ranges from 1 to 100, a setting of
5
will divide the range into120
,2140
,4160
,6180
, and81100
.  Size  The size of the range of each bucket, where the total number of buckets depends on the range of your data. For example, if your data ranges from 32 to 212, a setting of
25
will create 8 buckets from2550
,5175
,76100
, and so on until201225
. When set, the Buckets option will be ignored.
 Buckets  The number of buckets the range of values should be divided into. For example, if your data ranges from 1 to 100, a setting of
 X Axis  Configure the bucket settings for the X axis (time).
 Buckets  Same as above, but applied to the time range of the panel.
 Size  Same as above, but using time intervals rather than value intervals.
Data format
 Format  The type of distribution to use in the heatmap.
Time series
 A standard value distribution, where the Yaxis represents the numerical range of values in your data. This is typically used when you have a single metric and want to see how often different values occur.Time series buckets
 A metric distribution, where the Yaxis represents different metrics. This is typically used when you have multiple metrics and want to see how often a value is recorded for each metric.
Display
The Display tab lets you configure the look and feel of the heatmap.
Colors
 Mode  The color mode of the heatmap
opacity
 Change the opacity of each bucket, where more transparent means lower distribution, and more opaque means higher distribution.spectrum
 Change the color of each bucket, where on color means lower distribution, and another color means higher distribution.
 Color  When Mode is set to
opacity
, select the color to use.  Scale  When Mode is set to
opacity
, select how the transparency effect is applied to each bucket:linear
 Transparency is applied proportionally to the value.sqrt
 Transparency is applied exponentially to the value.
 Exponent  When Scale is set to
sqrt
, select how strong the transparency effect is. Higher numbers mean buckets with low distribution are more transparent.  Scheme  When Mode is set to
color
, select the color palette to use.
Color scale
 Min and Max  Map the range of colors to a minimum and maximum count for each bucket. For example, Max is set to 100, then buckets with more than 100 data points will be colored the same as buckets with 100 data points.
Legend
 Show  Show or hide the legend.
Buckets
 Space  The amount of space to leave between each bucket.
 Round  The amount of rounding to apply to the corners of each bucket.
Tooltip
 Show  Show or hide a tooltip when hovering over a bucket.
 Histogram  Show a histogram for the distribution that corresponds to the given time interval inside the tooltip.
 Decimals  The number of decimal places to show.
Time Range
The Time Range tab lets you adjust the range of data to use. Refer to the Lagoon Panels: Time Range documentation for more information.
Additional Resources
More information about the heatmap panel can be found in the Grafana: Heatmap Panel documentation.