ggaction 0.0.5

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

| Action | Supported marks | Field types | Important modes | | — | — | — | — | | encodeX | point, line, area, bar, rect, rule, text | point/bar/rect/rule/text: quantitative, temporal, ordinal, nominal; line/area: quantitative, temporal | field; rule also accepts datum; bar accepts aggregate or bin | | encodeY | point, line, area, bar, rect, rule, text | point/line/bar/rect/rule/text: quantitative, temporal, ordinal, nominal; area: quantitative, temporal | field; rule also accepts datum; bar accepts aggregate or count | | encodeX2 / encodeY2 | area, ranged bar, rect, rule | area/ranged bar/rect/rule: matching primary | secondary field; rule also accepts datum | | encodeTheta | point, line, arc | point/line: quantitative, temporal, ordinal, nominal; arc: ordinal, nominal | arc accepts aggregate: count or weighted sum for proportional sectors | | encodeR | point, line, arc | point/line/arc: quantitative | radial position; arc combines it with a categorical theta band | | encodeParallelCoordinates | line | line: quantitative, ordinal | atomic ordered dimensions; one namespaced scale and axis per dimension |

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 donuts, rose charts, or radial bars arc mark, 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
Bin and count values bar mark, quantitative field encodeHistogram or encodeX + encodeY Histograms
Estimate a distribution area mark, quantitative field encodeDensity Encodings
Draw full-span or bounded rules rule mark, field or datum endpoints encodeX, encodeY, encodeX2, encodeY2 Rule endpoints
Control within-band grouping complete ordinal-bar positions 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.

Shared inference

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. Arc marks accept nominal or ordinal theta; aggregate: "count" creates count-proportional sectors. aggregate: "sum" plus a non-negative finite weight field creates weighted proportional sectors. Categorical theta plus quantitative encodeR creates radial sectors. 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 with an explicit fieldType, but accept exactly one of field or datum:

program
  .createRuleMark()
  .encodeX({ datum: 15, fieldType: "quantitative" })
  .encodeY({ datum: 20, fieldType: "quantitative" })
  .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