Scales are a convenient abstraction for a fundamental task in visualization: mapping a dimension of abstract data to a visual representation. Although most often used for position-encoding quantitative data, such as mapping a measurement in meters to a position in pixels for dots in a scatterplot, scales can represent virtually any visual encoding, such as diverging colors, stroke widths, or symbol size. Scales can also be used with virtually any type of data, such as named categorical data or discrete data that requires sensible breaks.
For continuous quantitative data, you typically want a linear scale. (For time series data, a time scale.) If the distribution calls for it, consider transforming data using a power or log scale. A quantize scale may aid differentiation by rounding continuous data to a fixed set of discrete values; similarly, a quantile scale computes quantiles from a sample population, and a threshold scale allows you to specify arbitrary breaks in continuous data. Several built-in sequential color schemes are also provided.
For discrete ordinal (ordered) or categorical (unordered) data, an ordinal scale specifies an explicit mapping from a set of data values to a corresponding set of visual attributes (such as colors). The related band and point scales are useful for position-encoding ordinal data, such as bars in a bar chart or dots in an categorical scatterplot. Several built-in categorical color scales are also provided.
Scales have no intrinsic visual representation. However, most scales can generate and format ticks for reference marks to aid in the construction of axes.
Type alias for Continuous Scales. These map a (Float, Float) domain to a
(Float, Float) range.
Linear scales are a good default choice for continuous quantitative data because they preserve proportional differences. Each range value y can be expressed as a function of the domain value x: y = mx + b.
scale = linear ( 0, 1 ) ( 50, 100 )
convert scale 0.5 == 75Log 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.
The arguments are base, domain and range.
scale = log 10 ( 10, 1000 ) ( 50, 100 )
convert scale 100 == 75Identity 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 or brush.
This is identical to a ContinuousScale, except the domain values are Dates instead of Floats.
Time scales are a variant of linear scales that have a temporal domain: domain values are dates rather than floats, and invert likewise returns a date. Time scales implement ticks based on calendar intervals, taking the pain out of generating axes for temporal domains.
Continuous scales support the following operations:
Given a value from the domain, returns the corresponding value from the range. If the given value is outside the domain the mapping may be extrapolated such that the returned value is outside the range.
Given a value from the range, returns the corresponding value from the domain. Inversion is useful for interaction, say to determine the data value corresponding to the position of the mouse.
Retrieve the domain of the scale.
Retrieve the range of the scale.
Retrieve the minimum and maximum elements from the range.
The second argument controls approximately how many representative values from the scale’s domain to return. A good default value 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 are often used to display reference lines, or tick marks, in conjunction with the visualized data. The specified count is only a hint; the scale may return more or fewer values depending on the domain.
scale = linear ( 10, 100 ) ( 50, 100 )
ticks scale 10 == [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]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 that is used to generate the tick values.
Enables clamping on the domain, meaning the return value of the scale is always within the scale’s range.
scale = linear ( 10, 100 ) ( 50, 100 )
convert scale 1 == 45
convert (clamp scale) 1 == 50Returns a new scale which extends the domain so that it lands on round values. The second argument is the same as you would pass to ticks.
scale = linear ( 0.5, 99 ) ( 50, 100 )
domain (nice scale 10) == (0, 100)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 output range of a sequential scale is fixed by its interpolator function.
Type alias for sequential scales
Sequential scales support the following operations:
Given a value from the domain, returns the corresponding value from the range. If the given value is outside the domain the mapping may be extrapolated such that the returned value is outside the range.
Retrieve the domain of the scale.
Retrieve the minimum and maximum elements from the range.
Quantize scales are similar to linear scales, except they use a discrete rather
than continuous range. The continuous input domain is divided into uniform
segments based on the number of values in (i.e., the cardinality of) 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.
Type alias for quantize scales
Quantize scales support the following operations:
Given a value from the domain, returns the corresponding value from the range. If the given value is outside the domain the mapping may be extrapolated such that the returned value is outside the range.
Returns the extent of values in the domain for the corresponding value in the range. This method is useful for interaction, say to determine the value in the domain that corresponds to the pixel location under the mouse.
Retrieve the domain of the scale.
Retrieve the range of the scale.
Retrieve the minimum and maximum elements from the range.
The second argument controls approximately how many representative values from the scale’s domain to return. A good default value 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 are often used to display reference lines, or tick marks, in conjunction with the visualized data. The specified count is only a hint; the scale may return more or fewer values depending on the domain.
scale = linear ( 10, 100 ) ( 50, 100 )
ticks scale 10 == [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]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 that is used to generate the tick values.
Returns a new scale which extends the domain so that it lands on round values. The second argument is the same as you would pass to ticks.
scale = linear ( 0.5, 99 ) ( 50, 100 )
domain (nice scale 10) == (0, 100)
This API is highly polymorphic as each scale has different functions exposed. This is still done in a convenient and type-safe manner, however the cost is a certain ugliness and complexity of the type signatures. For this reason the supported functions are listed again for each category. It is best to ignore the type signatures when learning about the library.