Поле timeUnit в кодировании

В Vega-Lite поле timeUnit используется для преобразования временных значений в дискретные компоненты времени с целью упрощения агрегации, группировки и визуального анализа временных рядов. Оно применяется внутри описания кодирования (encoding) и позволяет извлекать из даты такие части, как год, месяц, день недели, час и их комбинации, формируя производные временные признаки без необходимости предварительной обработки данных.

Временные данные в Vega-Lite обычно представлены в виде значений JavaScript Date, строк ISO 8601 или числовых timestamp. Однако для визуализации часто требуется не точное время, а его структурные компоненты.

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

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

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

Пример базового использования:

{
  "data": { "url": "data.csv" },
  "mark": "bar",
  "encoding": {
    "x": {
      "field": "date",
      "type": "temporal",
      "timeUnit": "year",
      "axis": { "title": "Год" }
    },
    "y": {
      "aggregate": "count",
      "type": "quantitative"
    }
  }
}

В этом примере все даты приводятся к году, и данные группируются по годовым интервалам.

Основные категории timeUnit

Преобразования времени в Vega-Lite делятся на несколько логических групп.

Календарные компоненты

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

  • year — год
  • quarter — квартал
  • month — месяц (как число или имя)
  • date — день месяца
  • day — день недели

Пример:

"timeUnit": "month"

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

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

Позволяют анализировать внутрисуточную динамику:

  • hours
  • minutes
  • seconds
  • milliseconds

Пример:

"timeUnit": "hours"

Используется, например, для анализа активности пользователей по времени суток.

Комбинированные форматы

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

  • yearmonth
  • yearmonthdate
  • yearquarter
  • yearmonthdatehours

Эти комбинации формируют иерархические временные ключи.

Пример:

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

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

Поведение в шкалах и осях

Применение timeUnit изменяет не только сами значения, но и поведение шкал.

После преобразования:

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

Например, при использовании month ось будет содержать 12 категорий, даже если данные охватывают несколько лет.

Влияние на агрегацию данных

timeUnit часто используется совместно с aggregate. Это позволяет строить временные распределения без предварительного группирования.

Пример:

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

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

Отличие timeUnit от bin

Несмотря на внешнее сходство, timeUnit и bin решают разные задачи.

bin:

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

timeUnit:

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

Пример различия:

"timeUnit": "month"

группирует по календарным месяцам,

а

"bin": true

разбивает числовую ось на равные интервалы.

Сортировка и порядок значений

При использовании timeUnit порядок категорий определяется не алфавитно и не по исходным данным, а по временной логике:

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

Это поведение встроено в систему шкал Vega-Lite и не требует ручной настройки sort.

Формирование производных полей

Внутренне timeUnit создает вычисляемое поле, аналогичное трансформации calculate, но специализированное под временные данные. Это поле затем используется в кодировании как обычный field.

Например:

"timeUnit": "yearmonthdate"

эквивалентно созданию нового ключа, содержащего усечённую дату до уровня дня.

Взаимодействие с форматированием времени

Хотя timeUnit изменяет значение, визуальное представление меток управляется отдельно через axis.format.

Пример:

{
  "timeUnit": "yearmonth",
  "axis": {
    "format": "%Y-%m"
  }
}

Форматирование не влияет на группировку, но влияет на отображение.

Комбинирование с условными кодировками

timeUnit может использоваться в сочетании с условными выражениями для построения сложных визуализаций:

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

Пример:

{
  "condition": {
    "test": "datum.month === 12",
    "value": "red"
  },
  "field": "date",
  "type": "temporal",
  "timeUnit": "month"
}

Особенности обработки часовых поясов

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

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

Типичные ошибки использования

Часто встречающиеся проблемы при работе с timeUnit:

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

Практическое значение в визуальном моделировании

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

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

Оглавление