com.github.gwtd3.api.time

Class TimeScale

java.lang.Object

com.google.gwt.core.client.JavaScriptObject

com.github.gwtd3.api.scales.Scale<S>

com.github.gwtd3.api.scales.QuantitativeScale<S>

com.github.gwtd3.api.scales.ContinuousQuantitativeScale<TimeScale>

com.github.gwtd3.api.time.TimeScale

public class TimeScale
extends ContinuousQuantitativeScale<TimeScale>

D3's time scale is an extension of LinearScale that uses JavaScript Date objects as the domain representation.

Thus, unlike the normal linear scale, domain values are coerced to dates rather than numbers; similarly, the ContinuousQuantitativeScale.invert(double) function returns a date.

Most conveniently, the time scale also provides suitable ticks based on time intervals, taking the pain out of generating axes for nearly any time-based domain.

A scale object, such as that returned by d3.time.scale, is both an object and a function. That is: you can call the scale like any other function, and the scale has additional methods that change its behavior. Like other classes in D3, scales follow the method chaining pattern where setter methods return the scale itself, allowing multiple setters to be invoked in a concise statement.

The domain may be set as an array of two or more dates. If the elements in the given array are not dates, they will be coerced to dates; this coercion happens similarly when the scale is called.

Although time scales typically have just two dates in their domain, you can specify more than two dates for a polylinear scale. In this case, there must be an equivalent number of values in the output range.

Author:

Anthony Schiochet

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TimeScale()

Method Summary

Methods

Modifier and Type	Method and Description
TimeScale	nice(Interval interval) Extends the domain so that it starts and ends on nice round values as determined by the specified time interval.
TimeScale	nice(Interval interval, int step) Extends the domain so that it starts and ends on nice round values as determined by the specified time interval and step count.nd optional step count.
Formatter	tickFormat(int count) Returns a time Formatter function suitable for displaying a tick value.
<T> Array<T>	ticks() Alias for ticks(10).
<T> Array<T>	ticks(int count) Returns representative dates from the scale's input domain.
<T> Array<T>	ticks(Interval interval, int steps) Returns representative dates from the scale's input domain.

Methods inherited from class com.github.gwtd3.api.scales.ContinuousQuantitativeScale

clamp, clamp, invert, rangeRound, rangeRound, rangeRound

Methods inherited from class com.github.gwtd3.api.scales.Scale

apply, apply, apply, copy, domain, domain, domain, domain, range, range, range, range

Methods inherited from class com.google.gwt.core.client.JavaScriptObject

cast, createArray, createArray, createFunction, createObject, equals, hashCode, toSource, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TimeScale

protected TimeScale()

Method Detail

nice

public final TimeScale nice(Interval interval)

Extends the domain so that it starts and ends on nice round values as determined by the specified time interval.

This method typically modifies the scale's domain, and may only extend the bounds to the nearest round value.

Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [2009-07-13T00:02, 2009-07-13T23:48], the nice domain is [2009-07-13,2009-07-14].

If the domain has more than two values, nicing the domain only affects the first and last value.

Parameters:

interval -

Returns:

the current scale

nice

public final TimeScale nice(Interval interval,
             int step)

Extends the domain so that it starts and ends on nice round values as determined by the specified time interval and step count.nd optional step count. As an alternative to specifying an explicit time interval, a numeric count can be specified, and a time interval will be chosen automatically to be consistent with scale.ticks.

This method typically modifies the scale's domain, and may only extend the bounds to the nearest round value.

Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [2009-07-13T00:02, 2009-07-13T23:48], the nice domain is [2009-07-13,2009-07-14].

If the domain has more than two values, nicing the domain only affects the first and last value.

Parameters:

interval -

step -

Returns:

the current scale

ticks

public final <T> Array<T> ticks(int count)

Returns representative dates from the scale's input domain.

The returned tick dates are uniformly spaced (modulo irregular time intervals, such as months and leap years), have human-readable values (such as midnights), and are guaranteed to be within the extent of the input domain.

Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data.

Approximately count ticks will be returned. The specified count is only a hint; the scale may return more or fewer values depending on the input domain.

For example, to create 10 default ticks, say: scale.ticks(10);

Parameters:

count - the number of ticks to be returned; it is only a hint; the scale may return more or fewer values depending on the input domain

Returns:

the array of reference ticks

ticks

public final <T> Array<T> ticks()

Alias for ticks(10).

Returns:

the array of reference ticks

ticks

public final <T> Array<T> ticks(Interval interval,
                 int steps)

Returns representative dates from the scale's input domain.

The returned tick dates are uniformly spaced (modulo irregular time intervals, such as months and leap years), have human-readable values (such as midnights), and are guaranteed to be within the extent of the input domain.

Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data.

To create ticks at 15-minute intervals, say:

 
 scale.ticks(D3.time().minute().utc(), 15);
 
 

Note: for UTC scales, make sure to use the appropriate UTC range method (such as d3.time.minutes.utc). The following time intervals are considered for automatic ticks:

• 1-, 5-, 15- and 30- Time.second() .
• 1-, 5-, 15- and 30-Time.minute().
• 1-, 3-, 6- and 12-Time.hour().
• 1- and 2-Time.day().
• 1-Time.week().
• 1- and 3-Time.month().
• 1-Time.year().

This set of time intervals is somewhat arbitrary and additional values may be added in the future.

Parameters:

interval - the interval of time

steps - the number of interval between each tick

Returns:

the array of reference ticks

tickFormat

public final Formatter tickFormat(int count)

Returns a time Formatter function suitable for displaying a tick value.

The specified count should have the same value as the count that is used to generate the tick values. You don't have to use the scale's built-in tick format, but it automatically computes the appropriate display based on the input date.

The following time formats are considered:

• %Y - for year boundaries, such as "2011".
• %B - for month boundaries, such as "February".
• %b %d - for week boundaries, such as "Feb 06".
• %a %d - for day boundaries, such as "Mon 07".
• %I %p - for hour boundaries, such as "01 AM".
• %I:%M - for minute boundaries, such as "01:23".
• :%S - for second boundaries, such as ":45".
• .%L - milliseconds for all other times, such as ".012".

By using multi-scale time formats, the default tick format provides both local and global context for each time interval.

For example, by showing the sequence [11 PM, Mon 07, 01 AM], the tick formatter reveals information about hours, dates, and day simultaneously—rather than just the hours.

If you'd prefer single-scale time formatting, you can always use your own d3.time.format. You can also roll your own custom multi-scale time format.

Parameters:

the - number of ticks to take into account to create the Formatter.

Returns:

a number format