Chart Factories
Chart factories compose marks, axes, annotations, and chrome into a public
Chart. The generated inventory below is organized by chart family; use the
Chart Gallery when visual browsing is more
helpful. Its names, signatures, and defaults come directly from XY's public
Python callables.
Use chart() when different mark kinds share a panel. A family container is
usually clearer when the children represent one chart family.
Generated Factory API
Line and Area
xy.line_chart
A line chart composing `line` marks and axis/legend children.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.area_chart
An area chart composing `area` marks and axis/legend children.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.step_chart
A step chart composing `step` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.stairs_chart
A stairs chart composing `stairs` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
Scatter
xy.scatter_chart
A scatter chart composing `scatter` marks and axis/legend children.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
Polar
xy.polar_chart
A polar chart: the same marks, rendered through polar coordinates.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.radar_chart
A radar (spider) chart: one closed polygon per series.
Props
| Prop | Type | Description |
|---|---|---|
categories | Sequence[str] | Spoke labels, one per value. |
*children | Component | `area` (filled) or `line` (outline) marks carrying values, plus any axis/legend children. |
fill | bool | When False, filled `area` children are rebuilt as `line` outlines, so one call switches a whole chart between filled and outline radar without editing every mark. |
**props | Any | Any `polar_chart` keyword. |
xy.polar_bar_chart
Radial bars: each bar is an annular sector rather than a rectangle.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | `bar` marks plus axis/legend children. |
**props | Any | Any `polar_chart` keyword. |
xy.pie_chart
A pie or donut: one slice per label, sized by value.
Props
| Prop | Type | Description |
|---|---|---|
labels | Sequence[Any] | One category name per slice. |
values | ArrayLike | One non-negative value per slice. |
*children | Component | Extra components (legend placement, a user tooltip, …). |
hole | float | Inner radius fraction; 0 is a full pie, the default is a donut. |
pad | float | Gap between neighbouring slices, in PIXELS — constant from the hole to the rim. An angular pad would be `r · dtheta` wide and so taper to nothing toward the centre, which reads as the spacing being applied unevenly across the slice. |
colors | Optional[Sequence[str]] | One CSS colour per slice. Defaults to the palette cycle. |
corner_radius | float | Rounded slice corners, in px. |
show_values | bool | Include the value in the slice's name (legend + tooltip). Dropped for a slice whose value renders identically to its share — percentage-shaped input would otherwise print the same number twice. |
show_percent | bool | Include the share in the slice's name (legend + tooltip). |
**props | Any | Any `polar_chart` keyword (`width`, `height`, `title`, …). |
xy.wind_rose
A wind rose: directional frequency, stacked by speed band.
Props
| Prop | Type | Description |
|---|---|---|
directions | ArrayLike | Bearings in degrees, one per observation. |
speeds | ArrayLike | Speeds, one per observation. |
*children_in | Component | Extra components — an `xy.legend`, or an `xy.tooltip` to replace the default direction/count readout. |
sectors | int | Number of angular bins around the circle. |
speed_bins | Optional[Sequence[float]] | Upper edges of the speed bands. Defaults to four quartile bands derived from the data. Each band takes the next colour from the chart's palette cycle, as stacked series do everywhere else. |
**props | Any | Any `polar_chart` keyword. |
Bar and Column
xy.bar_chart
A bar chart composing `bar` marks and axis/legend children.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.column_chart
A column chart composing `column` marks and axis/legend children.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
Distributions
xy.histogram_chart
A histogram chart composing `histogram` marks and axis/legend children.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.ecdf_chart
An ECDF chart composing `ecdf` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.box_chart
A box/distribution chart composing `box` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.violin_chart
A violin chart composing `violin` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
Density and Grids
xy.hexbin_chart
A hexbin chart composing `hexbin` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.heatmap_chart
A heatmap chart composing `heatmap` marks and axis/legend children.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.contour_chart
A contour chart composing `contour` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
Uncertainty
xy.error_band_chart
An uncertainty-band chart composing `error_band` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.errorbar_chart
An error-bar chart composing `errorbar` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
Specialized
xy.stem_chart
A stem chart composing `stem` marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.segments_chart
A segment chart composing generic independent segment marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.sankey_chart
A Sankey diagram chart: flow layout, gradient ribbons, hidden axes.
Props
| Prop | Type | Description |
|---|---|---|
links | Any | Defaults to None. |
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.funnel_chart
A funnel chart: ordered stages, centered segments, hidden cross axis.
Props
| Prop | Type | Description |
|---|---|---|
*children | Any | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.triangle_mesh_chart
A filled triangular mesh chart.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
Annotations
xy.chart
A neutral single-panel chart for overlays and mixed mark composition.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
Facets and Layers
xy.chart
A neutral single-panel chart for overlays and mixed mark composition.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Additional positional arguments. |
**props | Any | Additional keyword arguments. |
xy.facet_chart
Repeat the child mark composition once per value of ``by``.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Marks, axes, annotations, and chart chrome for each panel. |
by | Union[str, ArrayLike, None] | Facet values or a column name resolved from chart-level data. |
cols | int | Maximum number of panel columns. |
share_x | bool | Whether panels share an x domain. |
share_y | bool | Whether panels share a y domain. |
link | Optional[Union[str, bool]] | Runtime-linked axes: ``True``/``"both"`` for both axes, ``"x"`` or ``"y"`` for one axis, and ``False``/``None`` to disable. |
link_select | bool | Whether data-space selections are echoed across panels. |
gap | int | Gap between panels in pixels. |
**props | Any | Additional shared chart properties. ``width`` is the total grid width, while ``height`` is the height of each panel; the composed height grows with the number of facet rows. |
Annotation-only compositions use the neutral chart() container, so that
factory appears under Annotations. It also appears beside facet_chart() in
Facets and Layers because layered marks use the same neutral container.
Shared Chart Props
Shared chart props
Initialize a chart composition.
Props
| Prop | Type | Description |
|---|---|---|
children | tuple[Component, ...] | Marks, axes, annotations, and chart chrome. |
title | Optional[str] | Title shown above the plot. |
width | int | str | Chart width in pixels or a CSS size such as ``"100%"``. |
height | int | str | Chart height in pixels or a CSS size such as ``"100%"``. |
padding | Union[float, Sequence[float], None] | Plot margins, as one value or a sequence of side values. Use zero for an edge-to-edge sparkline. |
data | TableLike | Chart-level data used by marks that omit their own ``data``. |
class_name | Optional[str] | CSS class applied to the chart container. |
class_names | Optional[dict[str, str]] | CSS classes keyed by stable chart DOM slot. |
style | Optional[dict[str, StyleValue]] | Inline style overrides for the chart container. |
styles | Optional[dict[str, dict[str, StyleValue]]] | Inline style mappings keyed by stable chart DOM slot. |
on_hover | Optional[Callable[[dict], None]] | Callback receiving hover event payloads. |
on_click | Optional[Callable[[dict], None]] | Callback receiving picked-mark click payloads. |
on_brush | Optional[Callable[[dict], None]] | Callback receiving brush event payloads. |
on_select | Optional[Callable[[Selection], None]] | Callback receiving data-space selections. |
on_view_change | Optional[Callable[[dict], None]] | Callback receiving viewport change payloads. |
hover | Optional[bool] | Whether pointer movement emits hover events. |
click | Optional[bool] | Whether picked marks emit click events. |
select | Optional[bool] | Whether shift-drag box selection is enabled. |
brush | Optional[bool] | Whether brush selection is enabled. |
crosshair | Optional[bool] | Whether plot-aligned hover guides are shown. |
navigation | Optional[bool] | Whether browser pan and zoom navigation is enabled. |
pan | Optional[bool] | Whether plain-drag panning is enabled. |
pan_axes | Optional[tuple[str, ...]] | Declared axis IDs translated by pan gestures. |
zoom | Optional[bool] | Whether viewport zoom is enabled. Defaults to on for Cartesian charts and off for polar ones (`wind_rose` excepted); |
default_drag_action | Optional[DefaultDragAction] | Initial action performed by a plain plot drag. |
zoom_axes | Optional[tuple[str, ...]] | Declared axis IDs changed by zoom gestures and controls. |
zoom_limits | Optional[ZoomLimits] | Minimum and maximum magnification globally or by axis. |
wheel_zoom | Optional[bool] | Whether wheel and trackpad zoom is available. |
box_zoom | Optional[bool] | Whether box zoom is available as a drag action. |
zoom_buttons | Optional[bool] | Whether modebar Zoom In/Out commands are available. |
double_click_reset | Optional[bool] | Whether double-click restores ``reset_axes``. |
reset_axes | Optional[tuple[str, ...]] | Declared axis IDs restored by reset. |
link_group | Optional[str] | Identifier used to synchronize charts in the browser. |
link_axes | Optional[tuple[str, ...]] | Axes synchronized within the link group. |
coords | str | Coordinate system, ``"cartesian"`` (default) or ``"polar"``. Under ``"polar"`` each mark's first channel is the angle and its second is the radius. Prefer ``xy.polar_chart(...)``, which sets this for you. |
The “Shared chart props” table is generated from the public Chart
constructor. Every ordinary factory accepts those props through **props;
facet_chart exposes its grid controls directly in its generated factory
table and forwards the remaining props to each panel.
Facet Constraints
facet_chart requires by= values or a column name resolved from chart-level
data=. Its width and height must be positive integer pixel counts; panel
columns and gap are integers. Marks that use row-aligned raw channels must use
compatible arrays or column names so each panel can be subset safely.
Shared facet axes coordinate panel domains and browser viewport changes.
FacetChart supports display, export, and memory reporting, but does not expose
Chart.append(), pick(), or select_range().
See Composition model for usage and Chart methods for the returned objects.