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
The goal of the `plotly.py`graphing library is to provide a pleasant Python interface for creating figure specifications for display using the `plotly.js` JavaScript library.
42
+
The goal of the `plotly.py`package is to provide a pleasant Python interface for creating figure specifications which are displayed by the [`plotly.js`](https://plot.ly/javascript) JavaScript graphing library.
43
43
44
44
In the context of the `plotly.js` library, a figure is specified by a declarative [JSON](https://www.json.org/json-en.html) data structure.
45
45
46
-
Therefore, the ultimate responsibility of `plotly.py` is to produce Python dictionaries that can be serialized into a JSON data structure that represents a valid figure.
46
+
Therefore, you should always keep in mind as you are creating and updating figures using the `plotly.py`package that its ultimate goal is to help users produce Python [dictionaries](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) that can be automatically [serialized](https://en.wikipedia.org/wiki/Serialization) into the JSON data structure that the `plotly.js` graphing library understands.
47
47
48
48
#### Figures As Dictionaries
49
49
50
-
The `fig` dictonary in the example below describes a figure containing a single `bar` trace and a title.
50
+
The `fig` dictonary in the example below describes a figure. It contains a single `bar` trace and a title.
51
51
52
52
```python
53
-
fig = {
53
+
fig =dict({
54
54
"data": [{"type": "bar",
55
55
"x": [1, 2, 3],
56
56
"y": [1, 3, 2]}],
57
-
"layout": {"title": {"text": "A Bar Chart"}}
58
-
}
57
+
"layout": {"title": {"text": "A Figure Specified By Python Dictionary"}}
58
+
})
59
59
60
60
# To display the figure defined by this dict, use the low-level plotly.io.show function
61
61
import plotly.io as pio
@@ -65,39 +65,45 @@ pio.show(fig)
65
65
66
66
Let's take a closer look at structure of the `fig` dictionary in order to better understand how `plotly.py` figures are built.
67
67
68
-
The first thing to notice is that the `fig` dictionary contains two keys. The `"data"`key stores a list of dictionaries while the `"layout"` key stores a dictionary.
68
+
##### The `"data"`Key
69
69
70
-
The `"data"` key stores a list of dictonaries because a figure can be made up of multiple individual traces. Each trace specification dictionary in the `"data"`list has a special `"type"` key that indicates the trace type that is being defined (e.g. a `"bar"`, `"scatter"`, `"contour"`, etc.). The rest of the keys in the trace specification dictionary are used to configure the properties of the trace of this type.
70
+
The `"data"` key stores the value of list which describes the trace or traces which make up a figure. It is still a list even if the figure only contains one trace, as in the example above.
71
71
72
-
The`"layout"` key stores a dictionary that specifies the properties of the figure's layout. In contrast to trace configuration options that apply to individual traces, the layout configuration options apply to the figure as a whole, customizing items like the axes, annotations, shapes, legend, and more.
72
+
Each trace in the list stored by the `"data"` key is itself defined by a dictionary. The type of the trace (`"bar"`, `"scatter"`, `"contour"`, etc...) is specified with a `"type"` key, and the rest of the keys in a trace specification dictionary (`x`, `y`, etc...) are used to define the properties specific to the trace of that type.
73
+
74
+
##### The `"layout"` Key
75
+
76
+
The`"layout"` key stores a dictionary that specifies properties related to customizing how the figure looks, such as its title, typography, margins, axes, annotations, shapes, legend and more. In contrast to trace configuration options, which apply only to individual traces, layout configuration options apply to the figure as a whole.
73
77
74
78
The [_Full Reference_](https://plot.ly/python/reference/) page contains descriptions of all of the supported trace and layout attributes and configuration options.
75
79
76
80
If working from the _Full Reference_ to build figures as Python dictionaries and lists suites your needs, go for it!
77
81
78
-
This is a perfectly valid way to use `plotly.py` to build figures. On the other hand, if you would like an API that offers a bit more assistance, read on to learn about `graph objects`.
82
+
This is a perfectly valid way to use `plotly.py` to build figures. On the other hand, if you would like to use an API that offers you a bit more assistance in the figure creation process, read on to learn about `graph objects`.
79
83
80
84
#### Figures as Graph Objects
81
85
82
86
As an alternative to working with Python dictionaries, the `plotly.py` graphing library provides a hierarchy of classes called "graph objects" that may be used to construct figures. Graph objects have several benefits compared to plain Python dictionaries.
83
87
84
-
1. Graph objects provide precise data validation. If you provide an invalid property name or an invalid property value as the key to a graph object, an exception will be raised with a helpful error message describing the problem. This is not the case if you use plain Python dictionaries to build your figures.
88
+
1. Graph objects provide precise data validation. If you provide an invalid property name or an invalid property value as the key to a graph object, an exception will be raised with a helpful error message describing the problem. This is not the case if you use plain Python dictionaries and lists to build your figures.
85
89
86
-
2. Graph objects contain descriptions of each property as Python `docstrings`. You can use these `docstrings` to learn about the available properties as an alternative to consulting the _Full Reference_.
90
+
2. Graph objects contain descriptions of each valid property as Python `docstrings`. You can use these `docstrings`in the development environment of your choice to learn about the available properties as an alternative to consulting the online_Full Reference_.
87
91
88
92
3. Properties of graph objects can be accessed using both dictionary-style key lookup (e.g. `fig["layout"]`) or class-style property access (e.g. `fig.layout`).
89
93
90
94
4. Graph objects support higher-level convenience functions for making updates to already constructed figures, as described below.
91
95
92
-
Graph objects are stored in a hierarchy of modules under the `plotly.graph_objects` package. Here is an example of one way that the figure in the example above could be constructed using graph objects.
96
+
**Graph objects are stored in a hierarchy of modules under the `plotly.graph_objects` package, so make sure to remember to `import plotly.graph_objects as go` when you want to use them.**
97
+
98
+
Below you can find an example of one way that the figure in the example above could be specified using a graph object instead of a dictionary.
93
99
94
100
```python
95
101
import plotly.graph_objects as go
96
102
97
103
fig = go.Figure(
98
104
data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],
99
105
layout=go.Layout(
100
-
title=go.layout.Title(text="A Bar Chart")
106
+
title=go.layout.Title(text="A Figure Specified By A Graph Object")
101
107
)
102
108
)
103
109
@@ -109,17 +115,36 @@ You can also create a graph object figure from a dictionary representation by pa
109
115
```python
110
116
import plotly.graph_objects as go
111
117
112
-
fig=go.Figure({
118
+
dict_of_fig=dict({
113
119
"data": [{"type": "bar",
114
120
"x": [1, 2, 3],
115
121
"y": [1, 3, 2]}],
116
-
"layout": {"title": {"text": "A Bar Chart"}}
122
+
"layout": {"title": {"text": "A Figure Specified By A Graph Object With A Dictionary"}}
117
123
})
118
124
125
+
fig = go.Figure(dict_of_fig)
126
+
119
127
fig.show()
120
128
```
121
129
122
-
Once you have a figure as a graph object, you can retrieve the Python dictionary representation using the `fig.to_dict()` method. You can also retrieve the JSON string representation using the `fig.to_json()` method.
130
+
##### Converting Graph Objects To Dictionaries and JSON
131
+
132
+
Graph objects can be turned into their Python dictionary representation using the `fig.to_dict()` method. You can also retrieve the JSON string representation of a graph object using the `fig.to_json()` method.
133
+
134
+
```python
135
+
import plotly.graph_objects as go
136
+
137
+
fig = go.Figure(
138
+
data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],
139
+
layout=go.Layout(
140
+
title=go.layout.Title(text="Converting Graph Objects To Dictionaries and JSON")
141
+
)
142
+
)
143
+
144
+
print("Dictionary Representation of A Graph Object:\n"+str(fig.to_dict()))
145
+
146
+
print("\n\nJSON Representation of A Graph Object:\n"+str(fig.to_json()))
147
+
```
123
148
124
149
### Creating Figures
125
150
@@ -136,7 +161,7 @@ import plotly.graph_objects as go
136
161
137
162
fig = go.Figure(
138
163
data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],
139
-
layout=dict(title=dict(text="A Bar Chart"))
164
+
layout=dict(title=dict(text="A Figure Specified By A Graph Object"))
facet_col="species", trendline="ols", title="Using update_traces() With Plotly Express Figures")
514
542
515
543
fig.update_traces(
516
544
line=dict(dash="dot", width=4),
@@ -542,18 +570,21 @@ Suppose the updates that you want to make to a collection of traces depend on th
542
570
543
571
As its first argument, the `for_each_trace()` method accepts a function that accepts and updates one trace at a time. Like `update_traces()`, `for_each_trace()` also accepts `selector`, `row`, and `col` arguments to control which traces should be considered.
544
572
545
-
Here is an example of using `for_each_trace()` to replace the equal-sign with a colon in the legend name of each trace in a figure produced by Plotly Express.
573
+
Here is an example of using `for_each_trace()` to convert the only markers for the `"setosa"` to square symbols in a Plotly Express Figure.
574
+
575
+
**Note that this is possible because Plotly Express figures are made up of a separate trace for each column in the input data frame**
0 commit comments