Using standalone scale objects in plots
To apply a standalone scale object to a plot, pass it to Plot.plot as the corresponding scale options, such as color.
Observable Plot · all subjects
scales
74 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Scale definition and purpose
Scales convert abstract values such as time or temperature to visual values such as position or color. Marks bind channels to scales; for example, the line's x channel is bound to the x scale. A scale operates as a function that takes an abstract value and returns the corresponding visual value.
Scale domain and range
The domain is the abstract values that the scale expects as input. For quantitative or temporal data, it is typically expressed as an extent such as [start, end]. For ordinal or nominal data, it is an array of values such as names or categories. The range is the visual values that the scale generates as output. For position scales, the range is typically an extent such as [left, right]; for color scales, it might be a continuous extent or an array of discrete colors.
Quantitative scale types for mathematical transforms
For quantitative data, the following scale types apply mathematical transforms: linear (default, linear translate and scale), pow (power/exponential transform), sqrt (square-root transform, pow with exponent 0.5), log (logarithmic transform), symlog (bi-symmetric logarithmic transform per Webber et al.).
Temporal scale types
For temporal data (dates), two variants of a linear scale are supported: utc (default, recommended for UTC time), and time (local time). UTC is recommended over local time as charts in UTC time are guaranteed to appear consistently to all viewers whereas charts in local time depend on the viewer's time zone.
Ordinal and categorical scale types
For ordinal data (e.g., strings), use the ordinal scale type or the point or band position scale types. The categorical scale type is also supported; it is equivalent to ordinal except as a color scale, where it provides a different default color scheme.
Identity scale type
The identity scale type allows opting out of a scale. This is useful if you wish to specify literal colors or pixel positions within a mark channel rather than relying on the scale to convert abstract values into visual values. For position scales (x and y), an identity scale is still quantitative and may produce an axis, yet unlike a linear scale the domain and range are fixed based on the plot layout.
Log scale base option
Log scales support a base option, say for powers of two. This does not affect the scale's encoding, but it does change where ticks are shown. Log scales default to base-10 ticks with SI-prefix notation.
Pow scale exponent option
The pow scale supports the exponent option, which defaults to 1 (for a linear scale). The sqrt scale is shorthand for a pow scale with exponent 0.5.
Symlog scale constant option
A symlog transform is a bi-symmetric logarithmic transform that works well with wide-range values that include zero. It can be configured with the scale.constant option (default 1).
Continuous scale clamp option
Continuous scales support a clamp option which, if true, clamps input values to the scale's domain before scaling. This is useful for preventing marks from escaping the chart area. Clamping is typically used in conjunction with setting an explicit domain since if the domain is inferred, no values will be outside the domain.
Continuous scale interpolate option
Continuous scales support an interpolate option specified either as a function that takes a single argument t in [0, 1] and returns the corresponding value from the range, or as a two-argument function that takes a pair of values [start, end] from the range and returns the corresponding interpolator from [0, 1], typically mapping 0 to start and 1 to end.
Piecewise domain for continuous scales
Continuous scales support a piecewise domain specified as an array of n domain values (with n >= 2), with a corresponding range having the same number of values. Each segment of the domain is mapped to the matching segment of the range using the scale's interpolator. When the domain has n > 2 elements and the range has two elements, the latter is automatically split into n - 1 segments of equal size. You must specify the scale's continuous type since a scale specified with a domain having more than two elements otherwise defaults to an ordinal scale.
Point scale definition and use
A point scale divides space into uniformly-spaced discrete values. It is commonly used for scatterplots (a dot mark) of ordinal data. It is the default scale type for ordinal data on the x and y scale.
Band scale definition and use
A band scale divides space into uniformly-spaced and -sized discrete intervals. It is commonly used for bar charts (bar marks).
Point and band scale padding option
Point and band scales support a padding option (proportion in [0, 1]) which specifies how much of the range to reserve to inset first and last point or band. For point scales, padding defaults to 0.5 (the gap between the first point and the edge is half the distance of the gap between points). For band scales, padding defaults to 0.1 (10% of available space reserved for separating bands).
Band scale paddingInner and paddingOuter options
For a band scale, you can further fine-tune padding with paddingInner (how much of the range to reserve to separate adjacent bands) and paddingOuter (how much of the range to reserve to inset first and last band), both proportions in [0, 1].
Ordinal position scale align option
Ordinal position scales support an align option (proportion in [0, 1]) which specifies where to distribute points or bands: 0 = at start, 0.5 = at middle, 1 = at end. Align defaults to 0.5 (centered).
Position scale round option
Position scales support a round option which, if true, forces the scale to snap to integer pixels. This defaults to true for point and band scales, and false for quantitative scales. Use caution with high-cardinality ordinal domains as rounding can lead to wasted space or even zero-width bands.
Year formatting in quantitative and band scales
If tick values are all integers between 1,500 and 2,500 (inclusive), Plot assumes the values represent years and formats ticks by default without thousand separators, such as 1996 instead of 1,996. You can explicitly suppress thousand separators with tickFormat: "d", or enable them with tickFormat: ",d".
Default quantitative color scale
The default quantitative color scale type is linear, and the default scheme is turbo. A wide variety of sequential, diverging, and cyclical schemes are supported, including ColorBrewer and viridis.
Color scale interpolate option with custom function
You can implement a custom color scheme by specifying the scale's range, or by passing an interpolate function that takes a parameter t in [0, 1]. The interpolate option can specify a color space such as rgb, or a two-argument function that takes a pair of values from the range.
Diverging color scale pivot option
Diverging color scales are intended to show positive and negative values, or more generally values above or below some pivot value. Diverging color scales default to the RdBu (red–blue) color scheme. The pivot defaults to zero, but you can change it with the pivot option, which should ideally be a value near the middle of the domain.
Diverging color scale symmetric option
By default, all diverging color scales are symmetric around the pivot; set symmetric to false if you want to cover the whole extent on both sides.
Categorical and ordinal color scales
Plot provides color scales for discrete data. Use the categorical type for categorical (nominal) unordered data, and the ordinal type for ordered data. Discrete color schemes are intended for data that has only a few unique values. If the size of the categorical domain exceeds the number of colors in the scheme, colors will be reused; combining values into an "other" category is recommended.
Color scheme options for quantitative and ordinal data
Sequential scale schemes supported for both quantitative and ordinal data include: Blues, Greens, Greys, Purples, Reds, Oranges (single-hue); Turbo, Viridis, Magma, Inferno, Plasma, Cividis, Cubehelix, Warm, Cool, BuGn, BuPu, GnBu, OrRd, PuBuGn, PuBu, PuRd, RdPu, YlGnBu, YlGn, YlOrBr, YlOrRd (multi-hue).
Cyclical color schemes
The following cyclical color schemes are supported: rainbow, sinebow.
Diverging color schemes
The following diverging scale schemes are supported: BrBG, PRGn, PiYG, PuOr, RdBu, RdGy, RdYlBu, RdYlGn, Spectral, BuRd, BuYlRd.
Categorical color schemes
The following categorical color schemes are supported: Accent, Category10, Dark2, Observable10, Paired, Pastel1, Pastel2, Set1, Set2, Set3, Tableau10.
Color interpolators
The following color interpolators are supported: rgb (red, green, blue), hsl (hue, saturation, lightness), lab (CIELAB), hcl (CIELCh).
Radius scale default type and range
The r (radius) scale type defaults to sqrt such that when used with the dot mark, the resulting area is proportional to the r channel value. The default range for the r scale is constructed such that a zero value maps to zero for an accurate areal encoding, while the first quartile of values is mapped to a radius of three pixels; this tends to be more stable with varying data.
Scale type inference from marks
A scale's type is most often inferred from associated marks' channel values: strings and booleans imply an ordinal scale; dates imply a utc scale; anything else is linear. Plot assumes data is consistently typed, so inference is based solely on the first non-null, non-undefined value.
Scale type inference from domain
If a scale's domain is specified explicitly, the scale's type is inferred from the domain values rather than channels. However, if the domain or range has more than two elements, the ordinal type (or point for position scales) is used.
Scale type inference from marks requiring specific types
Some marks declare the scale type for associated channels. For example, barX requires y to be a band scale. Further, the facet scales fx and fy are always band scales, and the r (radius) scale is implicitly a sqrt scale.
Quantitative scale default domain inference
If you don't specify a quantitative scale's domain, it is the extent (minimum and maximum) of associated channel values, except for the r (radius) scale where it goes from zero to the maximum.
Ordinal scale default domain inference
For an ordinal scale, the domain defaults to the sorted union (all distinct values in natural order) of associated values. To change the order, use the sort mark option.
Quantitative domain nice option
A quantitative domain can be extended to "nice" human-readable values with the nice option. If true (or a tick count), the domain is extended to nice round values.
Position scale default range
All position scales (x, y, fx, and fy) have implicit automatic ranges based on the chart dimensions. The x scale ranges from the left to right edge, while the y scale ranges from the bottom to top edge, accounting for margins.
Scale transform option
The transform scale option allows you to apply a function to all values before they are passed through the scale. This is convenient for transforming a scale's data, say to convert to thousands or between temperature units. For example: transform: (f) => (f - 32) * (5 / 9) to convert Fahrenheit to Celsius.
Scale percent option
The percent scale option is shorthand for a transform that multiplies values by 100; it also adds a percent symbol (%) to the default label.
Scale interval option
The interval scale option sets an ordinal scale's domain to the start of every interval within the extent of the data. It implicitly sets the transform of the scale to interval.floor, rounding values down to the start of each interval. The interval option can also be used for quantitative and temporal scales to enforce uniformity. The specified interval must expose interval.floor(value), interval.offset(value), and interval.range(start, stop) functions. The option can be specified as a number (with step), or as a string (second, minute, hour, day, week, month, quarter, half, year, monday, tuesday, wednesday, thursday, friday, saturday, sunday), or a skip interval like "3 months" or "10 years".
Scale domain option
The domain option sets the scale's domain (the extent of its inputs, abstract values). For quantitative scales, it is typically [min, max]. For ordinal or categorical scales, it is an array of values.
Scale range option
The range option sets the scale's range (the extent of its outputs, visual values). For position scales, it is typically [min, max]. For color scales, it might be a continuous extent or an array of discrete colors.
Scale unknown option
The unknown option sets the desired output value (defaults to undefined) for invalid input values. For quantitative and temporal scales, the unknown value is used whenever the input value is undefined, null, or NaN. For ordinal or categorical scales, the unknown value is returned for any input value outside the domain. For band or point scales, the unknown option has no effect; it is effectively always equal to undefined. If the unknown option is set to undefined (the default), or null or NaN, then the affected input values will be considered undefined and filtered from the output.
Scale reverse option
The reverse option reverses the domain (or the range), say to flip the chart along x or y. This is convenient when the domain is implied from data rather than specified explicitly.
Quantitative scale zero option
The zero option, if true, extends the domain to include zero if needed.
Special color scale types
In addition to the normal scale types (linear, sqrt, pow, log, symlog, ordinal), Plot supports special scale types for color: categorical (like ordinal, but defaults to observable10), sequential (like linear), cyclical (like linear, but defaults to rainbow), threshold (discretizes using thresholds given as the domain; defaults to rdylbu), quantile (discretizes by computing quantile thresholds; defaults to rdylbu), quantize (discretizes by computing uniform thresholds; defaults to rdylbu), diverging (like linear, but with a pivot; defaults to rdbu), diverging-log (like log, but with a pivot that defaults to 1), diverging-pow (like pow, but with a pivot), diverging-sqrt (like sqrt, but with a pivot), diverging-symlog (like symlog, but with a pivot).
Threshold scale domain and range behavior
For a threshold scale, the domain represents n (typically numeric) thresholds which will produce a range of n + 1 output colors. The ith color of the range applies to values that are smaller than the ith element of the domain and larger or equal to the i - 1th element of the domain.
Quantile scale domain and n option
For a quantile scale, the domain represents all input values to the scale, and the n option specifies how many quantiles to compute from the domain. n quantiles will produce n - 1 thresholds and an output range of n colors.
Quantize scale domain and n option
For a quantize scale, the domain will be transformed into approximately n quantized values, where n is an option that defaults to 5.
Color scale scheme option
Color scales support a scheme option which is a named color scheme in lieu of a range, such as reds.
Color scale interpolate option
Color scales support an interpolate option which, in conjunction with a range, specifies how to interpolate colors.
Scale object invert method
When applicable, scale objects expose a scale.invert(output) method which returns the corresponding input value from the scale's domain for the given output value.
Quantile and quantize color scales scheme and n options
For quantile and quantize color scales, the scheme option is used in conjunction with n, which determines how many quantiles or quantized values to compute, and thus the number of elements in the scale's range; it defaults to 5 (for quintiles in the case of a quantile scale).
Position scale inset option
Position scales support an inset option which insets the default range by the specified amount in pixels.
Position scale asymmetric inset options for x and fx
The x and fx scales support asymmetric insets: insetLeft (insets the start of the default range by the specified number of pixels) and insetRight (insets the end of the default range by the specified number of pixels).
Position scale asymmetric inset options for y and fy
The y and fy scales support asymmetric insets: insetTop (insets the top of the default range by the specified number of pixels) and insetBottom (insets the bottom of the default range by the specified number of pixels).
Scale axis options
Position scales support axis mark options as scale options, applying to the implicit axis: axis (the axis anchor: top, bottom for x or fx; left, right for y or fy; both; null to suppress), ticks (approximate number of ticks, or interval, or array of values), tickSpacing (approximate pixels between ticks if ticks is not specified), tickSize (length of each tick in pixels; default 6 for x and y, or 0 for fx and fy), tickPadding (separation between tick and label in pixels; default 3), tickFormat (function or specifier string to format tick values), tickRotate (whether to rotate tick labels, angle in degrees clockwise; default 0), fontVariant (font-variant attribute; defaults to tabular-nums if quantitative), label (string to label the axis), labelAnchor (label anchor: top, right, bottom, left, or center), labelArrow (label arrow: auto, up, right, down, left, none, or true), labelOffset (label position offset in pixels; default depends on margins and orientation), ariaLabel (short label representing the axis in accessibility tree), ariaDescription (textual description for the axis).
Scale grid and line options
Position scales support grid and line options for implicit marks: grid (whether to draw grid lines across the plot for each tick), line (if true, draw the axis line, only for x and y).
Top-level scale option shortcuts
Top-level options are supported as shorthand for scale options: grid (for x and y only), label, axis, inset, round, align, and padding.