Поле bandPosition

Назначение и семантика

bandPosition — параметр шкалы (scale) в Vega и Vega-Lite, определяющий относительное положение визуального элемента внутри диапазона (band) для дискретных шкал типа band, point и производных.

Шкала типа band делит доступное пространство оси на равные сегменты, соответствующие категориям. Каждый сегмент (band) имеет внутреннюю область, и bandPosition управляет тем, в какой точке этого сегмента будут размещаться графические примитивы, привязанные к шкале.

Ключевая характеристика:

  • значение задаётся в диапазоне от 0 до 1
  • определяет нормализованную позицию внутри band
  • влияет на визуальное смещение элементов (bars, rules, points)

Модель распределения band-шкалы

Для шкалы типа band каждая категория отображается как интервал:

|------ band 1 ------|------ band 2 ------|------ band 3 ------|

Каждый band имеет локальную систему координат:

  • 0 — начало интервала
  • 1 — конец интервала

bandPosition задаёт точку внутри этого интервала:

  • 0 — начало band
  • 0.5 — центр band
  • 1 — конец band

Математическая интерпретация

Если:

  • i — индекс категории
  • bandWidth — ширина одного band
  • step — шаг шкалы
  • bp — bandPosition

то позиция элемента вычисляется как:

x = scale(i) + bp * bandWidth

где scale(i) — начало соответствующего band.

Поведение по умолчанию

В Vega и Vega-Lite значение по умолчанию:

bandPosition = 0.5

Это означает центрирование элементов внутри band.

Такое поведение используется для:

  • точечных маркеров поверх категорий
  • линий (rule), проходящих через центр категории
  • симметричных визуализаций

Влияние на различные типы mark

Bar (столбчатые диаграммы)

Для bar-графиков bandPosition влияет на горизонтальное или вертикальное смещение полосы внутри категории.

Пример эффекта:

  • 0 — бар прижат к началу категории
  • 0.5 — бар центрирован
  • 1 — бар прижат к концу категории
{
  "mark": "bar",
  "encoding": {
    "x": { "field": "category", "type": "ordinal", "axis": { "labelAngle": 0 } },
    "y": { "field": "value", "type": "quantitative" }
  },
  "config": {
    "scale": {
      "bandPosition": 0
    }
  }
}
Tick и Rule marks

Для tick и rule значение bandPosition критично, поскольку эти элементы не заполняют весь band, а обозначают конкретную точку.

  • rule часто используется для средних значений или осевых линий
  • tick — для отметок внутри категорий
{
  "mark": "tick",
  "encoding": {
    "x": { "field": "category", "type": "ordinal" },
    "y": { "field": "value", "type": "quantitative" }
  },
  "config": {
    "scale": {
      "bandPosition": 0.5
    }
  }
}
Point marks

Для точечных диаграмм bandPosition определяет, где именно внутри категории располагается точка.

При bandPosition = 0.5 достигается визуальная центровка и симметрия распределения.

Связь с paddingInner и paddingOuter

bandPosition тесно связан с параметрами:

  • paddingInner
  • paddingOuter

Эти параметры изменяют размер band и отступы между ними, а bandPosition определяет локальное положение внутри уже скорректированного band.

Иерархия вычисления:

  1. вычисляется доступное пространство
  2. применяется padding
  3. формируются band-интервалы
  4. внутри band применяется bandPosition

Различие bandPosition и align

В Vega часто встречается параметр align, особенно в scale конфигурациях.

  • align влияет на распределение band относительно всей оси
  • bandPosition влияет на позицию внутри каждого band

Сравнение:

Параметр Область действия Эффект
align вся шкала сдвиг всех band
bandPosition отдельный band позиция внутри band

Использование в Vega-Lite конфигурации

В Vega-Lite bandPosition задаётся через config.scale.

{
  "data": {
    "values": [
      { "category": "A", "value": 28 },
      { "category": "B", "value": 55 },
      { "category": "C", "value": 43 }
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": { "field": "category", "type": "ordinal" },
    "y": { "field": "value", "type": "quantitative" }
  },
  "config": {
    "scale": {
      "bandPosition": 0.2
    }
  }
}

При таком значении все бары смещаются к началу категориального интервала.

Применение в комбинированных графиках

В сложных визуализациях, где на одной оси находятся несколько типов mark, bandPosition используется для выравнивания:

  • bar + line
  • bar + point overlay
  • stacked annotations

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

  • бары занимают весь band
  • линия проходит через центр (0.5)
  • точки смещаются к верхней границе (1 или 0)

Взаимодействие с шириной элементов

Для band scale ширина элемента часто определяется автоматически:

mark.width ≈ bandWidth

При этом bandPosition не изменяет ширину, а только смещает anchor point.

Следствие:

  • визуальный размер сохраняется
  • изменяется только точка привязки

Особенности при использовании point scale

Для point scale (где нет ширины band как интервала), bandPosition интерпретируется как дополнительный offset внутри шага между точками.

Это делает поведение менее очевидным:

  • при 0.5 точки равномерно центрированы
  • при крайних значениях возникает визуальный сдвиг всего ряда

Практическое влияние на оси

При использовании категориальной оси:

  • подписи оси не изменяют позицию band
  • bandPosition влияет только на marks
  • axis ticks остаются привязанными к центру band по умолчанию

Это приводит к необходимости согласованной настройки:

  • marks
  • axis
  • grid lines

Влияние на grid и reference lines

Grid линии и reference rules часто используют шкалу с bandPosition = 0.5, чтобы:

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

При изменении bandPosition может возникать:

  • смещение визуального центра графика
  • несоответствие между grid и marks

Поведение при stacked визуализациях

В stacked bar charts bandPosition влияет только на горизонтальное положение всей стопки внутри band, но не изменяет внутреннюю структуру stacking.

Это означает:

  • stacking вычисляется до bandPosition
  • bandPosition применяется после

Взаимодействие с discrete scales

Для всех дискретных шкал:

  • band
  • point
  • ordinal (через band internally)

bandPosition является универсальным механизмом тонкой настройки визуального выравнивания.

Типичные значения и их визуальный эффект

Значение Поведение
0 прижатие к началу band
0.25 лёгкий сдвиг к началу
0.5 центрирование
0.75 сдвиг к концу
1 прижатие к концу band

Ограничения и нюансы

  • не влияет на количественные шкалы
  • не изменяет domain или range
  • работает только в связке с band/point шкалами
  • может конфликтовать с ручным позиционированием mark.xOffset / yOffset

Поведение при responsive layout

При изменении размера контейнера:

  • bandWidth пересчитывается
  • bandPosition остаётся постоянным
  • абсолютный сдвиг меняется пропорционально

Это обеспечивает стабильность композиции при масштабировании визуализации.

Оглавление