Coord.polar
Transforms Cartesian coordinates into a polar coordinate system. The x-axis maps to angle (theta) and the y-axis maps to radius. Angles follow the math convention: θ = 0 points right (3 o'clock) and angles increase counter-clockwise.
gf.chart(seafood, { coord: gf.Coord.polar() })
.flow(gf.stack({ by: "species", dir: "x" }))
.mark(gf.rect({ w: "count", fill: "species" }))
.render(root, {
w: 400,
h: 300,
transform: { x: 200, y: 150 },
});Signature
Coord.polar(options?: {
innerRadius?: number; // donut hole, fraction [0,1) of outer radius. Default 0
centralAngle?: number; // total sweep in radians. Default 2π
baselineAngle?: number; // angle (radians) where θ's 0 sits, from 3 o'clock. Default 0
direction?: 1 | -1; // +1 CCW, -1 CW. Default 1 (counter-clockwise)
center?: [number, number]; // screen-space center offset. Default [0, 0]
});Parameters
All optional; the defaults give a centered, full-circle disc starting at 3 o'clock and going counter-clockwise. Coord.clock() is the same transform with 0 at 12 o'clock, going clockwise.
The number 0 on the angular axis always sits at baselineAngle, whatever the θ range and centralAngle. A range that starts at 0, like a pie's, starts at baselineAngle. A stack centered on 0 (a Unit({ domain: ..., traits: [Trait.diverging(...)] }) schema) is centered on baselineAngle, and its negative half runs back past it.
Maps (θ, r) → screen in the math convention: θ=0 at 3 o'clock, increasing counter-clockwise. θ is axis 0 (x, or the declared name theta), r is axis 1 (y, or r); dims and dir inside it may use theta/r.
| Option | Type | Default | Description |
|---|---|---|---|
innerRadius | number | 0 | Donut hole as a fraction [0,1) of the outer radius. |
centralAngle | number | 2π | Total angular sweep in radians. |
baselineAngle | number | 0 | The angle where the angular axis's 0 sits: radians, measured counter-clockwise from 3 o'clock. Data 0 on θ maps here for every θ range and every sweep. |
direction | number | 1 | +1 counter-clockwise, -1 clockwise (numeric ±1). |
center | [number, number] | [0, 0] | Screen-space center offset. |
Axis names
In every coordinate space, x, y, w, and h refer to the first and second axis. Under polar, the first axis is the angle and the second is the radius, so w is an angular extent and h is a radial one.
Polar also declares its own names for the two axes: theta for the angle and r for the radius. You can use them in two places:
- in a mark's
dimsoption, which is keyed by axis name. A plain value is a position, likex. An object names the parts of the axis you want to set:min,center,max,size, andembedded. - in an operator's
dir, as instack({ dir: "theta" }).
This chart is the one at the top of the page, written with the polar names:
gf.chart(seafood, { coord: gf.Coord.polar() })
.flow(gf.stack({ by: "species", dir: "theta" }))
.mark(gf.rect({ dims: { theta: { size: "count" } }, fill: "species" }))
.render(root, {
w: 400,
h: 300,
transform: { x: 200, y: 150 },
});The names only work inside a coordinate space that declares them. Outside polar, theta throws an error that lists the names you can use there. A coordinate space nested inside polar that declares no names, such as Coord.wavy(), hides them too.
Each part of an axis can be set once. w: 0.4 together with dims: { theta: { size: 0.4 } } is an error, because both set the angular size. x: 0 together with dims: { theta: { size: 0.4 } } is fine, because one sets the start and the other sets the size.
A circle's own r option is still its radius. The polar r axis only appears as a key inside dims, so the two do not collide:
chart(trips, { coord: Coord.polar() })
.flow(scatter({ by: "id", dims: { theta: "bearing", r: "distance" } }))
.mark(circle({ r: 4 }));Usage
Pass the coordinate transform to chart() via the coord option:
chart(data, { coord: Coord.polar() })
.flow(...)
.mark(...)
.render(container, opts);Coordinate Mapping
| Cartesian | Polar |
|---|---|
| x | angle (theta), 0 to 2π, 0 at right, counter-clockwise |
| y | radius from center |
Examples
// Basic polar chart
chart(data, { coord: Coord.polar() })
.flow(stack({ by: "category", dir: "x" }))
.mark(rect({ w: "value" }));
// Polar with spread for radial segments
chart(data, { coord: Coord.polar() })
.flow(spread({ by: "month", dir: "x" }))
.mark(rect({ w: 1, h: "value" }));
// Donut: a hollow center (inner radius = 50% of the outer radius)
chart(data, { coord: Coord.polar({ innerRadius: 0.5 }) })
.flow(stack({ by: "category", dir: "x" }))
.mark(rect({ w: "value" }));
// Partial fan: a 270° sweep instead of the full circle
chart(data, { coord: Coord.polar({ centralAngle: (3 * Math.PI) / 2 }) })
.flow(spread({ by: "month", dir: "x" }))
.mark(rect({ w: 1, h: "value" }));See Also
- clock — The same transform with 0° at 12 o'clock, going clockwise
