Merge branch 'doc-prod'

Author: nicolaskruchten

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

@@ -88,6 +88,26 @@ fig = px.sunburst(df, path=['continent', 'country'], values='pop',
 fig.show()
 ```
 
+### Sunburst of a rectangular DataFrame with discrete color argument in px.sunburst
+
+When the argument of `color` corresponds to non-numerical data, discrete colors are used. If a sector has the same value of the `color` column for all its children, then the corresponding color is used, otherwise the first color of the discrete color sequence is used.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.sunburst(df, path=['sex', 'day', 'time'], values='total_bill', color='day')
+fig.show()
+```
+
+In the example below the color of `Saturday` and `Sunday` sectors is the same as `Dinner` because there are only Dinner entries for Saturday and Sunday. However, for Female -> Friday there are both lunches and dinners, hence the "mixed" color (blue here) is used.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.sunburst(df, path=['sex', 'day', 'time'], values='total_bill', color='time')
+fig.show()
+```
+
 ### Rectangular data with missing values
 
 If the dataset is not fully rectangular, missing values should be supplied as `None`. Note that the parents of `None` entries must be a leaf, i.e. it cannot have other children than `None` (otherwise a `ValueError` is raised).

Diff for: doc/python/treemaps.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.0
+      jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.6.8
   plotly:
     description: How to make Treemap Charts with Plotly
     display_as: basic
@@ -66,17 +66,42 @@ fig.show()
 
 If a `color` argument is passed, the color of a node is computed as the average of the color values of its children, weighted by their values.
 
+**Note**: for best results, ensure that the first `path` element is a single root node. In the examples below we are creating a dummy column containing identical values for each row to achieve this.
+
 ```python
 import plotly.express as px
 import numpy as np
 df = px.data.gapminder().query("year == 2007")
-fig = px.treemap(df, path=['continent', 'country'], values='pop',
+df["world"] = "world" # in order to have a single root node
+fig = px.treemap(df, path=['world', 'continent', 'country'], values='pop',
                   color='lifeExp', hover_data=['iso_alpha'],
                   color_continuous_scale='RdBu',
                   color_continuous_midpoint=np.average(df['lifeExp'], weights=df['pop']))
 fig.show()
 ```
 
+### Treemap of a rectangular DataFrame with discrete color argument in px.treemap
+
+When the argument of `color` corresponds to non-numerical data, discrete colors are used. If a sector has the same value of the `color` column for all its children, then the corresponding color is used, otherwise the first color of the discrete color sequence is used.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+df["all"] = "all" # in order to have a single root node
+fig = px.treemap(df, path=['all', 'sex', 'day', 'time'], values='total_bill', color='day')
+fig.show()
+```
+
+In the example below the color of Saturday and Sunday sectors is the same as Dinner because there are only Dinner entries for Saturday and Sunday. However, for Female -> Friday there are both lunches and dinners, hence the "mixed" color (blue here) is used.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+df["all"] = "all" # in order to have a single root node
+fig = px.treemap(df, path=['all', 'sex', 'day', 'time'], values='total_bill', color='time')
+fig.show()
+```
+
 ### Rectangular data with missing values
 
 If the dataset is not fully rectangular, missing values should be supplied as `None`.
@@ -93,8 +118,9 @@ sales = [1, 3, 2, 4, 1, 2, 2, 1, 4, 1]
 df = pd.DataFrame(
     dict(vendors=vendors, sectors=sectors, regions=regions, sales=sales)
 )
+df["all"] = "all" # in order to have a single root node
 print(df)
-fig = px.treemap(df, path=['regions', 'sectors', 'vendors'], values='sales')
+fig = px.treemap(df, path=['all', 'regions', 'sectors', 'vendors'], values='sales')
 fig.show()
 ```
 ### Basic Treemap with go.Treemap

Diff for: doc/python/v4-migration.md

@@ -52,7 +52,7 @@ To migrate version 3 "online" functionality, first install the `chart-studio` pa
 $ pip install chart-studio
 ```
 
-of conda.
+or conda.
 
 ```
 $ conda install -c plotly chart-studio