Position Encodings

Cars scatterplot of horsepower and fuel economy — Quantitative positions with nominal color.

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

Goal	Required state	Actions	Detailed page
Position points	point mark, quantitative, temporal, or ordinal fields	`encodeX`, `encodeY`	Quantitative positions
Position Polar points	point mark, angle field and quantitative radius field	`encodeTheta`, `encodeR`	Polar point tutorial
Draw Polar lines or radar paths	line mark, angle field and quantitative radius field	`encodeTheta`, `encodeR`	Polar line tutorial
Draw pies, donuts, rose charts, or radial bars	arc mark, direct quantitative theta, categorical count/weighted-sum theta, or quantitative radius	`encodeTheta`, optional `encodeR`	Polar arc tutorial
Draw discrete or ranged cells	rect mark, two discrete positions or complete x/x2 and y/y2 pairs	`encodeX`, `encodeY`, optional `encodeX2`, `encodeY2`	Rect marks
Draw an aggregate time series	line mark, temporal x and quantitative y	`encodeX`, `encodeY`	Temporal lines
Build vertical aggregate bars	bar mark, ordinal/temporal x and quantitative y	`encodeX`, `encodeY`	Bar positions
Build horizontal aggregate bars	bar mark, quantitative x and ordinal/temporal y	`encodeX`, `encodeY`	Bar positions
Order categorical positions	nominal/ordinal x or y	`orderCategories`, `removeCategoryOrder`	Category ordering
Bin and count values	bar mark, quantitative field	`encodeHistogram` or `encodeX` + `encodeY`	Histograms
Estimate a distribution	area mark, quantitative field	`encodeDensity`	Encodings
Center aligned area series	area mark, quantitative/temporal x, non-negative quantitative y, nominal group	`encodeY({ stack: "center" })` or `encodeColor({ layout: "center" })`	Color encoding
Draw full-span or bounded rules	rule mark, field or datum endpoints	`encodeX`, `encodeY`, `encodeX2`, `encodeY2`	Rule endpoints
Control within-category grouping	categorical bar, point, or rule position	`encodeXOffset`, `encodeYOffset`	Offsets

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

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.

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:

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.

Encodings · Scale options · Coordinates · Series encodings