Line Segment Charts in Python
A line segments chart (also called a segment plot or segment graph) draws
independent start-to-end segments, each with its
own pair of endpoints. With xy you plot line segments in Python for
transitions, ranges, or arbitrary geometry that a connected line can't express,
and you can color each segment by a data channel. Every segment chart is
interactive out of the box: pan, zoom, and hover work with no configuration.
Jump to creating a segment chart, when to use segments, or the options.
Create a Segment Chart
Pass start endpoints (x0, y0) and end endpoints (x1, y1) to segments.
Each row becomes one independent segment, and a per-segment color channel maps
through the colormap:
Draw Ranges as Horizontal Segments
Give every segment the same y0 and y1 to draw horizontal ranges — one row
per category — and use a constant color with a thick width and reduced
opacity for a Gantt-style timeline:
Map a Color Channel with a Colorbar
Pass a numeric array to color, pin its scale with domain, and add
xy.colorbar() so readers can decode the mapped values — here a slope field
colored by gradient:
When to Use Segments
Segments draw independent start-to-end line segments, each with its own endpoints, so they suit transitions, ranges, error bars, or arbitrary geometry that isn't a single ordered path. When observations form one continuous trend that should be connected in order, use the line chart. For discrete impulses anchored to a baseline, use the stem plot.
Line Segment Options
Pass column names with data= instead of arrays when your endpoints live in a
table.
Related Charts
- Stem plots — impulses anchored to a common baseline.
- Line charts — connect ordered observations into a single trend.
API Reference
xy.segments_chart
A segment chart composing generic independent segment marks.
Props
| Prop | Type | Description |
|---|---|---|
*children | 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. |
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. |
FAQ
How do I draw line segments in Python?
Call xy.segments(x0=..., y0=..., x1=..., y1=...) inside xy.segments_chart(...)
and render it. Each row of endpoints becomes one independent segment.
How do I color each segment differently?
Pass a per-segment list to color and set a colormap. Each segment's value is
mapped through the colormap; pass a single CSS color instead for a constant hue.
How are segments different from a line chart?
A line chart connects ordered points into one continuous path. Segments are independent — each has its own start and end — so they can point in any direction and need not share endpoints.
Can I use segments for ranges or error bars?
Yes. Set the start and end endpoints to the low and high values of each range; because every segment is independent, they can represent arbitrary intervals.