Published-release documentation · release compatibility

Position Encodings

Choose the position family from the semantic mark and field relationship. All position actions infer the current mark, use or create a compatible coordinate, resolve a channel scale, and explicitly materialize the affected graphics.

Supported marks and modes

Choose an encoding

For ordinary grouped bar charts, prefer encodeColor({ field, layout: "group" }); it calls the matching advanced directional offset action for the same field.

For a center-stacked area, each group must have exactly one non-negative value at every x position. encodeY({ stack: "center" }) preserves the original y field and creates concrete lower/upper area boundaries around zero. The equivalent encodeColor({ layout: "center" }) also creates the matching nominal group when it is absent. Center stacking is not supported for bars, ranged areas, signed values, duplicate group/x rows, or missing positions.

Shared inference

• target defaults to the current compatible mark.
• coordinate uses the layer coordinate, then the documented main Cartesian or polar Polar default for the requested channel family.
• Scale IDs default to their channel names: x, y, theta, radius, xOffset, and yOffset.
• Automatic continuous y ranges run bottom-to-top. Discrete y positions run top-to-bottom so horizontal categories follow domain order.
• Temporal values accept finite timestamps, four-digit numeric/string years, and valid date strings. Four-digit values are interpreted as UTC years.
• Ambiguous resources produce an error instead of an arbitrary selection.

Polar positions

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

program
  .encodeTheta({ field: "angle" })
  .encodeR({ field: "distance" })
  .encodePointRadius({ value: 3 });

encodeTheta accepts point or line marks with quantitative, temporal, ordinal, or nominal fields. For an arc mark, an aggregate-free quantitative field makes one proportional sector per positive source row. aggregate: "count" over a nominal or ordinal field creates count-proportional sectors. aggregate: "sum" plus a non-negative finite weight field creates category-weighted proportional sectors. Categorical theta plus quantitative encodeR creates radial sectors; direct quantitative arc theta does not combine with encodeR. Quantitative angle scales are linear; temporal angles use time scales; discrete angles use point or band scales. The automatic range is [0, 360] degrees with 0 at 12 o’clock and clockwise positive direction.

encodeR accepts a quantitative field and linear, log, pow, sqrt, or symlog scale policies. Its automatic range fits the smaller plot dimension. Explicit ranges are non-negative logical pixels and must fit the current plot bounds.

The two actions are order-independent. One Polar channel may exist as an incomplete semantic assignment, but points or paths become visible only after both channels and their scales resolve. A line may use createLineMark({ closed: true }) for a closed radar path. Cartesian x/y and Polar theta/radius cannot be mixed on one layer.

Measured radial sectors

On an Arc mark with categorical theta, encodeR can aggregate a measure per category and encode either annular area or radial length. This fragment assumes program already has data with category and non-negative numeric value fields:

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

program
  .createArcMark({ innerRadius: 0.5 })
  .encodeTheta({ field: "category", fieldType: "nominal" })
  .encodeR({ field: "value", aggregate: "sum", mapping: "area" })
  .createRadialAxis();

Use mapping: "radius-length" to make length from the inner edge proportional to the aggregate. Use { aggregate: "count", mapping: "area" } without a field to count rows per category. Both modes use equal-angle sectors and a zero-based linear scale. Zero categories remain in categorical domains but draw no sector. Negative, nonfinite, all-zero, and unrepresentable positive-thickness inputs are errors.

The radial axis shows count or sum units with the same mapping as the sectors. An explicit radius range [inner, outer] defines the hole and must agree with an explicitly specified Arc innerRadius (ratio or fixed pixels). These modes require zero theta padding and padAngle: 0; nice: true, zero: false, and reverse: true are errors.

Reassigning encodeR preserves omitted mapping and aggregate. To change the mapping on a shared measured scale, use editScale({ id, radialMapping: "area" }); all its compatible sectors and radial guides update together. Ordinary point radius and measured Arc radius require separate scales.

Use encodeR({ field: "value", mapping: false }) to refine a measured Arc into ordinary row-level radial length. This one action removes the inherited count/sum aggregate, clears the scale’s measured mapping, and updates existing radial guides. It preserves the mark, data, categorical theta order, and compatible styling. This is an explicit semantic change: mapping: "area" makes aggregate annular area proportional to value, while mapping: false makes each row’s radius proportional to its value. A measured scale shared by another aggregate Arc must be separated before this transition.

Rule endpoints

Rule positions use the same encodeX and encodeY actions and accept exactly one of field or datum. Datum-only rules infer finite numbers as quantitative and other supported scalar values as nominal. Field rules, temporal data, and ambiguous values require an explicit fieldType:

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

program
  .createRuleMark()
  .encodeX({ datum: 15 })
  .encodeY({ datum: 20 })
  .encodeY2({ datum: 80, fieldType: "quantitative" });

encodeX2 and rule encodeY2 require their corresponding primary endpoint and share its scale, coordinate, and field type. x alone draws a vertical full-span rule; y alone draws a horizontal full-span rule. x+y+y2 and y+x+x2 draw bounded intervals, while all four endpoints draw a diagonal. Calling the same action again replaces only that endpoint.

Quantitative ranges

Full encodeXRange and encodeYRange accept field names or finite { datum: number } bounds for Rect and Rule marks. Either or both bounds may be constants; the two endpoints share one scale and coordinate. No source rows or columns are added. The wrapper validates the final pair before changing it and records the ordinary primary/secondary encoding actions.

Bar ranges require two fields. Temporal ranges also require two fields; use the individual position encoders for temporal constants. Area bounds retain the more specific requirements below.

Area bounds

Area encodeXRange and encodeYRange accept a field name or { datum: number } for each bound, with at least one field. Bounds retain their order even when they cross. The two endpoints share one scale; reassignment validates the final pair and scale together. encodeX2 and encodeY2 accept quantitative datum bounds without an explicit fieldType. Use a finite, nonzero baseline for log scales.

Related

Encodings · Scale options · Coordinates · Series encodings