Преобразование timeunit

Преобразование timeunit ≥ 5.8 разбивает значения даты и времени на интервалы заданных единиц. Часто его используют, чтобы группировать данные по месяцам или дням недели.

Параметры преобразования

Свойство	Тип	Описание
field	Field	Обязательно. Поле со значениями даты и времени.
units	String[ ]	Массив единиц времени, определяющих разбиение. См. справочник единиц времени. Если не задан, единицы выводятся из диапазона extent.
inferUnits	Boolean	Определять ли единицы по точности наблюдаемых дат (по умолчанию `false`). Полезно для уже сгруппированных данных, например по месяцам. Точность определяется во временной зоне timezone. При `true` этот параметр имеет приоритет, а units, step, maxbins и extent игнорируются.
step	Number	Число шагов между интервалами в единицах самой мелкой единицы из units (по умолчанию `1`). Если units не задан, параметр игнорируется.
timezone	String	Временная зона: `"local"` (по умолчанию) или `"utc"` для всемирного координированного времени UTC.
interval	Boolean	Выводить ли начало и конец интервала (по умолчанию `true`). При `false` записывается только начало интервала.
extent	Date[ ]	Массив из минимальной и максимальной даты, учитываемых при автоматическом выборе единиц. По умолчанию используются границы наблюдаемых значений field. Действует только при отсутствии units.
maxbins	Number	Максимальное число интервалов при автоматическом выборе единиц (по умолчанию `40`). Их может быть меньше из-за округления границ до удобных значений. Действует только при отсутствии units.
signal	String	Имя сигнала для вычисленного описания интервалов. Объект содержит unit (самую мелкую единицу), units (все единицы), step, start и stop.
as	String[ ]	Имена выходных полей для начала и конца интервала (по умолчанию `["unit0", "unit1"]`). При interval равном `false` записывается только первое поле.

Единицы времени

Поддерживаются следующие единицы времени. Каждая задаётся одной из строк:

"year" — годы григорианского календаря.
"quarter" — трёхмесячные кварталы, начинающиеся в январе, апреле, июле и октябре.
"month" — календарные месяцы: январь, февраль и так далее.
"date" — день месяца: 1 января, 2 января и так далее.
"week" — недели, начинающиеся в воскресенье. Дни до первого воскресенья года относятся к неделе 0; первое воскресенье начинает неделю 1, второе — неделю 2 и так далее.
"isoweek" — недели по ISO 8601 ≥ 6.4. Они начинаются в понедельник; неделя 1 содержит 4 января, то есть первый четверг года. Неделя относится к тому недельному году, на который приходится её четверг; он может отличаться от календарного года первого или последнего дня недели. Единицы "week" и "isoweek" нельзя сочетать.
"day" — день недели: воскресенье, понедельник и так далее.
"dayofyear" — день года: 1, 2, …, 365 и так далее.
"hours" — час дня: 00:00, 01:00 и так далее.
"minutes" — минута внутри часа: 12:00, 12:01 и так далее.
"seconds" — секунда внутри минуты: 12:00:00, 12:00:01 и так далее.
"milliseconds" — миллисекунда внутри секунды.

Параметр units принимает массив нужных единиц. Например, ["year", "month", "date"] сохраняет год, месяц и число, но не часы, минуты и секунды. Массив ["month", "date"] учитывает месяц и число без года; так удобно исследовать сезонные закономерности.

Использование

Хронологические единицы времени

Пример разбивает значения поля date по году и номеру недели, начинающейся в воскресенье (units), с шагом в две недели (step).

{"type": "timeunit", "field": "date", "units": ["year", "week"], "step": 2}

Замените "week" на "isoweek", чтобы использовать недели ISO 8601, начинающиеся в понедельник и нумеруемые по недельному году. Поскольку на границе года схемы различаются, сочетание ["year", "isoweek"] форматируется по недельному году (%G), а не календарному (%Y).

Для следующих входных данных:

[
  {"date": new Date(2018,  0, 11)},
  {"date": new Date(2018,  4, 12)},
  {"date": new Date(2018,  8,  7)},
  {"date": new Date(2018, 11, 23)}
]

преобразование timeunit создаёт результат:

[
  {"date": new Date(2018,  0, 11), "unit0": new Date(2018,  0,  7), "unit1": new Date(2018,  0, 21)},
  {"date": new Date(2018,  4, 12), "unit0": new Date(2018,  3, 29), "unit1": new Date(2018,  4, 13)},
  {"date": new Date(2018,  8,  7), "unit0": new Date(2018,  8,  2), "unit1": new Date(2018,  8, 16)},
  {"date": new Date(2018, 11, 23), "unit0": new Date(2018, 11, 23), "unit1": new Date(2019,  0,  6)}
]

Группировку по году и месяцу можно задать массивом "units": ["year", "month"].

Циклические единицы времени

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

{"type": "timeunit", "field": "date", "units": ["month"]}

Для следующих входных данных:

[
  {"date": new Date(2018,  0,  4)},
  {"date": new Date(2018,  4, 12)},
  {"date": new Date(2018,  8,  7)},
  {"date": new Date(2018, 11, 23)}
]

преобразование timeunit создаёт результат:

[
  {"date": new Date(2018,  0,  4), "unit0": new Date(2012,  0, 1), "unit1": new Date(2012, 1, 1)},
  {"date": new Date(2018,  4, 12), "unit0": new Date(2012,  4, 1), "unit1": new Date(2012, 5, 1)},
  {"date": new Date(2018,  8,  7), "unit0": new Date(2012,  8, 1), "unit1": new Date(2012, 9, 1)},
  {"date": new Date(2018, 11, 23), "unit0": new Date(2012, 11, 1), "unit1": new Date(2013, 0, 1)}
]

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

Когда "isoweek" используется без "year", выходным годом по умолчанию становится 2015-й. Это длинный год по ISO, содержащий все 53 возможных номера недель.

Для группировки по дню недели, начинающейся в воскресенье, используйте "units": ["day"]; для группировки по числу месяца независимо от месяца и года — "units": ["date"].