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:

• it naturally tries to reach its equilibrium by rearranging data points in the 2D space, which can be disruptive to the ordering of the data
• it requires several iterations to reach its equilibrium

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

• White House Salaries - Obama '16 VS Trump '17.
• This post uses a beeswarm plot (but not this plugin).
• This block allows to play with the options of this d3-beeswarm plugin.

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

• R package: <a href=http://www.cbs.dtu.dk/~eklund/beeswarm/'>http://www.cbs.dtu.dk/~eklund/beeswarm/

API

# d3.beeswarm()

Creates a new beeswarm with the default settings:

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

# beeswarm.datadata([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.

# beeswarm.distributeOn([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);
  })  

# beeswarm.radius([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 lower rendering radius will add some padding between data
• a higher rendering radius will add some overlapping between data (making the final viz more compacted as if there wasn't any overlapping, but with the drawback to not meet the non-overlapping constraint of beeswarm arrangement)

# beeswarm.orientation([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.

# beeswarm.side([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.

# beeswarm.arrange()

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

• issue option to arrange from minToMax, maxToMin, extremeToCenter, shuffled explains how to arrange in a particular order. It can be tested in this block.
• issue add a maximum size, and provide strategies if exceeded explains how to handle too large viz due to extreme accumulations. It can be tested in this block.