Time Utilities API

JavaScript date-time utilities for Vega. Provides a set of helper methods for working with date objects (or, equivalently, with UNIX timestamps). These methods are bound to the top-level vega object, and can also be used in a stand-alone fashion by using the vega-time package. For more general utility methods, see the Utilities API reference.

Time Units

The date-time utilities support a 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.

Multiple units can be listed in 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.

# vega.timeUnits(units) <>

Returns a standardized and sorted specifier for the given units, which must be an array of one or more valid time unit strings. The returned array contains the same units, sorted in decreasing over of unit size, such that the most granular unit is last (for example, ['year', 'month', 'date']). This method throws an error if the units array is empty, contains an invalid unit, or contains incompatible units. Specifically, the 'quarter', 'month', and 'date' units can not be used in conjunction with the 'week' or 'day' units.

# vega.timeUnitSpecifier(units[, specifiers]) <>

Returns a time format specifier string for the given time units. The optional specifiers object provides a set of desired specifier sub-strings for customizing the resulting time formats. The specifiers object may contain keys for both single time units ("year") and time unit sequences ("year-month-date"). This method will first standardize the input time units using the timeUnits method. It will then search, starting from the beginning of the units array, for the largest matching sequence defined in the specifiers object. Matching entries are then concatenated together, and the resulting string is whitespace-trimmed and returned.

If no specifiers object is provided, the following defaults are used:

{
  "year": "%Y ",
  "year-month": "%Y-%m ",
  "year-month-date": "%Y-%m-%d ",
  "quarter": "Q%q ",
  "month": "%b ",
  "date": "%d ",
  "week": "W%U ",
  "day": "%a ",
  "hours": "%H:00",
  "hours-minutes": "%H:%M",
  "minutes": "00:%M",
  "seconds": ":%S",
  "milliseconds": ".%L"
}

If a specifiers object is provided, its values are merged with the defaults above. As a result, for complete control callees may wish to override the multi-unit "year-month", "year-month-date", and "hours-minutes" entries in addition to any individual unit entries. The input specifiers object can use a null value to invalidate an entry in the defaults.

# vega.timeBin(options) <>

Determine a temporal binning scheme, for example to create a histogram. Based on the options provided given, this method will search over a space of possible time unit bins, applying constraints such as the maximum number of allowable bins. Given a set of options (see below), returns an object describing the binning scheme, in terms of units and step properties. These values can then be used as input to the timeFloor or utcFloor methods.

The supported options properties are:

extent: (required) A two-element ([min, max]) array indicating the date range over which the bin values are defined.
maxbins: The maximum number of allowable bins (default 40). There will often be fewer bins as the domain gets sliced at “nicely” rounded values.

Local Time Utilities

# vega.timeFormat([specifier]) <>

Returns a function that takes a date or timestamp as input and returns a formatted string in the local timezone. If a string-valued format specifier is provided, it must follow the d3-time-format syntax. In this case, this method is equivalent to d3-time-format’s timeFormat method.

If an object-valued specifier is provided, a multi-format function will be generated, which selects among different format specifiers based on the granularity of the input date value (that is, values residing on a year, month, date, etc., boundary can all be formatted differently). The input object should use proper time unit strings for keys. If no time format specifier is provided, a default multi-format function is returned, equivalent to using the following specifier:

{
  "year": "%Y",
  "quarter": "%B",
  "month": "%B",
  "week": "%b %d",
  "date": "%a %d",
  "hours": "%I %p",
  "minutes": "%I:%M",
  "seconds": ":%S",
  "milliseconds": ".%L"
}

If an input specifier object omits any of these key values, a default value will be used. Note that for this method the "date" and "day" units are interchangeable; if both are defined the "date" entry take precedence.

# vega.timeFloor(units[, step]) <>

Returns a function that performs flooring (truncation) of input dates to given time units in the local timezone. The units argument must be an array of valid time unit strings, for example ['year', 'month'] or ['week', 'date']. The optional step argument (default 1) indicates the number of time unit steps (of the smallest provided unit) to include as part of the truncation scheme. For example, utcFloor(['quarter']) is equivalent to utcFloor(['month'], 3).

# vega.timeInterval(unit) <>

Returns a d3-time interval for the given time unit in the local timezone.

# vega.timeOffset(unit, date[, step]) <>

Returns a new Date instance that offsets the given date by the specified time unit in the local timezone. The optional step argument indicates the number of time unit steps to offset by (default 1).

# vega.timeSequence(unit, start, stop[, step]) <>

Returns an array of Date instances from start (inclusive) to stop (exclusive), with each entry separated by the given time unit in the local timezone. The optional step argument indicates the number of time unit steps to take between each sequence entry (default 1).

# vega.dayofyear(date) <>

Returns the one-based day of the year for the given date, which should be either a Date object or timestamp value.

# vega.week(date) <>

Returns the week number of the year for the given date, which should be either a Date object or timestamp value. This function assumes 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..

UTC Time Utilities

# vega.utcFormat([specifier]) <>

Returns a function that takes a date or timestamp as input and returns a formatted string in Coordinated Universal Time (UTC). If a string-valued format specifier is provided, it must follow the d3-time-format syntax. In this case, this method is equivalent to d3-time-format’s utcFormat method.

This method also accepts object-valued specifiers for creating multi-format functions. If no argumennts are provided, a defualt multi-format function will be returned. For more details, see the timeFormat method documentation.

# vega.utcFloor(units[, step]) <>

Returns a function that performs flooring (truncation) of input dates to given time units in Coordinated Universal Time (UTC). The units argument must be an array of valid time unit strings, for example ['year', 'month'] or ['week', 'date']. The optional step argument (default 1) indicates the number of time unit steps (of the smallest provided unit) to include as part of the truncation scheme. For example, utcFloor(['quarter']) is equivalent to utcFloor(['month'], 3).

# vega.utcInterval(unit) <>

Returns a d3-time interval for the given time unit in Coordinated Universal Time (UTC).

# vega.utcOffset(unit, date[, step]) <>

Returns a new Date instance that offsets the given date by the specified time unit in Coordinated Universal Time (UTC). The optional step argument indicates the number of time unit steps to offset by (default 1).

# vega.utcSequence(unit, start, stop[, step]) <>

Returns an array of Date instances from start (inclusive) to stop (exclusive), with each entry separated by the given time unit in Coordinated Universal Time (UTC). The optional step argument indicates the number of time unit steps to take between each sequence entry (default 1).

# vega.utcweek(date) <>

Returns the week number of the year for the given date in Coordinated Universal Time (UTC), which should be either a Date object or timestamp value. This function assumes 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..