Поле legend в кодировании

Легенда в Vega и Vega-Lite является связующим звеном между визуальными каналами и семантическим значением данных. Она не отображает данные напрямую, а интерпретирует их отображение через шкалы (scales), обеспечивая обратное соответствие между визуальными переменными и исходными полями датасета.

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

Связь легенды с системой масштабирования

В Vega-Lite легенда всегда привязана к шкале (scale), которая участвует в кодировании одного из визуальных каналов:

color
opacity
size
shape
stroke
fill

Каждый из этих каналов может быть связан с полем данных через encoding, например:

{
  "mark": "circle",
  "encoding": {
    "color": {
      "field": "category",
      "type": "nominal"
    }
  }
}

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

Автоматическое создание легенды

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

используется дискретная шкала (nominal, ordinal)
канал поддерживает визуальную интерпретацию категорий
отсутствует явное отключение легенды

Пример отключения:

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

Структура объекта legend

Базовая структура legend в Vega-Lite:

"legend": {
  "title": "Категория",
  "orient": "right",
  "direction": "vertical"
}

Ключевые параметры:

title — заголовок легенды
orient — позиция (right, left, top, bottom)
direction — направление элементов (vertical, horizontal)
format — форматирование значений
labelColor — цвет текста меток
symbolType — тип маркера (circle, square, stroke)

Управление заголовком и форматированием

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

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

Заголовок может быть отключён:

"legend": {
  "title": null
}

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

Используется для числовых или временных шкал:

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

Для дат:

"legend": {
  "format": "%Y-%m"
}

Форматирование наследует правила d3-format и d3-time-format.

Расположение и ориентация легенды

Параметр orient определяет положение относительно графика:

right
left
top
bottom

Пример:

"legend": {
  "orient": "bottom"
}

В Vega-Lite расположение влияет на перераспределение пространства в layout-композиции.

Направление элементов легенды

Параметр direction управляет тем, как элементы легенды располагаются:

"legend": {
  "direction": "horizontal"
}

Типичные сценарии:

вертикальная легенда для категорий (по умолчанию)
горизонтальная легенда для компактных панелей

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

Тип маркера

"legend": {
  "symbolType": "square"
}

Поддерживаемые значения:

circle
square
triangle-up
stroke

Размер символов

"legend": {
  "symbolSize": 100
}

Цветовая настройка

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

Также доступны:

labelFont
labelFontSize
labelOpacity

Легенды для цветовых шкал

Дискретная шкала

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

Создаётся список значений с цветными маркерами.

Непрерывная шкала

Для количественных данных:

"color": {
  "field": "value",
  "type": "quantitative"
}

Легенда превращается в градиентную шкалу.

Градиентная легенда

Градиент отображается как непрерывная полоса:

"legend": {
  "gradientLength": 200,
  "gradientThickness": 10
}

Дополнительные параметры:

gradientDirection
tickCount
format

Управление отметками (ticks)

"legend": {
  "tickCount": 5
}

или более явно:

"legend": {
  "values": [0, 10, 20, 30, 40]
}

Позиционирование внутри Vega (низкоуровневая модель)

В Vega (не Vega-Lite) легенда описывается как отдельный компонент в блоке legends:

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

Здесь легенда напрямую связывается со шкалой scale.

Связь легенды с multiple scales

Один визуал может содержать несколько легенд:

"legends": [
  {
    "fill": "colorScale"
  },
  {
    "size": "sizeScale"
  }
]

Каждая легенда управляет своим каналом независимо.

Селективное отключение легенд

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

"encoding": {
  "color": {
    "field": "category",
    "legend": false
  }
}

Глобальное подавление возможно через:

"config": {
  "legend": {
    "disable": true
  }
}

Интерактивность легенды

Легенда может участвовать в интерактивных фильтрах:

"selection": {
  "sel": {
    "type": "multi",
    "fields": ["category"],
    "bind": "legend"
  }
}

При клике по элементу легенды происходит фильтрация данных.

Encode для кастомизации поведения

Vega-Lite позволяет переопределять поведение легенды через encode:

"legend": {
  "encode": {
    "labels": {
      "update": {
        "fontSize": {"value": 12}
      }
    }
  }
}

Возможные блоки:

labels
symbols
title

Легенды и порядок сортировки

"legend": {
  "sort": "ascending"
}

или пользовательский порядок:

"legend": {
  "sort": ["A", "B", "C"]
}

Сложные сценарии с трансформациями

При использовании transform легенда отражает уже преобразованные данные:

"transform": [
  {"calculate": "datum.value * 100", "as": "scaled"}
]

"encoding": {
  "color": {
    "field": "scaled",
    "type": "quantitative"
  }
}

Легенда автоматически адаптируется к новому диапазону значений.

Множественные легенды в одном графике

При комбинированном кодировании:

"encoding": {
  "color": {"field": "a", "type": "nominal"},
  "shape": {"field": "b", "type": "nominal"}
}

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

В фасетированных визуализациях:

легенда может дублироваться
может быть агрегирована на уровне верхнего слоя
может наследоваться от родительского spec

Конфликты легенды и layout

Если одновременно используются:

facet
title
legend.orient

может возникнуть перераспределение пространства, влияющее на:

ширину панели
высоту графика
размещение осей

Минимальная конфигурация легенды

"legend": true

означает использование поведения по умолчанию, без кастомизации.

Расширенные визуальные настройки