How to Use Conditional Encoding in Vega-Lite

Conditional encoding in Vega-Lite allows you to add dynamism to your data visualizations. Ever wanted certain elements to change color, size, or appearance based on specific conditions? This guide will show you how to achieve that!

What is Conditional Encoding?

Conditional encoding enables you to determine how elements in your chart are styled based on whether particular data meets defined conditions. For instance, you can highlight data points that fall within a certain range or satisfy a specific condition.

Here's a quick look at the structure:

{
  ...,
  "mark": ...,
  "encoding": {
    ...: {
      "condition": {
        "param": ..., // Parameter name or test predicate
        "field": ..., // Field or value if the condition is satisfied
        "type": ..., 
        ...
      },
      "value": ..., // Else case if the condition is NOT satisfied
      ...
    },
    ...
  },
  ...
}

How to Use Conditional Encoding

1. Using a param Name

Let's start with how to specify the condition using a param name.

{
  "condition": {
    "param": "...", // Name of the parameter
    "field": "...", // Field if parameter is satisfied
    "type": "...", 
  },
  "value": "..." // (Optional) Else-case (value if the parameter is NOT satisfied)
}

2. Using a test Predicate

Alternatively, you can use a test predicate.

{
  "condition": {
    "test": "datum.property === value", // Logical condition
    "field": "...",
    "type": "..."
  },
  "value": "..." // (Optional) Else-case
}

Examples and Applications

Conditional Field Definition

Here's an example where the color of rect marks changes based on a condition:

{
  "mark": "rect",
  "encoding": {
    "color": {
      "condition": {
        "param": "brush",
        "field": "count",
        "type": "quantitative"
      },
      "value": "grey"
    }
  }
}

Drag to select a region on the graph, and you'll see that the rect marks within the selection change color based on their aggregated count, while those outside remain grey.

Conditional Value Definition

In this example, marks within a selected interval become larger:

{
  "mark": "point",
  "encoding": {
    "size": {
      "condition": {
        "param": "brush",
        "value": 300
      },
      "field": "size",
      "type": "quantitative"
    }
  }
}

Marks within the dragged interval will be significantly larger than those outside it.

FAQ

1. What is Conditional Encoding used for?

Conditional encoding is used to dynamically change the appearance of chart elements based on specific conditions. This makes the visualization more interactive and informative.

2. Can I use multiple conditions?

Yes, you can combine multiple conditions using logical operators within a test predicate. For example:

"test": "datum.category === 'A' && datum.value > 10"

3. What are some common conditions?

Common conditions involve checking if data points fall within a particular range, belong to a specific category, or meet specific logical criteria.

By integrating conditional encoding into your Vega-Lite visualizations, you can create more dynamic and interactive data stories. Start experimenting now!