Condition

// A Single View or a Layer Specification{  ...,  "mark/layer": ...,  "encoding": {    ...: {      // Conditional encoding channel definition (if-clause)      "condition": {        // Parameter name or a test predicate        "param/test": ...,        // Field / value definition if the data is included in the `param` or if the `test` predicate is satisfied        "field/value": ...,        ...      },      // (Optional else-clause) Field / value definition if the data is NOT included in the `param` / if the `test` predicate is NOT satisfied      "field/value": ...,      ...    },    ...  },  ...}

Formark property channels as well astext and tooltip channels, thecondition property of their channel definitions can be used to determine encoding rules based on whether data values satisfy aparameter (e.g. fall withing aselection parameter) or satisfy atest predicate.

There are two ways to specify the condition:

(1) Specifyingparam name:

(2) Specifying atest predicate:

In addition, there are two ways to encode the data that satisfy the specified condition:

1. Combining oneconditional field definition with a single base value or datum definition.

2. Combining one or moreconditional datum or value definitions with a field, datum, or value definition.

Conditional Field Definition

// A Single View or a Layer Specification{  ...,  "mark/layer": ...,  "encoding": {    ...: {      // A conditional field definition (if-clause)      "condition": {        // Parameter name or a test predicate        "param/test": ...,        // Field if the data is included in the `param` or if the `test` predicate is satisfied        "field": ...,        "type": ...,        ...      },      // (Optional else-clause) value if the data is NOT included in the `param` / if the `test` predicate is NOT satisfied      "value/datum": ...    },    ...  },  ...}

A conditional field definition uses a data-driven encoding rule when marks satisfy aparameter (e.g. fall within aselection parameter) or satisfy a logical predicate. A value definition can be specified as the “else” case when the condition is not satisfied otherwise.

A condition field definition must contain eitheraparam name or atest predicate in addition to the encodedfield name and its datatype like a typicalfield definition. In addition, a condition field definition may contain other encoding properties including transformation functions (aggregate,bin,timeUnit) as well asscale andlegend (formark property channels) orformat (fortext and tooltip channels).

For example, in the following plot, the color ofrect marks is driven by a conditional field definition. Drag an interval selection and observe that marks are colored based on their aggregated count if they lie within the interval, and are grey otherwise.

Note: When using a conditional field definition, onlyvalue ordatum may be specified as the else (outer) branch.

Conditional Value Definition

// A Single View or a Layer Specification{  ...,  "mark/layer": ...,  "encoding": {    ...: {      // A conditional value definition (if-clause)      "condition": { // Parameter name or a test predicate        "param/test": ..., // Value if the data is included in the `param` or if the `test` predicate is satisfied        "value/datum": ...      },      // (Optional else-clause) field if the data is NOT included in the `param` / if the `test` predicate is NOT satisfied      "field": ... ,      "type": ...,      ...    },    ...  },  ...}

Condition value definitions and conditional datum definitions use a constant value encoding when data satisfy aparameter (e.g. fall withing aselection parameter) or satisfy a logical predicate. Another field, datum, or value definition can be specified as the “else” case when the condition is not satisfied.

A condition value/datum definition must contain eitheraparam name or atest predicate in addition to the encoded constantvalue or constant data value (datum).

For example, in the visualization below, a conditional value definition causes marks that fall within a dragged interval to be larger than those that lie outside it.

A field mapping can also be specified as the else (outer) branch. For example, below, we invert our original example: a conditional value definition sets therect marks to grey when they donot lie within the selection, and a regular field mapping is used otherwise. Notice, no marks are initially colored grey. This is because empty selections are treated as containing all data values.

Besides specifyingparam name, we can also specify atest condition.

This plot uses a conditional value definition value to use a black label for a light background.

The next plot uses a conditional value definition to color data points with null values in grey. Note that if the “else” case value is not specified, default mark color will be applied.