Time Unit

Time unit is used to discretize times in Vega-Lite. It can be used (1) with thetimeUnit property ofencoding field definitions, (2) asa standalone transform, or (3) with thetimeUnit property of afield predicate.

Vega-Lite supports the following time units:

• "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.

Vega-Lite time units can also be a string of consecutive time units to indicate desired intervals of time. For example,yearmonthdate indicates chronological time sensitive to year, month, and date (but not to hours, minutes, or seconds). The specifiermonthdate is sensitive to month and date, but not year, which can be useful for binning time values to look at seasonal patterns only.

• By default, all time units represent date time using local time.
• To use UTC time, you can add theutc prefix (e.g.,"utcyear","utcyearmonth").
• For timeUnit in encoding, you can also add"binned" prefix (e.g.,"binnedyearmonth" or"binnedutcyearmonth") for Chronological time units (i.e., units that are truncated date times, as opposed to circle time units, which bin data to parts of date times).

Documentation Overview

• Time Unit in Encoding Field Definition
  • Time Unit’s Band
  • Time Unit with Ordinal Fields
• Time Unit Transform
• UTC time
  • Input
  • Output
• Time Unit Parameters
  • Example: Customizing Step

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 atimeUnit property. For example, the chart below shows temperature in Seattle aggregated by month.

UsingtimeUnit with rect-based marks (includingbar,rect, andimage) will treat time units as intervals.

You can also add"binned" prefix if your data has already been binned and want Vega-Lite to apply the right formatting, including the right bands for the interval, to your charts.

By default, bar marks are placed from the beginning of a time interval (e.g., “month”) to the end of the interval.

SettingbandPosition to0 moves the bar to center-align with ticks.

Time Unit’s Band

By default, Vega-Lite encodes fields with timeUnit using the initial position of a time unit (which is equivalent to havingband = 0). However, one can set theband property to be0.5 to use place each data point in the middle of each time unit band.

Time Unit with Ordinal Fields

By default, fields with time units have “temporal” type and thus use time scales. However, time units can be also used with a discrete scale. For example, you can cast the field to have an"ordinal" type.

Time Unit Transform

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

AtimeUnit transform in thetransform 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 not automatically format the axis if thetimeUnit is applied outsideencoding 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 inISO format. Note that in JavaScript date strings without time are interpreted as UTC but date strings with time and without timezone as local.

If you don’t want to re-bin the data, you can also add"binned" prefix.

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 theformat to beutc with time format:

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 can 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.

Time Unit Parameters

To customize time unit properties, you can settimeUnit to be a time unit definition object. It can have the following properties.

Example: Customizing Step

Thestep parameter can be used to specify a bin size with respect to the smallest denominator in the time unit provided. The following example shows sum of distance traveled for each 5-minute interval.