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

A flag for binning a quantitative field, an object defining binning parameters, or indicating that the data for x or y channel are binned before they are imported into Vega-Lite ("binned").

  • If true, default binning parameters will be applied.

  • To indicate that the data for the x (or y) channel are already binned, you can set the bin property of the x (or y) channel to "binned" and map the bin-start field to x (or y) and the bin-end field to x2 (or y2). The scale and axis will be formatted similar to binning in Vega-lite. To adjust the axis ticks based on the bin step, you can also set the axis’s tickStep property.

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.

Example: Using Vega-Lite with Binned data

If you have data that is already binned outside of Vega-Lite, setting the bin property to "binned" will trigger Vega-Lite to render scales and axes similar to setting the bin 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 set the axis’s tickStep property.

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 with bin property of a field definition set to binned 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.

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
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: 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.