LineChartRenderer

Overview

In addition to rendering agents in an environment themselves, you might want to visualize aggregate data, such as average values across agents or maximum or minimum values. The flocc.LineChartRenderer class (from here on, just LineChartRenderer) allows you to display data about the agents in an environment over time, instead of representing the agents themselves.

Instantiating

A LineChartRenderer requires an Environment to render:

const environment = new Environment();
const chart = new LineChartRenderer(environment);

Options

A LineChartRenderer can also be instantiated with configuration options, which affect the output.

const opts = {
    background: string = 'transparent',
    height: number = 500,
    width: number = 500,
    range: {
      max: number = 500,
      min: number = 0
    }
};

const chart = new LineChartRenderer(environment, opts);

width / height

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

background

The background color of the chart. Defaults to a transparent background. Can be a color name ("gray", "pink"), a hex value ("#eee", "#ffe2e2"), or an rgb string ("rgb(255, 200, 220)").

range

An object with min and max keys whose values are numbers corresponding to the what range values should be drawn on the chart.

Methods

.mount(selector or element, opts)

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>
chart.mount('#some-element');
// or...
const element = document.getElementById('some-element');
chart.mount(element);

.metric(key, opts)

Calling .metric adds a metric to the line chart to be visualized over time. The required key parameter should match the key on the agent data you would like to visualize. For example, if you are trying to visualize the average age of agents, and each agent has a age key-value pair, you would call this:

chart.metric('age');

Then, with every tick of the environment, the chart will update to show the average age of all agents.

You can also pass in options to customize the visual display of the metric. The default options look like this:

const opts = {
  color: 'black',
  fn: flocc.utils.mean
};

color: Determines the color of the line drawn. Defaults to a black line. Can be a color name ("gray", "pink"), a hex value ("#eee", "#ffe2e2"), or an rgb string ("rgb(255, 200, 220)").

fn: A function that determines the value to be displayed for the metric. Any function that takes an array of numbers (corresponding to the values for all the agents with the metric's key-value pair) and returns a single number will work. Defaults to utils.mean. Other utility functions that can be used are utils.median, utils.sum, utils.stdDev, utils.min, and utils.max.

In addition to the above utility functions, you could also write a custom function to visualize aggregate agent data. For example, to visualize the number of agents with a size value over 50, you could use the following:

chart.metric('size', {
  fn: arr => {
    return arr.filter(size => size > 50).length;
  }
})