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: migration-guide.md
+52-4Lines changed: 52 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,7 @@
1
1
# Migration to Version 3
2
-
There are many new and great features in Plotly 3.0 including deeper Jupyter integration, deeper figure validation, improved performance, and more. This guide contains the a summary of the breaking changes that you need to be aware of when migrating code from version 2 to version 3.
2
+
There are many new and great features in Plotly 3.0 including deeper Jupyter integration, deeper figure validation, improved performance, and more. This guide contains the a summary of the breaking changes that you need to be aware of when migrating code from version 2 to version 3.
3
+
4
+
For a high level overview, read our [announcement post](https://medium.com/@plotlygraphs/introducing-plotly-py-3-0-0-7bb1333f69c6).
3
5
4
6
## Simple FigureWidget Example
5
7
We now have seamless integration with the Jupyter widget ecosystem. We've introduced a new graph object called `go.FigureWidget` that acts like a regular plotly `go.Figure` that can be directly displayed in the notebook.
@@ -10,8 +12,11 @@ import plotly
10
12
import plotly.graph_objs as go
11
13
12
14
f = go.FigureWidget()
15
+
f # printing the widget will display it
13
16
```
14
17
18
+
This means that `plotly.offline.iplot` and `plotly.offline.init_notebook_mode()` are no longer required (although still supported).
19
+
15
20
## Tab Completion
16
21
Entering ``f.add_<tab>`` displays add methods for all of the supported trace types. Try it!
Notice that you don't need to use one of the legacy `iplot` methods to display a `FigureWidget`. Its visual representation is the plot itself!
33
-
34
37
## New Plotly Object Representation
35
38
Plotly figures and graph objects have an updated `__repr__` method that displays objects in a pretty printed form that can be copied, pasted, and evaluated to recreate the object.
36
39
@@ -111,11 +114,56 @@ go.Scatter(
111
114
)
112
115
```
113
116
117
+
You can still use `dict` as well. The previous figure is equivalent to:
118
+
119
+
```
120
+
import plotly.graph_objs as go
121
+
dict(
122
+
type='scatter',
123
+
x=[0],
124
+
y=[0],
125
+
marker=go.scatter.Marker(
126
+
color='rgb(255,45,15)'
127
+
)
128
+
)
129
+
```
130
+
131
+
which is also equivalent to
132
+
```
133
+
import plotly.graph_objs as go
134
+
dict(
135
+
type='scatter',
136
+
x=[0],
137
+
y=[0],
138
+
marker=dict(
139
+
color='rgb(255,45,15)'
140
+
)
141
+
)
142
+
```
143
+
114
144
### Property Immutability
115
145
In order to support the automatic synchronization a `FigureWidget` object and the front-end view in a notebook, it is necessary for the `FigureWidget` to be aware of all changes to its properties. This is accomplished by presenting the individual properties to the user as immutable objects. For example, the `layout.xaxis.range` property may be assigned using a list, but it will be returned as a tuple. Similarly, object arrays (`Figure.data`, `Layout.images`, `Parcoords.dimensions`, etc.) are now represented as tuples of graph objects, not lists.
116
146
117
147
### Object Array Classes Deprecated
118
-
Since graph object arrays are now represented as tuple of graph objects, the following object array classes are deprecated: `go.Data`, `go.Annotations`, and `go.Frames`
148
+
Since graph object arrays are now represented as tuple of graph objects, the following object array classes are deprecated: `go.Data`, `go.Annotations`, and `go.Frames`. Instead, just use lists.
149
+
150
+
That is, previously we used:
151
+
```
152
+
layout = go.Layout(
153
+
annotations=go.Annotations([
154
+
go.layout.Annotations(text='annotation')
155
+
])
156
+
)
157
+
```
158
+
159
+
Now, we should write:
160
+
```
161
+
layout = go.Layout(
162
+
annotations=[
163
+
go.layout.Annotations(text='annotation')
164
+
]
165
+
)
166
+
```
119
167
120
168
### New Figure.data Assignment
121
169
There are new restriction on the assignment of traces to the `data` property of a figure. The assigned value must be a list or a tuple of a subset of the traces already present in the figure. Assignment to `data` may be used to reorder and remove existing traces, but it may not currently be used to add new traces. New traces must be added using the `add_trace`, `add_traces`, or `add_*` methods.
0 commit comments