d3-scale linear scale methods
Linear scale methods: linear.invert (compute domain value from range value), linear.domain (set input domain), linear.range (set output range), linear.rangeRound (set output range and enable rounding), linear.clamp (enable clamping), linear.unknown (set output for unknown inputs), linear.interpolate (set output interpolator), linear.ticks (compute representative domain values), linear.tickFormat (format ticks), linear.nice (extend domain to nice round numbers), linear.copy (copy scale).
scaleLinear constructor signature
scaleLinear(*domain*, *range*) constructs a new linear scale. If a single argument is specified, it is interpreted as the *range*. If either *domain* or *range* are not specified, each defaults to [0, 1]. Examples: d3.scaleLinear([0, 100], ["red", "blue"]) or d3.scaleLinear(["red", "blue"]) with default domain of [0, 1].
Linear scale mapping function
A linear scale instance is callable as *linear*(*value*). Given a *value* from the domain, it returns the corresponding value from the range. If the given *value* is outside the domain and clamping is not enabled, the mapping will be extrapolated such that the returned value is outside the range. Example: const x = d3.scaleLinear([10, 130], [0, 960]); x(20) returns 80; x(50) returns 320.
Color encoding with linear scale
Linear scales can map to color values. Example: const color = d3.scaleLinear([10, 100], ["brown", "steelblue"]); color(20) returns "rgb(154, 52, 57)"; color(50) returns "rgb(123, 81, 103)".
linear.invert method signature
*linear*.invert(*value*) given a *value* from the range, returns the corresponding value from the domain. Inversion is only supported if the range is numeric; if the range is not numeric, returns NaN. If the given *value* is outside the range and clamping is not enabled, the mapping may be extrapolated such that the returned value is outside the domain.
Inverting position encoding example
Example of inverting a position encoding: const x = d3.scaleLinear([10, 130], [0, 960]); x.invert(80) returns 20; x.invert(320) returns 50.
linear.domain method signature
*linear*.domain(*domain*) sets the scale's domain to the specified array of numbers and returns this scale. The array must contain two or more elements. If the elements are not numbers, they will be coerced to numbers. If *domain* is not specified, returns a copy of the scale's current domain.
Piecewise linear scale with diverging colors
Specifying more than two values in domain and range produces a piecewise scale. Example of diverging color scale: const color = d3.scaleLinear([-1, 0, 1], ["red", "white", "green"]); color(-0.5) returns "rgb(255, 128, 128)"; color(+0.5) returns "rgb(128, 192, 128)". Internally, piecewise scales perform a binary search for the range interpolator. The domain must be in ascending or descending order.
linear.range method signature
*linear*.range(*range*) sets the scale's range to the specified array of values and returns this scale. The array must contain two or more elements. Elements need not be numbers; any value supported by the underlying interpolator will work, though numeric ranges are required for invert. If *range* is not specified, returns a copy of the scale's current range.
linear.rangeRound method signature
*linear*.rangeRound(*range*) sets the scale's range to the specified array of values while also setting the scale's interpolator to interpolateRound; returns this scale. This is equivalent to linear.range(range).interpolate(d3.interpolateRound). The rounding interpolator is useful for avoiding antialiasing artifacts and can only be used with numeric ranges.
linear.clamp method signature
*linear*.clamp(*clamp*) enables or disables clamping and returns this scale. If clamping is disabled and the scale is passed a value outside the domain, it may return a value outside the range through extrapolation. If clamping is enabled, the return value is always within the range. Clamping also applies to *linear*.invert. If *clamp* is not specified, returns whether or not the scale currently clamps values.
Clamping example
Example of enabling clamping: const x = d3.scaleLinear([10, 130], [0, 960]); x(-10) returns -160 (outside range, clamping disabled). x.clamp(true); x(-10) returns 0 (clamped to range). x.invert(-160) returns 10 (clamped to domain).
linear.unknown method signature
*linear*.unknown(*value*) sets the output value of the scale for undefined or NaN input values and returns this scale. This is useful for specifying how missing or invalid data is displayed. If *value* is not specified, returns the current unknown value, which defaults to undefined.
Unknown value example
Example: const color = d3.scaleLinear([0, 100], ["red", "blue"]).unknown("#ccc"); color(NaN) returns "#ccc".
linear.interpolate method signature
*linear*.interpolate(*interpolate*) sets the scale's range interpolator factory. The scale's interpolator factory is used to create interpolators for each adjacent pair of values from the range; these interpolators then map a normalized domain parameter *t* in [0, 1] to the corresponding value in the range. If *factory* is not specified, returns the scale's current interpolator factory, which defaults to d3.interpolate.
Custom interpolator examples
Examples of specifying custom interpolators: const color = d3.scaleLinear(["red", "blue"]).interpolate(d3.interpolateHcl); or const color = d3.scaleLinear().domain([10, 100]).range(["brown", "steelblue"]).interpolate(d3.interpolateCubehelix.gamma(3));
Default interpolator reuses values pitfall
The default interpolator may reuse return values. If range values are objects, the value interpolator always returns the same object, modifying it in-place. This is typically acceptable when used to set an attribute or style, but if you need to store the scale's return value, you must specify your own interpolator or make a copy.
linear.ticks method signature
*linear*.ticks(*count*) returns approximately *count* representative values from the scale's domain. If *count* is not specified, it defaults to 10. The returned tick values are uniformly spaced, have human-readable values (such as multiples of powers of 10), and are guaranteed to be within the extent of the domain.
Ticks example
Example: const x = d3.scaleLinear([10, 100], ["red", "blue"]); x.ticks() returns [10, 20, 30, 40, 50, 60, 70, 80, 90, 100].
linear.tickFormat method signature
*linear*.tickFormat(*count*, *specifier*) returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values. The specified *count* should have the same value as the count used to generate the tick values. An optional *specifier* allows a custom format where the precision is automatically set by the scale.
tickFormat example
Example: const x = d3.scaleLinear([0.1, 1], ["red", "blue"]); const f = x.tickFormat(); f(0.1) returns "0.1"; f(1) returns "1.0". Example with custom specifier: const x = d3.scaleLinear([-1, 1], [0, 960]); const f = x.tickFormat(5, "+%"); x.ticks(5) returns [-1, -0.5, 0, 0.5, 1]; f(-0.5) returns "-50%".
linear.nice method signature
*linear*.nice(*count*) 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. An optional tick *count* argument allows greater control over the step size used to extend the bounds. If the domain has more than two values, nicing the domain only affects the first and last value.
linear.nice example
Example: const x = d3.scaleLinear([0.241079, 0.969679], [0, 960]).nice(); x.domain() returns [0.2, 1]. With count argument: const x = d3.scaleLinear([0.241079, 0.969679], [0, 960]).nice(40); x.domain() returns [0.24, 0.98].
linear.copy method signature
*linear*.copy() returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.
copy example
Example: const x1 = d3.scaleLinear([0, 100], ["red", "blue"]); const x2 = x1.copy();
tickFormat standalone function signature
d3.tickFormat(*start*, *stop*, *count*, *specifier*) returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values, as determined by d3.tickStep. An optional *specifier* allows a custom format where the precision is automatically set as appropriate for the tick interval.
tickFormat standalone function example
Example: const f = d3.tickFormat(0, 1, 20); f(1) returns "1.00". Example with custom specifier: const f = d3.tickFormat(-1, 1, 5, "+%"); f(-0.5) returns "-50%".
scaleIdentity constructor signature
d3.scaleIdentity(*range*) constructs a new identity scale with the specified range (and by extension, domain). If *range* is not specified, it defaults to [0, 1]. 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.
scaleIdentity restrictions
Identity scales do not support rangeRound, clamp, or interpolate methods. These scales are occasionally useful when working with pixel coordinates, such as in conjunction with an axis.
scaleIdentity example
Example: const x = d3.scaleIdentity([0, 960]);
scaleRadial constructor signature
d3.scaleRadial(*domain*, *range*) constructs a new radial scale with the specified domain and range. If *domain* or *range* is not specified, each defaults to [0, 1].
scaleRadial properties and restrictions
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.
scaleRadial example
Example: const r = d3.scaleRadial([100, 200], [0, 480]);
Linear scale formula
Linear scales map a continuous, quantitative input domain to a continuous output range using a linear transformation (translate and scale). Each range value *y* can be expressed as a function of the domain value *x*: *y* = *mx* + *b*. If the range is also numeric, the mapping may be inverted.
Piecewise scale domain requirements
For piecewise scales, the domain must be in ascending or descending order. Internally, a piecewise scale performs a binary search for the range interpolator corresponding to the given domain value. If the domain and range have different lengths *N* and *M*, only the first *min(N,M)* elements in each are observed.
Scale inversion precision note
For a valid value *y* in the range, *linear*(*linear*.invert(*y*)) approximately equals *y*; similarly, for a valid value *x* in the domain, *linear*.invert(*linear*(*x*)) approximately equals *x*. The scale and its inverse may not be exact due to the limitations of floating point precision.
Nicing domain behavior
Nicing a scale only modifies the current domain; it does not automatically nice domains that are subsequently set using *linear*.domain. You must re-nice the scale after setting the new domain, if desired.