D3 plugin which computes a 'beeswarm' arrangement

Downloads in past


0.0.56 years ago7 years agoMinified + gzip package size for d3-beeswarm in KB


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.


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.



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>
  var swarm = d3.beeswarm();


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:
      .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.



# 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:
       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