Polar Charts in Python

A polar chart (also called a polar plot or polar graph) places each observation by an angle (theta, or θ) and a distance from the center (radius, or r). It is a natural fit for cyclic measurements, directional observations, antenna patterns, radar comparisons, and wind distributions.

Jump to a polar line chart, the angular axis, or supported marks and limits.

XY uses the same composition model as its Cartesian charts. Put line, scatter, area, bar, column, heatmap, contour, or errorbar marks inside polar_chart(). Focused helpers build radar, radial bar, and wind rose charts on the same coordinate system.

The first mark channel becomes θ and the second becomes r. Angles use radians by default:

Without an authored sector, polar_chart() draws a full circular frame. Its angular axis defaults to 0..2π, and a linear radial axis starts at zero and ends at the largest radius. Pass domain= to r_axis() when the radial view must stay fixed.

Heatmap cells follow rings and spokes rather than stretching a Cartesian image into a circle. Contours share that projection, so they can be layered over the field with one colorbar:

The polar heatmap path inverse-samples the source grid at the requested browser or export resolution. Pixels inside a hole or outside an authored sector stay transparent. Contours remain projected vector geometry.

The overview owns numeric theta/r data and shared coordinate-system behavior. Use a focused page when the data already matches one of these higher-level compositions.

Radar charts space named dimensions evenly around the frame and close filled or outlined profiles automatically.

Radial bar charts turn bars into annular sectors with scalar or per-item angular widths and configurable inner radii.

The pie and donut guide turns unequal-width sectors and base= into polished share, progress-ring, revenue-mix, and gauge blocks.

Wind rose charts bin raw compass bearings into directional sectors and stack their counts by speed band.

theta_axis() accepts the ordinary x_axis() options for labels, ticks, formatting, and styling, plus five polar settings:

The compass combination xy.theta_axis(unit="degrees", zero="N", direction="clockwise") makes 0° point north, 90° east, 180° south, and 270° west.

A numeric zero is always an offset in radians counterclockwise from east, independent of the data unit. Exact tick_values take priority over automatic angular ticks. When tick_labels are omitted, authored fractional degree values retain their precision (for example, 22.5 renders as 22.5°).

sector=(start, end) clips marks and ticks to that angular interval and fits the chart to the visible arc's bounding box. On theta_axis(), domain= is a compatibility alias for sector=; pass one or the other, not both. Numeric theta keeps its independent full-turn data and tick range. Set grid_shape="linear" to join spoke intersections into polygonal radial rings.

Category strings also work as theta coordinates. They are spaced evenly around a full turn or across an authored sector, and their labels take priority over numeric angle formatting. radar_chart() remains the convenient composition when every series shares one category list and should close automatically.

r_axis() accepts the same options as y_axis(). Use label= for the measured quantity, domain=(minimum, maximum) for a fixed radial range, and tick_values= when rings must land at exact values. Radial axes support type_="linear", "log", or "symlog".

The automatic linear range begins at zero so the center keeps its usual meaning; log autorange remains strictly positive. An explicit domain can choose a different inner value. hole= reserves a shared display-space inner-radius fraction from 0 up to (but not including) 1. origin= places the shared radial origin in data space, so an origin below the visible minimum creates an annulus. hole and origin are mutually exclusive, and a log-axis origin must be positive.

Filled areas and annular sectors are clipped to the visible radial interval. For example, a bar extending past the outer ring draws up to that ring instead of disappearing, and a filled area crossing the radial minimum is trimmed instead of reflecting through the center. A sector wholly outside the interval disappears. Scatter points and line vertices outside the interval are culled; an out-of-range vertex splits a line into visible runs instead of connecting through its mirrored polar position.

Both angular (xerr) and radial (yerr) uncertainty project through the polar coordinate system. This example fits the plot to a 220° compass sector and clips the marks to a shared inner hole:

Interactive polar charts deliberately expose a smaller gesture set than Cartesian charts:

• Hover reports the nearest point or field cell: its series name, radial value, and any color or size encoding. The numeric angle is left out — the cursor is already on it — while an authored spoke label survives and xy.tooltip(labels={"x": ...}) opts the angle back in. A hole or excluded part of a sector is not hit-testable.
• Wheel and modebar zoom scale the radial maximum while keeping the radial minimum fixed. Reset restores the original radial range.
• Theta rotation/panning, interactive sector zoom, box zoom, rectangular or lasso selection, brushing, and crosshairs are not currently available.

Keeping the radial minimum fixed prevents an ordinary zoom from unexpectedly turning a disc into an annulus. See Interactions and selections for the general interaction configuration surface.

Explicit padding=(top, right, bottom, left) is preserved by the polar layout. Increase the bottom or side value to reserve a stable band for a legend, caption, or other surrounding content; the disc stays centered in the remaining plot box.

Point-anchored text, label, marker, arrow, and callout annotations interpret data coordinates as (theta, r) consistently in the browser, SVG, and native raster output. Their dx and dy offsets remain screen-space pixels. Polar rules and bands remain deferred because they require spoke/ring and sector/annulus geometry instead of Cartesian lines and rectangles; using one on a polar chart raises at payload build instead of drawing a Cartesian approximation.

The Matplotlib-style compatibility layer routes a polar subplot through the same renderer:

Polar routing works through plt.subplot(projection="polar"), fig.add_subplot(..., projection="polar"), plt.axes(projection="polar"), and plt.subplots(subplot_kw={"projection": "polar"}). The polar=True alias is accepted by subplot(), add_subplot(), and axes(), or inside subplot_kw; it is not a direct plt.subplots(polar=True) argument. Ordinary plot, scatter, fill, bar, heatmap/image, contour, and errorbar calls share the core polar renderer. fill() maps its boundary to a radial area against r=0, which matches a full-turn filled profile but not every arbitrary closed Matplotlib polygon. The shim preserves theta zero, direction, offset, and authored theta grids. Degree-based set_thetamin()/set_thetamax() share view state with radian set_xlim(), while set_rorigin() authors the data-space radial origin. Their corresponding getters, radial limits, ticks, grids, categorical theta, and log/symlog radial scales use the same core axes.

The stateful plt.polar(), plt.thetagrids(), and plt.rgrids() convenience wrappers are not part of this increment; call the corresponding methods on the polar axes. Keep and reuse the returned axes handle: passing projection="polar" again while reactivating an existing plt.subplot() is not supported. See the Matplotlib compatibility guide for the full boundary.

The supported polar primitives are line, scatter, area, bar, column, heatmap, contour, and errorbar. The radar, radial bar, and wind rose helpers compose those primitives; they do not add separate renderers.

Current limits:

• Histograms, box plots, hexbin, density grids, generic segments, and meshes are rejected instead of being drawn with incorrect geometry. Polar errorbar and contour use narrowly allowlisted projected segments; they do not make every segment-backed mark legal.
• Polar lines and filled-area boundaries connect observations with straight chords. Repeat the first observation at one full turn when manually closing a line; the radar helper handles closure itself.
• Polar traces use direct rendering rather than Cartesian line decimation or scatter-density aggregation. line, scatter, and area are limited to 200,000 points per trace; a larger point trace raises ValueError. Heatmap/contour grids are not rejected merely because their cell count exceeds that point ceiling.
• Polar rules and bands need dedicated spoke, ring, annulus, or sector geometry and raise instead of falling back to Cartesian geometry.
• Polar LOD, facets/animation, interactive theta rotation/pan, sector zoom, and annulus/sector selection remain deferred.

Supported marks and point-anchored annotations use the same polar projection in the browser, SVG, PDF, and native raster exporters, so the chart can be displayed live or exported through the usual chart methods.

• Radar charts — compare named dimensions with closed profiles.
• Radial bar charts — annular sectors, pies, and donuts.
• Wind rose charts — directional frequency split into magnitude bands.
• Line charts — trends on Cartesian axes.
• Scatter charts — relationships and multichannel points on Cartesian axes.
• Bar charts — rectangular categorical and numeric bars.
• Axes and scales — shared labels, domains, ticks, and styling options.
• Display and export — notebooks, HTML, PNG, SVG, PDF, JPEG, and WebP.

Put a supported mark such as xy.line(theta, radius), xy.heatmap(z, x=theta, y=radius), or xy.errorbar(theta, radius, yerr=...) inside xy.polar_chart(...). Angles are radians by default.

See the radar chart guide for filled and outlined profiles, the category/value contract, and shared-scale configuration.

See the wind rose guide for directional bins, speed bands, input validation, and compass conventions.

See Pie and Donut Charts for four live unequal-width sector compositions with center metrics and Reflex legends.

Add xy.theta_axis(unit="degrees"). The angle data and generated tick labels will both use degrees.

Use xy.theta_axis(unit="degrees", zero="N", direction="clockwise") for the standard compass convention. The wind rose helper applies it automatically.

Yes. Create the axes with plt.subplot(projection="polar") or plt.subplots(subplot_kw={"projection": "polar"}). Lines, scatter, radial-to-zero fills, bars, heatmaps/images, contours, and error bars route through the polar renderer. Theta zero/direction/offset and min/max, authored theta grids, radial origin, radial limits/ticks/grids, categorical theta, and log/symlog radius are supported. Arbitrary closed-polygon fills remain a documented approximation.