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": ...,
      ...
    },
    ...
  },
  ...
}

For mark property channels as well as text and tooltip channels, the condition property of their channel definitions can be used to determine encoding rules based on whether data values satisfy a parameter (e.g. fall withing a selection parameter) or satisfy a test predicate.

There are two ways to specify the condition:

(1) Specifying param name:

(2) Specifying a test predicate:

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

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

2. Combining one or more conditional 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 a parameter (e.g. fall within a selection 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 either a param name or a test predicate in addition to the encoded field name and its data type like a typical field definition. In addition, a condition field definition may contain other encoding properties including transformation functions (aggregate, bin, timeUnit) as well as scale and legend (for mark property channels) or format (for text and tooltip channels).

For example, in the following plot, the color of rect 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, only value or datum 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 a parameter (e.g. fall withing a selection 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 either a param name or a test predicate in addition to the encoded constant value 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 the rect marks to grey when they do not 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 specifying param name, we can also specify a test 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.