Merge pull request #2001 from plotly/doc-prod

Doc prod back merge

Author: nicolaskruchten

Diff for: CHANGELOG.md

@@ -36,6 +36,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 section [#1969](https://github.com/plotly/plotly.py/pull/1969).
  - All continuous colorscales now accept a `_r` suffix that reverses their direction [#1933](https://github.com/plotly/plotly.py/pull/1933)
  - Docstrings of plotly.py are now doctested [#1921](https://github.com/plotly/plotly.py/pull/1921).
+ - Reversing a predefined colorscale by appending `_r` to its name [#1933](https://github.com/plotly/plotly.py/pull/1933)
 
 ## [4.3.0] - 2019-11-11
 

Diff for: doc/Makefile

@@ -38,7 +38,7 @@ $(HTML_DIR)/2019-07-03-%.html: $(IPYNB_DIR)/%.ipynb
 	@echo "[nbconvert]  $<"
 	@jupyter nbconvert $< --to html --template nb.tpl \
 	  	--output-dir $(HTML_DIR) --output 2019-07-03-$*.html \
-	  	--execute
+	  	--execute > $(FAIL_DIR)/$* 2>&1  && rm -f $(FAIL_DIR)/$*
 
 
 $(REDIR_DIR)/2019-07-03-redirect-next-%.html: $(IPYNB_DIR)/%.ipynb

Diff for: doc/apidoc/plotly.express.rst

@@ -33,12 +33,19 @@ plotly's high-level API for rapid figure generation. ::
     box
     strip
     histogram
+    pie
+    treemap
+    sunburst
+    funnel
+    funnel_area
     scatter_matrix
     parallel_coordinates
     parallel_categories
     choropleth
+    choropleth_mapbox
     density_contour
     density_heatmap
+    density_mapbox
     imshow
 
 

Diff for: doc/python/box-plots.md

@@ -39,7 +39,7 @@ jupyter:
 A [box plot](https://en.wikipedia.org/wiki/Box_plot) is a statistical representation of numerical data through their quartiles. The ends of the box represent the lower and upper quartiles, while the median (second quartile) is marked by a line inside the box. For other statistical representations of numerical data, see [other statistical charts](https://plot.ly/python/statistical-charts/).
 
 
-## Box Plot with Plotly Express
+## Box Plot with `plotly.express`
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
 

Diff for: doc/python/colorscales.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.1
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -62,6 +62,28 @@ fig = px.scatter(iris, x="sepal_width", y="sepal_length",
 fig.show()
 ```
 
+### Reversing a predefined colorscale
+
+You can reverse a predefined colorscale by appending `_r` to its name, for colorscales given either as a string or a `plotly` object. 
+
+```python
+import plotly.express as px
+iris = px.data.iris()
+fig = px.scatter(iris, x="sepal_width", y="sepal_length",
+                 color="sepal_length", color_continuous_scale='Magma_r')
+
+fig.show()
+```
+
+```python
+import plotly.express as px
+data = [[1, .3, .5, .9], 
+        [.3, .1, .4, 1],
+        [.2, .8, .9, .3]]
+fig = px.imshow(data, color_continuous_scale=px.colors.diverging.Tealrose_r)
+fig.show()
+```
+
 ### Custom Discretized Heatmap Colorscale
 
 ```python

Diff for: doc/python/funnel-charts.md

@@ -1,26 +1,27 @@
 ---
 jupyter:
   jupytext:
+    notebook_metadata_filter: plotly
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
     name: python3
   plotly:
-    permalink: python/funnel-charts/
-    redirect_from: python/funnel-chart/
     description: How to make funnel-chart plots in Python with Plotly.
-    name: Funnel Chart
-    thumbnail: thumbnail/funnel.jpg
-    language: python
     display_as: financial
-    order: 4
+    language: python
     layout: base
+    name: Funnel Chart
+    order: 4
     page_type: example_index
+    permalink: python/funnel-charts/
+    redirect_from: python/funnel-chart/
+    thumbnail: thumbnail/funnel.jpg
 ---
 
 
@@ -29,7 +30,40 @@ jupyter:
 Funnel charts are often used to represent data in different stages of a business process. It’s an important mechanism in Business Intelligence to identify potential problem areas of a process. For example, it’s used to observe the revenue or loss in a sales process for each stage, and displays values that are decreasing progressively. Each stage is illustrated as a percentage of the total of all values.
 
 
-### Basic Funnel Plot
+### Basic Funnel Plot with plotly.express
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
+
+With `px.funnel`, each row of the DataFrame is represented as a stage of the funnel.
+
+
+```python
+import plotly.express as px
+data = dict(
+    number=[39, 27.4, 20.6, 11, 2], 
+    stage=["Website visit", "Downloads", "Potential customers", "Requested price", "invoice sent"])
+fig = px.funnel(data, x='number', y='stage')
+fig.show()
+```
+
+### Stacked Funnel Plot with plotly.express
+
+```python
+import plotly.express as px
+import pandas as pd
+stages = ["Website visit", "Downloads", "Potential customers", "Requested price", "invoice sent"]
+df_mtl = pd.DataFrame(dict(number=[39, 27.4, 20.6, 11, 3], stage=stages))
+df_mtl['office'] = 'Montreal'
+df_toronto = pd.DataFrame(dict(number=[52, 36, 18, 14, 5], stage=stages))
+df_toronto['office'] = 'Toronto'
+df = pd.concat([df_mtl, df_toronto], axis=0)
+fig = px.funnel(df, x='number', y='stage', color='office')
+fig.show()
+```
+
+### Basic Funnel Chart with graph_objects trace go.Funnel
+
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Funnel` function from `plotly.graph_objects`.
 
 ```python
 from plotly import graph_objects as go
@@ -60,7 +94,7 @@ fig = go.Figure(go.Funnel(
 fig.show()
 ```
 
-### Stacked Funnel Plot
+### Stacked Funnel Plot with go.Funnel
 
 ```python
 from plotly import graph_objects as go
@@ -92,7 +126,21 @@ fig.add_trace(go.Funnel(
 fig.show()
 ```
 
-#### Basic Area Funnel Plot
+### Basic Area Funnel Plot with plotly.express
+
+With `px.funnel_area`, each row of the DataFrame is represented as a stage of
+the funnel.
+
+```python
+import plotly.express as px
+fig = px.funnel_area(names=["The 1st","The 2nd", "The 3rd", "The 4th", "The 5th"],
+                    values=[5, 4, 3, 2, 1])
+fig.show()
+```
+
+### Basic Area Funnel Plot with go.Funnelarea
+
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Funnelarea` function from `plotly.graph_objects`.
 
 ```python
 from plotly import graph_objects as go

Diff for: doc/python/heatmaps.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.7.3
   plotly:
     description: How to make Heatmaps in Python with Plotly.
     display_as: scientific
@@ -34,7 +34,26 @@ jupyter:
     thumbnail: thumbnail/heatmap.jpg
 ---
 
-### Basic Heatmap
+### Heatmap with `plotly.express` and `px.imshow`
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly. With `px.imshow`, each value of the input array is represented as a heatmap pixel.
+
+`px.imshow` makes opiniated choices for representing heatmaps, such as using square pixels. To override this behaviour, you can use `fig.update_layout` or use the `go.Heatmap` trace from `plotly.graph_objects` as described below. 
+
+For more examples using `px.imshow`, see the [tutorial on displaying image data with plotly](/python/imshow).
+
+```python
+import plotly.express as px
+
+fig = px.imshow([[1, 20, 30],
+                 [20, 1, 60],
+                 [30, 60, 1]])
+fig.show()
+```
+
+### Basic Heatmap with `plotly.graph_objects`
+
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Heatmap` function from `plotly.graph_objects`.
 
 ```python
 import plotly.graph_objects as go

Diff for: doc/python/mapbox-county-choropleth.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.7.3
   plotly:
     description: How to make a Mapbox Choropleth Map of US Counties in Python with
       Plotly.
@@ -40,7 +40,9 @@ jupyter:
 To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
 
 
-Making choropleth maps with `go.Choroplethmapbox` requires two main types of input: GeoJSON-formatted geometry information *where each `feature` has an `id`* and a list of values indexed by feature id. The GeoJSON data is passed to the `geojson` attribute, and the data is passed into the `z` attribute, in the same order as the IDs are passed into the `location` attribute.
+### Introduction: main parameters for choropleth mapbox charts
+
+Making choropleth maps requires two main types of input: GeoJSON-formatted geometry information *where each `feature` has an `id`* and a list of values indexed by feature id. The GeoJSON data is passed to the `geojson` attribute, and the data is passed into the `z` (`color` for `px.choropleth_mapbox`) attribute, in the same order as the IDs are passed into the `location` attribute.
 
 
 #### GeoJSON with `feature.id`
@@ -67,7 +69,39 @@ df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-
 df.head()
 ```
 
-#### Carto base map: no token needed
+### Choropleth map using plotly.express and carto base map (no token needed)
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
+
+With `px.choropleth_mapbox`, each row of the DataFrame is represented as a region of the choropleth.
+
+```python
+from urllib.request import urlopen
+import json
+with urlopen('https://raw.githubusercontent.com/plotly/datasets/master/geojson-counties-fips.json') as response:
+    counties = json.load(response)
+
+import pandas as pd
+df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv",
+                   dtype={"fips": str})
+
+import plotly.express as px
+
+fig = px.choropleth_mapbox(df, geojson=counties, locations='fips', color='unemp',
+                           color_continuous_scale="Viridis", 
+                           range_color=(0, 12),
+                           mapbox_style="carto-positron",
+                           zoom=3, center = {"lat": 37.0902, "lon": -95.7129},
+                           opacity=0.5,
+                           labels={'unemp':'unemployment rate'}
+                          )
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Choropleth map using plotly.graph_objects and carto base map (no token needed)
+
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Choroplethmapbox` function from `plotly.graph_objects`.
 
 ```python
 from urllib.request import urlopen

Diff for: doc/python/mapbox-density-heatmaps.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,10 +20,9 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.7.3
   plotly:
-    description: How to make a Mapbox Density Heatmap in Python
-      with Plotly.
+    description: How to make a Mapbox Density Heatmap in Python with Plotly.
     display_as: maps
     language: python
     layout: base
@@ -42,14 +41,34 @@ To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public
 
 
 
-#### Stamen Terrain base map: no token needed
+### Stamen Terrain base map (no token needed): density mapbox with `plotly.express`
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). 
+
+With `px.density_mapbox`, each row of the DataFrame is represented as a point smoothed with a given radius of influence.
+
+```python
+import pandas as pd
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
+
+import plotly.express as px
+fig = px.density_mapbox(df, lat='Latitude', lon='Longitude', z='Magnitude', radius=10,
+                        center=dict(lat=0, lon=180), zoom=0,
+                        mapbox_style="stamen-terrain")
+fig.show()
+```
+
+### Stamen Terrain base map (no token needed): density mapbox with `plotly.graph_objects`
+
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Densitymapbox` function from `plotly.graph_objects`.
 
 ```python
 import pandas as pd
 quakes = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
 
 import plotly.graph_objects as go
-fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude, radius=10))
+fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude, 
+                                 radius=10))
 fig.update_layout(mapbox_style="stamen-terrain", mapbox_center_lon=180)
 fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()