Home

Awesome

d3-beeswarm

This d3 plugin produces a beeswarm arrangement, thanks to a dedicated algorithm and without the use a the d3.force layout.

Available only for d3 v3.x and d3 v4.

Context

Beeswarm is a one-dimensional scatter plot with closely-packed, non-overlapping points. The beeswarm plot is a useful technique when we wish to see not only the measured values of interest for each data point, but also the distribution of these values

Some beeswarm-like plot implementation uses force layout, but the force layout simulation has some drawbacks:

This beeswarm plugin uses a dedicated one pass algorithm. By default, this plugin arranges data in an horizontal way, ie. along the x-axis. In this case, the final arrangement is constraint in x and free in y. This means that the position of each data reflects its precise x value, while y position doesn't reflect any data-related value (and only serves the non-overlapping constraint). This plugin can also arrange data in a vertical way.

Examples

Installing

If you use NPM, npm install d3-beeswarm. Otherwise, load https://rawgit.com/Kcnarf/d3-beeswarm/master/build/d3-beeswarm.js to make it available in AMD, CommonJS, or vanilla environments. In vanilla, a d3 global is exported:

<script src="https://d3js.org/d3.v3.min.js"></script>
<script src="https://rawgit.com/Kcnarf/d3-beeswarm/master/build/d3-beeswarm.js"></script>
<script>
  var swarm = d3.beeswarm();
</script>

TL;DR;

In your javascript, in order to define the arrangement:

var swarm = d3
  .beeswarm()
  .data(data) // set the data to arrange
  .distributeOn(function(d) {
    // set the value accessor to distribute on
    return xScale(d.foo); // evaluated once on each element of data
  }) // when starting the arrangement
  .radius(4) // set the radius for overlapping detection
  .orientation('horizontal') // set the orientation of the arrangement
  // could also be 'vertical'
  .side('symetric') // set the side(s) available for accumulation
  // could also be 'positive' or 'negative'
  .arrange(); // launch arrangement computation;
// return an array of {datum: , x: , y: }
// where datum refers to an element of data
// each element of data remains unchanged

Then, later in your javascript, in order to draw the swarm:

d3.selectAll('circle')
  .data(swarm)
  .enter()
  .append('circle')
  .attr('cx', function(bee) {
    return bee.x;
  })
  .attr('cy', function(bee) {
    return bee.y;
  })
  .attr('r', 4)
  .style('fill', function(bee) {
    return fillScale(bee.datum.bar);
  });

In the last line, bee.datum refers to the original datum.

Reference

API

<a name="beeswarm" href="#beeswarm">#</a> d3.<b>beeswarm</b>()

Creates a new beeswarm with the default settings:

distributeOn = function(d) {
  return d.x;
};
radius = 4;
orientation = 'horizontal';
side = 'symetric';

<a name="beeswarm_data" href="#beeswarm_data">#</a> <i>beeswarm.</i><b>data</b>data</b>([data])

If data is specified, set the array of data to arrange and returns this beeswarm. If data is not specified, returns the current array of data to arrange.

<a name="beeswarm_distributeOn" href="#beeswarm_distributeOn">#</a> <i>beeswarm.</i><b>distributeOn</b>([callback])

If callback is specified, set the callback that evaluates the value to distribute on and returns this beeswarm. If callback is not specified, return the current callback, which defaults to function(d) { return d.x; }.

The callback is evaluated once, on each element to arrange, at the beginning of the arrangement computation. The callback must return the final x-coordinate for an horizontal arrangement (or the final y-coordinate for a vertical arrangement). So if you use a d3.scale, your code should look like:

d3.beeswarm()
  .data(data)
  .distributeOn(function(d) {
    return xScale(d.foo);
  });

<a name="beeswarm_radius" href="#beeswarm_radius">#</a> <i>beeswarm.</i><b>radius</b>([radius])

Without any argument, returns the current radius of the layout. If radius is specified, sets the radius of each datum to the specified number. If radius is not specified, returns the current radius, which defaults to 4.

The arrangement uses this radius as a constraint, and arranges each datum so that there is no overlapping. However, when its time to draw each datum, you can use another rendering radius:

<a name="beeswarm_orientation" href="#beeswarm_orientation">#</a> <i>beeswarm.</i><b>orientation</b>([orientation])

If orientation is specified, set the orientation to the specified value (within 'horizontal' or 'vertical') and returns this beeswarm. If orientation is not specified, returns the current orientation, which defaults to 'horizontal'.

A 'horizontal' orientation will arrange data along the x-axis. A 'vertical' arrangement will arrange data along the y-axis.

<a name="beeswarm_side" href="#beeswarm_side">#</a> <i>beeswarm.</i><b>side</b>([side])

If side is specified, set the side to the specified value (within 'symetric', 'positive' or 'negative') and returns this beeswarm. If side is not specified, returns the current side, which defaults to 'symetric'.

A 'symetric' side arranges data around the main axis, placing data above and below the axis. A 'positive'side arranges data only above the main axis. A 'negative'side arranges data only below the main axis.

<a name="beeswarm_arrange" href="#beeswarm_arrange">#</a> <i>beeswarm.</i><b>arrange</b>()

Launches the arrangement computation. Return an array of {x: , y: , datum: }, where x and y are the computed coordinates, and datum refers to the original element of data.

How To