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 X-axis 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 X-axis, and the number of data points in each bucket along the Y-axis.

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 long-term 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 1-day, 1-week, 1-month, 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 X-axis, and the distribution is plotted on the Y-axis. 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

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

2. From the list of available panels, select Heatmap.

   The heatmap panel will be added to your dashboard.

   https://g.lagoon.soracom.io

   

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 Y-axis 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 Y-axis.
• Y-Min and Y-Max - Specify the minimum and maximum values of the Y-axis. If blank, the Y-axis 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 into 1-20, 21-40, 41-60, 61-80, and 81-100.
  • 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 from 25-50, 51-75, 76-100, and so on until 201-225. When set, the Buckets option will be ignored.
• 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 Y-axis 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 Y-axis 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.