Поле labels: включение и отключение

Поле labels в спецификациях Vega-Lite и Vega относится к одному из ключевых механизмов управления текстовыми подписями на визуализациях: отображением значений данных, подписей осей, легенд и аннотаций. Архитектура системы не сводит labels к единственному полю данных, а распределяет управление ими между несколькими слоями: mark properties, encoding channels, axis/legend configuration и transform-проекциями.

В Vega-Lite отсутствует единое универсальное поле labels, как в некоторых высокоуровневых библиотеках визуализации. Вместо этого используется концептуальная модель:

  • labels как результат encoding (например, text)
  • labels как часть axis configuration
  • labels как часть legend configuration
  • labels как самостоятельные текстовые marks

Такое разделение позволяет независимо управлять различными типами подписей без конфликта между слоями визуализации.

Подписи данных (data labels) через mark text

Основной способ включения labels, привязанных к данным, реализуется через mark text.

{
  "mark": "text",
  "encoding": {
    "x": {"field": "x", "type": "quantitative"},
    "y": {"field": "y", "type": "quantitative"},
    "text": {"field": "value", "type": "quantitative"}
  }
}

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

Включение labels

Включение достигается добавлением encoding:

  • text → активирует отображение
  • отсутствие text → labels не создаются
"text": {"field": "name"}

Отключение labels

Отключение достигается удалением encoding или заменой на null-поведение через transform:

{
  "mark": "text",
  "encoding": {
    "text": null
  }
}

или полным удалением канала:

{
  "mark": "point",
  "encoding": {
    "x": {"field": "x", "type": "quantitative"},
    "y": {"field": "y", "type": "quantitative"}
  }
}

В этом случае labels отсутствуют полностью, поскольку нет текстового mark.

Axis labels: управление подписями осей

Axis labels представляют отдельный уровень системы и управляются через axis.labels.

Включение axis labels

По умолчанию оси отображают подписи автоматически, если ось активна:

{
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}

Явное включение:

"axis": {
  "labels": true
}

Отключение axis labels

Отключение выполняется через флаг labels: false:

{
  "encoding": {
    "x": {
      "field": "category",
      "type": "nominal",
      "axis": {
        "labels": false
      }
    }
  }
}

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

Контроль поведения labels на осях

Axis labels также поддерживают:

  • labelAngle
  • labelLimit
  • labelOverlap
  • labelColor
  • labelFontSize

Эти параметры не включают и не выключают labels напрямую, но регулируют их отображение и читаемость.

Legend labels: подписи категорий

Legend labels управляются через legend.label* параметры.

Включение legend labels

По умолчанию legend отображает labels, если есть категориальная шкала:

{
  "mark": "point",
  "encoding": {
    "color": {"field": "type", "type": "nominal"}
  }
}

Отключение legend labels

Отключение выполняется через:

"legend": {
  "labelFontSize": 0
}

или более корректно:

"legend": null

Полное отключение legend убирает и labels, и сам блок легенды.

Частичное управление labels легенды

  • labelExpr — трансформация текста
  • labelLimit — обрезка
  • labelFont — типографика

Conditional labels (условное отображение)

Labels могут быть включены или отключены динамически через condition.

"text": {
  "condition": {
    "test": "datum.value > 10",
    "value": "datum.value"
  },
  "value": null
}

В этом случае:

  • labels появляются только при выполнении условия
  • иначе отключаются (становятся null)

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

Отключение labels через opacity и size

Хотя формально labels не выключаются через эти параметры, часто используется визуальное подавление:

"mark": {
  "type": "text",
  "opacity": 0
}

или:

"fontSize": 0

Такой подход сохраняет структуру данных, но убирает визуальное представление.

Labels и transform-слой

В Vega-Lite трансформации могут влиять на labels косвенно:

  • calculate → формирует текст
  • filter → удаляет элементы с labels
  • aggregate → изменяет плотность подписей

Пример генерации labels через вычисление:

"transform": [
  {
    "calculate": "datum.value + ' units'",
    "as": "labelText"
  }
],
"encoding": {
  "text": {"field": "labelText"}
}

Vega: низкоуровневое управление labels

В Vega labels представлены через mark definitions:

{
  "type": "text",
  "encode": {
    "enter": {
      "text": {"field": "value"},
      "x": {"field": "x"},
      "y": {"field": "y"}
    }
  }
}

Отключение:

  • удаление text encode
  • или использование пустого значения
"text": {"value": ""}

Vega предоставляет более точный контроль, но требует явного описания каждого слоя.

Различие между Vega и Vega-Lite в управлении labels

Аспект Vega-Lite Vega
Уровень абстракции высокий низкий
labels как поле через encoding через mark encode
авто-оси labels есть нет
отключение labels axis.labels: false ручное удаление
гибкость ограниченная максимальная

Производительность labels при плотных данных

При большом количестве точек labels становятся фактором деградации производительности:

  • увеличивается DOM-дерево (SVG)
  • растёт количество текстовых узлов
  • ухудшается рендеринг при overlap

Типовые стратегии отключения:

  • axis.labels: false
  • использование sampling трансформаций
  • агрегация данных перед отображением labels
  • замена text marks на tooltips

Взаимодействие labels с tooltips

Labels часто заменяются tooltip-слоем:

"encoding": {
  "tooltip": [
    {"field": "name"},
    {"field": "value"}
  ]
}

В этом случае:

  • labels отключаются
  • данные доступны только при наведении
  • визуальная плотность уменьшается

Итоговая модель управления labels

Механизм labels в Vega/Vega-Lite представляет многослойную систему:

  • data labels через text encoding
  • axis labels через axis.labels
  • legend labels через legend.label*
  • conditional labels через condition
  • programmatic labels через transforms

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

Оглавление