Each sector's size: a numeric column or expression. A negative value is an error; a zero or missing one draws nothing.
categorycolumn
The sectors' categories: they fill the sectors unless fill is given, so the legend lists them.
bycolumn | column[]
One pie per group, drawn as concentric rings that each sum to their own total, each ring's sectors aligned to the inner ones they sum (in row order; sort sorts each ring on its own and breaks that); for pies side by side, use a Facet.
sort"none" | "asc" | "desc" | category[]
The sectors' order clockwise from start_angle: row order, by value, or a list of categories (the others after them). Default: "none".
start_anglenumber
Where the pie starts, clockwise from 12 o'clock. Default: 0 degrees.
end_anglenumber
Where the pie ends, clockwise from 12 o'clock; below start_angle the sectors run counter-clockwise. Default: 360 degrees.
pad_anglenumber
A gap between sectors, taken from their shares as d3.pie's pad_angle is; with by, from each sector's own share (at most half its width, so a very small sector gets a narrower gap), so the rings stay aligned. Default: 0 degrees.
inner_radiusnumber
The hole's radius as a fraction of the disk's: above 0 makes a donut. Default: 0.
outer_radiusnumber
The pie's radius as a fraction of the disk's. Default: 1.
Text at each sector's centroid: its category, its value, its percent of its pie, a column, or an expression; a label that would overlap a larger sector's is hidden.
sector_label_formatstring
A d3-format string for numeric sector labels. Default: ".0%" for "percent", ",.7~r" otherwise.
text_colorcolor
The sector labels' color. Default: "#ffffff".
font_sizenumber
The sector labels' font size. Default: 12 px.
placement{anchor, size}
Where the pie goes in a Cartesian plot: anchor in data coordinates, size in pixels. In a polar plot the pie fills the disk. Default: centered in the frame, across 90% of its shorter side.
datatable
A table for this mark alone: a mark with data displays on its own, in a Plot of its own.
Appearance
fillchannel
The fill color: a CSS color, or a column of numbers or categories mapped to colors. Default: the category column.
colorchannel
The line or text color: a CSS color, or a column mapped to colors.
opacitychannel
The opacity, 0 to 1: a number, or a column (categories map through opacity_scale). Default: 1.
outline_colorchannel
The outline's color: a CSS color, or a column of categories mapped through outline_color_scale.
outline_opacitychannel
Border opacity from 0 to 1: a number, numeric column, array or expression. Fades the border over the fill; mark opacity still applies to both. Missing values hide the border. Default: 1.
outline_widthchannel
The outline's width in CSS pixels, drawn inside the mark's edge (a point's at most its radius). Default: 0.
Scales
fill_scalescale
The fill's scale, which marks can share: continuous({domain, colormap, transform}) for numbers, categorical({domain, range}) or ordinal() for categories.
color_scalescale
A scale for color that marks can share.
colormapstring | color[] | object
The colormap of a numeric fill or color: a name, a list of colors, or {colors, space, positions}. Default: the theme's (Viridis).
outline_color_scalescale
A categorical() scale from the outline_color column's categories to colors.
opacity_scalescale
A categorical() scale from the opacity column's categories to opacities, 0 to 1.
Display
labelstring
The mark's name in the legend and the settings pane.
legendboolean
Whether the mark has a legend entry. Default: True.
visibleboolean
Whether the mark is drawn. Default: True.
domainsboolean
Whether the mark's data counts toward its axes' automatic domains; false leaves them to the other marks (a reference line, a decorative part). Default: True.
How the mark mixes with what is drawn under it; any mode but normal draws it transparent, and SVG and PDF exports draw additive and subtractive as an image. Default: "normal".
glownumber
How much the mark glows: its own color times glow blooms around it in the plot's presentation (0 does not glow); the Plot's bloom effect sets the bloom's strength and radius. SVG and PDF exports draw the whole plot as an image. Default: 0.
shadeShadeSpec
A plugin's shade (registerPlugin): { kind, ...parameters }, as { kind: "hatch", spacing: 6 } (Python hm.shade("hatch", spacing=6)), recolors each fragment the mark draws; picking, tooltips, domains and legends are unchanged. SVG and PDF exports draw a shaded mark as an image.
optionsstring[]
The settings the settings pane shows for this mark, by name.
namestring
The mark's name in the settings pane, and the name facet.endpoint() and partition.endpoint() find it by.
Interaction
identityidentity
Whose rows these are for selections: an identity() shared by tables that show the same things. Default: its data's.
selectboolean | selection | object
Click to replace the selection; an exact repeat clears it. Shift/Meta/Ctrl-click toggles membership (whole series for Line, Area): true uses its data's selection, or give a selection(). input("root").set("id") writes an input instead: a click sets it to the clicked row's id (a drill-down's root), .set(literal(v)) to a constant, .reset() to its default, and a click on nothing restores its default (input("root", {default}), else a Select of that name's, else null); several marks may write one input.
hoverboolean | selection | object
Mark the row under the pointer as @hovered (a whole series for Line, Area), without fading the others: true uses its data's hover, or give a selection(). input("focus").set("series") writes an input instead: while the pointer is on a row the input shows its series (or .set(literal(v)), a constant), then its committed value again (a hover that would change this mark's own rows is an error).
tooltipboolean | field[] | object
Show the nearest row's values in a box by the pointer: true, a list of fields, or {fields, radius, content}. Default: the Plot's.
nearestboolean | selection | object
Mark the row a tooltip shows as @nearest, with or without the tooltip: under the pointer, else the nearest drawn row within radius pixels (a whole series for Line, Area): true, a selection(), or {selection, radius}. Default: the Plot's.
Which interaction states fade this mark's other rows to selection_opacity; "hovered" fades them while hovering, "nearest" while a row is nearest. Default: the states it sets, except hover and nearest.
selection_opacitynumber
The opacity of the rows outside the selection while one is active. Default: 0.25.
enter_effectboolean | "fade" | object
How rows that arrive in a keyed update appear: "fade", or {effect, duration, easing}. animate()'s enter option is the value a channel starts from.
exit_effectboolean | "fade" | object
How rows that leave in a keyed update disappear, as enter_effect. animate()'s exit option is the value a channel ends at.
Animation
animationboolean
Animate changes to the mark's values. Default: False.
animation_durationnumber
How long an animated change takes. Default: 300 ms.
This mark's own z transform, instead of its frame's. Default: its frame's.
z_invertbooleansetting
Reverse this mark's z direction. Default: False.
zbounds[number, number]setting
The z extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
zrange[number, number]setting
Where this mark's z extent lands, in its frame's world units. Default: its frame's.
Shading
litbooleansetting
Shade the mark with the plot's lights. Default: False.
transparentbooleansetting
Draw the mark in the transparent pass, blended in depth order with other transparent marks. Default: False.
Advanced renderer options
max_instancesnumber | null
The most rows drawn; past it the rows are sampled (null draws them all), though SVG and PDF exports draw every row. Default: None.
Usage
A sector per row, its angle its value’s share of the total, clockwise from 12 o’clock (d3.pie’s convention, with angles in degrees). category fills the sectors, so <Legend for={pie} channel="fill"> (Python hm.Legend(target=pie, channel="fill")) lists the categories. innerRadius above 0 makes a donut; startAngle and endAngle make a partial pie; padAngle separates the sectors; sort orders them by value or by a list of categories. sectorLabel writes each sector’s "category", "value", "percent", a column, or an expression at its centroid; a label that would overlap a larger sector’s is hidden.
In a polar Plot or Frame the pie fills the disk. In a Cartesian one (the default Plot) the Pie places a polar Frame of its own: centered in the frame’s domain and across 90% of its shorter side, or where placement puts it (anchor in data coordinates, size in pixels), so a pie can sit beside other marks as an inset.
A negative value is a data error naming its row; a zero, missing or hidden value draws nothing. Put a key on the data and turn on animation to tween the sectors when the values change. by draws one pie per group as concentric rings; in row order, a ring’s sectors start and end where the inner sectors whose values they sum do (a sunburst), each sector’s padAngle coming out of its own share (at most half its width, so a very small sector gets a narrower gap). A sort sorts each ring on its own, which breaks that alignment. For pies side by side, put the Pie in a Facet:
Pie is a built-in template (TODO 130.3): the PieGeometry transform, a Rect for the sectors and a Text for their labels, importable from hmplot/charts. See “Writing a pattern” in docs/USAGE.md.