|
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. To get started right away with Plotly, check out the tutorial below: |
| 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 | 3 |
|
4 | 4 | ## Simple FigureWidget Example |
5 | 5 | 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. |
@@ -43,7 +43,7 @@ FigureWidget({ |
43 | 43 | }) |
44 | 44 | ``` |
45 | 45 |
|
46 | | -## New add_trace method that handles subplots |
| 46 | +## New add trace methods that handle subplots |
47 | 47 | The legacy `append_trace` method for adding traces to subplots has been deprecated in favor of the new `add_trace`, `add_traces`, and `add_*` methods. Each of these new methods accepts optional row/column information that may be used to add traces to subplots for figures initialized by the `plotly.tools.make_subplots` function. |
48 | 48 |
|
49 | 49 | Let's create a subplot then turn it into a FigureWidget to display in the notebook. |
|
80 | 80 |
|
81 | 81 | ## Breaking Changes |
82 | 82 |
|
| 83 | +## Graph Objects Superclass |
| 84 | +Graph objects are no longer `dict` subclasses, though they still provide many `dict`-like magic methods. |
| 85 | + |
| 86 | +## Graph Objects Hierarchy |
| 87 | +All graph objects are now placed in a package hierarchy that matches their position in the object hierarchy. For example, `go.Marker` is now accessible as `go.scatter.Marker` or `go.bar.Marker` or whatever trace it is nested within. By providing unique objects under the parent-trace namespace, we can provide better validation (the properties for a marker object within a scatter trace may be different than the properties of a marker object within a bar trace). Although deprecated, the previous objects are still supported, they just won’t provide the same level of validation as our new objects. |
| 88 | + |
| 89 | +For example, the following approach to creating a `Marker` object for a `Scatter` trace is now deprecated. |
| 90 | +``` |
| 91 | +import plotly.graph_objs as go |
| 92 | +go.Scatter( |
| 93 | + x=[0], |
| 94 | + y=[0], |
| 95 | + marker=go.Marker( |
| 96 | + color='rgb(255,45,15)' |
| 97 | + ) |
| 98 | +) |
| 99 | +``` |
| 100 | + |
| 101 | +Instead, use the `Marker` object in the `go.scatter` package. |
| 102 | + |
| 103 | +``` |
| 104 | +import plotly.graph_objs as go |
| 105 | +go.Scatter( |
| 106 | + x=[0], |
| 107 | + y=[0], |
| 108 | + marker=go.scatter.Marker( |
| 109 | + color='rgb(255,45,15)' |
| 110 | + ) |
| 111 | +) |
| 112 | +``` |
| 113 | + |
83 | 114 | ### Property Immutability |
84 | | -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. |
| 115 | +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 | + |
| 117 | +### 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` |
85 | 119 |
|
86 | 120 | ### New Figure.data Assignment |
87 | 121 | 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. |
@@ -112,5 +146,7 @@ import plotly.graph_objs as go |
112 | 146 | go.Bar(x=[1]) |
113 | 147 | ``` |
114 | 148 |
|
115 | | -### Removal of undocumented methods |
116 | | -Several undocumented `Figure` methods have been removed. These include: `.to_string`, `.strip_style`, `.get_data`, `.validate` and `.to_dataframe`. |
| 149 | +### Removal of undocumented methods and properties |
| 150 | + - Several undocumented `Figure` methods have been removed. These include: `.to_string`, `.strip_style`, `.get_data`, `.validate` and `.to_dataframe`. |
| 151 | + |
| 152 | + - Graph objects no longer support the undocumented `_raise` parameter. They are always validated and always raise an exception on validation failures. It is still possible to pass a dict to `plot`/`iplot` with `validate=False` to bypass validation. |
0 commit comments