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.
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);
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.
The minimum and maximum values for which to draw the buckets of the histogram. Defaults to 0
and 1
.
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:
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.
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 |
![]() |
![]() |
The width and height (in pixels) of the histogram. Defaults to 500 each.
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.
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);
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']);