API Reference ▸ Layouts ▸ Histogram Layout
The D3 4.0 API Reference has moved. This page describes the D3 3.x API.
A histogram layout shows the distribution of data by grouping discrete data points into bins. See bl.ock 3048450 for example usage.
# d3.layout.histogram()
Constructs a new histogram function with the default value accessor, range function, and bin function. By default, the histogram function returns frequencies. The returned layout object is both an object and a function. That is: you can call the layout like any other function, and the layout has additional methods that change its behavior. Like other classes in D3, layouts follow the method chaining pattern where setter methods return the layout itself, allowing multiple setters to be invoked in a concise statement.
# histogram(values[, index])
Evaluates the histogram function on the specified array of values. An optional index may be specified, which is passed along to the range and bin function. The return value is an array of arrays: each element in the outer array represents a bin, and each bin contains the associated elements from the input values. In addition, each bin has three attributes:
- x - the lower bound of the bin (inclusive).
- dx - the width of the bin; x + dx is the upper bound (exclusive).
- y - the count (if frequency is true), or the probability (if frequency is false).
Note that the y attribute is the same as the length attribute, in frequency mode.
# histogram.value([accessor])
Specifies how to extract a value from the associated data; accessor is a function which is invoked on each input value passed to histogram, equivalent to calling values.map(accessor) before computing the histogram. The default value function is the built-in Number, which is similar to the identity function. If accessor is not specified, returns the current value accessor.
# histogram.range([range])
Specifies the range of the histogram. Values outside the specified range will be ignored. The range may be specified either as a two-element array representing the minimum and maximum value of the range, or as a function that returns the range given the array of values and the current index passed to histogram. The default range is the extent (minimum and maximum) of the values. If range is not specified, returns the current range function.
# histogram.bins()
# histogram.bins(count)
# histogram.bins(thresholds)
# histogram.bins(function)
Specifies how to bin values in the histogram. If no argument is specified, the current binning function is returned, which defaults to an implementation of Sturges' formula that divides values into bins using uniformly-spaced values. If a count is specified, the value range is divided evenly into the specified number of bins.
If an array of thresholds is specified, it defines the value thresholds used to bin, starting with the leftmost (lowest) value and ending with rightmost (highest) value. The n + 1 thresholds specify n bins. Any values less than thresholds[1] will be placed in the first bin; likewise any values greater than or equal to thresholds[thresholds.length - 2] will be placed in the last bin. Thus, although the first and last threshold are not used to assign values to bins, they are still necessary to define the x property of the first bin and the dx property of the last bin, respectively.
Lastly, if a binning function is specified, it is invoked when the layout is passed data, being passed the current range, the array of values and the current index passed to histogram. This function must then return an array of thresholds as described in the previous paragraph.
# histogram.frequency([frequency])
Specifies the meaning of the generated bins’ y-values. If frequency is true, which is the default, the y-value represents the count of elements in the bin. If false, it represents the probability of a random element in the sample population being in that bin. Note that this is a probability, not a probability density, and so for irregular histograms, you must normalize the y-value by the bin width (bin.y / bin.dx) for the area of the displayed bar to be proportional to the probability. If frequency is not specified, returns the current frequency boolean.