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 or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "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 | Null

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.

  • If "binned", this indicates that the data for the x (or y) channel are already binned. You can 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 tickMinStep property.

Default value: false

See also: bin documentation.

Example: Histogram

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

Example: Histogram with Ordinal Scale

While binned field has "quantitative" type by default, 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 bin to e.g. {"binned": true, "step": 2}.

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. 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., "val") is provided, the end field will be "val_end".

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 properties are used. To customize binning properties, 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 Array

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

Default value: true
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 maximum number of output bins. There will often be fewer bins since the domain get sliced at “nicely-rounded” values.

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.