Поле labels и labelExpr

В Vega-Lite термин «labels» не является единым универсальным полем с фиксированной структурой во всех контекстах. Вместо этого он проявляется через несколько механизмов отображения текстовых подписей: оси (axis labels), легенды (legend labels), подписи точек (text marks) и аннотации. Общая концепция заключается в управлении текстовыми представлениями данных и метаданных визуализации через декларативные правила.

На уровне спецификации Vega-Lite ключевую роль играют следующие сущности:

  • подписи осей (axis.label)
  • подписи легенд (legend.label)
  • текстовые метки данных (mark: "text" + encoding)
  • форматирование через выражения (labelExpr)

Подписи осей и их структура

Подписи осей формируются автоматически на основе шкалы, но могут быть переопределены через параметры оси:

{
  "mark": "point",
  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "y", "type": "quantitative" }
  },
  "encoding": {
    "x": {
      "field": "x",
      "type": "quantitative",
      "axis": {
        "labelAngle": -45,
        "labelFontSize": 12
      }
    }
  }
}

Ключевые параметры label-уровня осей:

  • labelAngle — поворот текста
  • labelFontSize — размер шрифта
  • labelColor — цвет
  • labelAlign, labelBaseline — выравнивание
  • format — формат числовых значений

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

Легенды и labels в legend

Легенды в Vega-Lite используют отдельную подсистему отображения подписей:

{
  "mark": "circle",
  "encoding": {
    "color": {
      "field": "category",
      "type": "nominal",
      "legend": {
        "title": "Категории",
        "labelFontSize": 11,
        "labelLimit": 120
      }
    }
  }
}

Параметры легенды:

  • title — заголовок легенды
  • labelLimit — ограничение длины текста с обрезкой
  • labelExpr — выражение для динамического формирования текста
  • format — форматирование значений

Легенды тесно связаны с доменом шкалы (scale domain), поэтому labels в этом контексте всегда производны от значений данных.

Текстовые метки как основной механизм labels

Наиболее гибкая форма labels реализуется через mark "text":

{
  "data": { "values": [
    { "x": 1, "y": 10, "label": "A" },
    { "x": 2, "y": 20, "label": "B" }
  ]},
  "mark": "text",
  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "y", "type": "quantitative" },
    "text": { "field": "label" }
  }
}

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

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

  • align, baseline — позиционирование текста
  • dx, dy — смещение
  • fontSize, fontWeight, color
  • limit — обрезка текста

Поле labelExpr и выражения Vega

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

Пример в axis:

{
  "mark": "bar",
  "encoding": {
    "x": { "field": "value", "type": "quantitative" }
  },
  "encoding": {
    "x": {
      "field": "value",
      "type": "quantitative",
      "axis": {
        "labelExpr": "datum.value + ' ед.'"
      }
    }
  }
}

Здесь datum.value представляет значение тика оси.

Логика выражений labelExpr

Expression language Vega поддерживает:

  • арифметику
  • строковую конкатенацию
  • условные выражения
  • доступ к данным через datum
  • встроенные функции форматирования

Пример условного labelExpr:

{
  "axis": {
    "labelExpr": "datum.value > 100 ? 'Высокое: ' + datum.value : datum.value"
  }
}

Это позволяет формировать семантически насыщенные подписи без изменения исходных данных.

labelExpr в легендах

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

{
  "encoding": {
    "color": {
      "field": "type",
      "type": "nominal",
      "legend": {
        "labelExpr": "'Тип: ' + datum.value"
      }
    }
  }
}

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

Ограничения labelExpr

Несмотря на гибкость, expression-based labels имеют ограничения:

  • отсутствие доступа к внешним API
  • невозможность выполнения асинхронных операций
  • ограниченный набор функций Vega expression runtime
  • невозможность модификации структуры данных

Выражения работают только в контексте рендеринга, не влияя на исходный dataset.

Связь labels с масштабами и форматированием

В Vega-Lite labels часто зависят от scale transformation:

  • числовые значения проходят через scale
  • даты форматируются через time-scale
  • категории отображаются напрямую или через labelExpr

Пример форматирования дат:

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

При этом format является статическим механизмом, тогда как labelExpr позволяет реализовать динамическую логику:

{
  "axis": {
    "labelExpr": "timeFormat(datum.value, '%Y-%m')"
  }
}

Приоритеты отображения labels

При конфликте различных механизмов применяется следующий приоритет:

  1. labelExpr (если задан)
  2. format
  3. автоматическое форматирование Vega-Lite

Это важно при комбинировании нескольких уровней конфигурации.

Применение labels в комплексных визуализациях

В составных графиках (facet, repeat, concat) labels могут наследоваться и переопределяться на каждом уровне:

{
  "facet": {
    "row": {
      "field": "region",
      "type": "nominal",
      "header": {
        "labelExpr": "'Регион: ' + datum.value"
      }
    }
  }
}

Здесь labels применяются к заголовкам фасетов, а не к осям или данным напрямую.

Семантика labels в архитектуре Vega-Lite

Модель отображения labels строится как слой поверх:

  • данных (data)
  • шкал (scales)
  • осей и легенд (axes/legends)
  • mark-сущностей

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

Оглавление