Wiki ▸ [[API Reference]] ▸ [[Layouts]] ▸

Histogram Layout

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 whether the histogram's `y`

value is a count (frequency) or a probability (density); the default is frequency. If *frequency* is not specified, returns the current frequency boolean.