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. |
| interval | String | A boolean flag (default true) indicating if the transform should output both the start and end bin values. If false, only the starting (floored) bin value is written to the output. ≥ 5.8 |
| 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 (default 20). There will often be fewer bins as the domain gets sliced at “nicely” rounded values. |
| 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. |
| span | Number | The value span over which to generate bin boundaries. The default is extent[1] - extent[0]. This parameter allows automatic step size determination over custom spans (for example, a zoomed-in region) while retaining the overall extent. ≥ 5.6 |
| 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}
]