You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/python/figure-structure.md
+8-8Lines changed: 8 additions & 8 deletions
Original file line number
Diff line number
Diff line change
@@ -53,7 +53,7 @@ Figures are represented as trees with named nodes called "attributes" which are
53
53
54
54
When building a figure, it is *not necessary to populate every attribute* of every object. At render-time, the JavaScript layer will compute default values for each required unspecified attribute, depending upon the ones that are specified, as documented in the [Figure Reference](/python/reference/). An example of this would be `layout.xaxis.range`, which may be specified explicitly, but if not will be computed based on the range of `x` values for every trace linked to that axis. The JavaScript layer will ignore unknown attributes or malformed values, although the `plotly.graph_objects` module provides Python-side validation for attribute values. Note also that if [the `layout.template` key is present (as it is by default)](/python/templates/) then default values will be drawn first from the contents of the template and only if missing from there will the JavaScript layer infer further defaults. The built-in template can be disabled by setting `layout.template="none"`.
55
55
56
-
## High-Level Structure
56
+
###High-Level Structure
57
57
58
58
The root node of a figure may contain three attributes:
59
59
@@ -82,7 +82,7 @@ The root node of a figure may contain three attributes:
82
82
83
83
> Note: At [render-time](/python/renderers/), it is also possible to control certain figure behaviors which are not considered part of the figure proper i.e. the behaviour of the "modebar" and how the figure relates to mouse actions like scrolling. The object that contains these options is called the [`config`, and has its own documentation page](/python/configuration-options/). It is exposed in Python as the `config` keyword argument of the `.show()` method on `plotly.graph_objects.Figure` objects.
84
84
85
-
## Positioning With Paper or Container Coordinates
85
+
###Positioning With Paper or Container Coordinates
86
86
87
87
Various figure components configured within the layout of the figure support positioning attributes named `x` or `y`, whose values may be specified in "paper coordinates" (sometimes referred to as "plot fractions" or "normalized coordinates"). Examples include `layout.xaxis.domain` or `layout.legend.x` or `layout.annotation[].x`.
88
88
@@ -92,7 +92,7 @@ Note that the contents of the `layout.margin` attribute are by default computed
92
92
93
93
The figure title may be positioned using "container coordinates" which have `(0,0)` and `(1,1)` anchored at the bottom-left and top-right of the figure, respectively, and therefore are independent of the values of layout.margin.
94
94
95
-
## 2D Cartesian Trace Types and Subplots
95
+
###2D Cartesian Trace Types and Subplots
96
96
97
97
The most commonly-used kind of subplot is a [two-dimensional Cartesian subplot](/python/axes/). Traces compatible with these subplots support `xaxis` and `yaxis` attributes whose values must refer to corresponding objects in the layout portion of the figure. For example, if `xaxis="x"`, and `yaxis="y"` (which is the default) then this trace is drawn on the subplot at the intersection of the axes configured under `layout.xaxis` and `layout.yaxis`, but if `xaxis="x2"` and `yaxis="y3"` then the trace is drawn at the intersection of the axes configured under `layout.xaxis2` and `layout.yaxis3`. Note that attributes such as `layout.xaxis` and `layout.xaxis2` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of different types can be drawn on the same subplot.
98
98
@@ -110,7 +110,7 @@ The following trace types are compatible with 2d-cartesian subplots via the `xax
110
110
*[`carpet`](/python/carpet-plot/): a special trace type for building [carpet plots](/python/carpet-plot/), in that other traces can use as subplots (see below)
111
111
*[`splom`](/python/splom/): multi-dimensional scatter plots which implicitly refer to many 2-d cartesian subplots at once.
112
112
113
-
## 3D, Polar and Ternary Trace Types and Subplots
113
+
###3D, Polar and Ternary Trace Types and Subplots
114
114
115
115
Beyond 2D cartesian subplots, figures can include [three-dimensional cartesian subplots](/python/3d-charts/), [polar subplots](/python/polar-chart/) and [ternary subplots](/python/ternary-plots/). The following trace types support attributes named `scene`, `polar` or `ternary`, whose values must refer to corresponding objects in the layout portion of the figure i.e. `ternary="ternary2"` etc. Note that attributes such as `layout.scene` and `layout.ternary2` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of a compatible type can be placed on the same subplot.
116
116
@@ -130,7 +130,7 @@ The following trace types are compatible with ternary subplots via the `ternary`
130
130
131
131
*[`scatterternary`](/python/ternary-plots/), which can be used to draw individual markers, [curves and filled areas](/python/ternary-contour/)
132
132
133
-
## Map Trace Types and Subplots
133
+
###Map Trace Types and Subplots
134
134
135
135
Figures can include two different types of map subplots: [geo subplots for outline maps](/python/map-configuration/) and [mapbox subplots for tile maps](/python/mapbox-layers/). The following trace types support attributes named `geo` or `mapbox`, whose values must refer to corresponding objects in the layout i.e. `geo="geo2"` etc. Note that attributes such as `layout.geo2` and `layout.mapbox` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of a compatible type can be placed on the same subplot.
136
136
@@ -145,7 +145,7 @@ The following trace types are compatible with mapbox subplots via the `mapbox` a
145
145
*[`choroplethmapbox`](/python/mapbox-county-choropleth/): colored polygons on tile maps
146
146
*[`densitymapbox`](/python/mapbox-density-heatmaps/): density heatmaps on tile maps
147
147
148
-
## Traces Which Are Their Own Subplots
148
+
###Traces Which Are Their Own Subplots
149
149
150
150
Certain trace types cannot share subplots, and hence have no attribute to map to a corresponding subplot in the layout. Instead, these traces are their own subplot and support a `domain` attribute for position, which enables the trace to be positioned in paper coordinates (see below). With the exception of `pie` and `funnelarea`, such traces also do not support legends (see below)
151
151
@@ -158,7 +158,7 @@ The following trace types are their own subplots and support a domain attribute:
*[`indicator`](http://indicators/): big numbers, [gauges](/python/gauge-charts/), and [bullet charts](/python/bullet-charts/)
160
160
161
-
## Carpet Trace Types and Subplots
161
+
###Carpet Trace Types and Subplots
162
162
163
163
Certain trace types use [traces of type `carpet` as a subplot](/python/carpet-plot/). These support a `carpet` attribute whose value must match the value of the `carpet` attribute of the `carpet` trace they are to be drawn on. Multiple compatible traces can be placed on the same `carpet` trace.
164
164
@@ -167,7 +167,7 @@ The following trace types are compatible with `carpet` trace subplots via the `c
167
167
*[`scattercarpet`](/python/carpet-scatter/), which can be used to draw individual markers, curves and filled areas
168
168
*[`contourcarpet`](/python/carpet-plot/)
169
169
170
-
## Trace Types, Legends and Color Bars
170
+
###Trace Types, Legends and Color Bars
171
171
172
172
Traces of most types can be optionally associated with a single legend item in the [legend](/python/legend/), which can be shown via the `showlegend` attribute. Traces which are their own subplots (see above) do not support this, with the exception of traces of type `pie` and `funnelarea` for which every distinct color represented in the trace gets a separate legend item. Users may show or hide traces by clicking or double-clicking on their associated legend item. Traces that support legend items also support the `legendgroup` attribute, and all traces with the same legend group are treated the same way during click/double-click interactions.
0 commit comments