Condition

Edit this page

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 fall within a selection.

There are two ways to use the condition property:

1) Combining one conditional field definition with one base value definition.

2) Combining one or more conditional value with a field definition or a value definition.

Conditional Field Definition

// Specification of a Single View
{
  ...,
  "encoding": {           // Encoding
    ...: {
      "condition": {      // Conditional rule for data inside the selection
        // Selection name
        "selection": ...,
        // Field definition if the data is included in the selection (if)
        "field": ..., "type": "quantitative"
      },
      "value": ...        // The encoding value set for data outside the selection (else)
    },
    ...
  },
  ...
}

A conditional field definition uses a data-driven encoding rule when marks fall within a selection, and a value encoding otherwise. As shown in the table below, the full gamut of encoding properties including transformation functions (aggregate, bin, timeUnit) as well as scale and legend are available here.

Property Type Description
selection String | Object

Required. A selection name, or a series of composed selections.

field String | RepeatRef

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.

Note: 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.

Note: field is not required if aggregate is count.

type Type

Required. The encoded field’s type of measurement ("quantitative", "temporal", "ordinal", or "nominal").

bin Boolean | BinParams

A flag for binning a quantitative field, or an object defining binning parameters. If true, default binning parameters will be applied.

Default value: false

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)

aggregate Aggregate

Aggregation function for the field (e.g., mean, sum, median, min, max, count).

Default value: undefined (None)

scale Scale

An object defining properties of the channel’s scale, which is the function that transforms values in the data domain (numbers, dates, strings, etc) to visual values (pixels, colors, sizes) of the encoding channels.

Default value: If undefined, default scale properties are applied.

legend Legend | Null

An object defining properties of the legend. If null, the legend for the encoding channel will be removed.

Default value: If undefined, default legend properties are applied.

For example, in the following visualization, 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 a value may be specified as the else (outer) branch.

Conditional Value Definition

// Specification of a Single View
{
  ...,
  "encoding": {           // Encoding
    ...: {
      "condition": {      // Conditional rule for data inside the selection
        "selection": ..., // Selection name
        "value": ...      // Value if the data is included in the selection (if)
      },
      ... // A field definition or a value definition for data outside the selection (else)
    },
    ...
  },
  ...
}

A condition value definition uses a value encoding when data fall within a selection. When data lie outside a selection, either a value or field encoding may be used.

Property Type Description
selection String | Object

Required. A selection name, or a series of composed selections.

value Number | String | Boolean

Required. A constant value in visual domain (e.g., "red" / “#0099ff” for color, values between 0 to 1 for opacity).

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, all marks are initially colored grey. This is because empty selections are treated as containing all data values.