In addition to rendering agents in an environment themselves, you might want to visualize aggregate data, such as the number of agents with values in certain ranges. The flocc.Histogram class (from here on, just Histogram) allows you to display data about the distribution of agent values in an environment, instead of representing the agents themselves.

Instantiating

A Histogram requires an Environment to render, as well as a DOM element in which to mount, and a metric (key or keys of agent data whose values to bucket):

const environment = new Environment();
const histogram = new Histogram(environment);
histogram.mount('#container');
histogram.metric('size');

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

const opts = {
    aboveMax: boolean = false,
    belowMin: boolean = false,
    buckets: number = 1 | Array<any>,
    color: string = 'black' | Array<string>,
    epsilon: number = 0,
    height: number = 500,
    max: number = 1,
    min: number = 0,
    width: number = 500,
    scale: 'relative' | 'fixed' = 'fixed'
};
const histogram = new Histogram(environment, opts);

buckets

The number of buckets in which to sort agent values within the given range. The below histograms visualize the same agents in their environment, sorted into two buckets and four buckets, respectively.

Alternatively, buckets can be an array containing any primitive types (numbers, strings, or booleans), which the Histogram will use to match exact agent values, rather than ranges of values.

min / max

The minimum and maximum values for which to draw the buckets of the histogram. Defaults to 0 and 1.

aboveMax / belowMin

If these parameters are set to true, they will display an extra bucket(s) for agents whose values fall above or below the range given by max and min, respectively. For example, a Histogram with max = 1, min = 0, buckets = 5, and aboveMax and belowMin both set to true might look like this:

epsilon

If buckets is an array rather than a number, and if the bucket values are numbers, a number epsilon can be included to match agents within a range of the exact bucket value. For example, if buckets is [1, 2, 3], with epsilon 0.01, an agent with a value 1.01 would fall into bucket 1 but an agent with a value 1.5 would not be bucketed.

scale

Depending on whether this is "relative" or "fixed", the height of the chart will either be relative to the highest bar value or to the number of agents in the environment, respectively (see example below). Defaults to "fixed."

fixed: chart height = total # of agents	relative: chart height = value of highest bar

width / height

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

color

The color of bars on the histogram. Defaults to black. Can be a color name ("gray", "pink"), a hex value ("#eee", "#ffe2e2"), or an rgb string ("rgb(255, 200, 220)"). If visualizing multiple metrics, this can be an array of strings with the order of the colors matching the order of the metrics.

.mount(selector or element)

Calling .mount specifies where on the page the chart should be drawn. If passed a CSS selector (like #id or .class), it will look for the first matching element on the page, and use that as a container. If passed an element directly, it will use that element as a container.

<div id="some-element"></div>

histogram.mount('#some-element');
// or...
const element = document.getElementById('some-element');
histogram.mount(element);

.metric(key: string or keys: Array<string> or key1: string, key2: string, …)

Calling .metric sets the metric(s) that the histogram will visualize. If using a single metric, the key parameter should match the key on the agent data to bucket. For example, if you are trying to visualize the distribution of agent ages, and each agent has a age key-value pair, you would call this:

histogram.metric('age');

Then, with every tick of the environment, the chart will update to show the distribution of agent ages.

For multiple metrics, pass either an array of strings or individual strings as separate parameters, like this:

histogram.metric('age', 'height');
// or
histogram.metric(['age', 'height']);