Time Unit

Time unit is used to discretize times in Vega-Lite. It can either be used inside encoding field definitions or as a transform.

Vega-Lite supports the following time units:

• "year", "yearquarter", "yearquartermonth", "yearmonth", "yearmonthdate", "yearmonthdatehours", "yearmonthdatehoursminutes", "yearmonthdatehoursminutesseconds".
• "quarter", "quartermonth"
• "month", "monthdate"
• "date" (Day of month, i.e., 1 - 31)
• "day" (Day of week, i.e., Monday - Friday)
• "hours", "hoursminutes", "hoursminutesseconds"
• "minutes", "minutesseconds"
• "seconds", "secondsmilliseconds"
• "milliseconds"

By default, all time units represent date time using local time. To use UTC time, you can add the utc prefix (e.g., utcyearmonth).

Documentation Overview

• Documentation Overview
• Time Unit in Encoding Field Definition
• Time Unit Transform
• UTC time
  • Input
  • Output

Time Unit in Encoding Field Definition

// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {
    "x": {
      "timeUnit": ...,               // time unit
      "field": ...,
      "type": "temporal",
      ...
    },
    "y": ...,
    ...
  },
  ...
}

A field definition can include a timeUnit property. For example, the chart below shows shows temperature in Seattle aggregated by month.

Note that temporal fields use continuous scales by default for all mark types including "bar".

If you want to use a discrete scale instead, you can cast the field to have an "ordinal" type. This casting strategy can be useful for time units with low cardinality such as "month".

Time Unit Transform

// Any View Specification
{
  ...,
  "transform": [
    {"timeUnit": ..., "field": ..., "as": ...} // TimeUnit Transform
     ...
  ],
  ...
}

A timeUnit transform in the transform array has the following properties:

In the example below, we use the time unit transform to extract the month component of the dates. We can then visualize the hottest temperature. Note that Vega-Lite will automatically format the axis if the timeUnit is applied outside encoding so we have to format it manually. For this reason, you should prefer time units as part of encoding definitions.

UTC time

Input

To parse data in local time or UTC time, there are three cases:

1. Times are parsed as UTC time if the date strings are in ISO format. Note that in JavaScript date strings without time are interpreted as UTC but but date strings with time and without timezone as local.

1. If that is not the case, by default, times are assumed to be local.

1. To parse inline data or url data without ISO format as UTC time, we need to specify the format to be utc

Output

By default, Vega-Lite will output data in local time (even when input is parsed as UTC time). To output data in UTC time, we need to specify either a UTC time unit or scale:

1. UTC time unit when input data is in local time.

1. UTC scale type when you have input data in UTC time.

Do not use UTC time unit and the UTC scale type at the same time since that will cause Vega-Lite to shift the output time twice.