TimeUnit Transform

The timeunit transform ≥ 5.8 discretizes date-time values into time unit bins. A common use case is to group data values into specific time intervals, such as months or days of the week.

Transform Parameters

Property Type Description
field Field Required. The data field of date-time values.
units String[ ] An array of time unit specifiers defining how date-time values should be binned. See the time unit reference for more. If unspecified, the units will be inferred based on the value extent.
step Number The number of steps between bins in terms of the smallest provided time unit in units (default 1). If units is unspecified, this parameter is ignored.
timezone String The timezone to use, one of "local" (default) for the local timezone or "utc" for Coordinated Universal Time (UTC).
interval Boolean A boolean flag (default true) indicating if both the start and end unit values should be output. If false, only the starting (floored) time unit value is written to the output.
extent Date[ ] A two-element array with the minimum and maximum values to consider for inferred time units. If unspecified, the observed minimum and maximum values of field will be used. This parameter is applicable only if the units parameter is unspecified.
maxbins Number The maximum number of bins to create for inferred time units (default 40). There will often be fewer bins as the domain gets sliced at “nicely” rounded values. This parameter is applicable only if the units parameter is unspecified.
signal String If defined, binds the computed time unit specification to a signal with the given name. The bound object has unit (the smallest time unit), units (the array of all time units), step, start, and stop properties.
as String[ ] The output fields at which to write the start and end time unit interval values. The default is ["unit0", "unit1"]. Only the first field will be written if the interval parameter is false.

Time Units

The timeunit transform accepts the following set of pre-defined time units. A single unit value is one of the following strings:

  • "year" - Gregorian calendar years.
  • "quarter" - Three-month intervals, starting in one of January, April, July, and October.
  • "month" - Calendar months (January, February, etc.).
  • "date" - Calendar day of the month (January 1, January 2, etc.).
  • "week" - Sunday-based weeks. Days before the first Sunday of the year are considered to be in week 0, the first Sunday of the year is the start of week 1, the second Sunday week 2, etc..
  • "day" - Day of the week (Sunday, Monday, etc.).
  • "dayofyear" - Day of the year (1, 2, …, 365, etc.).
  • "hours" - Hours of the day (12:00am, 1:00am, etc.).
  • "minutes" - Minutes in an hour (12:00, 12:01, etc.).
  • "seconds" - Seconds in a minute (12:00:00, 12:00:01, etc.).
  • "milliseconds" - Milliseconds in a second.

The units transform parameter accepts an array to indicate desired intervals of time. For example, ["year", "month", "date"] indicates chronological time sensitive to year, month, and date (but not to hours, minutes, or seconds). The specifier ["month", "date"] is sensitive to month and date, but not year, which can be useful for binning time values to look at seasonal patterns only.

Usage

Chronological Time Units

This example discretizes values in the date field by year and Sunday-based week number (units), using two week intervals (step).

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

Given the input data

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

the timeunit transform produces the output

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

Alternatively, a grouping by year and month is specified using "units": ["year", "month"].

Cyclical Time Units

This example discretizes values in the date field by month, regardless of the year.

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

Given the input data

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

the timeunit transform produces the output

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

Note that the output dates default to the year 2012. This default is chosen as it is a leap year (and so the date February 29 is respected) that begins on a Sunday (and so days of the week will order properly at the beginning of the year).

A similar grouping by Sunday-based day of week is specified by "units": ["day"], whereas grouping by day of the month (regardless of year or month) is specified by "units": ["date"].