Contour Plots in Python
A contour plot (also called a contour graph) in python draws iso-value lines across a 2D field so ridges,
basins, and gradients in the surface become visible. With xy you build an
interactive contour plot from a NumPy grid: choose the number of levels, fill
between them or keep clean lines, and pan, zoom, and hover work by default.
Jump to creating a contour plot, levels and fills, or the options table.
Create a Contour Plot
Pass a 2D array of values to contour, with optional x and y coordinates.
Set levels to control how many iso-value bands are drawn and filled=True to
shade between them:
Line Contours at Explicit Levels
Keep filled=False for clean iso-lines and pass levels an explicit list to
place contours at exact values — useful when specific thresholds matter — with
width thickening the strokes:
Signed Fields with Dashed Negatives
For a field that crosses zero, set dash_negative=True so negative contours
are dashed, use more levels to resolve the structure, and add an
xy.colorbar() to tie levels back to values:
Levels, Filled, and Line Contours
levels sets how many iso-value bands the field is sliced into — more levels
resolve finer structure. Keep filled=False for clean contour lines, or set
filled=True to shade each band with the colormap. Use dash_negative to
distinguish contours below zero, which is handy for signed fields.
Contour Plot Options
Add to show the level-to-color
scale. Pass column names with data= instead of arrays when your data is a
table.
Related Charts
- Heatmaps — color every grid cell instead of drawing bands.
- Hexbin plots — build a density field from scattered points.
- Colorbar component — add a visible color scale to a contour plot.
API Reference
xy.contour_chart
A contour chart composing `contour` 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 make a contour plot in Python?
Pass a 2D array to xy.contour(z, x=x, y=y) inside xy.contour_chart(...) and
render it. The contour chart supports pan, zoom, and hover out of the box.
What is the difference between a filled and a line contour?
filled=False draws only the iso-value lines; filled=True shades each band
between contours with the colormap for a continuous surface look.
How do I control the number of contour levels?
Set levels to an integer for that many evenly spaced bands, or pass an
explicit list of values to place contours at exact levels.
How do I show negative contours differently?
Set dash_negative=True so contours with negative values are dashed, making the
sign of a signed field easy to read.