Функции дат и времени

В экосистеме Vega и Vega-Lite работа с датами и временем строится на двух уровнях: выражения (expression language Vega) и декларативные преобразования/кодировки (Vega-Lite). Оба уровня опираются на JavaScript Date, но предоставляют специализированные функции для анализа временных рядов, агрегаций и визуальных шкал.

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

Создание и преобразование временных значений

Конструкторы дат

В выражениях Vega доступна функция создания даты из компонент:

datetime(year, month, date, hours, minutes, seconds, milliseconds)

Особенности:

  • month начинается с 0 (январь = 0)
  • все параметры после года опциональны

Примеры:

datetime(2026, 0, 1)        // 1 января 2026
datetime(2026, 5, 21, 12)   // 21 июня 2026, 12:00

Альтернативный конструктор:

time(year, month, date, hours, minutes, seconds, milliseconds)

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

Текущее время

Функция получения текущего момента:

now()

Возвращает Date, соответствующий моменту вычисления выражения.

Доступ к компонентам даты

В Vega expression language предусмотрены функции извлечения компонентов времени:

  • year(d)
  • quarter(d)
  • month(d)
  • date(d) — день месяца
  • day(d) — день недели (0–6)
  • hours(d)
  • minutes(d)
  • seconds(d)
  • milliseconds(d)

Пример:

year(datum.timestamp)
month(datum.timestamp)
date(datum.timestamp)

Эти функции активно применяются в calculate трансформациях и условных выражениях.

Работа с временными зонами (UTC)

Для корректной работы с глобальными данными часто используется UTC-логика.

В Vega выражениях доступны UTC-версии операций через стандартный JavaScript Date, но логика часто реализуется через:

  • нормализацию входных данных
  • использование ISO-форматов
  • временные преобразования на уровне timeUnit

Например:

year(datum.timestamp)

при UTC-данных интерпретируется как год в UTC-контексте, если вход уже нормализован.

Парсинг и форматирование времени

Разбор строк в дату

timeParse(format)(string)

Пример:

timeParse("%Y-%m-%d")("2026-05-21")

Форматы:

  • %Y — год
  • %m — месяц
  • %d — день
  • %H — часы
  • %M — минуты
  • %S — секунды

Форматирование даты в строку

timeFormat(format)(date)

Пример:

timeFormat("%Y-%m-%d")(new Date())

Используется для подписей осей, tooltip и вычисляемых полей.

TimeUnit в Vega-Lite

В Vega-Lite основной механизм работы с временной дискретизацией — timeUnit.

Базовая идея

timeUnit преобразует непрерывное время в дискретные группы:

{
  "timeUnit": "yearmonth",
  "field": "timestamp",
  "type": "temporal"
}

Основные единицы времени

Год и его разбиения

  • year
  • quarter
  • month

Календарные единицы

  • week
  • day
  • date

Временные компоненты

  • hours
  • minutes
  • seconds
  • milliseconds

Составные единицы

  • yearmonth
  • yearmonthdate
  • yearmonthdatehours

Пример агрегации по времени

{
  "data": {"url": "data.csv"},
  "mark": "line",
  "encoding": {
    "x": {
      "field": "date",
      "timeUnit": "yearmonth",
      "type": "temporal"
    },
    "y": {
      "aggregate": "sum",
      "field": "value"
    }
  }
}

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

Временные шкалы (scales)

В Vega и Vega-Lite временные данные используют шкалу типа:

{
  "type": "time"
}

Особенности:

  • непрерывная числовая интерпретация Date
  • поддержка интервалов разной плотности (дни, месяцы, годы)
  • автоматическая адаптация tick generation

Пример:

{
  "encoding": {
    "x": {
      "field": "timestamp",
      "type": "temporal",
      "scale": {"type": "time"}
    }
  }
}

Округление времени через timeUnit

timeUnit не только группирует, но и фактически округляет дату до начала интервала.

Пример:

"timeUnit": "month"

Вход:

2026-05-21 14:32:10

Результат:

2026-05-01 00:00:00

Это поведение критично при построении:

  • гистограмм временных рядов
  • календарных тепловых карт
  • сезонных анализов

Использование времени в calculate и filter

Вычисляемые поля

{
  "calculate": "year(datum.timestamp)",
  "as": "year"
}

Фильтрация по времени

{
  "filter": "year(datum.timestamp) >= 2020"
}

Можно комбинировать:

{
  "filter": "month(datum.timestamp) === 0"
}

Интервалы и сезонные паттерны

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

  • сезонность (месяцы)
  • недельные паттерны
  • суточные циклы

Пример выделения дня недели:

{
  "calculate": "day(datum.timestamp)",
  "as": "weekday"
}

Форматирование осей времени

Vega-Lite поддерживает автоматическое форматирование:

{
  "axis": {
    "format": "%b %Y"
  }
}

Распространённые форматы:

  • %Y — год
  • %b — сокращённый месяц
  • %B — полный месяц
  • %d — день месяца

Дополнительно:

  • автоматическое сокращение меток
  • адаптация под плотность данных

Работа с временными данными в tooltip

{
  "tooltip": [
    {"field": "timestamp", "type": "temporal"},
    {"field": "value", "type": "quantitative"}
  ]
}

Vega автоматически форматирует дату в человекочитаемый вид, если не задан formatType.

Поведение null и некорректных дат

При работе с временем:

  • null значения игнорируются в агрегациях
  • некорректные строки после timeParse возвращают null
  • вычисления с null приводят к пропуску записи

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

Оптимизация в Vega/Vega-Lite достигается за счёт:

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

Особенно критично при больших потоках данных:

  • логирование событий
  • финансовые котировки
  • телеметрия

Сравнение уровней обработки времени

Vega expression layer

  • гибкая логика
  • функции year, month, timeParse
  • вычисления на уровне строк

Vega-Lite layer

  • декларативные timeUnit
  • автоматическая агрегация
  • интеграция с encoding

Разделение позволяет:

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

Типичные паттерны использования

Линия временного ряда

{
  "mark": "line",
  "encoding": {
    "x": {"field": "date", "type": "temporal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}

Месячная агрегация

{
  "x": {
    "field": "date",
    "timeUnit": "yearmonth",
    "type": "temporal"
  }
}

Сезонная аналитика

{
  "calculate": "month(datum.date)",
  "as": "month"
}

Временная модель как основа аналитики

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

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

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

Оглавление