Введение в Vega-Lite

В этом уроке мы последовательно составим спецификацию диаграммы: зададим данные, выберем графические элементы, свяжем их свойства с полями данных, вычислим средние значения и настроим оформление. В конце разберём, как поместить готовую диаграмму на веб-страницу.

Рекомендуем проходить урок, постепенно создавая визуализацию в онлайн-редакторе Vega. Дополняйте спецификацию по мере чтения. Если результат отличается от ожидаемого, сравните свою спецификацию с примерами урока.

Содержание урока

Данные

Предположим, у нас есть таблица с категориальным полем a и числовым полем b:

a b
C 2
C 7
C 4
D 1
D 2
D 6
E 8
E 4
E 7

Каждую строку можно представить объектом в массиве JSON:

[
  {"a": "C", "b": 2},
  {"a": "C", "b": 7},
  {"a": "C", "b": 4},
  {"a": "D", "b": 1},
  {"a": "D", "b": 2},
  {"a": "D", "b": 6},
  {"a": "E", "b": 8},
  {"a": "E", "b": 4},
  {"a": "E", "b": 7}
]

Для визуализации в Vega-Lite добавим данные непосредственно в свойство data спецификации:

{
  "data": {
    "values": [
      {"a": "C", "b": 2},
      {"a": "C", "b": 7},
      {"a": "C", "b": 4},
      {"a": "D", "b": 1},
      {"a": "D", "b": 2},
      {"a": "D", "b": 6},
      {"a": "E", "b": 8},
      {"a": "E", "b": 4},
      {"a": "E", "b": 7}
    ]
  }
}

Свойство data задаёт источник данных. В этом примере данные встроены непосредственно через свойство values. Помимо встроенных данных, Vega-Lite поддерживает другие виды источников данных.

Графические элементы и кодирование

Данные есть, но мы ещё не указали, как их показать. Основа диаграммы — графический элемент, или mark. Его положение, размер и цвет могут зависеть от поля данных или быть постоянными.

Чтобы показать данные точками, зададим свойству mark значение point.

Кажется, что получилась одна точка. На самом деле Vega-Lite рисует точку для каждого объекта массива, но они перекрываются, поскольку положение каждой точки ещё не задано.

Чтобы разделить точки по категориям, свяжем поле a с каналом x в объекте encoding:

...
"encoding": {
  "x": {"field": "a", "type": "nominal"}
}
...

Объект encoding сопоставляет каналы кодирования (например, x и y) определениям полей данных. Определение канала описывает имя поля (field) и его тип данных (type). Здесь поле a сопоставлено каналу x — горизонтальному положению точек; тип nominal задан потому, что поле содержит категории. Подробнее см. документацию типов данных.

Vega-Lite автоматически добавляет ось с подписями категорий и заголовком. Но три точки каждой категории всё ещё перекрываются: пока задано только кодирование поля a.

Добавим поле b на ось y. Тип quantitative сообщает, что его значения числовые.

...
"y": {"field": "b", "type": "quantitative"}
...

Теперь видны исходные точки. Сетку на оси Y Vega-Lite добавил автоматически. О типах данных и каналах кодирования можно прочитать в справочнике.

Преобразование данных: агрегирование

Чтобы показать среднее значение b для каждой категории, добавим "aggregate": "average" к определению канала y. Например, для категории D среднее равно (1 + 2 + 6) / 3 = 3.

Мы вычислили агрегированные значения каждой категории и показали их точками. Обычно такие значения показывают столбчатой диаграммой. Для этого достаточно заменить тип графического элемента:

- "mark": "point"
+ "mark": "bar"

Числовые значения расположены на оси Y, поэтому столбцы вертикальны. Если поменять каналы X и Y местами, диаграмма станет горизонтальной.

Настройка оформления

Vega-Lite автоматически задаёт свойства оформления по умолчанию. Их можно изменить дополнительными свойствами. Например, чтобы заменить заголовок оси x «Среднее b» (Average of b) на «Среднее значение b» (Mean of b), задайте свойство title оси в канале x.

Публикация диаграммы на веб-странице

Мы познакомились с основными компонентами спецификации Vega-Lite. Теперь посмотрим, как опубликовать визуализацию.

Для встраивания Vega-Lite в веб-страницу можно использовать Vega-Embed. Например, создайте страницу со следующим содержимым:

<!doctype html>
<html>
  <head>
    <title>Столбчатая диаграмма Vega-Lite</title>
    <meta charset="utf-8" />

    <script src="https://cdn.jsdelivr.net/npm/vega@6.2.0"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-lite@6.4.3"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-embed@7.1.0"></script>

    <style media="screen">
      /* Добавить расстояние между ссылками Vega-Embed  */
      .vega-actions a {
        margin-right: 5px;
      }
    </style>
  </head>
  <body>
    <h1>Шаблон встраивания визуализации Vega-Lite</h1>
    <!-- Контейнер визуализации -->
    <div id="vis"></div>

    <script>
      // Присвоить спецификацию локальной переменной vlSpec.
      var vlSpec = {
        $schema: 'https://vega.github.io/schema/vega-lite/v6.json',
        data: {
          values: [
            {a: 'C', b: 2},
            {a: 'C', b: 7},
            {a: 'C', b: 4},
            {a: 'D', b: 1},
            {a: 'D', b: 2},
            {a: 'D', b: 6},
            {a: 'E', b: 8},
            {a: 'E', b: 4},
            {a: 'E', b: 7},
          ],
        },
        mark: 'bar',
        encoding: {
          y: {field: 'a', type: 'nominal'},
          x: {
            aggregate: 'average',
            field: 'b',
            type: 'quantitative',
            axis: {
              title: 'Среднее b',
            },
          },
        },
      };

      // Встроить визуализацию в контейнер с id `vis`
      vegaEmbed('#vis', vlSpec);
    </script>
  </body>
</html>

В этой странице зависимости Vega-Lite (Vega-Embed, Vega и Vega-Lite) сначала загружаются в элементе head. HTML-элемент div с id vis служит контейнером визуализации.

В JavaScript переменная vlSpec содержит спецификацию Vega-Lite в формате JSON. Метод vegaEmbed преобразует её в спецификацию Vega и вызывает среду выполнения Vega, чтобы показать диаграмму в контейнере div.

Если открыть страницу в браузере, появится столбчатая диаграмма, как на нашей демонстрационной странице. Также в оригинале доступен пример Vega-Lite Block, который можно скопировать и изменить.

Следующие шаги

Теперь вы можете создать сайт со встроенной спецификацией Vega-Lite. Чтобы узнать больше: