# 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 | The data field to bin.Required. |

extent | Number[ ] | A two-element array with the minimum and maximum values of the bin range.Required. |

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}
]
```