charts.Lollipop
A stem from a baseline to each value, with a point at its end.
Static preview; loading the interactive plot
import hmplot as hm
data = {"category": ["A", "B", "C", "D", "E"], "value": [18, 31, 12, 44, 26]}
with hm.Plot(data=data, height=300, axes2d=True) as plot:
hm.charts.Lollipop(x="category", y="value")
plot
Options
Keywords are snake_case.
Options
orientation"horizontal" | "vertical"- Whether the stems run along y ("vertical") or along x ("horizontal"). Default: horizontal when only y is categorical, else vertical.
baselinechannel- Where the stems start: a number or a column. Values on either side of it get a stem. Default:
0. stemobject- The stems' own Segments props, as one object: {color: "gray", width: 2, dash: [2, 2]}. Defaults to the Lollipop theme's color and width (#8a949e and 1.5 pixels).
datatable- A table for this mark alone: a mark with data displays on its own, in a Plot of its own.
Position
xchannel- The categories along x for vertical stems, or the values the stems reach for horizontal ones.
ychannel- The values the stems reach for vertical stems, or the categories along y for horizontal ones.
zchannel- The z position, in a 3D plot: a column, per-row values, or one value.
positionchannel- Positions as one column or an N x 2 (or N x 3) array, instead of x, y and z.
Appearance
fillchannel- The fill color: a CSS color, or a column of numbers or categories mapped to colors.
colorchannel- The line or text color: a CSS color, or a column mapped to colors.
sizechannel- The heads' diameter in CSS pixels: a number, or a column mapped through size_scale (by default onto the automatic size range). Default:
5px. widthchannel- The line width: a number, or a column mapped to widths. In px.
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).
size_scalescale- The size's scale, which marks can share: continuous({domain, range, transform}) for numbers (without a range, the automatic one), or categories with a numeric range.
width_scalescale- A scale for width that marks can share, as size_scale.
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. blend"normal" | "additive" | "multiply" | "screen" | "subtractive"- 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.
respondboolean | "selected" | "brushed" | "hovered" | "nearby" | "nearest" | selection | array- 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:
300ms. animation_easing"linear" | "quad-in" | "quad-out" | "quad-in-out" | "cubic-in" | "cubic-out" | "cubic-in-out" | "sine-in-out"- The animation's easing. Default:
"cubic-in-out".
Symbol rotation
rotationnumber- The symbol's rotation. Default:
0degrees.
Symbol
shapestring | column | string[]- The point symbol: a shape name, a column of categories mapped to shapes, or one name per row. Default:
"circle". shape_scalescale- A categorical() scale from the shape column's categories to shape names.
Size units
size_units"px" | "data"- What size measures: CSS pixels whatever the zoom, or units of the x axis, so zooming scales the points. Default:
"px".
Legend settings
legend_font_sizenumbersetting- The size of the mark's legend text. Default: the theme's (14 in the default theme). In px.
legend_font_familystringsetting- The font of the mark's legend text, a CSS font-family. Default: the plot's font.
legend_text_colorcolorsetting- The color of the mark's legend text. Default:
"#40505d". legend_tick_formatstringsetting- How a colorbar labels numbers: a d3-format string, or a %-pattern for dates. Default:
".3~g".
Color settings
quantizebooleansetting- Step a numeric fill or color into `levels` colors instead of a smooth gradient. Default:
False. levelsnumbersetting- How many colors quantize steps through. Default:
10.
Limits
max_elementsnumbersetting- The most rows the mark prepares on the GPU. Default:
250000.
The mark's own axes
x_transform"linear" | "log" | "sqrt" | "symlog"setting- This mark's own x transform, instead of its frame's. Default: its frame's.
x_invertbooleansetting- Reverse this mark's x direction. Default:
False. xbounds[number, number]setting- The x extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
xrange[number, number]setting- Where this mark's x extent lands, in its frame's world units. Default: its frame's.
y_transform"linear" | "log" | "sqrt" | "symlog"setting- This mark's own y transform, instead of its frame's. Default: its frame's.
y_invertbooleansetting- Reverse this mark's y direction. Default:
False. ybounds[number, number]setting- The y extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
yrange[number, number]setting- Where this mark's y extent lands, in its frame's world units. Default: its frame's.
z_transform"linear" | "log" | "sqrt" | "symlog"setting- 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.
Geometry
detailnumbersetting- How finely a point's or a surface's geometry is divided (sphere segments, grid cells).
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 stem from baseline (a number or a column, default 0) to each y, on either side of it, with a point at the end. Stems run along y, or along x when y is the categorical column (orientation overrides the detection); z places both parts in 3D. Style the stems with their stem object (stem={{ color: "gray", width: 2, dash: [2, 2] }} in Svelte, stem={"color": "gray", "width": 2, "dash": [2, 2]} in Python), or with theme.marks.Lollipop.color and .width. stemColor and stemWidth are removed; use stem.color and stem.width. The heads are Points, sized as Points are: size is a head’s diameter in CSS pixels (5 by default), and the stems default to 1.5 CSS pixels wide. size and the head-only properties (fill, shape, select, hover, brush) apply to the heads, while visible, opacity, respond, identity, enterEffect/exitEffect, and the animation switches apply to both, and the mark’s one legend entry toggles both.
Lollipop is a built-in template (TODO 130.3): BarGeometry places each stem’s base and tip, a Segments draws the stems and Points the heads. It is importable from hmplot/charts; “Writing a pattern” in docs/USAGE.md has a hand-written lollipop as a worked example.