Структура Vega-спецификации

Vega представляет собой декларативную систему описания визуализаций данных, где график задаётся не императивным кодом, а структурированным JSON-описанием. Центральным элементом является спецификация (specification) — объект, который полностью определяет данные, преобразования, масштабирование, визуальные примитивы и интерактивное поведение.

Общая форма спецификации

Базовая структура Vega-спецификации строится вокруг нескольких ключевых блоков:

  • "$schema" — версия схемы Vega
  • "description" — текстовое описание визуализации
  • "width" и "height" — размеры холста
  • "padding" — внутренние отступы
  • "data" — источники данных
  • "scales" — преобразование данных в визуальные координаты
  • "axes" — оси координат
  • "marks" — графические примитивы
  • "signals" — реактивные переменные (интерактивность)
  • "legends" — легенды
  • "projections" — географические проекции (для карт)

Минимальный пример структуры:

{
  "$schema": "https://vega.github.io/schema/vega/v5.json",
  "width": 400,
  "height": 200,
  "data": [
    {
      "name": "table",
      "values": [
        {"x": 1, "y": 28},
        {"x": 2, "y": 55}
      ]
    }
  ],
  "scales": [],
  "marks": []
}

Даже минимальная спецификация уже требует определения данных и области отрисовки, но без масштабов и marks визуализация остаётся пустой.

Блок data: источник данных и этапы подготовки

Структура данных

Блок data представляет собой массив источников. Каждый источник — независимый поток данных, который может:

  • загружаться из внешних файлов
  • формироваться встроенно
  • вычисляться из других источников
  • трансформироваться через pipeline
{
  "data": [
    {
      "name": "sales",
      "url": "data/sales.json",
      "format": {"type": "json"}
    }
  ]
}

Встроенные данные

{
  "name": "inline",
  "values": [
    {"category": "A", "value": 30},
    {"category": "B", "value": 80}
  ]
}

Трансформации данных

Одной из ключевых особенностей Vega является система transform. Она позволяет описывать обработку данных прямо внутри спецификации.

Основные типы трансформаций:

  • filter — фильтрация
  • calculate — вычисляемые поля
  • aggregate — агрегация
  • bin — разбиение числовых диапазонов
  • sort — сортировка
  • stack — стековые диаграммы
  • fold / pivot — преобразование структуры

Пример вычисляемого поля:

{
  "data": [
    {
      "name": "table",
      "values": [
        {"x": 1, "y": 2},
        {"x": 2, "y": 3}
      ],
      "transform": [
        {
          "type": "formula",
          "as": "y2",
          "expr": "datum.y * 10"
        }
      ]
    }
  ]
}

Агрегация

{
  "type": "aggregate",
  "groupby": ["category"],
  "fields": ["value"],
  "ops": ["sum"],
  "as": ["total"]
}

Агрегация формирует новые наборы данных, которые далее используются в масштабах и marks.

Блок scales: преобразование данных в визуальные координаты

Scales — один из центральных механизмов Vega. Он связывает абстрактные данные с визуальным представлением.

Структура scale

{
  "scales": [
    {
      "name": "xscale",
      "type": "band",
      "domain": {"data": "table", "field": "category"},
      "range": "width"
    }
  ]
}

Основные типы шкал

  • linear — линейное отображение
  • log — логарифмическая шкала
  • band — категориальные полосы
  • point — дискретные точки
  • time — временные шкалы
  • ordinal — категориальные значения

Domain и Range

  • domain — входные значения (данные)
  • range — выходные значения (экранные координаты)

Пример числовой шкалы:

{
  "name": "yscale",
  "type": "linear",
  "domain": {"data": "table", "field": "value"},
  "range": "height"
}

Поддержка динамических доменов

Domain может вычисляться динамически:

  • от фильтрованных данных
  • от агрегированных значений
  • от сигналов (signals)

Блок axes: координатные оси

Axes отображают визуальную интерпретацию шкал.

{
  "axes": [
    {
      "orient": "bottom",
      "scale": "xscale"
    },
    {
      "orient": "left",
      "scale": "yscale"
    }
  ]
}

Параметры осей

  • orient — расположение (top, bottom, left, right)
  • scale — связанная шкала
  • title — подпись оси
  • grid — отображение сетки
  • tickCount — количество делений

Axes в Vega не являются обязательными, но критичны для интерпретируемых графиков.

Блок marks: графические примитивы

Marks — основной визуальный слой Vega. Именно здесь определяется, как данные превращаются в графические элементы.

Типы marks

  • rect — прямоугольники
  • symbol — точки/символы
  • line — линии
  • area — области
  • text — текст
  • group — контейнеры

Базовая структура mark

{
  "marks": [
    {
      "type": "rect",
      "from": {"data": "table"},
      "encode": {
        "enter": {
          "x": {"scale": "xscale", "field": "category"},
          "y": {"scale": "yscale", "field": "value"},
          "width": {"scale": "xscale", "band": 1},
          "height": {"value": 20}
        }
      }
    }
  ]
}

Encode: реактивное описание визуальных свойств

encode делится на три стадии:

  • enter — начальное создание
  • update — обновление
  • exit — удаление

Пример обновления цвета:

"update": {
  "fill": {"value": "steelblue"}
}

Привязка к данным

Каждый mark может использовать:

  • from.data — источник данных
  • transform — локальные преобразования
  • group — вложенные структуры

Блок signals: реактивная система

Signals — механизм реактивного управления состоянием визуализации.

Пример сигнала

{
  "signals": [
    {
      "name": "threshold",
      "value": 50
    }
  ]
}

Использование сигналов

Signals могут:

  • управлять шкалами
  • изменять фильтрацию данных
  • реагировать на события мыши
  • управлять параметрами marks

Пример привязки к encode:

"opacity": {
  "signal": "threshold > datum.value ? 1 : 0.3"
}

Интерактивные события

Signals могут обновляться событиями:

{
  "name": "hovered",
  "on": [
    {
      "events": "rect:mouseover",
      "update": "datum"
    }
  ]
}

Блок legends: легенды визуализации

Legends связывают визуальные переменные с категориями данных.

{
  "legends": [
    {
      "fill": "colorScale",
      "title": "Категории"
    }
  ]
}

Типы легенд

  • цветовые
  • размерные
  • символические

Legend автоматически извлекает domain шкалы и отображает соответствия.

Блок projections: географические преобразования

Используется при создании карт.

{
  "projections": [
    {
      "name": "projection",
      "type": "mercator"
    }
  ]
}

Основные типы

  • mercator
  • equirectangular
  • orthographic

Projections применяются к геоданным и связываются с path marks.

Иерархическая структура спецификации

Vega-спецификация строится как система взаимосвязанных уровней:

  1. Data layer — источники и трансформации
  2. Scale layer — преобразование значений
  3. Layout layer — размеры и координаты
  4. Mark layer — визуальные элементы
  5. Interaction layer — signals и события

Эта структура обеспечивает строгую декларативную модель, в которой каждый уровень зависит от предыдущего, но не нарушает его инкапсуляцию.

Связи между блоками

Ключевая особенность Vega — явные связи:

  • data → scale (домен шкал строится из данных)
  • scale → marks (визуализация опирается на шкалы)
  • signals → data/scales/marks (динамическое управление)
  • marks → legends (автоматическая генерация легенд)

Эти связи формируют граф зависимостей, который Vega использует для реактивного обновления визуализации.

Декларативная модель как система описания графа вычислений

Vega-спецификация фактически является описанием направленного графа вычислений, где:

  • узлы — данные, сигналы, шкалы и marks
  • рёбра — зависимости между ними
  • обновления — реактивные пересчёты

Это позволяет системе:

  • минимизировать перерисовки
  • изолировать изменения
  • обеспечивать предсказуемое поведение визуализации
Оглавление