Review and updates to migration guide

migration-guide.md

@@ -1,11 +1,11 @@
-# Migration to Plotly 3.0.0
+# 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. To get started right away with Plotly, check out the tutorial below:
 
 ## Simple FigureWidget Example
-We now have a seamless integration of Jupyter support and the Plotly objects. We've introduced a new graph object called `go.FigureWidget` that acts like a regular plotly `go.Figure` that can be displayed in Jupyter.
+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.
 
 Simple Example: Make a Scatter Plot
-```
+```python
 import plotly
 import plotly.graph_objs as go
 
@@ -22,11 +22,15 @@ Entering `f.add_scatter(<tab>)` displays the names of all of the top-level prope
 
 Entering `f.add_scatter(<shift+tab>)` displays the signature pop-up. Expanding this pop-up reveals the method doc string which contains the descriptions of all of the top level properties. Let's finish add a scatter trace to `f`:
 
-```
-f.add_scatter(x=[1,2,3], y=[4,3,2])
+```python
+f.add_scatter(x=[1,2,3], y=[3,4,2])
 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.
 
@@ -39,27 +43,12 @@ FigureWidget({
 })
 ```
 
-## New Figure.data Assignment
-- Assignment to the `Figure.data` property must contain a permutation of a subset of the existing traces. Assignment can be used to reorder and remove traces, but cannot currently add new traces.
-
-Suppose a figure, fig, has 3 traces. The following command is valid and it will move the third trace to be the first, the first trace to be the second, and it will remove the second trace.
-
-```
-fig.data = [fig.data[2], fig.data[0]]
-```
-
-However this is not valid:
-```
-fig.data = [fig.data[0], go.Scatter(y=[2, 3, 1])]
-```
-
-It's not valid because it's introducing a new trace during assignment. This trace would need to be added using `add_trace` instead.
-
+## New add_trace method that handles subplots
+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. 
 
-## FigureWidget Subplot Example
-Let's create a subplot then turn it into a FigureWidget to display in the notebook. Note that `append_trace` is now deprecated. Use `add_trace` or `add_traces` instead.
+Let's create a subplot then turn it into a FigureWidget to display in the notebook.
 
-```
+```python
 import plotly
 import plotly.graph_objs as go
 import plotly.tools as tls
@@ -70,27 +59,58 @@ dataset = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/
 subplot = tls.make_subplots(2, 2, print_grid=False)
 f2 = go.FigureWidget(subplot)
 
-f2.add_trace(go.Scatter(x=dataset['Age'], y=dataset['Pregnancies'], mode='markers'), 1,1)
-f2.add_trace(go.Scatter(x=dataset['Age'], y=dataset['BMI'], mode='markers'), 1,2)
-f2.add_trace(go.Scatter(x=dataset['Age'], y=dataset['SkinThickness'], mode='markers'), 2,1)
-f2.add_trace(go.Scatter(x=dataset['Age'], y=dataset['BloodPressure'], mode='markers'), 2,2)
-f2.layout.title = 'Age against variables relating to diabetes'
+# Use add_trace method with optional row/col parameters
+f2.add_trace(go.Scatter(x=dataset['Age'], y=dataset['Pregnancies'], mode='markers'), row=1, col=1)
+
+# Use add_traces with optional rows/cols parameters
+f2.add_traces([
+    go.Scatter(x=dataset['Age'], y=dataset['BMI'], mode='markers'),
+    go.Scatter(x=dataset['Age'], y=dataset['SkinThickness'], mode='markers')],
+    rows=[1, 2], cols=[2, 1]
+)
+
+# Use add_scatter with optional row/col parameters
+f2.add_scatter(x=dataset['Age'], y=dataset['BloodPressure'], mode='markers', row=2, col=2)
+
+f2.layout.title = 'Age and Diabetes Factors'
 f2
 ```
 
+![Simple Subplots](example_images/subplot_methods.png)
+
 ## Breaking Changes
-Run the following examples to see what is now deprecated or not valid:
 
-- Data array properties may not be specified as scalars:
+### 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.
+
+### 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. 
+
+For example, suppose a figure, `fig`, has 3 traces. The following command is valid and it will move the third trace to be the first, the first trace to be the second, and it will remove the second trace.
+
 ```
-import plotly.graph_objs as go
-go.Bar(x=1)
+fig.data = [fig.data[2], fig.data[0]]
+```
+
+However this is not valid:
+```
+fig.data = [fig.data[0], go.Scatter(y=[2, 3, 1])]
 ```
 
-- Several undocumented `Figure` methods have been removed. These include: `.to_string`, `.strip_style`, `.get_data`, `.validate` and `.to_dataframe`.
+It's not valid because it's introducing a new trace during assignment. This trace would need to be added using `add_trace` instead.
 
-- Object arrays such as `Figure.data` and `Layout.images` are now represented as tuples of graph objects, not lists. Run the following as a sanity check:
+### Data array properties may not be specified as scalars
+For example, the following is now invalid:
+```
+import plotly.graph_objs as go
+go.Bar(x=1)
+```
 
+This should be replaced by: 
 ```
-type(go.Figure().data)
+import plotly.graph_objs as go
+go.Bar(x=[1])
 ```
+
+### Removal of undocumented methods
+Several undocumented `Figure` methods have been removed. These include: `.to_string`, `.strip_style`, `.get_data`, `.validate` and `.to_dataframe`.