d3-scale

117 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

d3-scale module structure

d3-scale provides encodings that map abstract data to visual representation. It includes linear scales (including identity and radial), power scales (pow, sqrt), and log scales, each with configuration methods for domain, range, clamping, interpolation, and ticks.

Band scales for categorical or ordinal position encoding

Band scales are used for categorical or ordinal data as a position encoding.

Point scales for categorical or ordinal position encoding

Point scales are used for categorical or ordinal data as a position encoding.

Threshold scales for discrete encoding

Threshold scales are used for quantitative data as a discrete encoding.

Sequential scales for sequential color encoding

Sequential scales are used for quantitative data as a sequential color encoding.

Quantize scales for discrete encoding

Quantize scales are used for quantitative data as a discrete encoding.

Diverging scales for diverging color encoding

Diverging scales are used for quantitative data as a diverging color encoding.

Ordinal scales for categorical or ordinal data

Ordinal scales are used for encoding categorical or ordinal data.

Scale purpose and use cases

Scales map a dimension of abstract data to a visual representation. They are most often used for encoding data as position, such as mapping time and temperature to horizontal and vertical position in a scatterplot. Scales can represent virtually any visual encoding, such as color, stroke width, or symbol size, and can work with virtually any type of data, including named categorical data or discrete data that requires sensible breaks.

Linear scales for quantitative data

Linear scales are used for encoding quantitative data.

Time scales for time-series data

Time scales are used for encoding time-series data.

Pow scales for wide-range quantitative data

Pow scales are used for quantitative data that has a wide range.

Log scales for wide-range quantitative data

Log scales are used for quantitative data that has a wide range.

Symlog scales for wide-range quantitative data

Symlog scales are used for quantitative data that has a wide range.

d3-axis for visualizing scale encoding

The d3-axis module is used for visualizing a scale's encoding. The scale methods ticks() and tickFormat() can also be used for this purpose.

d3-scale-chromatic for color schemes

The d3-scale-chromatic module provides color schemes for use with scales.

diverging.range method

diverging.range(range) sets the scale's output range. If range is specified, the given three-element array is converted to an interpolator function using piecewise. Example: d3.scaleDiverging().range(['blue', 'white', 'red'])

scaleDiverging signature and basic construction

scaleDiverging(domain, interpolator) 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.

Diverging scale domain requirements

A diverging scale's domain must be numeric and must contain exactly three values. The three values represent the extreme negative value, the neutral value, and the extreme positive value.

scaleDiverging with interpolator array

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. Example: d3.scaleDiverging(['blue', 'white', 'red'])

scaleDiverging interpolator range mapping

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.

diverging.interpolator method

diverging.interpolator(interpolator) sets the scale's interpolator to the specified function if interpolator is specified, or returns the scale's current interpolator if no argument is provided.

diverging.rangeRound method

diverging.rangeRound(range) sets the scale's output range and implicitly uses interpolateRound as the interpolator, analogous to linear.rangeRound.

scaleDivergingPow signature

scaleDivergingPow(domain, range) returns a new diverging scale with an exponential transform, analogous to a power scale.

scaleDivergingSqrt signature

scaleDivergingSqrt(domain, range) returns a new diverging scale with a square-root transform, analogous to a sqrt scale.

scaleDivergingSymlog signature

scaleDivergingSymlog(domain, range) returns a new diverging scale with a symmetric logarithmic transform, analogous to a symlog scale.

Diverging scales do not expose invert and interpolate methods

Diverging scales do not expose invert and interpolate methods, unlike linear scales.

Diverging scales typical use case

Diverging scales are typically used for a color encoding. The d3-scale-chromatic module provides additional color interpolators for diverging scales.

scaleLog signature and defaults

scaleLog(domain, range) constructs a new log scale. The domain defaults to [1, 10] and range defaults to [0, 1]. The base defaults to 10, default interpolator is used, and clamping is disabled by default.

Log scale domain restrictions

A log scale domain must be strictly-positive or strictly-negative; it must not include or cross zero. For a positive domain, the scale has well-defined behavior for positive values. For a negative domain, the scale has well-defined behavior for negative values where input and output values are implicitly multiplied by -1. The behavior is undefined if you pass a value of opposite sign.

Log scale mapping formula

The mapping from domain value x to range value y in a log scale is expressed as: y = m log(x) + b.

log.base method

log.base(base) sets the base for the logarithmic scale. If base is not specified, it returns the current base, which defaults to 10. The base affects which ticks are chosen but does not affect the encoding of the scale itself.

log.ticks method

log.ticks(count) returns tick values customized for a log scale. If the base is an integer, returned ticks are uniformly spaced within each integer power of base; otherwise one tick per power of base is returned. Ticks are guaranteed to be within the domain extent. If orders of magnitude in the domain exceed count, at most one tick per power is returned. If count is not specified, it defaults to 10.

log.tickFormat method

log.tickFormat(count, specifier) returns a formatter for log scale ticks. The count typically matches the count used to generate tick values. If there are too many ticks, the formatter may return empty strings for some labels, but ticks are still shown. You can provide a format specifier like "$,f"; if the specifier lacks a defined precision, the scale sets it automatically. Specify count as Infinity to disable filtering.

log.nice method

log.nice() extends the domain to integer powers of the base. If the domain has more than two values, nicing affects only the first and last value. Nicing modifies only the current domain; you must re-nice after setting a new domain if desired.

scaleLog example with base 2

const x = d3.scaleLog([1, 1024], [0, 960]).base(2);

scaleLog example with ticks

const x = d3.scaleLog([1, 100], [0, 960]); const T = x.ticks(); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100]

log.tickFormat example

const x = d3.scaleLog([1, 100], [0, 960]); const T = x.ticks(); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, …] const f = x.tickFormat(); T.map(f); // ["1", "2", "3", "4", "5", "", "", "", "", "10", …]

log.nice example

const x = d3.scaleLog([0.201479, 0.996679], [0, 960]).nice(); x.domain(); // [0.1, 1]

scaleOrdinal constructor

Constructs a new ordinal scale with the specified domain and range. Signature: scaleOrdinal(domain, range). If domain is not specified, it defaults to an empty array. If range is not specified, it defaults to an empty array; an ordinal scale always returns undefined until a non-empty range is defined. Example: const color = d3.scaleOrdinal(["a", "b", "c"], ["red", "green", "blue"]).

Ordinal scale invoke function

Given a value in the input domain, returns the corresponding value in the output range. Signature: ordinal(value). If the given value is not in the scale's domain and the unknown value is implicit (the default), then the value is implicitly added to the domain and the next-available value in the range is assigned to it. Example: color("a") returns "red".

ordinal.domain method

Sets or gets the domain of an ordinal scale. If domain is specified, sets the domain to the specified array of values. If not specified, returns the current domain. The first element in domain is mapped to the first element in the range, the second domain value to the second range value, and so on. Domain values are stored internally in an InternMap from primitive value to index. Setting the domain is optional if the unknown value is implicit; the domain will be inferred implicitly from usage by assigning each unique value passed to the scale a new value from the range. Example: color.domain(["a", "b", "c"]).

ordinal.range method

Sets or gets the range of an ordinal scale. If range is specified, sets the range to the specified array of values. If not specified, returns the current range. The first element in the domain is mapped to the first element in range, the second domain value to the second range value, and so on. If there are fewer elements in the range than in the domain, the scale will reuse values from the start of the range. Example: const color = d3.scaleOrdinal().range(["red", "green", "blue"]).

ordinal.unknown method

Sets or gets the output value of the scale for unknown input values. If value is specified, sets the output value for unknown input values and returns the scale. If not specified, returns the current unknown value, which defaults to d3.scaleImplicit. The implicit value enables implicit domain construction. Example: const color = d3.scaleOrdinal(["a", "b", "c"], d3.schemeTableau10).unknown(null); color("d") returns null.

ordinal.copy method

Returns an exact copy of an ordinal scale. Changes to the original scale will not affect the returned scale, and vice versa. Signature: ordinal.copy(). Example: const c2 = c1.copy().

scaleImplicit special value

A special value for ordinal.unknown that enables implicit domain construction: unknown values are implicitly added to the domain. When a scale's unknown value is set to scaleImplicit (the default), querying the scale with a value not in the domain automatically adds that value to the domain and assigns it the next available range value. Example: color.unknown() returns d3.scaleImplicit.

Ordinal scale behavior with sparse ranges

If there are fewer elements in the range than in the domain, the ordinal scale will reuse values from the start of the range. This wraps around the range array to accommodate more domain values than range values.

Implicit domain inference pitfall

When inferring the domain implicitly from usage (the default behavior with scaleImplicit), the resulting domain order depends on the order in which values are queried. This makes the behavior non-deterministic and dependent on ordering. An explicit domain is recommended for deterministic behavior.

scalePow constructor signature and defaults

scalePow(domain, range) constructs a new pow scale. If domain or range are not specified, each defaults to [0, 1]. The default exponent is 1, the default interpolator is the standard interpolator from d3-interpolate, and clamping is disabled by default.

Power scale formula

Power scales apply an exponential transform to the input domain value before computing the output range value. The relationship is expressed as y = mx^k + b, where k is the exponent value. Power scales also support negative domain values, in which case the input value and the resulting output value are multiplied by -1.

scaleSqrt constructor signature and defaults

scaleSqrt(domain, range) constructs a new pow scale with the exponent set to 0.5. If domain or range are not specified, each defaults to [0, 1]. This is a convenience method equivalent to d3.scalePow(…).exponent(0.5).

pow.exponent getter and setter

The exponent method on a pow scale either sets or gets the exponent value. If exponent is specified, it sets the current exponent to the given numeric value and returns the scale. If exponent is not specified, it returns the current exponent, which defaults to 1. If the exponent is 1, the pow scale is effectively a linear scale.

scalePow example with exponent

Example creating a pow scale with domain [0, 100], range ["red", "blue"], and exponent 2: const x = d3.scalePow([0, 100], ["red", "blue"]).exponent(2);

scaleSqrt example

Example creating a square root scale with domain [0, 100] and range ["red", "blue"]: const x = d3.scaleSqrt([0, 100], ["red", "blue"]);

quantize().range() method

range(range) sets the scale's range to the specified array of values if range is specified. The array may contain any number of discrete values, and the elements need not be numbers; any value or type will work. If range is not specified, returns the scale's current range.

scaleQuantize constructor

scaleQuantize(domain, range) constructs a new quantize scale with the specified domain and range. If either domain or range is not specified, each defaults to [0, 1]. Example: const color = d3.scaleQuantize([0, 100], d3.schemeBlues[9]).

Quantize scale value mapping

A quantize scale returns the corresponding value in the output range for a given value in the input domain. The continuous input domain is divided into uniform segments based on the number of values in the output range. Each range value y can be expressed as a quantized linear function of the domain value x: y = m round(x) + b.

quantize().invertExtent() method

invertExtent(value) returns the extent of values in the domain [x0, x1] for the corresponding value in the range; this is the inverse of the scale function. This method is useful for interaction, such as determining the value in the domain that corresponds to the pixel location under the mouse. Example: width.invertExtent(2) returns [40, 70].

quantize().domain() method

domain(domain) sets the scale's domain to the specified two-element array of numbers if domain is specified. If the elements are not numbers, they will be coerced to numbers. The numbers must be in ascending order or the behavior is undefined. If domain is not specified, returns the scale's current domain.

quantize().thresholds() method

thresholds() returns the array of computed thresholds within the domain. The number of returned thresholds is one less than the length of the range: values less than the first threshold are assigned the first element in the range, whereas values greater than or equal to the last threshold are assigned the last element in the range. Example: color.thresholds() returns [0.2, 0.4, 0.6, 0.8].

Give your agent this brain