Merge pull request #4589 from plotly/recent-docs-updates

Merge recent docs updates

doc/python/bar-charts.md

@@ -304,6 +304,56 @@ fig.update_layout(barmode='stack')
 fig.show()
 ```
 
+### Stacked Bar Chart From Aggregating a DataFrame 
+
+Stacked bar charts are a powerful way to present results summarizing categories generated using the Pandas aggregate commands. `pandas.DataFrame.agg` produces a wide data set format incompatible with `px.bar`. Transposing and updating the indexes to achieve `px.bar` compatibility is a somewhat involved option. Here is one straightforward alternative, which presents the aggregated data as a stacked bar using plotly.graph_objects.
+
+```python
+from plotly import graph_objects as go
+import pandas as pd
+
+# Get one year of gapminder data
+url = 'https://raw.githubusercontent.com/plotly/datasets/master/gapminderDataFiveYear.csv'
+df = pd.read_csv(url)
+df = df[df['year']==2007]
+df["gdp"]=df["pop"]*df['gdpPercap']
+
+
+# Build the summary of interest
+df_summarized = df.groupby("continent", observed=True).agg("sum").reset_index()
+
+df_summarized["percent of world population"]=100*df_summarized["pop"]/df_summarized["pop"].sum()
+df_summarized["percent of world GDP"]=100*df_summarized["gdp"]/df_summarized["gdp"].sum()
+
+
+df = df_summarized[["continent", 
+"percent of world population",
+"percent of world GDP",
+]]
+
+# We now have a wide data frame, but it's in the opposite orientation from the one that px is designed to deal with.
+# Transposing it and rebuilding the indexes is an option, but iterating through the DF using graph objects is more succinct. 
+
+fig=go.Figure()
+for category in df_summarized["continent"].values:
+    fig.add_trace(go.Bar(
+            x=df.columns[1:],
+            # We need to get a pandas series that contains just the values to graph; 
+            # We do so by selecting the right row, selecting the right columns
+            # and then transposing and using iloc to convert to a series
+            # Here, we assume that the bar element category variable is in column 0
+            y=list(df.loc[df["continent"]==category][list(df.columns[1:])].transpose().iloc[:,0]),
+            name=str(category)
+
+
+        )
+)
+fig.update_layout(barmode="stack")
+
+fig.show()
+```
+
+
 ### Bar Chart with Hover Text
 
 ```python

doc/python/hover-text-and-formatting.md

@@ -283,6 +283,58 @@ print("user_defined hovertemplate:", fig.data[0].hovertemplate)
 fig.show()
 ```
 
+### Specifying the formatting and labeling of custom fields in a Plotly Express figure using a hovertemplate
+
+This example adds custom fields to a Plotly Express figure using the custom_data parameter and then adds a hover template that applies d3 formats to each element of the customdata[n] array and uses HTML to customize the fonts and spacing. 
+
+```python
+# %%
+import plotly.graph_objects as go
+import plotly.express as px
+import pandas as pd
+import math
+import numpy as np
+
+data = px.data.gapminder()
+df = data[data['year']==2007]
+df = df.sort_values(['continent', 'country'])
+
+df.rename(columns={"gdpPercap":'GDP per capita', "lifeExp":'Life Expectancy (years)'}, inplace=True)
+
+fig=px.scatter(df, 
+               x='GDP per capita',
+               y='Life Expectancy (years)', 
+               color='continent', 
+               size=np.sqrt(df['pop']),           
+               # Specifying data to make available to the hovertemplate
+               # The px custom_data parameter has an underscore, while the analogous graph objects customdata parameter has no underscore.
+               # The px custom_data parameter is a list of column names in the data frame, while the graph objects customdata parameter expects a data frame or a numpy array.
+               custom_data=['country', 'continent', 'pop'], 
+)
+
+# Plotly express does not have a hovertemplate parameter in the graph creation function, so we apply the template with update_traces
+fig.update_traces(
+    hovertemplate = 
+                "<b>%{customdata[0]}</b><br>" +
+                "<b>%{customdata[1]}</b><br><br>" +
+                "GDP per Capita: %{x:$,.0f}<br>" +
+                "Life Expectation: %{y:.0f}<br>" +
+                "Population: %{customdata[2]:,.0f}" +
+                "<extra></extra>",
+    mode='markers',
+    marker={'sizemode':'area',
+            'sizeref':10},
+)
+
+fig.update_layout(
+        xaxis={
+            'type':'log'},
+        )
+
+fig.show()
+```
+
+
 ### Hover Templates with Mixtures of Period data
 
 *New in v5.0*
@@ -319,7 +371,7 @@ fig.show()
 
 ### Advanced Hover Template
 
-The following example shows how to format a hover template.
+This produces the same graphic as in "Specifying the formatting and labeling of custom fields in a Plotly Express figure using a hovertemplate" above, but does so with the `customdata` and `text` parameters of `graph_objects`.  It shows how to specify columns from a dataframe to include in the customdata array using the df[["col_i", "col_j"]] subsetting notation.  It then references those variables using e.g. %{customdata[0]} in the hovertemplate.  It includes comments about major differences between the parameters used by `graph_objects` and `plotly.express`.  
 
 ```python
 import plotly.graph_objects as go
@@ -343,21 +395,31 @@ continent_data = {continent:df_2007.query("continent == '%s'" %continent)
 
 fig = go.Figure()
 
-for continent_name, continent in continent_data.items():
-    fig.add_trace(go.Scatter(
-        x=continent['gdpPercap'],
-        y=continent['lifeExp'],
-        name=continent_name,
-        text=continent['continent'],
-        hovertemplate=
-        "<b>%{text}</b><br><br>" +
-        "GDP per Capita: %{x:$,.0f}<br>" +
-        "Life Expectation: %{y:.0%}<br>" +
-        "Population: %{marker.size:,}" +
-        "<extra></extra>",
-        marker_size=continent['size'],
+for continent_name, df in continent_data.items():
+    fig.add_trace(
+        go.Scatter(
+            x=df['gdpPercap'],
+            y=df['lifeExp'],
+            marker_size=df['size'],
+            name=continent_name,
+
+            # The next three parameters specify the hover text
+            # Text supports just one customized field per trace 
+            # and is implemented here with text=df['continent'],  
+            # Custom data supports multiple fields through numeric indices in the hovertemplate 
+            # In we weren't using the text parameter in our example, 
+            # we could instead add continent as a third customdata field.
+            customdata=df[['country','pop']],  
+            hovertemplate=
+                "<b>%{customdata[0]}</b><br>" +
+                "<b>%{text}</b><br><br>" +
+                "GDP per Capita: %{x:$,.0f}<br>" +
+                "Life Expectancy: %{y:.0f}<br>" +
+                "Population: %{customdata[1]:,.0f}" +
+                "<extra></extra>",
         ))
 
+
 fig.update_traces(
     mode='markers',
     marker={'sizemode':'area',