This website is for Vega-Lite v3. 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 facet, 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 FacetFieldDef | FacetMapping

Required. Definition for how to facet the data. One of: 1) a field definition for faceting the plot by one field 2) An object that maps row and column channels to their field definitions
spec LayerSpec | FacetedUnitSpec

Required. A specification of the view that gets faceted.
columns Number

The number of columns to include in the view composition layout.

Default value: undefined – An infinite number of columns (a single row) will be assumed. This is equivalent to hconcat (for concat) and to using the column channel (for facet and repeat).

Note:

1) This property is only for:

  • the general (wrappable) concat operator (not hconcat/vconcat)
  • the facet and repeat operator with one field/repetition definition (without row/column nesting)

2) Setting the columns to 1 is equivalent to vconcat (for concat) and to using the row channel (for facet and repeat).

Facet Field Definition

A facet field definition has the following properties:

Property Type Description
bin Boolean | BinParams | 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.
field Field

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.

See also: field documentation.

Notes: 1) 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. 2) 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)

See also: timeUnit documentation.
type String

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

Note:

  • Data values for a temporal field can be either a date-time string (e.g., "2015-03-07 12:32:17", "17:01", "2015-03-16". "2015") or a timestamp number (e.g., 1552199579097).
  • Data type describes the semantics of the data rather than the primitive data types (number, string, etc.). The same primitive data type can have different types of measurement. For example, numeric data can represent quantitative, ordinal, or nominal data.
  • When using with bin, the type property can be either "quantitative" (for using a linear bin scale) or "ordinal" (for using an ordinal bin scale).
  • When using with timeUnit, the type property can be either "temporal" (for using a temporal scale) or "ordinal" (for using an ordinal scale).
  • When using with aggregate, the type property refers to the post-aggregation data type. For example, we can calculate count distinct of a categorical field "cat" using {"aggregate": "distinct", "field": "cat", "type": "quantitative"}. The "type" of the aggregate output is "quantitative".
  • Secondary channels (e.g., x2, y2, xError, yError) do not have type as they have exactly the same type as their primary channels (e.g., x, y).

See also: type documentation.
header Header

An object defining properties of a facet’s header.

Note

  1. Unlike a positional field definition, a facet field definition has the header property instead of scale and axis.
  2. Since facet, 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.

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

A field definition for the horizontal facet of trellis plots.
row FacetFieldDef

A field definition for the vertical facet of trellis plots.

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.

Example

Here are examples of full row-facet and wrapped facet specifications. For more example, see the example gallery.

Row-Facet

The following specification uses the facet operator to vertically facet the histograms for the “horsepower” of cars by “origin” (using "row"). 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.

Wrapped Facet

Facet, Row, and Column Encoding Channels

The facet channels (facet, row, and column) are encoding channels that serves as macros for a facet specification. Vega-Lite automatically translates this shortcut to use the facet operator.

Examples

Here are examples of row-facet and wrapped facet plots that use encoding to specify the faceted fields. For more example, see the example gallery.

Row-Facet (with Row Encoding)

Under the hood, Vega-Lite translates this spec with "row" channel to the more flexible specs with the facet operator above.

Wrapped Facet (with Facet Encoding)

Under the hood, Vega-Lite translates this spec with "facet" channel to the more flexible specs with the facet operator above.

Resolve

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

To override this behavior, you can set resolve to "independent":

Facet Configuration

// Top-level View Specification
{
  ...,
  "config": { // Configuration Object

    "facet": { // - Facet Configuration
      "spacing": ...,
      "columns": ...,
    },
    ...
  }
}

The facet configuration supports the following properties:

Property Type Description
columns Number

The number of columns to include in the view composition layout.

Default value: undefined – An infinite number of columns (a single row) will be assumed. This is equivalent to hconcat (for concat) and to using the column channel (for facet and repeat).

Note:

1) This property is only for:

  • the general (wrappable) concat operator (not hconcat/vconcat)
  • the facet and repeat operator with one field/repetition definition (without row/column nesting)

2) Setting the columns to 1 is equivalent to vconcat (for concat) and to using the row channel (for facet and repeat).
spacing Number

The default spacing in pixels between composed sub-views.

Default value: 20