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

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

Time Unit in Encoding Field Definition

{
  "data": ... ,
  "mark": ... ,
  "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.

{
  "data": {"url": "data/seattle-temps.csv"},
  "mark": {
    "type": "line",
    "interpolate": "monotone"
  },
  "encoding": {
    "x": {
      "timeUnit": "month", "field": "date", "type": "temporal"
    },
    "y": {"aggregate": "mean", "field": "temp", "type": "quantitative"}
  },
  "config": {
    "axis": {"shortTimeLabels": true}
  }
}

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

{
  "data": {"url": "data/seattle-weather.csv"},
  "mark": "bar",
  "encoding": {
    "x": {
      "timeUnit": "month",
      "field": "date",
      "type": "temporal"
    },
    "y": {
      "aggregate": "mean",
      "field": "precipitation",
      "type": "quantitative"
    }
  }
}

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

{
  "data": {"url": "data/seattle-weather.csv"},
  "mark": "bar",
  "encoding": {
    "x": {
      "timeUnit": "month",
      "field": "date",
      "type": "ordinal"
    },
    "y": {
      "aggregate": "mean",
      "field": "precipitation",
      "type": "quantitative"
    }
  }
}

Time Unit Transform

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

{
  "data": {"url": "data/seattle-weather.csv"},
  "mark": "line",
  "transform": [{
    "timeUnit": "month",
    "field": "date",
    "as": "month"
  }],
  "encoding": {
    "x": {
      "field": "month",
      "type": "temporal",
      "axis": {
        "format": "%b"
      }
    },
    "y": {
      "aggregate": "max",
      "field": "temp_max",
      "type": "quantitative"
    }
  }
}

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.

{
  "data": {"url": "data/cars.json"},
  "mark": "text",
  "encoding": {
    "x": {"field": "Year", "type": "temporal", "timeUnit": "year"},
    "y": {"field": "Horsepower", "type": "quantitative", "aggregate": "mean"},
    "text": {"field": "Year", "type": "temporal", "timeUnit": "year"}
  }
}

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

{
  "data": {
    "values": [
      {"date": "10 Oct 2011 22:48:00"},
      {"date": "11 Oct 2022 23:00:00"}
    ]
  },
  "mark": "point",
  "encoding": {
    "y": {
      "timeUnit": "hours",
      "field": "date",
      "type": "ordinal",
      "axis": {"title": "time"}
    }
  }
}

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

{
  "data": {
    "values": [
      {"date": "10 Oct 2011 22:48:00"},
      {"date": "11 Oct 2022 23:00:00"}
    ],
    "format": {
      "parse": {"date": "utc:'%d %b %Y %H:%M:%S'"}
    }
  },
  "mark": "point",
  "encoding": {
    "y": {
      "timeUnit": "hours",
      "field": "date",
      "type": "ordinal",
      "axis": {"title": "time"}
    }
  }
}

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.

{
  "data": {
    "values": [
      {"date": "Sun, 01 Jan 2012 23:00:00","price": 150},
      {"date": "Sun, 02 Jan 2012 00:00:00","price": 100},
      {"date": "Sun, 02 Jan 2012 01:00:00","price": 170},
      {"date": "Sun, 02 Jan 2012 02:00:00","price": 165},
      {"date": "Sun, 02 Jan 2012 03:00:00","price": 200}
    ]
  },
  "mark": "line",
  "encoding": {
    "x": {
      "field": "date",
      "type": "temporal",
      "timeUnit": "utcyearmonthdatehoursminutes"
    },
    "y": {"field": "price","type": "quantitative"}
  }
}

2) UTC scale type when you have input data in UTC time.

{
  "data": {
    "values": [
      {"date": "Sun, 01 Jan 2012 23:00:00","price": 150},
      {"date": "Sun, 02 Jan 2012 00:00:00","price": 100},
      {"date": "Sun, 02 Jan 2012 01:00:00","price": 170},
      {"date": "Sun, 02 Jan 2012 02:00:00","price": 165},
      {"date": "Sun, 02 Jan 2012 03:00:00","price": 200}
    ]
  },
  "mark": "line",
  "encoding": {
    "x": {
      "field": "date",
      "type": "temporal",
      "timeUnit": "yearmonthdatehoursminutes",
      "scale": {"type": "utc"}
    },
    "y": {"field": "price","type": "quantitative"}
  }
}

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.