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 Encoding Field

This is the preferred way to express binning in Vega-Lite.

// 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: Binned color

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

Bin Transform

While Vega-Lite supports binning in transforms, the preferred way is to use binning in the encoding field.

// 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

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 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 that Vega-Lite currently does not track which fields are binned and thus cannot optimize how axes and legends are formatted. For this reason we use 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
maxbins Number

Maximum number of bins.

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

base Number

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

Default value: 10

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.

minstep Number

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

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.

nice Boolean

If true (the default), attempts to make the bin boundaries use human-friendly boundaries, such as multiples of ten.

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.