Поле legends

В Vega-Lite легенды являются декларативным способом описания связи между визуальными каналами (цвет, форма, размер, прозрачность и др.) и исходными данными. В терминологии спецификации используется поле legend, которое настраивается внутри encoding для конкретного канала либо глобально через config.legend.

В контексте Vega-Lite легенда не является отдельным объектом интерфейса, а вычисляется автоматически на основе шкал (scales), типов данных и применённых трансформаций. В Vega легенды могут быть описаны более низкоуровнево, как часть системы guide components, но концептуально подход остаётся схожим: легенда отражает отображение данных на визуальные переменные.

Легенда связывает:

  • домен данных (значения в поле)
  • визуальное представление (цвет, форма, размер)
  • интерпретацию пользователем

В Vega-Lite легенда создаётся автоматически, если:

  • используется дискретное или непрерывное шкалирование
  • канал поддерживает отображение (color, size, shape, opacity, strokeWidth и др.)
  • не отключена явно через legend: null

Базовая структура легенды в encoding

Легенда задаётся внутри канала:

{
  "mark": "point",
  "encoding": {
    "color": {
      "field": "category",
      "type": "nominal",
      "legend": {
        "title": "Категория"
      }
    }
  }
}

Если legend не указан, Vega-Lite создаёт стандартную конфигурацию автоматически.

Отключение легенды

Легенда может быть полностью отключена:

"color": {
  "field": "type",
  "type": "nominal",
  "legend": null
}

Отключение применяется, когда:

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

Основные параметры legend

title

Заголовок легенды:

"legend": {
  "title": "Тип продукта"
}

При отсутствии title используется имя поля или шкалы.

orient

Определяет расположение:

  • "right" (по умолчанию)
  • "left"
  • "top"
  • "bottom"
"legend": {
  "orient": "bottom"
}

direction

Определяет направление элементов:

  • "vertical"
  • "horizontal"

format

Форматирование значений:

"legend": {
  "format": ".2f"
}

Используется d3-format синтаксис.

Легенды для дискретных шкал

Для nominal и ordinal типов данных легенда строится как список категорий.

Пример:

"color": {
  "field": "region",
  "type": "nominal",
  "legend": {
    "title": "Регион",
    "columns": 2
  }
}

Особенности:

  • каждая категория отображается отдельным символом
  • порядок может быть алфавитным или заданным scale domain
  • поддерживаются кастомные цвета и символы

Легенды для непрерывных шкал

Для quantitative данных легенда становится градиентной шкалой.

"color": {
  "field": "value",
  "type": "quantitative",
  "legend": {
    "title": "Значение"
  }
}

Виды:

  • линейный градиент
  • логарифмическая шкала (через scale)
  • бинированные легенды

Бинированные легенды

При использовании bin: true создаётся дискретизация:

"color": {
  "field": "age",
  "type": "quantitative",
  "bin": true,
  "legend": {
    "title": "Возраст (интервалы)"
  }
}

Результат — легенда интервалов вместо непрерывной шкалы.

Настройка символов легенды

Для каналов shape и color можно управлять отображением символов:

"legend": {
  "symbolType": "circle",
  "symbolSize": 100
}

Доступные параметры:

  • symbolType: форма маркера
  • symbolSize: размер
  • symbolStrokeWidth: толщина обводки

Многострочные и многоколоночные легенды

columns

"legend": {
  "columns": 3
}

Используется при большом количестве категорий.

labelLimit

Ограничение длины текста:

"legend": {
  "labelLimit": 120
}

Позиционирование и размеры

clipHeight

Ограничение высоты:

"legend": {
  "clipHeight": 80
}

Если элементов больше, появляется прокрутка или обрезка.

padding

Отступы между элементами легенды:

"legend": {
  "padding": 10
}

Управление текстом легенды

labelFont, labelFontSize

"legend": {
  "labelFontSize": 12,
  "labelFont": "Arial"
}

labelColor

"legend": {
  "labelColor": "#333"
}

Фильтрация и интерактивность

В Vega-Lite легенды могут быть интерактивными фильтрами:

"legend": {
  "bind": "legend"
}

При этом выбор значения в легенде может:

  • фильтровать данные
  • подсвечивать серии
  • изменять отображение других слоёв

Условные легенды

Легенда может быть динамической через condition:

"color": {
  "condition": {
    "test": "datum.value > 50",
    "value": "red"
  },
  "value": "blue",
  "legend": {
    "title": "Условная легенда"
  }
}

Легенды в многослойных визуализациях

В layered charts легенды могут:

  • объединяться автоматически
  • разделяться по resolve: legend
  • конфликтовать между слоями

Пример разрешения конфликтов:

"resolve": {
  "legend": {
    "color": "independent"
  }
}

Возможные режимы:

  • shared
  • independent

Глобальная конфигурация legend

Через config.legend задаются дефолты:

{
  "config": {
    "legend": {
      "titleFontSize": 14,
      "labelFontSize": 11,
      "symbolLimit": 50
    }
  }
}

Эти настройки применяются ко всем легендам, если не переопределены локально.

Связь legend и scale

Легенда напрямую зависит от шкалы:

  • scale.domain → значения легенды
  • scale.range → цвета/формы
  • scale.type → тип легенды (discrete / continuous)

Пример:

"color": {
  "field": "category",
  "type": "nominal",
  "scale": {
    "domain": ["A", "B", "C"],
    "range": ["red", "green", "blue"]
  },
  "legend": {
    "title": "Группа"
  }
}

Скрытые особенности поведения

  • legend может не появиться при отсутствии шкалы
  • агрегированные поля могут менять структуру легенды
  • трансформации (aggregate, stack) влияют на домен
  • пустые значения могут быть отображены как отдельная категория

Каналы, поддерживающие legend

Наиболее типичные:

  • color
  • opacity
  • size
  • shape
  • stroke
  • fill

Каждый канал может иметь собственную легенду или быть объединённым через scale.

Отличия Vega и Vega-Lite в работе с легендами

В Vega:

  • легенды описываются как отдельные legends
  • требуется ручное связывание с scale
  • больше контроля над layout

В Vega-Lite:

  • легенды генерируются автоматически
  • настройка осуществляется через encoding
  • минимизация ручной работы

Частые паттерны использования legend

Разделение по категориям

"color": {
  "field": "segment",
  "type": "nominal",
  "legend": {
    "title": "Сегмент рынка"
  }
}

Градиент значений

"color": {
  "field": "temperature",
  "type": "quantitative",
  "legend": {
    "title": "Температура (°C)"
  }
}

Размер как количественная метрика

"size": {
  "field": "population",
  "type": "quantitative",
  "legend": {
    "title": "Население"
  }
}
Оглавление