From 3bc18ed1ff7a2476c756172585a16e70b9cf6dd8 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 23 Jan 2020 09:55:44 -0500
Subject: [PATCH] added discrete color examples

---
 doc/python/sunburst-charts.md | 20 ++++++++++++++++++++
 doc/python/treemaps.md        | 20 ++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/doc/python/sunburst-charts.md b/doc/python/sunburst-charts.md
index 9e8c39de811..cb9bc8f8cdd 100644
--- a/doc/python/sunburst-charts.md
+++ b/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 --git a/doc/python/treemaps.md b/doc/python/treemaps.md
index 169648efe67..018705b8e98 100644
--- a/doc/python/treemaps.md
+++ b/doc/python/treemaps.md
@@ -77,6 +77,26 @@ fig = px.treemap(df, path=['continent', 'country'], values='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()
+fig = px.treemap(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.treemap(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`.