Merge pull request #3980 from plotly/docs-dec

Add group scatter + rounded corners on treemap + multi-axis examples (next release)

Author: nicolaskruchten

doc/python/graphing-multiple-chart-types.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.14.1
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.8.0
   plotly:
     description: How to design figures with multiple chart types in python.
     display_as: file_settings
@@ -56,6 +56,84 @@ fig.add_bar(x=fruits, y=[2,1,3], name="Last year")
 fig.show()
 ```
 
+#### Grouped Bar and Scatter Chart
+
+*New in 5.12*
+
+In this example, we display individual data points with a grouped scatter chart and show averages using a grouped bar chart. `offsetgroup` links the bar trace for smoker with the scatter trace for smoker, and the bar trace for non-smoker with the scatter trace for non-smoker. If you deselect a trace using the legend, other traces maintain the position of the traces they are linked to.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.tips()[data.tips()["day"] == "Sun"]
+
+mean_values_df = df.groupby(by=["sex", "smoker"], as_index=False).mean(
+    numeric_only=True
+)
+
+smoker_mean = mean_values_df[mean_values_df.smoker == "Yes"].sort_values(
+    by="tip", ascending=False
+)
+non_smoker_mean = mean_values_df[mean_values_df.smoker == "No"].sort_values(
+    by="tip", ascending=False
+)
+
+smoker = df[df.smoker == "Yes"].sort_values(by="tip", ascending=False)
+non_smoker = df[df.smoker == "No"].sort_values(by="tip", ascending=False)
+
+fig = go.Figure()
+
+fig.add_trace(
+    go.Bar(
+        x=smoker_mean.sex,
+        y=smoker_mean.tip,
+        name="Average (Smoker)",
+        marker_color="IndianRed",
+        offsetgroup="smoker",
+    )
+)
+
+
+fig.add_trace(
+    go.Bar(
+        x=non_smoker_mean.sex,
+        y=non_smoker_mean.tip,
+        name="Average (Non-Smoker)",
+        marker_color="LightSalmon",
+        offsetgroup="non-smoker",
+    )
+)
+
+
+fig.add_trace(
+    go.Scatter(
+        x=non_smoker.sex,
+        y=non_smoker.tip,
+        mode="markers",
+        name="Individual tips (Non-Smoker)",
+        marker=dict(color="LightSteelBlue", size=5),
+        offsetgroup="non-smoker",
+    )
+)
+
+fig.add_trace(
+    go.Scatter(
+        x=smoker.sex,
+        y=smoker.tip,
+        mode="markers",
+        name="Individual tips (Smoker)",
+        marker=dict(color="LightSlateGrey", size=5),
+        offsetgroup="smoker",
+    )
+)
+
+fig.update_layout(scattermode="group")
+
+fig.show()
+
+```
+
 #### Line Chart and a Bar Chart
 
 ```python
@@ -121,4 +199,4 @@ fig.show()
 ```
 
 #### Reference
-See https://plotly.com/python/reference/ for more information and attribute options!
+See https://plotly.com/python/reference/ for more information and attribute options!

doc/python/line-and-scatter.md

@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.3'
       jupytext_version: 1.14.1
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.8
+    version: 3.8.0
   plotly:
     description: How to make scatter plots in Python with Plotly.
     display_as: basic
@@ -117,6 +117,39 @@ fig.update_traces(marker_size=10)
 fig.show()
 ```
 
+### Grouped Scatter Points
+
+*New in 5.12*
+
+By default, scatter points at the same location are overlayed. We can see this in the previous example, with the values for Canada for bronze and silver. Set `scattermode='group'` to plot scatter points next to one another, centered around the shared location.
+
+```python
+import plotly.express as px
+
+df = px.data.medals_long()
+
+fig = px.scatter(df, y="count", x="nation", color="medal")
+fig.update_traces(marker_size=10)
+fig.update_layout(scattermode="group")
+fig.show()
+```
+
+*New in 5.12*
+
+You can configure the gap between groups of scatter points using `scattergap`. Here we set it to `0.75`, which brings the points closer together by allocating more space to the gap between groups. If you don't set `scattergap`, a default value of `0` is used, unless you have `bargap` set. If you have `bargap` set, the `scattergap` defaults to that value. 
+
+
+```python
+import plotly.express as px
+
+df = px.data.medals_long()
+
+fig = px.scatter(df, y="count", x="nation", color="medal")
+fig.update_traces(marker_size=10)
+fig.update_layout(scattermode="group", scattergap=0.75)
+fig.show()
+```
+
 ### Error Bars
 
 Scatter plots support [error bars](https://plotly.com/python/error-bars/).

doc/python/multiple-axes.md

@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.3'
       jupytext_version: 1.14.1
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.8
+    version: 3.8.0
   plotly:
     description: How to make a graph with multiple axes (dual y-axis plots, plots
       with secondary axes) in python.
@@ -249,5 +249,108 @@ fig.update_layout(
 fig.show()
 ```
 
+#### Automatically Shifting Axes
+
+*New in 5.12*
+
+To automatically reposition axes to avoid overlap with other axes with the same `overlaying` value, set `autoshift=True`. For `autoshift` to work on an axis, you'll also need to set `anchor="free"` on that axis.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6], name="yaxis data"))
+
+fig.add_trace(go.Scatter(x=[2, 3, 4], y=[40, 50, 60], name="yaxis2 data", yaxis="y2"))
+
+fig.add_trace(
+    go.Scatter(x=[4, 5, 6], y=[1000, 2000, 3000], name="yaxis3 data", yaxis="y3")
+)
+
+fig.add_trace(
+    go.Scatter(x=[3, 4, 5], y=[400, 500, 600], name="yaxis4 data", yaxis="y4")
+)
+
+
+fig.update_layout(
+    xaxis=dict(domain=[0.25, 0.75]),
+    yaxis=dict(
+        title="yaxis title",
+    ),
+    yaxis2=dict(
+        title="yaxis2 title",
+        overlaying="y",
+        side="right",
+    ),
+    yaxis3=dict(title="yaxis3 title", anchor="free", overlaying="y", autoshift=True),
+    yaxis4=dict(
+        title="yaxis4 title",
+        anchor="free",
+        overlaying="y",
+        autoshift=True,
+    ),
+)
+
+fig.update_layout(
+    title_text="Shifting y-axes with autoshift",
+)
+
+fig.show()
+
+```
+
+### Shift Axes by a Specific Number of Pixels
+
+*New in 5.12*
+
+Set a `shift` value on an axis to shift an axis by that number of pixels. A positive value shifts an axis to the right. A negative value shifts it to the left. Here, we shift `yaxis4` 100 pixels further to the left.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6], name="yaxis data"))
+
+fig.add_trace(go.Scatter(x=[2, 3, 4], y=[40, 50, 60], name="yaxis2 data", yaxis="y2"))
+
+fig.add_trace(
+    go.Scatter(x=[4, 5, 6], y=[1000, 2000, 3000], name="yaxis3 data", yaxis="y3")
+)
+
+fig.add_trace(
+    go.Scatter(x=[3, 4, 5], y=[400, 500, 600], name="yaxis4 data", yaxis="y4")
+)
+
+
+fig.update_layout(
+    xaxis=dict(domain=[0.25, 0.75]),
+    yaxis=dict(
+        title="yaxis title",
+    ),
+    yaxis2=dict(
+        title="yaxis2 title",
+        overlaying="y",
+        side="right",
+    ),
+    yaxis3=dict(title="yaxis3 title", anchor="free", overlaying="y", autoshift=True),
+    yaxis4=dict(
+        title="yaxis4 title",
+        anchor="free",
+        overlaying="y",
+        autoshift=True,
+        shift=-100,
+    ),
+)
+
+fig.update_layout(
+    title_text="Shifting y-axes by a specific number of pixels",
+)
+
+fig.show()
+
+```
+
 #### Reference
 All of the y-axis properties are found here: https://plotly.com/python/reference/YAxis/.  For more information on creating subplots see the [Subplots in Python](/python/subplots/) section.

doc/python/treemaps.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.14.1
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.8.0
   plotly:
     description: How to make Treemap Charts with Plotly
     display_as: basic
@@ -145,6 +145,23 @@ fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
 fig.show()
 ```
 
+### Treemap with Rounded Corners
+
+
+*New in 5.12*
+
+Update treemap sectors to have rounded corners by configuring the `cornerradius` in px.
+
+```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.update_traces(marker=dict(cornerradius=5))
+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` class from `plotly.graph_objects`](/python/graph-objects/).