Parameter-space plots
Visualizing values defined over two independent parameters
Plotly · Class
go.Carpet
A go.Carpet trace defines a Plotly carpet plot using parameter coordinates a and b and plotted coordinates x and y. Its aaxis and baxis settings control the carpet axes, while related traces can reference it by identifier.
How it works
go.Carpet creates a carpet-plot trace whose points are described by parameter coordinates a and b, with corresponding plotted coordinates in y and optionally x. Axis appearance is configured through aaxis and baxis, and the trace can serve as the coordinate system for related carpet traces.
Syntax
plotly.graph_objects.Carpet(arg=None, a=None, a0=None, aaxis=None, b=None, b0=None, baxis=None, carpet=None, customdata=None, da=None, db=None, hoverinfo=None, hoverlabel=None, hovertemplate=None, ids=None, meta=None, name=None, opacity=None, type=None, uirevision=None, visible=None, x=None, y=None, **kwargs)Parameters
| Name | Type | Description |
|---|---|---|
a | list, numpy array, or Pandas series | Parameter-coordinate values along the a direction; may be one- or two-dimensional according to the trace data. |
b | list, numpy array, or Pandas series | Parameter-coordinate values along the b direction; may be one- or two-dimensional according to the trace data. |
x | list, numpy array, or Pandas series | Plotted x coordinates for carpet points; optional when creating a cheater plot. |
y | list, numpy array, or Pandas series | Plotted y coordinates for carpet points. |
aaxis | Carpet.Aaxis | Configuration for the a parameter axis. |
baxis | Carpet.Baxis | Configuration for the b parameter axis. |
carpet | string | Identifier used by related carpet traces. |
Returns
A plotly.graph_objects.Carpet trace object.
Key points
- Use y for the carpet's plotted coordinates and add x when explicit horizontal coordinates are needed.
- Inputs may be two-dimensional, with x and y dimensions aligned to the corresponding a and b dimensions.
- The y attribute represents the plotted y coordinate at every carpet point.
- Assign an identifier to the carpet when scattercarpet or contourcarpet traces need to reference it.
- Configure the parameter axes with aaxis and baxis settings.
Common mistakes
- Omitting x produces a cheater plot: Plotly derives x from y rather than using explicit x coordinates.
- For one-dimensional inputs, keep x, y, a, and b the same length so each point has matching coordinates.
Example: Basic carpet plot
import plotly.graph_objects as go
fig = go.Figure(go.Carpet(
a=[0, 1, 2, 3, 0, 1, 2, 3],
b=[4, 4, 4, 4, 5, 5, 5, 5],
x=[2, 3, 4, 5, 2.2, 3.1, 4.1, 5.1],
y=[1, 1.4, 1.6, 1.75, 2, 2.5, 2.7, 2.75]
))
fig.show()Creates and displays a Plotly carpet trace from paired a/b parameter coordinates and x/y plot coordinates.
When to use it
Custom carpet axes
Showing a coordinate grid with custom parameter axes
Related carpet traces
Adding contour or scatter traces to an existing carpet coordinate system
Interview questions
QHow are coordinates represented in go.Carpet?
Carpet coordinates use a and b as the parameter-space coordinates. The displayed location is supplied by y and optionally x; x and y can be either one-dimensional or two-dimensional arrays.
Follow-up: What happens when x is omitted? Plotly treats the trace as a cheater plot and fills x using y.
QWhat shape constraints apply to Carpet data?
A one-dimensional representation requires x, y, a, and b to have equal lengths. Two-dimensional x and y arrays must match the corresponding dimensions of a and b.
Follow-up: Why might a two-dimensional representation be preferable? It can express a structured grid whose dimensions correspond directly across the parameter and plotted-coordinate arrays.
QHow are axes and related traces connected to a carpet?
The aaxis and baxis attributes control the two carpet axes, including their visual configuration. A related scattercarpet or contourcarpet trace can identify this carpet through its carpet attribute.
Follow-up: How can another trace select the coordinate system? Give that trace the identifier assigned to the Carpet trace's carpet attribute.
Related
plotly.graph_objects.Carpet.Aaxisplotly.graph_objects.Carpet.Baxisplotly.graph_objects.Scattercarpetplotly.graph_objects.Contourcarpet