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

Faceting a Plot into a Trellis Plot

Edit this page

A Trellis plot (or small multiple) is a series of similar plots that displays different subsets of the same data, facilitating comparison across subsets.

There are two ways to facet views in Vega-Lite:

First, the facet operator is one of Vega-Lite’s view composition operators. This is the most flexible way to create faceted plots and allows composition with other operators.

Second, as a shortcut you can use the column or row encoding channels.

Documentation Overview

Facet Operator

To create a faceted view, define how the data should be faceted in facet and how each facet should be displayed in the spec.

{
  "facet": {
    ... // Facet definition
  },
  "spec": ...  // Specification
}

In addition to common properties of a view specification, a facet specification has the following properties:

Property Type Description
facet FacetMapping

Required. An object that describes mappings between row and column channels and their field definitions.
spec LayerSpec | SingleViewSpec

Required. A specification of the view that gets faceted.
align VgLayoutAlign | RowCol

The alignment to apply to grid rows and columns. The supported string values are "all", "each", and "none".

  • For "none", a flow layout will be used, in which adjacent subviews are simply placed one after the other.
  • For "each", subviews will be aligned into a clean grid structure, but each row or column may be of variable size.
  • For "all", subviews will be aligned and each row or column will be sized identically based on the maximum observed size. String values for this property will be applied to both grid rows and columns.

Alternatively, an object value of the form {"row": string, "column": string} can be used to supply different alignments for rows and columns.

Default value: "all".
bounds String

The bounds calculation method to use for determining the extent of a sub-plot. One of full (the default) or flush.

  • If set to full, the entire calculated bounds (including axes, title, and legend) will be used.
  • If set to flush, only the specified width and height values for the sub-view will be used. The flush setting can be useful when attempting to place sub-plots without axes or legends into a uniform grid structure.

Default value: "full"
center Boolean | RowCol

Boolean flag indicating if subviews should be centered relative to their respective rows or columns.

An object value of the form {"row": boolean, "column": boolean} can be used to supply different centering values for rows and columns.

Default value: false
spacing Number | RowCol

The spacing in pixels between sub-views of the composition operator. An object of the form {"row": number, "column": number} can be used to set different spacing values for rows and columns.

Default value: 10
resolve Resolve

Scale, axis, and legend resolutions for facets.

Facet Mapping

The facet property of a faceted view specification describes mappings between row and column and their field definitions:

Property Type Description
column FacetFieldDef

Horizontal facets for trellis plots.
row FacetFieldDef

Vertical facets for trellis plots.

Facet Field Definition

A FacetFieldDef is a field definition that has header (instead of scale and axis).

Property Type Description
aggregate Aggregate

Aggregation function for the field (e.g., mean, sum, median, min, max, count).

Default value: undefined (None)
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
field String | RepeatRef

Required. A string defining the name of the field from which to pull a data value or an object defining iterated values from the repeat operator.

Note: Dots (.) and brackets ([ and ]) can be used to access nested objects (e.g., "field": "foo.bar" and "field": "foo['bar']"). If field names contain dots or brackets but are not nested, you can use \\ to escape dots and brackets (e.g., "a\\.b" and "a\\[0\\]"). See more details about escaping in the field documentation.

Note: field is not required if aggregate is count.
timeUnit TimeUnit

Time unit (e.g., year, yearmonth, month, hours) for a temporal field. or a temporal field that gets casted as ordinal.

Default value: undefined (None)
type Type

Required. The encoded field’s type of measurement ("quantitative", "temporal", "ordinal", or "nominal"). It can also be a "geojson" type for encoding ‘geoshape’.
header Header

An object defining properties of a facet’s header.

Note Since row and column represent actual data fields that are used to partition the data, they cannot encode a constant value. In addition, you should not facet by quantitative fields unless they are binned, or temporal fields unless you use timeUnit.

Example

Below are three histograms for the horsepower of cars. Each chart shows the histogram for one origin (Europe, Japan, and USA).

This is the same example as below but the facet operator is more flexible as it allows composition and more customization such as overriding scale, axis, and legend resolution.

You can find more examples in the example gallery.

Similar to axes of position channels, a header of a facet channel provides guides to convey the data value that each row and column represent.

You can find more about facet headers in the header documentation.

Row & Column Encoding Channels

The row and column encoding channels.

The facet channels are encoding channels, which produce a trellis plot that facets a plot into columns or rows respectively. Vega-Lite automatically translates this shortcut to use the facet operator.

Property Type Description
row FacetFieldDef

Vertical facets for trellis plots.
column FacetFieldDef

Horizontal facets for trellis plots.

Example

Vega-Lite translates this spec to the more flexible spec with the facet operator above.

You can find more examples in the example gallery.

Resolve

The default resolutions for facet are shared scales, axes, and legends.