This website is for Vega-Lite v2. Go to the main Vega-Lite homepage for the latest release.

Binning

Edit this page

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

There are two ways to define binning in Vega-Lite: the bin property in encoding field definitions and the bin transform.

Documentation Overview

Binning in Encoding Field Definition

// A Single View Specification
{
  "data": ... ,
  "mark": ... ,
  "encoding": {
    "x": {
      "bin": ...,               // bin
      "field": ...,
      "type": "quantitative",
      ...
    },
    "y": ...,
    ...
  },
  ...
}

You can directly bin an encoding field by using the bin property in a field definition.

Property Type Description
bin Boolean | BinParams

A flag for binning a quantitative field, or an object defining binning parameters. If true, default binning parameters will be applied.

Default value: false

Example: Histogram

Mapping binned values and its count to a bar mark produces a histogram.

Example: Histogram with Ordinal Scale

Setting the binned field’s type to "ordinal" produces a histogram with an ordinal scale.

Example: Binned color

You can use binning to discretize color scales. Vega-Lite automatically creates legends with range labels.

Bin Transform

// Any View Specification
{
  ...
  "transform": [
    {"bin": ..., "field": ..., "as" ...} // Bin Transform
     ...
  ],
  ...
}

The bin transform in the transform array has the following properties:

Property Type Description
bin Boolean | BinParams

Required. An object indicating bin properties, or simply true for using default bin parameters.
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.

Example: Histogram with Bin Transform

Instead of using the bin 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 instead.

While binning in transform is more verbose than in encoding, it can be useful if you want to perform additional calculation before encoding the data.

Note: Vega-Lite currently does not track which fields are binned and thus cannot optimize how axes and legends are formatted. For this reason we have to set the type to ordinal in the example above.

Bin Parameters

If bin is true, default binning parameters are used. To customize binning parameters, you can set bin to a bin definition object, which can have the following properties:

Property Type Description
base Number

The number base to use for automatic bin determination (default is base 10).

Default value: 10
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: [5, 2]
extent Number[]

A two-element ([min, max]) array indicating the range of desired bin values.
maxbins Number

Maximum number of bins.

Default value: 6 for row, column and shape channels; 10 for other channels
minstep Number

A minimum allowable step size (particularly useful for integer values).
nice Boolean

If true (the default), attempts to make the bin boundaries use human-friendly boundaries, such as multiples of ten.
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.

Example: Customizing Max Bins

Setting the maxbins parameter changes the number of output bins.

Ordinal Bin

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.