# Bin Transform

The bin transform discretizes numeric values into a set of bins. A common use case is to create a histogram.

## Transform Parameters

Property Type Description
field Field Required. The data field to bin.
extent Number[ ] Required. A two-element array with the minimum and maximum values of the bin range.
anchor Number A value in the binned domain at which to anchor the bins, shifting the bin boundaries if necessary to ensure that a boundary aligns with the anchor value. By default, the minimum bin extent value serves as the anchor.
maxbins Number The maximum number of bins to create (default `20`).
base Number The number base to use for automatic bin determination (default `10`).
step Number An exact step size to use between bins. If provided, options such as maxbins will be ignored.
steps Number[ ] An array of allowable step sizes to choose from.
minstep Number The minimum allowed bin step size (default `0`).
divide Number[ ] Allowable bin step sub-divisions. The default value is `[5, 2]`, which indicates that for base 10 numbers (the default base) automatic bin determination can consider dividing bin step sizes by 5 and/or 2.
nice Boolean If `true` (the default), attempts to make the bin boundaries use human-friendly boundaries, such as multiples of ten.
signal String If defined, binds the computed binning specification (an object with start, stop and step properties) to a signal with the given name.
as String[ ] The output fields at which to write the start and end bin values. The default is `["bin0", "bin1"]`.

## Usage

This example will bin values in the amount field into one of 5 bins between 0 and 10.

``````{"type": "bin", "field": "amount", "extent": [0, 10], "maxbins": 5}
``````

Given the input data

``````[
{"amount": 3.7},
{"amount": 6.2},
{"amount": 5.9},
{"amount": 8}
]
``````

the bin transform produces the output

``````[
{"amount": 3.7, "bin0": 2, "bin1": 4},
{"amount": 6.2, "bin0": 6, "bin1": 8},
{"amount": 5.9, "bin0": 4, "bin1": 6},
{"amount": 8, "bin0": 8, "bin1": 10}
]
``````