Поле values: явные позиции делений

В Vega-Lite контроль расположения делений (ticks) на осях выполняется через конфигурацию шкалы (scale) и оси (axis). Одним из наиболее прямых способов задания фиксированных позиций является использование поля values, которое переопределяет автоматическую генерацию делений и задаёт их явно.

Поле values применяется внутри описания оси и влияет только на отображаемые метки (ticks) и подписи, не меняя исходные данные и не вмешиваясь в вычисление шкалы, если диапазон значений позволяет их отобразить.

По умолчанию Vega-Lite использует алгоритм автоматического выбора «красивых» значений делений. Этот алгоритм учитывает диапазон данных, тип шкалы (linear, log, time), размер графика и плотность меток. При использовании values этот механизм частично или полностью отключается: система перестаёт подбирать деления самостоятельно и использует строго заданный набор.

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

Базовая структура применения values

{
  "mark": "line",
  "encoding": {
    "x": {
      "field": "x",
      "type": "quantitative",
      "axis": {
        "values": [0, 10, 20, 30, 40]
      }
    },
    "y": {
      "field": "y",
      "type": "quantitative"
    }
  }
}

В этом примере ось X получает строго заданные позиции делений. Автоматическое распределение отключается, а подписи появляются только в точках 0, 10, 20, 30 и 40.

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

Поле values поддерживает разные типы данных в зависимости от типа шкалы:

Числовые значения

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

"values": [0, 5, 10, 15, 20]

Такая форма наиболее распространена и применяется в линейных шкалах.

Временные значения

Для временных шкал используются строки в формате даты или объекты даты:

"values": [
  "2024-01-01",
  "2024-02-01",
  "2024-03-01"
]

или

"values": [
  {"year": 2024, "month": 0, "date": 1},
  {"year": 2024, "month": 1, "date": 1}
]

Vega-Lite интерпретирует такие значения через стандартный парсер времени Vega.

Категориальные значения

Для ordinal-шкал values может задавать конкретный порядок категорий:

"values": ["низкий", "средний", "высокий"]

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

Влияние values на масштабирование оси

При использовании values поведение шкалы изменяется следующим образом:

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

Важно учитывать, что values не является заменой domain. Если требуется ограничить диапазон данных, используется:

"scale": {
  "domain": [0, 50]
}

Поле values лишь управляет отображаемыми метками внутри этого диапазона.

Сочетание values и tickCount

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

"axis": {
  "tickCount": 10,
  "values": [0, 25, 50, 75, 100]
}

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

Использование с дробными и неравномерными шкалами

При работе с неравномерными данными values позволяет вручную задать «контрольные точки» визуализации:

"values": [0, 1, 1.5, 3, 7, 12, 20]

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

Временные оси и контроль ключевых дат

Временные шкалы часто требуют выделения конкретных дат, например:

"axis": {
  "values": [
    "2020-01-01",
    "2020-03-01",
    "2020-06-01",
    "2020-12-01"
  ]
}

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

При этом Vega-Lite автоматически нормализует даты к внутреннему представлению времени Vega, что позволяет корректно отрисовывать даже при смене часового пояса.

Конфликты с форматированием оси

При явном задании values форматирование меток через labelExpr или format продолжает применяться к каждому значению:

"axis": {
  "values": [1000, 2000, 3000],
  "labelExpr": "datum.value / 1000 + 'K'"
}

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

Поведение при выходе за пределы данных

Если values содержит элементы, которые не попадают в текущий domain шкалы, поведение зависит от конфигурации:

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

Пример:

"scale": {
  "domain": [0, 50]
},
"axis": {
  "values": [0, 25, 50, 75, 100]
}

Здесь 75 и 100 будут отброшены.

Практика использования в аналитических графиках

Явные деления применяются в случаях, когда требуется:

  • выделение нормативных порогов (например, 60%, 80%, 95%);
  • фиксация бизнес-метрик (целевые значения продаж);
  • синхронизация нескольких графиков по общей шкале;
  • визуальное выравнивание контрольных точек между разными визуализациями.

Комбинация с multiple axes

При наличии нескольких слоёв или осей values часто используется для унификации:

"axis": {
  "values": [0, 50, 100]
}

Обе оси могут быть приведены к единому набору делений, что упрощает сравнение графиков.

Особенности поведения в логарифмических шкалах

В log-scale values интерпретируются как уже преобразованные значения, но фактически отображаются через логарифмическое преобразование шкалы:

"scale": {
  "type": "log"
},
"axis": {
  "values": [1, 10, 100, 1000]
}

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

Взаимодействие с grid lines

Сетка (grid) также следует значениям values, если она привязана к оси:

  • линии сетки совпадают с tick-позициями;
  • дополнительная интерполяция не выполняется;
  • плотность сетки полностью контролируется вручную.

Это важно при создании технических графиков, где требуется строгая привязка к дискретным уровням.

Ограничения использования values

Несмотря на гибкость, существуют ограничения:

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

Поле values остаётся инструментом ручного контроля, а не автоматической оптимизации, и применяется там, где важна точная структура оси, а не адаптивность.

Оглавление