px examples for pie, funnel/funnelarea, sunburst/treemap (#1995)

* pie chart tutorial using px

* funnel chart

* examples for sunburst and treemap

* px intro

Author: emmanuelle

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

doc/python/pie-charts.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
@@ -33,9 +33,66 @@ jupyter:
     thumbnail: thumbnail/pie-chart.jpg
 ---
 
-### Basic Pie Chart ###
+A pie chart is a circular statistical chart, which is divided into sectors to illustrate numerical proportion. 
 
-A pie chart ``go.Pie`` object is a circular statistical chart, which is divided into sectors to illustrate numerical proportion. Data visualized by the sectors of the pie is set in `values`. The sector labels are set in `labels`. The sector colors are set in `marker.colors`. 
+If you're looking instead for a multilevel hierarchical pie-like chart, go to the
+[Sunburst tutorial](/python/sunburst-charts/).
+
+### Pie chart 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/).
+
+In `px.pie`, data visualized by the sectors of the pie is set in `values`. The sector labels are set in `names`.
+
+```python
+import plotly.express as px
+df = px.data.gapminder().query("year == 2007").query("continent == 'Europe'")
+df.loc[df['pop'] < 2.e6, 'country'] = 'Other countries' # Represent only large countries
+fig = px.pie(df, values='pop', names='country', title='Population of European continent')
+fig.show()
+```
+
+### Pie chart with repeated labels
+
+Lines of the dataframe with the same value for `names` are grouped together in the same sector.
+
+```python
+import plotly.express as px
+# This dataframe has 244 lines, but 4 distinct values for `day`
+df = px.data.tips()
+fig = px.pie(df, values='tip', names='day')
+fig.show()
+```
+
+### Setting the color of pie sectors with px.pie
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.pie(df, values='tip', names='day', color_discrete_sequence=px.colors.sequential.RdBu)
+fig.show()
+```
+
+### Customizing a pie chart created with px.pie
+
+In the example below, we first create a pie chart with `px,pie`, using some of its options such as `hover_data` (which columns should appear in the hover) or `labels` (renaming column names). For further tuning, we call `fig.update_traces` to set other parameters of the chart (you can also use `fig.update_layout` for changing the layout).
+
+```python
+import plotly.express as px
+df = px.data.gapminder().query("year == 2007").query("continent == 'Americas'")
+fig = px.pie(df, values='pop', names='country', 
+             title='Population of American continent',
+             hover_data=['lifeExp'], labels={'lifeExp':'life expectancy'})
+fig.update_traces(textposition='inside', textinfo='percent+label')
+fig.show()
+```
+
+### Basic Pie Chart with go.Pie
+
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Pie` function from `plotly.graph_objects`.
+
+
+In `go.Pie`, data visualized by the sectors of the pie is set in `values`. The sector labels are set in `labels`. The sector colors are set in `marker.colors`. 
 
 If you're looking instead for a multilevel hierarchical pie-like chart, go to the
 [Sunburst tutorial](/python/sunburst-charts/).

doc/python/sunburst-charts.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
@@ -33,14 +33,40 @@ jupyter:
     thumbnail: thumbnail/sunburst.gif
 ---
 
-### Basic Sunburst Plot ###
-Sunburst plots visualize hierarchical data spanning outwards radially from root to leaves. The sunburst sector hierarchy is determined by the entries in `labels` and in `parents`. The root starts from the center and children are added to the outer rings.
+Sunburst plots visualize hierarchical data spanning outwards radially from root to leaves. The sunburst sector hierarchy is determined by the entries in `labels` (`names` in `px.sunburst`) and in `parents`. The root starts from the center and children are added to the outer rings.
 
 Main arguments:
-1. `labels`: sets the labels of sunburst sectors.
+1. `labels` (`names` in `px.sunburst` since `labels` is reserved for overriding columns names): sets the labels of sunburst sectors.
 2. `parents`: sets the parent sectors of sunburst sectors. An empty string `''` is used for the root node in the hierarchy. In this example, the root is "Eve".
 3. `values`: sets the values associated with sunburst sectors, determining their width (See the `branchvalues` section below for different modes for setting the width).
 
+### Basic Sunburst 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.sunburst`, each row of the DataFrame is represented as a sector of the sunburst.
+
+```python
+import plotly.express as px
+data = dict(
+    character=["Eve", "Cain", "Seth", "Enos", "Noam", "Abel", "Awan", "Enoch", "Azura"],
+    parent=["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve" ],
+    value=[10, 14, 12, 10, 2, 6, 6, 4, 4])
+
+fig =px.sunburst(
+    data,
+    names='character',
+    parents='parent',
+    values='value',
+)
+fig.show()
+```
+
+### Basic Sunburst Plot with go.Sunburst
+
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Sunburst` function from `plotly.graph_objects`.
+
+
 ```python
 import plotly.graph_objects as go
 

doc/python/treemaps.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
@@ -33,9 +33,28 @@ jupyter:
     thumbnail: thumbnail/treemap.png
 ---
 
-### Basic Treemap
 
-[Treemap charts](https://en.wikipedia.org/wiki/Treemapping) visualize hierarchical data using nested rectangles. Same as [Sunburst](https://plot.ly/python/sunburst-charts/) the hierarchy is defined by [labels](https://plot.ly/python/reference/#treemap-labels) and [parents](https://plot.ly/python/reference/#treemap-parents) attributes. Click on one sector to zoom in/out, which also displays a pathbar in the upper-left corner of your treemap. To zoom out you can use the path bar as well.
+[Treemap charts](https://en.wikipedia.org/wiki/Treemapping) visualize hierarchical data using nested rectangles. Same as [Sunburst](https://plot.ly/python/sunburst-charts/) the hierarchy is defined by [labels](https://plot.ly/python/reference/#treemap-labels) (`names` for `px.treemap`) and [parents](https://plot.ly/python/reference/#treemap-parents) attributes. Click on one sector to zoom in/out, which also displays a pathbar in the upper-left corner of your treemap. To zoom out you can use the path bar as well.
+
+### Basic Treemap 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.treemap`, each row of the DataFrame is represented as a sector of the treemap.
+
+```python
+import plotly.express as px
+fig = px.treemap(
+    names = ["Eve","Cain", "Seth", "Enos", "Noam", "Abel", "Awan", "Enoch", "Azura"],
+    parents = ["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve"]
+)
+fig.show()
+```
+
+### Basic Treemap with go.Treemap
+
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Treemap` function from `plotly.graph_objects`.
+
 
 ```python
 import plotly.graph_objects as go
@@ -269,4 +288,4 @@ fig.show()
 ```
 
 #### Reference
-See https://plot.ly/python/reference/#treemap for more information and chart attribute options!
+See https://plot.ly/python/reference/#treemap for more information and chart attribute options!