d3-scale

# pow.invert(value) · Source, Examples

See continuous.invert.

# pow.exponent([exponent]) · Source, Examples

If exponent is specified, sets the current exponent to the given numeric value. If exponent is not specified, returns the current exponent, which defaults to 1. (Note that this is effectively a linear scale until you set a different exponent.)

# pow.domain([domain]) · Source, Examples

See continuous.domain.

# pow.range([range]) · Source, Examples

See continuous.range.

# pow.rangeRound([range]) · Source, Examples

See continuous.rangeRound.

# pow.clamp(clamp) · Source, Examples

# pow.interpolate(interpolate) · Source, Examples

See continuous.interpolate.

# pow.ticks([count]) · Source, Examples

See continuous.ticks.

# pow.tickFormat([count[, specifier]]) · Source, Examples

See continuous.tickFormat.

# pow.nice([count]) · Source, Examples

See continuous.nice.

# pow.copy() · Source, Examples

# d3.scaleSqrt([[domain, ]range]) · Source, Examples

Constructs a new continuous power scale with the specified domain and range, the exponent 0.5, the default interpolator and clamping disabled. If either domain or range are not specified, each defaults to [0, 1]. This is a convenience method equivalent to d3.scalePow(…).exponent(0.5).

Log Scales

Log scales are similar to linear scales, except a logarithmic transform is applied to the input domain value before the output range value is computed. The mapping to the range value y can be expressed as a function of the domain value x: y = m log(x) + b.

As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative; the domain must not include or cross zero. A log scale with a positive domain has a well-defined behavior for positive values, and a log scale with a negative domain has a well-defined behavior for negative values. (For a negative domain, input and output values are implicitly multiplied by -1.) The behavior of the scale is undefined if you pass a negative value to a log scale with a positive domain or vice versa.

# d3.scaleLog([[domain, ]range]) · Source, Examples

Constructs a new continuous scale with the specified domain and range, the base 10, the default interpolator and clamping disabled. If domain is not specified, it defaults to [1, 10]. If range is not specified, it defaults to [0, 1].

# log(value) · Source, Examples

# log.invert(value) · Source, Examples

See continuous.invert.

# log.base([base]) · Source, Examples

If base is specified, sets the base for this logarithmic scale to the specified value. If base is not specified, returns the current base, which defaults to 10.

# log.domain([domain]) · Source, Examples

See continuous.domain.

# log.range([range]) · Source, Examples

See continuous.range.

# log.rangeRound([range]) · Source, Examples

See continuous.rangeRound.

# log.clamp(clamp) · Source, Examples

# log.interpolate(interpolate) · Source, Examples

See continuous.interpolate.

# log.ticks([count]) · Source, Examples

Like continuous.ticks, but customized for a log scale. If the base is an integer, the returned ticks are uniformly spaced within each integer power of base; otherwise, one tick per power of base is returned. The returned ticks are guaranteed to be within the extent of the domain. If the orders of magnitude in the domain is greater than count, then at most one tick per power is returned. Otherwise, the tick values are unfiltered, but note that you can use log.tickFormat to filter the display of tick labels. If count is not specified, it defaults to 10.

# log.tickFormat([count[, specifier]]) · Source, Examples

Like continuous.tickFormat, but customized for a log scale. The specified count typically has the same value as the count that is used to generate the tick values. If there are too many ticks, the formatter may return the empty string for some of the tick labels; however, note that the ticks are still shown. To disable filtering, specify a count of Infinity. When specifying a count, you may also provide a format specifier or format function. For example, to get a tick formatter that will display 20 ticks of a currency, say log.tickFormat(20, "$,f"). If the specifier does not have a defined precision, the precision will be set automatically by the scale, returning the appropriate format. This provides a convenient way of specifying a format whose precision will be automatically set by the scale.

# log.nice() · Source, Examples

Like continuous.nice, except extends the domain to integer powers of base. For example, for a domain of [0.201479…, 0.996679…], and base 10, the nice domain is [0.1, 1]. If the domain has more than two values, nicing the domain only affects the first and last value.

# log.copy() · Source, Examples

Symlog Scales

See A bi-symmetric log transformation for wide-range data by Webber for more.

# d3.scaleSymlog([[domain, ]range]) · Source, Examples

Constructs a new continuous scale with the specified domain and range, the constant 1, the default interpolator and clamping disabled. If domain is not specified, it defaults to [0, 1]. If range is not specified, it defaults to [0, 1].

# symlog.constant([constant]) · Source, Examples

If constant is specified, sets the symlog constant to the specified number and returns this scale; otherwise returns the current value of the symlog constant, which defaults to 1. See “A bi-symmetric log transformation for wide-range data” by Webber for more.

Identity Scales

Identity scales are a special case of linear scales where the domain and range are identical; the scale and its invert method are thus the identity function. These scales are occasionally useful when working with pixel coordinates, say in conjunction with an axis. Identity scales do not support rangeRound, clamp or interpolate.

# d3.scaleIdentity([range]) · Source, Examples

Constructs a new identity scale with the specified domain and range. If range is not specified, it defaults to [0, 1].

Radial Scales

Radial scales are a variant of linear scales where the range is internally squared so that an input value corresponds linearly to the squared output value. These scales are useful when you want the input value to correspond to the area of a graphical mark and the mark is specified by radius, as in a radial bar chart. Radial scales do not support interpolate.

# d3.scaleRadial([[domain, ]range]) · Source, Examples

Constructs a new radial scale with the specified domain and range. If domain or range is not specified, each defaults to [0, 1].

Time Scales

Time scales are a variant of linear scales that have a temporal domain: domain values are coerced to dates rather than numbers, and invert likewise returns a date. Time scales implement ticks based on calendar intervals, taking the pain out of generating axes for temporal domains.

For example, to create a position encoding:

var x = d3.scaleTime()
    .domain([new Date(2000, 0, 1), new Date(2000, 0, 2)])
    .range([0, 960]);

x(new Date(2000, 0, 1,  5)); // 200
x(new Date(2000, 0, 1, 16)); // 640
x.invert(200); // Sat Jan 01 2000 05:00:00 GMT-0800 (PST)
x.invert(640); // Sat Jan 01 2000 16:00:00 GMT-0800 (PST)

For a valid value y in the range, time(time.invert(y)) equals y; similarly, for a valid value x in the domain, time.invert(time(x)) equals x. The invert method is useful for interaction, say to determine the value in the domain that corresponds to the pixel location under the mouse.

# d3.scaleTime([[domain, ]range]) · Source, Examples

Constructs a new time scale with the specified domain and range, the default interpolator and clamping disabled. If domain is not specified, it defaults to [2000-01-01, 2000-01-02]. If range is not specified, it defaults to [0, 1].

# time(value) · Source, Examples

# time.invert(value) · Source, Examples

See continuous.invert.

# time.domain([domain]) · Source, Examples

See continuous.domain.

# time.range([range]) · Source, Examples

See continuous.range.

# time.rangeRound([range]) · Source, Examples

See continuous.rangeRound.

# time.clamp(clamp) · Source, Examples

# time.interpolate(interpolate) · Source, Examples

See continuous.interpolate.

# time.ticks([count]) · Source, Examples
# time.ticks([interval])

Returns representative dates from the scale’s domain. The returned tick values are uniformly-spaced (mostly), have sensible values (such as every day at midnight), and are guaranteed to be within the extent of the domain. Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data.

An optional count may be specified to affect how many ticks are generated. If count is not specified, it defaults to 10. The specified count is only a hint; the scale may return more or fewer values depending on the domain. For example, to create ten default ticks, say:

var x = d3.scaleTime();

x.ticks(10);
// [Sat Jan 01 2000 00:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 03:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 06:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 09:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 12:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 15:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 18:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 21:00:00 GMT-0800 (PST),
//  Sun Jan 02 2000 00:00:00 GMT-0800 (PST)]

The following time intervals are considered for automatic ticks:

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

In lieu of a count, a time interval may be explicitly specified. To prune the generated ticks for a given time interval, use interval.every. For example, to generate ticks at 15-minute intervals:

var x = d3.scaleTime()
    .domain([new Date(2000, 0, 1, 0), new Date(2000, 0, 1, 2)]);

x.ticks(d3.timeMinute.every(15));
// [Sat Jan 01 2000 00:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:15:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:30:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:45:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:15:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:30:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:45:00 GMT-0800 (PST),
//  Sat Jan 01 2000 02:00:00 GMT-0800 (PST)]

Alternatively, pass a test function to interval.filter:

x.ticks(d3.timeMinute.filter(function(d) {
  return d.getMinutes() % 15 === 0;
}));

Note: in some cases, such as with day ticks, specifying a step can result in irregular spacing of ticks because time intervals have varying length.

# time.tickFormat([count[, specifier]]) · Source, Examples
# time.tickFormat([interval[, specifier]])

Returns a time format function suitable for displaying tick values. The specified count or interval is currently ignored, but is accepted for consistency with other scales such as continuous.tickFormat. If a format specifier is specified, this method is equivalent to format. If specifier is not specified, the default time format is returned. The default multi-scale time format chooses a human-readable representation based on the specified date as follows:

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

Although somewhat unusual, this default behavior has the benefit of providing both local and global context: for example, formatting a sequence of ticks as [11 PM, Mon 07, 01 AM] reveals information about hours, dates, and day simultaneously, rather than just the hours [11 PM, 12 AM, 01 AM]. See d3-time-format if you’d like to roll your own conditional time format.

# time.nice([count]) · Source, Examples
# time.nice([interval])

Extends the domain so that it starts and ends on nice round values. This method typically modifies the scale’s domain, and may only extend the bounds to the nearest round value. See continuous.nice for more.

An optional tick count argument allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain. Alternatively, a time interval may be specified to explicitly set the ticks. If an interval is specified, an optional step may also be specified to skip some ticks. For example, time.nice(d3.timeSecond.every(10)) will extend the domain to an even ten seconds (0, 10, 20, etc.). See time.ticks and interval.every for further detail.

Nicing is useful if the domain is computed from data, say using extent, 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.

# time.copy() · Source, Examples

# d3.scaleUtc([[domain, ]range]) · Source, Examples

Equivalent to scaleTime, but the returned time scale operates in Coordinated Universal Time rather than local time.

Sequential Scales

Sequential scales, like diverging scales, are similar to continuous scales in that they map a continuous, numeric input domain to a continuous output range. However, unlike continuous scales, the input domain and output range of a sequential scale always has exactly two elements, and the output range is typically specified as an interpolator rather than an array of values. These scales do not expose invert and interpolate methods.

# d3.scaleSequential([[domain, ]interpolator]) · Source, Examples

Constructs a new sequential scale with the specified domain and interpolator function or array. If domain is not specified, it defaults to [0, 1]. If interpolator is not specified, it defaults to the identity function. When the scale is applied, the interpolator will be invoked with a value typically in the range [0, 1], where 0 represents the minimum value and 1 represents the maximum value. For example, to implement the ill-advised HSL rainbow scale:

var rainbow = d3.scaleSequential(function(t) {
  return d3.hsl(t * 360, 1, 0.5) + "";
});

A more aesthetically-pleasing and perceptually-effective cyclical hue encoding is to use d3.interpolateRainbow:

var rainbow = d3.scaleSequential(d3.interpolateRainbow);

If interpolator is an array, it represents the scale’s two-element output range and is converted to an interpolator function using d3.interpolate.

# sequential(value) · Source, Examples

# sequential.domain([domain]) · Source, Examples

See continuous.domain. Note that a sequential scale’s domain must be numeric and must contain exactly two values.

# sequential.clamp([clamp]) · Source, Examples

# sequential.interpolator([interpolator]) · Source, Examples

If interpolator is specified, sets the scale’s interpolator to the specified function. If interpolator is not specified, returns the scale’s current interpolator.

# sequential.range([range]) · Source, Examples

See continuous.range. If range is specified, the given two-element array is converted to an interpolator function using d3.interpolate.

# sequential.rangeRound([range]) · Source, Examples

See continuous.rangeRound. If range is specified, implicitly uses d3.interpolateRound as the interpolator.

# sequential.copy() · Source, Examples

# d3.scaleSequentialLog([[domain, ]range]) · Source, Examples

A sequential scale with a logarithmic transform, analogous to a log scale.

# d3.scaleSequentialPow([[domain, ]range]) · Source, Examples

A sequential scale with an exponential transform, analogous to a power scale.

# d3.scaleSequentialSqrt([[domain, ]range]) · Source, Examples

A sequential scale with a square-root transform, analogous to a d3.scaleSqrt.

# d3.scaleSequentialSymlog([[domain, ]range]) · Source, Examples

A sequential scale with a symmetric logarithmic transform, analogous to a symlog scale.

# d3.scaleSequentialQuantile([[domain, ]range]) · Source, Examples

A sequential scale using a p-quantile transform, analogous to a quantile scale.

# sequentialQuantile.quantiles(n) · Source, Examples

Returns an array of n + 1 quantiles. For example, if n = 4, returns an array of five numbers: the minimum value, the first quartile, the median, the third quartile, and the maximum.

Diverging Scales

Diverging scales, like sequential scales, are similar to continuous scales in that they map a continuous, numeric input domain to a continuous output range. However, unlike continuous scales, the input domain and output range of a diverging scale always has exactly three elements, and the output range is typically specified as an interpolator rather than an array of values. These scales do not expose invert and interpolate methods.

# d3.scaleDiverging([[domain, ]interpolator]) · Source, Examples

Constructs a new diverging scale with the specified domain and interpolator function or array. If domain is not specified, it defaults to [0, 0.5, 1]. If interpolator is not specified, it defaults to the identity function. When the scale is applied, the interpolator will be invoked with a value typically in the range [0, 1], where 0 represents the extreme negative value, 0.5 represents the neutral value, and 1 represents the extreme positive value. For example, using d3.interpolateSpectral:

var spectral = d3.scaleDiverging(d3.interpolateSpectral);

If interpolator is an array, it represents the scale’s three-element output range and is converted to an interpolator function using d3.interpolate and d3.piecewise.

# diverging(value) · Source, Examples

# diverging.domain([domain]) · Source, Examples

See continuous.domain. Note that a diverging scale’s domain must be numeric and must contain exactly three values. The default domain is [0, 0.5, 1].

# diverging.clamp([clamp]) · Source, Examples

# diverging.interpolator([interpolator]) · Source, Examples

If interpolator is specified, sets the scale’s interpolator to the specified function. If interpolator is not specified, returns the scale’s current interpolator.

# diverging.range([range]) · Source, Examples

See continuous.range. If range is specified, the given three-element array is converted to an interpolator function using d3.interpolate and d3.piecewise.

# diverging.rangeRound([range]) · Source, Examples

See continuous.range. If range is specified, implicitly uses d3.interpolateRound as the interpolator.

# diverging.copy() · Source, Examples