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.

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").

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.

By default, Vega-Lite automatically creates axes with default properties for row and column channels of a faceted view. User can set the header property of row- or column-field definition to an object to customize header properties.

Property Type Description
format String

The formatting pattern for labels. This is D3’s number format pattern for quantitative fields and D3’s time format pattern for time field.

See the format documentation for more information.

Default value: derived from numberFormat config for quantitative fields and from timeFormat config for temporal fields.

title String | Null

A title for the field. If null, the title will be removed.

Default value: derived from the field’s name and transformation function (aggregate, bin and timeUnit). If the field has an aggregate function, the function is displayed as a part of the title (e.g., "Sum of Profit"). If the field is binned or has a time unit applied, the applied function will be denoted in parentheses (e.g., "Profit (binned)", "Transaction Date (year-month)"). Otherwise, the title is simply the field name.

Note: You can customize the default field title format by providing the [fieldTitle property in the config or fieldTitle function via the compile function’s options.

See also: You may also use guide-title and guide-label style configs to customize common styles for axis, legend, and header labels and titles.

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.