Binning discretizes numeric values into a set of bins. A common use case is tocreate a histogram.
There are two ways to define binning in Vega-Lite:thebin property in encoding field definitions andthebin transform.
// A Single View or a Layer Specification{ ..., "mark/layer": ..., "encoding": { "x": { "bin": ..., // bin "field": ..., "type": "quantitative", ... }, "y": ..., ... }, ...}You can directly bin anencoding field by using thebin property in afield definition.
| Property | Type | Description |
|---|---|---|
| bin | Boolean |BinParams | String | Null | A flag for binning a
Default value: See also: |
Mapping binned values and its count to abar mark produces a histogram.
While binned field has"quantitative" type by default, setting the binned field’stype to"ordinal" produces a histogram with an ordinal scale.
You can use binning to discretize color scales. Vega-Lite automatically creates legends with range labels.
If you have data that is already binned outside of Vega-Lite, setting thebin property to"binned" will trigger Vega-Lite to render scales and axes similar to setting thebin property in encoding field definitions. Note that you have to specify field names that encode the start and end of each bin. To adjust the axis ticks based on the bin step, you can setbin to e.g.{"binned": true, "step": 2}.
// Any View Specification{ ... "transform": [ {"bin": ..., "field": ..., "as" ...} // Bin Transform ... ], ...}Thebin transform in thetransform array has the following properties:
| Property | Type | Description |
|---|---|---|
| bin | Boolean |BinParams | Required. An object indicating bin properties, or simply |
| field | String | Required. The data field to bin. |
| as | String | String[] | Required. The output fields at which to write the start and end bin values. This can be either a string or an array of strings with two elements denoting the name for the fields for bin start and bin end respectively. If a single string (e.g., |
Instead of using thebin property of a field definition, you can also use a bin transform to derive a new field (e.g.,bin_IMDB_Rating), and encode the new field with bin property of a field definition set tobinned instead.
While binning intransform is more verbose than inencoding, it can be useful if you want to perform additional calculation before encoding the data.
Ifbin istrue, default binning properties are used. To customize binning properties, you can setbin to a bin definition object, which can have the following properties:
| Property | Type | Description |
|---|---|---|
| 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. Default value: the minimum bin extent value |
| base | Number | The number base to use for automatic bin determination (default is base 10). Default value: |
| divide | Number[] | Scale factors indicating allowable subdivisions. The default value is [5, 2], which indicates that for base 10 numbers (the default base), the method may consider dividing bin sizes by 5 and/or 2. For example, for an initial step size of 10, the method can check if bin sizes of 2 (= 10/5), 5 (= 10/2), or 1 (= 10/(5*2)) might also satisfy the given constraints. Default value: |
| extent | Array | A two-element ( |
| maxbins | Number | Maximum number of bins. Default value: |
| minstep | Number | A minimum allowable step size (particularly useful for integer values). |
| nice | Boolean | If true, attempts to make the bin boundaries use human-friendly boundaries, such as multiples of ten. Default value: |
| step | Number | An exact step size to use between bins. Note: If provided, options such as maxbins will be ignored. |
| steps | Number[] | An array of allowable step sizes to choose from. |
Setting themaxbins parameter changes the maximum number of output bins. There will often be fewer bins since the domain get sliced at “nicely-rounded” values.
Usually, you should set the type of binned encodings to be quantitative. Vega-Lite automatically creates axes and legends that best represent binned data. However, if you want to sort the bins or skip empty bins, you can set the type to ordinal.
For example, this following plot shows binned values sort by count.