# Binning data

Bin quantitative values into consecutive, non-overlapping intervals, as in histograms. (See also Observable Plot’s bin transform.)

## bin()

`const bin = d3.bin().value((d) => d.culmen_length_mm);`

Examples · Source · Constructs a new bin generator with the default settings. The returned bin generator supports method chaining, so this constructor is typically chained with *bin*.value to assign a value accessor. The returned generator is also a function; pass it data to bin.

*bin*(*data*)

`const bins = d3.bin().value((d) => d.culmen_length_mm)(penguins);`

Bins the given iterable of *data* samples. Returns an array of bins, where each bin is an array containing the associated elements from the input *data*. Thus, the `length`

of the bin is the number of elements in that bin. Each bin has two additional attributes:

`x0`

- the lower bound of the bin (inclusive).`x1`

- the upper bound of the bin (exclusive, except for the last bin).

Any null or non-comparable values in the given *data*, or those outside the domain, are ignored.

*bin*.value(*value*)

`const bin = d3.bin().value((d) => d.culmen_length_mm);`

If *value* is specified, sets the value accessor to the specified function or constant and returns this bin generator.

`bin.value() // (d) => d.culmen_length_mm`

If *value* is not specified, returns the current value accessor, which defaults to the identity function.

When bins are generated, the value accessor will be invoked for each element in the input data array, being passed the element `d`

, the index `i`

, and the array `data`

as three arguments. The default value accessor assumes that the input data are orderable (comparable), such as numbers or dates. If your data are not, then you should specify an accessor that returns the corresponding orderable value for a given datum.

This is similar to mapping your data to values before invoking the bin generator, but has the benefit that the input data remains associated with the returned bins, thereby making it easier to access other fields of the data.

*bin*.domain(*domain*)

`const bin = d3.bin().domain([0, 1]);`

If *domain* is specified, sets the domain accessor to the specified function or array and returns this bin generator.

`bin.domain() // [0, 1]`

If *domain* is not specified, returns the current domain accessor, which defaults to extent. The bin domain is defined as an array [*min*, *max*], where *min* is the minimum observable value and *max* is the maximum observable value; both values are inclusive. Any value outside of this domain will be ignored when the bins are generated.

For example, to use a bin generator with a linear scale `x`

, you might say:

`const bin = d3.bin().domain(x.domain()).thresholds(x.ticks(20));`

You can then compute the bins from an array of numbers like so:

`const bins = bin(numbers);`

If the default extent domain is used and the thresholds are specified as a count (rather than explicit values), then the computed domain will be niced such that all bins are uniform width.

Note that the domain accessor is invoked on the materialized array of values, not on the input data array.

*bin*.thresholds(*count*)

`const bin = d3.bin().thresholds([0, 0.5, 1]);`

If *thresholds* is specified, sets the threshold generator to the specified function or array and returns this bin generator.

`bin.thresholds() // () => [0, 0.5, 1]`

If *thresholds* is not specified, returns the current threshold generator, which by default implements Sturges’ formula. (Thus by default, the values to be binned must be numbers!) Thresholds are defined as an array of values [*x0*, *x1*, …]. Any value less than *x0* will be placed in the first bin; any value greater than or equal to *x0* but less than *x1* will be placed in the second bin; and so on. Thus, the generated bins will have *thresholds*.length + 1 bins.

Any threshold values outside the domain are ignored. The first *bin*.x0 is always equal to the minimum domain value, and the last *bin*.x1 is always equal to the maximum domain value.

`const bin = d3.bin().thresholds(20);`

If a *count* is specified instead of an array of *thresholds*, then the domain will be uniformly divided into approximately *count* bins; see ticks.

`const bin = d3.bin().thresholds((values) => [d3.median(values)]);`

You may also implement your own threshold generator taking three arguments: the array of input *values* derived from the data, and the domain represented as *min* and *max*. The generator may then return either the array of numeric thresholds or the *count* of bins; in the latter case the domain is divided uniformly into approximately *count* bins; see ticks. For instance, you might want to use time ticks when binning time-series data; see example.

## thresholdFreedmanDiaconis(*values*, *min*, *max*)

`const bin = d3.bin().thresholds(d3.thresholdFreedmanDiaconis);`

Source · Returns the number of bins according to the Freedman–Diaconis rule; the input *values* must be numbers.

## thresholdScott(*values*, *min*, *max*)

`const bin = d3.bin().thresholds(d3.thresholdScott);`

Source · Returns the number of bins according to Scott’s normal reference rule; the input *values* must be numbers.

## thresholdSturges(*values*, *min*, *max*)

`const bin = d3.bin().thresholds(d3.thresholdSturges);`

Source · Returns the number of bins according to Sturges’ formula; the input *values* must be numbers.