Faceting a Plot into a Trellis Plot
Edit this pageA Trellis plot (or small multiple) is a series of similar plots that displays different subsets of the same data, facilitating comparison across subsets.
There aretwo ways to facet views in Vega-Lite:
First, thefacet operator is one of Vega-Lite’sview 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 thefacet,column, orrow encoding channels.
Documentation Overview
Facet Operator
To create a faceted view, define how the data should be faceted infacet and how each facet should be displayed in thespec.
{ "facet": { ... // Facet definition }, "spec": ... // Specification}
In addition tocommon 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 mapsrow andcolumn 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 tohconcat (forconcat) and to using thecolumn channel (forfacet andrepeat). Note: 1) This property is only for: - the general (wrappable)
concat operator (nothconcat/vconcat) - the
facet andrepeat operator with one field/repetition definition (without row/column nesting)
2) Setting thecolumns to1 is equivalent tovconcat (forconcat) and to using therow channel (forfacet andrepeat). |
Facet Field Definition
A facetfield definition has the following properties:
| Property | Type | Description |
|---|
| bin | Boolean |BinParams | Null | A flag for binning aquantitative field,an object defining binning parameters, or indicating that the data forx ory channel are binned before they are imported into Vega-Lite ("binned"). Iftrue, defaultbinning parameters will be applied. If"binned", this indicates that the data for thex (ory) channel are already binned. You can map the bin-start field tox (ory) and the bin-end field tox2 (ory2). 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’stickMinStep 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 therepeat 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 thefield documentation. 2)field is not required ifaggregate iscount. |
| timeUnit | TimeUnit | String |TimeUnitParams | Time unit (e.g.,year,yearmonth,month,hours) for a temporal field. ora 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 specifiedaggregate (exceptargmin andargmax),bin, scale type, customsort order, nortimeUnit or (2) if you wish to use an ordinal scale for a field withbin ortimeUnit. Default value: 1) For a datafield,"nominal" is the default data type unless the field encoding hasaggregate,channel,bin, scale type,sort, ortimeUnit that satisfies the following criteria: "quantitative" is the default type if (1) the encoded field containsbin oraggregate except"argmin" and"argmax", (2) the encoding channel islatitude orlongitude channel or (3) if the specified scale type isa quantitative scale."temporal" is the default type if (1) the encoded field containstimeUnit or (2) the specified scale type is a time or utc scale"ordinal" is the default type if (1) the encoded field contains acustomsort order, (2) the specified scale type is an ordinal/point/band scale, or (3) the encoding channel isorder.
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 isa 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, thetype property can be either"quantitative" (for using a linear bin scale) or"ordinal" (for using an ordinal bin scale). - When using with
timeUnit, thetype property can be either"temporal" (default, for using a temporal scale) or"ordinal" (for using an ordinal scale). - When using with
aggregate, thetype property refers to the post-aggregation data type. For example, we can calculate countdistinct 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 havetype as they must have exactly the same type as their primary channels (e.g.,x,y).
See also:type documentation. |
| header | Header | Null | An object defining properties of a facet’s header. |
Note
- Unlike apositional field definition, a facet field definition has the
header property instead ofscale andaxis. - Since
facet,row andcolumn represent actual data fields that are used to partition the data, they cannot encode a constantvalue. In addition, you should not facet by quantitative fields unless they arebinned, or temporal fields unless you usetimeUnit.
Row/Column Facet Mapping
Thefacet property of a faceted view specification describes mappings betweenrow andcolumn 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. |
Facet Headers
Similar to axes of position channels, aheader 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 theheader documentation.
Example
Here are examples of full row-facet and wrapped facet specifications. For more example, see theexample gallery.
Row-Facet
The following specification uses thefacet 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 asbelow 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
Thefacet channels (facet,row, andcolumn) areencoding 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 tofield,type,bin, andtimeUnit,field definitions forrow,column andfacet 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 ofthe view composition configuration (20 by default) |
In addition, thefacet channel should include thecolumns 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 tohconcat (forconcat) and to using thecolumn channel (forfacet andrepeat). Note: 1) This property is only for: - the general (wrappable)
concat operator (nothconcat/vconcat) - the
facet andrepeat operator with one field/repetition definition (without row/column nesting)
2) Setting thecolumns to1 is equivalent tovconcat (forconcat) and to using therow channel (forfacet andrepeat). |
Meanwhile, therow andcolumn 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 ofthe 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 theexample gallery.
Row Facet (with Row Encoding)
Under the hood, Vega-Lite translates this spec with"row" channel to the more flexiblespecs 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 flexiblespecs with the facet operator above.
Resolve
The defaultresolutions for row/column facet are shared scales, axes, and legends.
To override this behavior, you can setresolve 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 tohconcat (forconcat) and to using thecolumn channel (forfacet andrepeat). Note: 1) This property is only for: - the general (wrappable)
concat operator (nothconcat/vconcat) - the
facet andrepeat operator with one field/repetition definition (without row/column nesting)
2) Setting thecolumns to1 is equivalent tovconcat (forconcat) and to using therow channel (forfacet andrepeat). |
| spacing | Number | The default spacing in pixels between composed sub-views. Default value:20 |