Merge pull request #192 from plotly/v4.3-docs

V4.3 docs

Author: nicolaskruchten

python/animations.md

@@ -26,7 +26,7 @@ jupyter:
 #### Animated figures with Plotly Express
 Several Plotly Express functions support the creation of animated figures through the `animation_frame` and `animation_group` arguments.
 
-Here is an example of an animated scatter plot creating using Plotly Express
+Here is an example of an animated scatter plot creating using Plotly Express. Note that you should always fix the `x_range` and `y_range` to ensure that your data remains visible throughout the animation.
 
 ```python
 import plotly.express as px
@@ -36,6 +36,22 @@ px.scatter(gapminder, x="gdpPercap", y="lifeExp", animation_frame="year", animat
            log_x=True, size_max=55, range_x=[100,100000], range_y=[25,90])
 ```
 
+#### Animated Bar Charts with Plotly Express
+
+ Note that you should always fix the `y_range` to ensure that your data remains visible throughout the animation.
+
+```python
+import plotly.express as px
+
+gapminder = px.data.gapminder()
+
+fig = px.bar(gapminder, x="continent", y="pop", color="continent",
+  animation_frame="year", animation_group="country", range_y=[0,4000000000])
+fig.show()
+```
+
+#### Animated figures with Graph Objects
+
 The remainder of this section describes the low-level API for constructing animated figures manually.
 
 

python/facet-plots.md

@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.6.8
   plotly:
     description: How to make Facet and Trellis Plots in Python with Plotly.
     display_as: statistical
@@ -58,6 +58,18 @@ fig = px.bar(tips, x="size", y="total_bill", color="sex", facet_row="smoker")
 fig.show()
 ```
 
+### Wrapping Column Facets
+
+When the facet dimension has a large number of unique values, it is possible to wrap columns using the `facet_col_wrap` argument. 
+
+```python
+import plotly.express as px
+df = px.data.gapminder()
+fig = px.scatter(df, x='gdpPercap', y='lifeExp', color='continent', size='pop',
+                facet_col='year', facet_col_wrap=4)
+fig.show()
+```
+
 ### Histogram Facet Grids
 
 ```python
@@ -67,3 +79,27 @@ fig = px.histogram(tips, x="total_bill", y="tip", color="sex", facet_row="time",
        category_orders={"day": ["Thur", "Fri", "Sat", "Sun"], "time": ["Lunch", "Dinner"]})
 fig.show()
 ```
+
+### Facets with independent axes
+
+By default, facet axes are linked together: zooming inside one of the facets will also zoom in the other facets. You can disable this behaviour when you use `facet_row` only, by disabling `matches` on the Y axes, or when using `facet_col` only, by disabling `matches` on the X axes. It is not recommended to use this approach when using `facet_row` and `facet_col` together, as in this case it becomes very hard to understand the labelling of axes and grid lines. 
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", color='sex', facet_row="day")
+fig.update_yaxes(matches=None)
+fig.show()
+```
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", color='sex', facet_col="day")
+fig.update_xaxes(matches=None)
+fig.show()
+```
+
+```python
+
+```

python/images.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.1'
-      jupytext_version: 1.1.7
+      jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.5
+    version: 3.7.3
   plotly:
     description: How to add images to charts as background images or logos.
     display_as: file_settings
@@ -30,10 +30,13 @@ jupyter:
     order: 31
     permalink: python/images/
     thumbnail: thumbnail/images.png
+    v4upgrade: true
 ---
 
 #### Add a Background Image
 
+In this page we explain how to add static, non-interactive images as background, logo or annotation images to a figure. For exploring image data in interactive charts, see the [tutorial on displaying image data](/python/imshow).
+
 ```python
 import plotly.graph_objects as go
 
@@ -46,8 +49,7 @@ fig.add_trace(
 )
 
 # Add images
-fig.update_layout(
-    images=[
+fig.add_layout_image(
         go.layout.Image(
             source="https://images.plot.ly/language-icons/api-home/python-logo.png",
             xref="x",
@@ -59,7 +61,6 @@ fig.update_layout(
             sizing="stretch",
             opacity=0.5,
             layer="below")
-    ]
 )
 
 # Set templates
@@ -112,14 +113,14 @@ fig.add_trace(
 )
 
 # Add image
-fig.update_layout(
-    images=[dict(
+fig.add_layout_image(
+    dict(
         source="https://raw.githubusercontent.com/cldougl/plot_images/add_r_img/vox.png",
         xref="paper", yref="paper",
         x=1, y=1.05,
         sizex=0.2, sizey=0.2,
         xanchor="right", yanchor="bottom"
-    )],
+    )
 )
 
 # update layout properties
@@ -171,30 +172,26 @@ for (x, y), n in zip(simulated_absorptions, names):
     fig.add_trace(go.Scatter(x=x, y=y, name=n))
 
 # Add images
-fig.update_layout(
-    images=[go.layout.Image(
+fig.add_layout_image(
+    go.layout.Image(
         source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/benzene.png",
-        xref="paper",
-        yref="paper",
         x=0.75,
         y=0.65,
-        sizex=0.3,
-        sizey=0.3,
-        xanchor="right",
-        yanchor="bottom"
-    ), go.layout.Image(
+    ))
+fig.add_layout_image(go.layout.Image(
         source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/naphthalene.png",
-        xref="paper",
-        yref="paper",
         x=0.9,
         y=0.3,
+        )
+)
+fig.update_layout_images(dict(
+        xref="paper",
+        yref="paper",
         sizex=0.3,
         sizey=0.3,
         xanchor="right",
         yanchor="bottom"
-        )
-    ]
-)
+))
 
 # Add annotations
 fig.update_layout(
@@ -277,8 +274,8 @@ fig.update_yaxes(
 )
 
 # Add image
-fig.update_layout(
-    images=[go.layout.Image(
+fig.add_layout_image(
+    go.layout.Image(
         x=0,
         sizex=img_width * scale_factor,
         y=img_height * scale_factor,
@@ -288,7 +285,7 @@ fig.update_layout(
         opacity=1.0,
         layer="below",
         sizing="stretch",
-        source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")]
+        source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")
 )
 
 # Configure other layout