Skip to content

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.

python
from gofish import chart, stack, rect, Coord

chart(seafood, coord=Coord.polar()) \
    .flow(stack(by="species", dir="x")) \
    .mark(rect(w="count", fill="species")) \
    .render(w=400, h=300)

Signature ​

python
Coord.polar(
    *,
    inner_radius: float | None = None,   # donut hole, fraction [0,1) of outer radius
    central_angle: float | None = None,  # total sweep in radians (default 2π)
    baseline_angle: float | None = None,  # angle (radians) where θ's 0 sits, from 3 o'clock (default 0)
    direction: int | None = None,        # +1 CCW, -1 CW (default 1)
    center: tuple[float, float] | None = None,  # screen-space center offset
) -> Coord

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 baseline_angle, whatever the θ range and central_angle. A range that starts at 0, like a pie's, starts at baseline_angle. A stack centered on 0 (a Unit(domain=..., traits=[Trait.diverging(...)]) schema) is centered on baseline_angle, 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.

OptionTypeDefaultDescription
inner_radiusfloat0Donut hole as a fraction [0,1) of the outer radius.
central_anglefloat2πTotal angular sweep in radians.
baseline_anglefloat0The 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.
directionfloat1+1 counter-clockwise, -1 clockwise (numeric ±1).
centertuple[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 dims keyword, a dict keyed by axis name. A plain value is a position, like x. A dict names the parts of the axis you want to set: "min", "center", "max", "size", and "embedded".
  • in an operator's dir, as in stack(dir="theta").
python
chart(data, coord=Coord.polar()) \
    .flow(spread(by="category", dir="theta")) \
    .mark(rect(dims={"theta": {"size": 0.4}, "r": {"size": "value"}},
               em_x=True, em_y=True))

This is the same chart as spread(by="category", dir="x") with rect(w=0.4, h="value", em_x=True, em_y=True). The names only work inside a coordinate space that declares them; anywhere else, "theta" raises 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.

A circle's own r keyword is still its radius. The polar r axis only appears as a key inside dims, so scatter(by="id", dims={"theta": "bearing", "r": "distance"}) with circle(r=4) places each dot by bearing and distance and draws it with radius 4.

Usage ​

Pass the coordinate transform to chart via the coord keyword:

python
chart(data, coord=Coord.polar()) \
    .flow(...) \
    .mark(...) \
    .render(w=400, h=300)

Coordinate Mapping ​

CartesianPolar
xangle (theta), 0 to 2π, 0 at right, counter-clockwise
yradius from center

Examples ​

python
# 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(inner_radius=0.5)) \
    .flow(stack(by="category", dir="x")) \
    .mark(rect(w="value"))

# Partial fan: a 270° sweep instead of the full circle
import math
chart(data, coord=Coord.polar(central_angle=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