D3 · all subjects

d3-time

38 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

d3.timeInterval API signature

d3.timeInterval(floor, offset, count, field) implements a new custom time interval. The floor function rounds down to the nearest boundary, offset shifts a date by intervals, count tallies interval boundaries between two dates, and field is optional for identifying a date field.

Time interval methods: floor, round, ceil, offset, range, filter, every, count

An interval object has these methods: floor() rounds down to nearest boundary, round() rounds to nearest boundary, ceil() rounds up to nearest boundary, offset(date, k) offsets a date by k intervals, range(start, stop, step) generates dates at interval boundaries, filter(predicate) creates a filtered subset, every(k) creates a filtered subset (alias for filter), and count(start, end) counts boundaries between two dates.

Local time intervals: millisecond, second, minute, hour, day, week variants

D3 provides local time intervals: d3.timeMillisecond, d3.timeSecond, d3.timeMinute, d3.timeHour, d3.timeDay, and week intervals starting on different days (d3.timeSunday, d3.timeMonday, d3.timeTuesday, d3.timeWednesday, d3.timeThursday, d3.timeFriday, d3.timeSaturday). Also available: d3.timeMonth and d3.timeYear.

UTC time intervals: utcMillisecond, utcSecond, utcMinute, utcHour, utcDay, utcWeek variants

D3 provides UTC time intervals: d3.utcMillisecond, d3.utcSecond, d3.utcMinute, d3.utcHour, d3.utcDay, and UTC week intervals (d3.utcSunday, d3.utcMonday, d3.utcTuesday, d3.utcWednesday, d3.utcThursday, d3.utcFriday, d3.utcSaturday). Also available: d3.utcMonth and d3.utcYear. Additionally, d3.unixDay provides day intervals in UTC but not month-aligned.

Time interval range aliases: plural functions

D3 provides plural function names as aliases for calling .range() on intervals: d3.timeMilliseconds, d3.timeSeconds, d3.timeMinutes, d3.timeHours, d3.timeDays, d3.timeWeeks, d3.timeSundays, d3.timeMondays, d3.timeTuesdays, d3.timeWednesdays, d3.timeThursdays, d3.timeFridays, d3.timeSaturdays, d3.timeMonths, d3.timeYears. Similar UTC variants exist (d3.utcMilliseconds, d3.utcSeconds, etc.) along with d3.unixDays.

Time tick generation: d3.timeTicks, d3.utcTicks, d3.timeTickInterval, d3.utcTickInterval

d3.timeTicks generates representative values from a time interval for local time. d3.utcTicks generates representative values from a time interval for UTC. d3.timeTickInterval generates representative values from a time interval for local time. d3.utcTickInterval generates representative values from a time interval for UTC.

d3-time module purpose

The d3-time module provides calendar math APIs for working with time. It does not implement its own calendaring system but instead provides a convenient API on top of ECMAScript Date. It ignores leap seconds and can only work with the local time zone and Coordinated Universal Time (UTC). The module is used by D3's time scales to generate sensible ticks, by D3's time format, and can be used directly for tasks like calendar layouts.

interval(date) - default floor behavior

Calling an interval directly like d3.utcMonday() or d3.timeDay(*date*) is equivalent to interval.floor(*date*), except if *date* is not specified it defaults to the current time. For example, d3.timeYear(*date*) and d3.timeYear.floor(*date*) are equivalent.

interval.floor(date) - round down to boundary

Returns a new date representing the latest interval boundary date before or equal to *date*. For example, d3.timeDay.floor(*date*) typically returns 12:00 AM local time on the given *date*. This method is idempotent: if the specified *date* is already floored to the current interval, a new date with an identical time is returned. The returned date is the minimum expressible value of the associated interval.

interval.round(date) - round to nearest boundary

Returns a new date representing the closest interval boundary date to *date*. For example, d3.timeDay.round(*date*) typically returns 12:00 AM local time on the given *date* if it is on or before noon, and 12:00 AM of the following day if it is after noon. This method is idempotent: if the specified *date* is already rounded to the current interval, a new date with an identical time is returned.

interval.ceil(date) - round up to boundary

Returns a new date representing the earliest interval boundary date after or equal to *date*. For example, d3.timeDay.ceil(*date*) typically returns 12:00 AM local time on the date following the given *date*. This method is idempotent: if the specified *date* is already ceilinged to the current interval, a new date with an identical time is returned. The returned date is the maximum expressible value of the associated interval.

interval.offset(date, step) - add intervals

Returns a new date equal to *date* plus *step* intervals. If *step* is not specified it defaults to 1. If *step* is negative, the returned date will be before the specified *date*; if *step* is zero, a copy of the specified *date* is returned; if *step* is not an integer, it is floored. This method does not round the specified *date* to the interval. For example, if *date* is today at 5:34 PM, then d3.timeDay.offset(*date*, 1) returns 5:34 PM tomorrow even if daylight saving changes.

interval.range(start, stop, step) - generate dates

Returns an array of dates representing every interval boundary after or equal to *start* (inclusive) and before *stop* (exclusive). If *step* is specified, then every *step*th boundary will be returned; for example, for d3.timeDay a *step* of 2 will return every other day. If *step* is not an integer, it is floored. The first date in the returned array is the earliest boundary after or equal to *start*; subsequent dates are offset by *step* intervals and floored. Aliases for interval.range are provided as plural forms of the corresponding interval, such as utcMondays.

interval.filter(test) - create filtered interval

Returns a new interval that is a filtered subset of this interval using the specified *test* function. The *test* function is passed a date and should return true if and only if the specified date should be considered part of the interval. The returned filtered interval does not support interval.count.

interval.every(step) - create stepped interval

Returns a filtered view of this interval representing every *step*th date. The meaning of *step* is dependent on this interval's parent interval as defined by the field function. For example, d3.timeMinute.every(15) returns an interval representing every fifteen minutes, starting on the hour: :00, :15, :30, :45, etc. Note that for some intervals, the resulting dates may not be uniformly-spaced; d3.timeDay's parent interval is d3.timeMonth, and thus the interval number resets at the start of each month. If *step* is not valid, returns null. If *step* is one, returns this interval. The returned filtered interval does not support interval.count.

interval.count(start, end) - count boundaries

Returns the number of interval boundaries after *start* (exclusive) and before or equal to *end* (inclusive). This behavior is slightly different than interval.range because its purpose is to return the zero-based number of the specified *end* date relative to the specified *start* date. For example, d3.timeDay.count(d3.timeYear(now), now) computes the current zero-based day-of-year number.

timeInterval(floor, offset, count, field) constructor

Constructs a new custom interval given the specified *floor* and *offset* functions and optional *count* and *field* functions. The *floor* function takes a single date argument and rounds it down to the nearest interval boundary. The *offset* function takes a date and an integer step and advances the date by the specified number of boundaries (step may be positive, negative or zero). The optional *count* function takes a start and end date (already floored to the current interval) and returns the number of boundaries between start (exclusive) and end (inclusive); if not specified, the returned interval does not expose interval.count or interval.every methods. The optional *field* function takes a date (already floored to the current interval) and returns the field value corresponding to the number of boundaries between this date (exclusive) and the latest previous parent boundary; if not specified, it defaults to counting boundaries since the UNIX epoch of January 1, 1970 UTC.

timeInterval example constructor

Example of constructing a custom UTC day interval: const utcDay = d3.timeInterval( (date) => date.setUTCHours(0, 0, 0, 0), // floor (date, step) => date.setUTCDate(date.getUTCDate() + step), // offset (start, end) => (end - start) / 864e5, // count (date) => date.getUTCDate() - 1 // field );

timeMillisecond, utcMillisecond intervals

Milliseconds in local time (timeMillisecond) or UTC time (utcMillisecond); the shortest available time unit.

timeSecond, utcSecond intervals

Seconds in local time (timeSecond) or UTC time (utcSecond) (e.g., 01:23:45.0000 AM); 1,000 milliseconds. Note that ECMAScript ignores leap seconds.

timeMinute, utcMinute intervals

Minutes in local time (timeMinute) or UTC time (utcMinute) (e.g., 01:02:00 AM); 60 seconds. Note that ECMAScript ignores leap seconds.

timeHour, utcHour intervals

Hours in local time (timeHour) or UTC time (utcHour) (e.g., 01:00 AM); 60 minutes. Note that advancing time by one hour in local time can return the same hour or skip an hour due to daylight saving.

timeDay, utcDay intervals

Days in local time (timeDay) or UTC time (utcDay) (e.g., February 7, 2012 at 12:00 AM); typically 24 hours. Days in local time may range from 23 to 25 hours due to daylight saving. d3.unixDay is like d3.utcDay, except it counts days since the UNIX epoch (January 1, 1970) such that interval.every returns uniformly-spaced dates rather than varying based on day-of-month.

timeWeek, utcWeek intervals

Alias for timeSunday (local) or utcSunday (UTC); 7 days and typically 168 hours. Weeks in local time may range from 167 to 169 hours due to daylight saving.

Day-of-week intervals - local time

D3 provides day-of-week intervals based on when weeks start in local time: timeSunday, timeMonday, timeTuesday, timeWednesday, timeThursday, timeFriday, timeSaturday. For example, timeSunday represents Sunday-based weeks in local time (e.g., February 5, 2012 at 12:00 AM).

Day-of-week intervals - UTC time

D3 provides day-of-week intervals based on when weeks start in UTC time: utcSunday, utcMonday, utcTuesday, utcWednesday, utcThursday, utcFriday, utcSaturday. For example, utcSunday represents Sunday-based weeks in UTC time (e.g., February 5, 2012 at 12:00 AM).

timeMonth, utcMonth intervals

Months in local time (timeMonth) or UTC time (utcMonth) (e.g., February 1, 2012 at 12:00 AM); ranges from 28 to 31 days.

timeYear, utcYear intervals

Years in local time (timeYear) or UTC time (utcYear) (e.g., January 1, 2012 at 12:00 AM); ranges from 365 to 366 days.

unixDay interval

Like d3.utcDay, except it counts days since the UNIX epoch (January 1, 1970) such that interval.every returns uniformly-spaced dates rather than varying based on day-of-month.

Plural interval range aliases

D3 provides plural aliases for interval.range() for convenience: timeMilliseconds, timeSeconds, timeMinutes, timeHours, timeDays, timeWeeks, timeSundays, timeMondays, timeTuesdays, timeWednesdays, timeThursdays, timeFridays, timeSaturdays, timeMonths, timeYears, and corresponding utc* versions (utcMilliseconds, utcSeconds, etc.).

timeTicks(start, stop, count) function

Equivalent to d3.utcTicks but in local time. Returns an array of approximately *count* dates at regular intervals between *start* and *stop* (inclusive).

timeTickInterval(start, stop, count) function

Returns the time interval that would be used by d3.timeTicks given the same arguments.

utcTicks(start, stop, count) function

Returns an array of approximately *count* dates at regular intervals between *start* and *stop* (inclusive). If *stop* is before *start*, dates are returned in reverse chronological order; otherwise dates are returned in chronological order. The function considers the following UTC time intervals: 1 second, 5 seconds, 15 seconds, 30 seconds, 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, 12 hours, 1 day, 2 days, 1 week, 1 month, 3 months, 1 year. Multiples of milliseconds (for small ranges) and years (for large ranges) are also considered following the rules of d3.ticks. The interval producing the number of dates closest to *count* is used. If *count* is a time interval, this function behaves similarly to interval.range except that both *start* and *stop* are inclusive and it may return dates in reverse chronological order if *stop* is before *start*.

utcTicks example

Example of using utcTicks: const start = new Date("1970-03-01"); const stop = new Date("1996-03-19"); const count = 4; const ticks = d3.utcTicks(start, stop, count); // [1975-01-01, 1980-01-01, 1985-01-01, 1990-01-01, 1995-01-01]

utcTickInterval(start, stop, count) function

Returns the time interval that would be used by d3.utcTicks given the same arguments. If there is no associated interval, such as when *start* or *stop* is invalid, returns null.

utcTickInterval example

Example of using utcTickInterval: const start = new Date("1970-03-01"); const stop = new Date("1996-03-19"); const count = 4; const interval = d3.utcTickInterval(start, stop, count); // d3.utcYear.every(5)

Date comparison pitfall - use coercion

The == and === operators do not compare Date objects by value, so you cannot use them to tell whether a specified *date* has already been floored. Instead, coerce to a number and then compare. For example, to check if a date is a day boundary: function isDay(date) { return +d3.timeDay.floor(date) === +date; } This is more reliable than testing whether the time is 12:00 AM, as in some time zones midnight may not exist due to daylight saving.

Naive day counting fails with daylight saving

Computing the number of days between two dates by simple arithmetic fails due to daylight saving and month/year irregularities. For example, const start = new Date(2015, 02, 01); const end = new Date(2015, 03, 01); const days = (end - start) / 864e5; returns 30.958333333333332 instead of the correct 31. Use d3.timeDay.count(start, end) instead, which returns 31.

Give your agent this brain