Поле format и formatType

Параметры format и formatType в Vega-Lite используются для управления отображением значений данных при их визуализации, прежде всего в текстовых каналах, подписях осей, tooltip и других местах, где требуется преобразование «сырых» значений в человекочитаемый вид. Эти параметры находятся на границе между моделью данных и представлением, опираясь на систему форматирования D3 и расширенные правила интерпретации типов.

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

  • числовые значения (округление, разделители тысяч, процентный вид)
  • временные значения (даты и время в различных локализациях и стилях)
  • строковые значения (как правило, без изменений, но с возможными шаблонами)
  • UTC-времена с фиксированным часовым поясом

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

  • text
  • tooltip
  • axis.label
  • legend.label
  • header.label

Свойство format

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

Для чисел используется синтаксис форматов D3 (d3-format), например:

  • .2f — фиксированное число с двумя знаками после запятой
  • , — разделитель тысяч
  • .1% — процентный формат
  • $.2f — формат валюты (при условии ручного добавления символа)

Пример числового форматирования:

{
  "mark": "text",
  "encoding": {
    "text": {
      "field": "value",
      "type": "quantitative",
      "format": ",.2f"
    }
  }
}

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

Форматирование дат и времени

Для временных данных format использует спецификаторы D3-time-format.

Примеры:

  • %Y — год (2026)
  • %m — месяц (01–12)
  • %d — день месяца
  • %H:%M — часы и минуты
  • %Y-%m-%d — стандартная дата

Пример:

{
  "mark": "text",
  "encoding": {
    "text": {
      "field": "date",
      "type": "temporal",
      "format": "%Y-%m-%d"
    }
  }
}

Значения временного поля будут приведены к формату ISO-подобной строки без времени.

Свойство formatType

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

Основные значения:

  • "number" — числовое форматирование через d3-format
  • "time" — локальное время через d3-time-format
  • "utc" — UTC-время через d3-time-format
  • "string" — строковая обработка без сложного преобразования

Взаимосвязь format и formatType

Логика применения следующая:

  1. formatType определяет механизм обработки
  2. format задаёт правила преобразования внутри выбранного механизма
  3. результат подставляется в визуальный канал

Ошибочная комбинация приводит либо к игнорированию форматирования, либо к некорректному отображению значений.

Числовые форматы и поведение formatType=“number”

При использовании числового типа применяется библиотека d3-format. Форматная строка интерпретируется как спецификатор числа с фиксированной точностью, экспонентой или разделителями.

Пример с осью:

{
  "mark": "point",
  "encoding": {
    "x": {
      "field": "value",
      "type": "quantitative",
      "axis": {
        "format": ",.0f",
        "formatType": "number"
      }
    }
  }
}

В этом случае значения на оси X отображаются как целые числа с разделением тысяч.

Форматы времени и formatType=“time”

При работе с локальным временем применяется d3-time-format, где строка форматирования соответствует календарным компонентам даты.

Пример для оси:

{
  "mark": "line",
  "encoding": {
    "x": {
      "field": "timestamp",
      "type": "temporal",
      "axis": {
        "format": "%H:%M",
        "formatType": "time"
      }
    }
  }
}

Результат — отображение времени в формате часов и минут.

Форматы UTC и formatType=“utc”

UTC-формат используется для строгой временной шкалы без локального смещения. Это особенно важно при анализе событий, где временная зона не должна влиять на интерпретацию.

{
  "mark": "line",
  "encoding": {
    "x": {
      "field": "timestamp",
      "type": "temporal",
      "axis": {
        "format": "%Y-%m-%dT%H:%M",
        "formatType": "utc"
      }
    }
  }
}

Значения интерпретируются как универсальное время.

formatType=“string” и его поведение

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

  • категориальных данных
  • заранее подготовленных строк
  • случаев, когда format применяется как шаблон вывода

Пример:

{
  "mark": "text",
  "encoding": {
    "text": {
      "field": "category",
      "type": "nominal",
      "formatType": "string"
    }
  }
}

Форматирование в axis, legend и tooltip

Оси

В axis форматирование влияет на подписи шкалы:

{
  "axis": {
    "format": ".1f",
    "formatType": "number"
  }
}

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

Легенды

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

{
  "legend": {
    "format": ".0%",
    "formatType": "number"
  }
}

Это особенно важно при отображении долей и вероятностей.

Tooltip

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

{
  "tooltip": {
    "field": "value",
    "type": "quantitative",
    "format": ",.2f",
    "formatType": "number"
  }
}

Поведение при отсутствии formatType

Если formatType не указан, Vega-Lite делает вывод на основе типа данных:

  • quantitative → number
  • temporal → time
  • nominal/ordinal → string (или отсутствие форматирования)

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

Внутренние ограничения и особенности интерпретации

Форматирование не изменяет данные, а только их визуальное представление. Это означает:

  • агрегации выполняются до форматирования
  • сортировка не зависит от format
  • фильтрация не учитывает format
  • format применяется только на этапе рендеринга

Также важно учитывать, что некорректный формат может привести к:

  • пустым значениям в визуализации
  • fallback к стандартному отображению
  • игнорированию formatType

Согласование format с преобразованиями данных

При использовании трансформаций (transform, calculate, aggregate) форматирование применяется к уже изменённому набору данных. Это создаёт цепочку:

  1. исходные данные
  2. трансформации
  3. масштабирование
  4. форматирование вывода

Например, при агрегации:

{
  "aggregate": [{"op": "mean", "field": "value", "as": "avg"}]
}

и последующем отображении:

{
  "field": "avg",
  "type": "quantitative",
  "format": ".3f",
  "formatType": "number"
}

Форматирование и локализация

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

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

Полная локализация требует внешнего уровня над Vega-Lite.

Практическая роль в сложных визуализациях

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

  • уменьшение количества значащих цифр
  • унификация представления метрик
  • синхронизация отображения временных шкал
  • приведение разнотипных источников данных к единому виду

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

Оглавление