The flocc.Heatmap class (from here on, just Heatmap) can be used to visualize the distribution of Agents across two metrics. While Histograms are useful for showing the distribution of Agents along a single metric (or on multiple metrics using the same scale), a Heatmap can show how two metrics relate to one another — correlation, inverse correlation, in a nonlinear manner, randomly (no correlation), and more.

Instantiating

A Heatmap requires an Environment to render, as well as a DOM element in which to mount:

const environment = new Environment();
const heatmap = new Heatmap(environment);
heatmap.mount('#container');

for (let i = 0; i < 1000; i++) {
  environment.addAgent(
    new Agent({
      x: utils.uniform(),
      y: Math.abs(Math.sin(i) ** 2)
    })
  );

When visualized with a CanvasRenderer, the distribution looks like this — evenly distributed horizontally, with more clustered close to 0 and to 1.

A Heatmap can also be instantiated with configuration options, which affect the visual appearance.

const opts = {
    x: string = 'x' | Axis,
    y: string = 'y' | Axis,
    from: string = 'white',
    to string = 'black',
    max: number, // only for scale: 'fixed'
    width: number = 500,
    height: number = 500,
    scale: 'relative' | 'fixed' = 'relative'
};
const heatmap = new Heatmap(environment, opts);

x and y can simply be strings, in which case those strings will be used to look for Agentdata with keys matching, and plot them along the corresponding axis. For our example above, using the default configuration options, a Heatmap would render this:

One thing to note is that, although this appears close to the CanvasRenderer‘s output, the y-axis is flipped here. On a CanvasRenderer, the y values run from top to bottom (following computer graphics conventions), whereas on a Heatmap, they run from bottom to top, following human-readable visualization conventions.

Now, let’s see how adjusting the options affects the output:

x / y

As noted above, x and y can simply be strings, in which case they will be used to gather Agent data (i.e. for x: "age", it will look for agent.get("age") values). Using strings for x and y, these defaults are set:

• Range of 0 to 1
• 10 buckets (0 to 0.1, 0.1 to 0.2, 0.2 to 0.3, etc.)

If you want to visualize Agents whose values lie outside of the range of 0 to 1, or use a different number of buckets, then you should instead pass a configuration object like this:

const heatmap = new Heatmap({
  x: {
    key: "x",
    min: 0.5,
    max: 0.75,
    buckets: 5
  }
});

Again using our example, this configuration will result in the following output:

Notice that only 5 buckets are drawn along the x-axis, and the range now runs from 0.25 to 0.75, while all the options for the y-axis have remained the same.

The x and y options only support strings, or objects with key, min, max, and buckets key-value pairs.

The other top-level Heatmap options that can be configured are:

from / to

A string representing the colors to use when there are 0 agents and the maximum number of agents, respectively. Defaults to "white" for from and "black" for to. For the above example, if from is set to "purple" and to is set to "yellow", this would render:

from and to can be color names ("gray", "pink"), hex values ("#eee", "#ffe2e2"), or rgb strings ("rgb(255, 200, 220)").

scale

The scale can be either "relative" or "fixed". This defaults to "relative", in which case the maximum number of agents in a single cell is automatically used as the highest value in the scale (that cell will be drawn using the to value). This will also update if Agent distribution changes over time, so that on one tick the maximum number of agents might be different from the next.

If set to "fixed", then you supply the number to use as the maximum value (as the max option, read on:)

max

Not to be confused with the max option for x and y. When using a fixed scale, set this number to be the value for the maximum number of Agents (cells for which to be drawn using the to value). Any cells containing a number of Agents greater than this value will also be drawn using the to value.

In the above example, the maximum number of Agents in a single cell is 29. However, by setting scale to "fixed" and max to 15, this is rendered instead:

width / height

The width and height (in pixels) of the Heatmap. Defaults to 500 each.