What is a Heatmap Report?
The Heatmap report provides an ideal way to quickly compare activity between learners. Like the Leaderboard report, each Heatmap report shows text-based data, but also presents a visual representation of your learners’ activities by using varying intensities of color. Darker and lighter backgrounds on cells are used to visually highlight outlier values. For instance, if you are looking at test scores for a group of learners, you can easily identify higher performers because their corresponding colors would be darker.
- User Types
- Any user with access to the report builder (Global Admins, Area Admins, and some Users) can edit a Heatmap report. All users can view a Heatmap report.
- Pricing
- Available on paid plans (Analyst, CLO, and Enterprise).
- Expertise
- Anybody (both beginners and experts) can use this feature.
Creating and Editing a Heatmap Report
Use the report builder to create new Heatmap reports and to configure existing Heatmap reports.
Heatmap Report Filters and Options
Beyond the typical report builder filters and options, the Heatmap report provides options that are unique to the Heatmap report.
Heatmap Filter
When setting up a new Heatmap report or configuring an existing Heatmap report, click Heatmap in the filter menu:
In the Heatmap filter, you’ll choose what you’d like to rank (using the Organized menu), how you’d like to rank it (using the Measures menu), whether you want to show data values in addition to the heatmap colors (using the Value Labels menu), and how to scale the heatmap colors (with Scale Colors).
Organized
On the Organized menu, you’ll choose what you’d like to rank on the Heatmap. Choose an option from the Organized menu and the rows on the Heatmap will be what you’ve chosen.
Measures
On the Measures menu, you’ll choose which measures you’d like to rank what you chose in the Organized menu. You can choose multiple measures for the same Heatmap report, and each measure you choose is given a column in the Heatmap report.
Related: What are Measures?
To add a measure to the Heatmap, choose a measure from the Select a Measure menu and click the Add Measure button next to the menu. You’ll see the measure added to the Heatmap, and the measure will be added to the Measures section. To deselect a measure, click the X next to the Measure in the Measures section:
As a note, the first 10 measures will appear on the report preview when looking at a heatmap report in a dashboard. When clicking on the report to view in more detail, you can scroll horizontally to see additional measures past the 10th.
Value Labels
In Value Labels menu, you'll choose whether you want the actual numbers to appear on your Heatmap or if you want to let your users decide whether to see the actual numbers.
If you choose Always Hide, no numbers will show on your Heatmap:
If you choose Always Show, numbers will show on your Heatmap:
If you choose Select in UI, your users can decide whether they want to see Heatmap values with a toggle on the Heatmap:
Scale Colors
In the Scale Colors menu, you'll choose whether you want the colors of your heatmap to scale across all of the measures of the heatmap or whether you want the colors to scale within each measure.
If you choose Across All Measures, the color scale for the Heatmap will be set to the highest value across all measure values:
If you choose By Individual Measures, each measure will have its own color scale. Each measure's color scale will be determined by the highest value across each measure:
Default Sort
The default sort menu determines the order rows will be sorted by default. Sorting Ascending means that lower numbers or letters near the start of the alphabet will be listed first. Sorting Descending means that higher numbers or letters nearer the end of the alphabet will be listed first.
Advanced Configuration
Advanced configuration is designed to be used by expert users who understand JSON and the properties of xAPI statements.
Related: Check out our Advanced Configuration guide for more information on customizing your reports.
Whether or not values are shown can be configured in Advanced Configuration. Along with this, you can choose to exclude measures from being shaded.
Property |
Explanation |
Example values |
showValues |
Whether or not to show values on heatmap grid squares. |
null true false |
nonShadedMeasures |
This property takes an array of measures to exclude shading from |
[0, 1] |
If show values is null, the report viewer will be able to select whether or not to show values in the UI, without having to use the report builder.
Heatmap Custom Chart Colors
If you use custom chart colors, these will be used to determine the colors used for the background of cells in the heatmap.
- The first color is the color used for null values, for example on a heatmap showing quiz scores, if a person has no score for the quiz. The default color for this is grey.
- The second color is the color used for the very lowest value in the range of values present in the data (often 0). The default color for this is white.
- The third color is used for the lower end of the gradient. The default color for this is very light grey.
- The fourth color is used for the upper end of the gradient and for the very highest value in the range of values present in the data. The default color for this is a dark blue.
Hint: If you use custom chart colors, but want to show the heatmap in default Watershed colors, you can use this configuration in your report:
"colors": [ "#e5e5e5", "#ffffff", "#f5f5f5", "#006691" ]
Advanced Color Options
If the above standard color options are not granular enough for your reporting purposes, the advancedColors property can be used to further control the Heatmap coloring. There are two ways that the advancedColors property can work: as a color gradient or a discrete color band---both covered in more detail below.
Color Gradient
To set a color gradient within a range, a color stop should be used. A 'color-stop' is a number in the range [0, 1], with an rgb color.
The color-stop syntax in its simplest form:
color-stop at <i> color <c>
where i
is the position of the stop on the number line (between 0 and 1, inclusive), and c
is the color of the stop
A slightly more advanced form is shown here that can be used to set the color before/after a certain value:
color-stop before <i> color <c> tolerance <t>;
color-stop after <i> color <c> tolerance <t>
where i
and c
are the position and color of the stop, respectively, and t
is a number that represents the degree to which the stop is nudged above or below i
As shown above, tolerance
is optional, if you leave it out, the interpreter will add the default tolerance, 10000
To add multiple expressions within the advancedColors, the expressions will be delimited by semicolons.
Color Gradient Example
The following is an example of the full color-stop syntax in practice:
"advancedColors": [
"color-stop before 0.0 color #ffffff tolerance 100000; color-stop at 0.0 color #000000; color-stop at 0.25 color #0000ff; color-stop at 0.5 color #0700ff; color-stop at 0.75 color #7f00ff; color-stop at 1.0 color #ff00ff;"
]
The above expression will display the following:
Discrete Color Bands
To set a discrete color band (e.g. every score between 80%-100% should be the same shade of green), a color-block
property is introduced.
The color-block syntax is as follows:
color-block <lower-bound> <m> <upper-bound> <n> color <c> tolerance <t>
where:
lower-bound
is one of: gt
, gte
('greater than' and 'greater than or equal to', respectively)
m
is the lower-bound value between 0 and 1, inclusive
upper-bound
is one of: lt
, lte
('less than' and 'less than or equal to', respectively)
n
is the upper-bound value between 0 and 1, inclusive
c
and t
are the same as described above and are the color and tolerance
Discrete Color Blocks Example
The following is an example of the full color-block syntax in practice:
"advancedColors": [
"color-block lt 0 color #e5e5e5 tolerance 100000; color-block gte 0 lte 0.4 color #ff007f tolerance 100000; color-block gt 0.4 lt 0.7 color #00ff7f; color-block gt 0.7 color #007fff;"
]
The above expression will display the following: