From 213602df6c89b45ce2b811ed2591171c961408e7 Mon Sep 17 00:00:00 2001 From: Chris Parmer Date: Fri, 6 Jul 2018 11:50:55 -0400 Subject: [PATCH] A few updates to the migration guide (#1048) --- migration-guide.md | 56 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 52 insertions(+), 4 deletions(-) diff --git a/migration-guide.md b/migration-guide.md index 71ea8e9d67..98f90b37ff 100644 --- a/migration-guide.md +++ b/migration-guide.md @@ -1,5 +1,7 @@ # Migration to Version 3 -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. +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. + +For a high level overview, read our [announcement post](https://medium.com/@plotlygraphs/introducing-plotly-py-3-0-0-7bb1333f69c6). ## Simple FigureWidget Example 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 import plotly.graph_objs as go f = go.FigureWidget() +f # printing the widget will display it ``` +This means that `plotly.offline.iplot` and `plotly.offline.init_notebook_mode()` are no longer required (although still supported). + ## Tab Completion Entering ``f.add_`` displays add methods for all of the supported trace types. Try it! ``` @@ -29,8 +34,6 @@ f ![Simple Scatter](example_images/simple_scatter.png) -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! - ## New Plotly Object Representation 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. @@ -111,11 +114,56 @@ go.Scatter( ) ``` +You can still use `dict` as well. The previous figure is equivalent to: + +``` +import plotly.graph_objs as go +dict( + type='scatter', + x=[0], + y=[0], + marker=go.scatter.Marker( + color='rgb(255,45,15)' + ) +) +``` + +which is also equivalent to +``` +import plotly.graph_objs as go +dict( + type='scatter', + x=[0], + y=[0], + marker=dict( + color='rgb(255,45,15)' + ) +) +``` + ### Property Immutability 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. ### Object Array Classes Deprecated -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` +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. + +That is, previously we used: +``` +layout = go.Layout( + annotations=go.Annotations([ + go.layout.Annotations(text='annotation') + ]) +) +``` + +Now, we should write: +``` +layout = go.Layout( + annotations=[ + go.layout.Annotations(text='annotation') + ] +) +``` ### New Figure.data Assignment 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.