This website is for Vega-Lite v4. 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 | UnitSpec

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

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

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

Vega-Lite automatically infers data types in many cases as discussed below. However, type is required for a field if: (1) the field is not nominal and the field encoding has no specified aggregate (except argmin and argmax), bin, scale type, custom sort order, nor timeUnit or (2) if you wish to use an ordinal scale for a field with bin or timeUnit.

Default value:

1) For a data field, "nominal" is the default data type unless the field encoding has aggregate, channel, bin, scale type, sort, or timeUnit that satisfies the following criteria: - "quantitative" is the default type if (1) the encoded field contains bin or aggregate except "argmin" and "argmax", (2) the encoding channel is latitude or longitude channel or (3) if the specified scale type is a quantitative scale. - "temporal" is the default type if (1) the encoded field contains timeUnit or (2) the specified scale type is a time or utc scale - ordinal"" is the default type if (1) the encoded field contains a custom sort order, (2) the specified scale type is an ordinal/point/band scale, or (3) the encoding channel is order.

2) For a constant value in data domain (datum): - "quantitative" if the datum is a number - "nominal" if the datum is a string - "temporal" if the datum is a date time object

Note: - 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. - 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). - 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" (default, 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"}. The "type" of the aggregate output is "quantitative". - Secondary channels (e.g., x2, y2, xError, yError) do not have type as they must 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.

Facet Field Definition

In addition to field, type, bin, and timeUnit, field definitions for row, column and facet channels may also include these properties:

Property Type Description
align String

The alignment to apply to row/column facet’s subplot. 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.

Default value: "all".
center Boolean

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

Default value: false
spacing Number

The spacing in pixels between facet’s sub-views.

Default value: Depends on "spacing" property of the view composition configuration (20 by default)

In addition, the facet channel should include the columns property:

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

Meanwhile, the row and column channel could include the following properties:

Property Type Description
align String

The alignment to apply to row/column facet’s subplot. 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.

Default value: "all".
center Boolean

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

Default value: false
spacing Number

The spacing in pixels between facet’s sub-views.

Default value: Depends on "spacing" property of the view composition configuration (20 by default)

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.

Grid Facet (with Row and column Encoding)

Using both "row" and "column" channels produce a grid of small multiples.

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