d3-hist2d

2D Histogram

d3.hist2d plugin implements a non-blocking rectangular binning. It's useful for displaying a scatterplot with millions of points, aggregating the data into a more coarse representation suitable for display.

It can be used as a module of a larger application, because it doesn't block the UI, it computes the values between each animation frame.

Inspired by the work of Mike Bostock.

Example

http://bl.ocks.org/herkulano/4f43dbf3473dc5503052

Usage

# hist2d([data], callback)

Expects [data] to be an array of arrays: [[1,2],[3,4],...]

The callback function is called when the binning is complete. It sends the data to its parameter.

d3.hist2d()
  .bins(40)
  .domain([[0, 100], [0, 100]])
  (data, draw);
 
function draw(hist) {
  // hist is the binned data
}

The returned data is an array of bins. Each bin contains its position in columns and rows as x and y:

• x - the column's position
• y - the row's position

Bins that are empty are omitted.

# hist2d.bins(bins)

Sets the number of columns and rows for the bins of the rectangular histogram. The total number of bins is columns * rows === bins * bins

# hist2d.indices([x index, y index])

Defines the indices of the data in the original array. This is useful if the data has more than two values or if the values are out of order.

Example:

[
  [0, 43, 12248, 30],
  [1, 45, 12398, 40],
  [2, 46, 12456, 50],
  ...
]
 
// we want to use [2] as x and [1] as y
d3.hist2d()
  .bins(40)
  .indices([2, 1])
  .domain([[0, 100], [0, 100]])
  (data, draw);

If indices is not set it defaults to [0, 1].

# hist2d.domain([ [x domain], [y domain] ])

Sets the input domains for x and y. Expects an array with two arrays of numbers.

# hist2d.size([width, height])

[width, height] of the scatterplot. Sets the width and height of the cells size / bins.

# hist2d.size()

Returns an array with the width and height of the cells [width, height].

# hist2d.interval(interval)

The binning function is non-blocking, so the values are computed between each animation frame for 12ms by default.

License & Acknowledgements

LICENSE