Published-release documentation · release compatibility

Position Scales

Compatibility matrix

The field type, channel, mark recipe, and all consumers of a shared scale must agree. editScale validates that complete matrix before applying any semantic or graphical change. This page owns position scales. For appearance consumers and their exact mark restrictions, use the scale-family matrix and field stroke.

Continuous scales

Explicit numeric time ranges are honored for centered temporal bars as well as their shared line/rule/text consumers. Only automatic temporal-bar ranges receive the usual center inset. Explicit ranges remain fixed after Canvas edits; reverse applies last. Bandwidth follows the minimum mapped time gap; when subtracting two finite endpoints would overflow, a finite conservative slot estimate is retained.

Automatic ranges use current plot bounds. For automatic linear domains, zero: true includes zero and nice: true then expands to rounded boundaries. Automatic temporal nice expands to UTC calendar boundaries. Time scales reject zero.

For quantitative positions, log requires a strictly positive or strictly negative domain and rejects zero. pow is sign-preserving, sqrt is its fixed exponent-0.5 specialization, and symlog supports values on both sides of zero. Point, line, area, bar, and rule materializers use the same mapping, and axes and grids read the same resolved scale.

When an automatic transformed domain contains one finite value, ggaction pads it to a finite, type-valid pair and places that value at the middle of the transformed range whenever both surrounding endpoints are representable. A log constant stays entirely positive or entirely negative. Explicit transformed domains still require two distinct values.

Temporal field values are normalized while resolving the scale, without rewriting the source dataset. Finite timestamps are accepted directly; four-digit numbers or strings are UTC years, and validated YYYY-MM-DD or YYYY/MM/DD strings are UTC calendar dates.

The precedence is:

explicit domain > nice / zero > inferred domain
reverse(explicit range > inferred range)

clamp: true constrains values outside a continuous position domain to the nearest range endpoint. reverse: true reverses the final resolved range. Ordinal scales support reverse but reject nice, zero, and clamp.

Binned bar x scales

A binned bar x encoding defaults to nice: true and zero: false. Automatic nice bin boundaries use 1, 2, 3, 5 × 10ⁿ steps and never create more than bin.maxBins intervals. Explicit domains remain unchanged; nice and zero do not expand them.

The resolved scale domain contains the outer bin boundaries. Concrete bin counts and rect geometry are materialized once count/zero-stack y is present.

A histogram count y scale defaults to nice: true and zero: true. Its automatic domain uses total counts per x bin rather than raw source values. The x action leaves the collection empty; the y action resolves both scales and materializes concrete histogram rectangles.

Aggregate ordinal bar y scales

An ordinal bar aggregate y scale defaults to nice: true and zero: false. Its automatic domain uses one final aggregate value per ordinal x/category and series cell rather than raw source values. Group and overlay layouts also include their semantic zero baseline in the automatic domain, even when zero: false; that option does not remove an endpoint required by bar geometry. This includes parameterized quantile and ordered first/last results. An explicit group or overlay domain must contain zero, while explicit range values remain authoritative. The y action resolves the scale but leaves rectangles empty until grouping semantics are available.

Measured radius scales

Arc encodeR with count/sum and mapping: "area" or "radius-length" uses category aggregates for its domain. The domain starts at zero and its upper bound must cover every aggregate. Marks and radial guides share the mapping.

The lower scale actions expose the stored policy as radialMapping. createScale({ id: "radius", radialMapping: "area" }) creates an unbound linear measured scale; editScale({ id: "radius", radialMapping: "radius-length" }) updates all compatible consumers. Explicit domains use [0, positiveMaximum] and ranges use [inner, outer], with 0 <= inner < outer.

To turn one measured Arc into ordinary row-level radius while reusing its scale, call encodeR({ field, mapping: false }). The action clears the Arc aggregate before delegating the radialMapping removal to editScale, then refreshes the scale, sectors, axis, and grid together. It rejects a scale that still has another measured consumer. Direct editScale({ radialMapping: undefined }) continues to require that measured radius encodings have already been removed.

Related

Scale overview · Encodings · Troubleshooting