Merge pull request #4104 from plotly/march-docs

Docs for next release + Update Plotlyjs version

Author: archmoj

Diff for: CHANGELOG.md

@@ -2,6 +2,17 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## UNRELEASED
+
+### Updated
+  - Updated Plotly.js to from version 2.18.2 to version 2.20.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2200----2023-03-15) for more information. Notable changes include:
+    - Add `title.automargin` to enable automatic top and bottom margining for both container and paper referenced titles [[#6428](https://github.com/plotly/plotly.js/pull/6428)],
+   with thanks to [Gamma Technologies](https://www.gtisoft.com/) for sponsoring the related development.
+    - Add `label` attribute to shapes [[#6454](https://github.com/plotly/plotly.js/pull/6454)], with thanks to the [Volkswagen](https://www.volkswagenag.com) Center of Excellence for Battery Systems for sponsoring development!
+    - Add `labelalias` to various axes namely cartesian, gl3d, polar, smith, ternary, carpet,
+   indicator and colorbar [[#6481](https://github.com/plotly/plotly.js/pull/6481)],
+   this feature was anonymously sponsored: thank you to our sponsor!
+
 ## [5.13.1] - 2023-02-24
 
 ### Updated

Diff for: doc/python/aggregations.md

@@ -144,7 +144,7 @@ import plotly.io as pio
 
 import pandas as pd
 
-df = pd.read_csv("https://plotly.com/~public.health/17.csv")
+df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/US-shooting-incidents.csv")
 
 data = [dict(
   x = df['date'],

Diff for: doc/python/axes.md

@@ -154,6 +154,25 @@ fig.update_yaxes(ticklabelposition="inside top", title=None)
 fig.show()
 ```
 
+#### Specifying Label Aliases 
+
+*New in 5.14*
+
+With `labelalias`, you can specify replacement text for specific tick and hover labels. In this example, the dataset has the values of "Sat" and "Sun" in the day column. By setting `labelalias=dict(Sat="Saturday", Sun="Sunday")`, we swap these out for "Saturday" and "Sunday".
+
+```python
+import plotly.express as px
+import pandas as pd
+
+df = px.data.tips()
+df = df[df.day.isin(['Sat', 'Sun'])].groupby(by='day', as_index=False).sum(numeric_only=True)
+
+fig = px.bar(df, x="day", y="total_bill")
+fig.update_xaxes(labelalias=dict(Sat="Saturday", Sun="Sunday"))
+
+fig.show()
+```
+
 ##### Set axis title text with Graph Objects
 
 Axis titles are set using the nested `title.text` property of the x or y axis. Here is an example of creating a new figure and using `update_xaxes` and `update_yaxes`, with magic underscore notation, to set the axis titles.

Diff for: doc/python/colorscales.md

@@ -6,9 +6,9 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.14.5
   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.10.9
   plotly:
     description: How to set, create and control continuous color scales and color
       bars in scatter, bar, map and heatmap figures.
@@ -298,6 +298,41 @@ fig.update_layout(coloraxis_colorbar=dict(
 fig.show()
 ```
 
+### Using Label Aliases on Colorbars
+
+*New in 5.14*
+
+Using `labelalias` you can replace some labels on the `colorbar` with alternative values. In this example, the `colorbar` has five `tickvals`. Using `labelalias`, instead of displaying all labels as the numbers in `tickvals`, we swap out three of the labels for text.
+
+```python
+import plotly.graph_objects as go
+
+import urllib
+import json
+
+# Load heatmap data
+response = urllib.request.urlopen(
+    "https://raw.githubusercontent.com/plotly/datasets/master/custom_heatmap_colorscale.json")
+dataset = json.load(response)
+
+# Create and show figure
+fig = go.Figure()
+
+fig.add_trace(go.Heatmap(
+    z=dataset["z"],
+    colorbar=dict(
+        title="Surface Heat",
+        titleside="top",
+        tickmode="array",
+        tickvals=[2, 25, 50, 75, 100],
+        labelalias={100: "Hot", 50: "Mild", 2: "Cold"},
+        ticks="outside"
+    )
+))
+
+fig.show()
+```
+
 ### Custom Discretized Heatmap Color scale with Graph Objects
 
 ```python

Diff for: doc/python/figure-labels.md

@@ -6,9 +6,9 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.14.5
   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.10.9
   plotly:
     description: How to set the global font, title, legend-entries, and axis-titles
       in python.
@@ -86,6 +86,26 @@ fig.update_xaxes(title_font_family="Arial")
 fig.show()
 ```
 
+### Set Automargin on the Plot Title
+
+*New in 5.14*
+
+Set `automargin=True` to allow the title to push the figure margins. With `yref` set to `paper`, `automargin=True`  expands the margins to make the title visible, but doesn't push outside the container. With `yref` set to `container`, `automargin=True` expands the margins, but the title doesn't overlap with the plot area, tick labels, and axis titles. 
+
+
+```python
+import plotly.express as px
+
+df = px.data.gapminder().query("continent == 'Oceania'")
+fig = px.line(df, x="year", y="gdpPercap", color="country")
+
+fig.update_layout(
+    title=dict(text="GDP-per-capita", font=dict(size=50), automargin=True, yref='paper')
+)
+
+fig.show()
+```
+
 ### Fonts and Labels in Dash
 
 [Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash dash-daq`, click "Download" to get the code and run `python app.py`.

Diff for: doc/python/horizontal-vertical-shapes.md

@@ -139,6 +139,47 @@ fig.add_vrect(x0="2018-09-24", x1="2018-12-18", row="all", col=1,
               fillcolor="green", opacity=0.25, line_width=0)
 fig.show()
 ```
+#### Text Labels on Shapes
+
+*New in 5.14*
+
+[Text labels on shapes](/python/shapes/#addingtextlabelstoshapes), introduced in version 5.14, is now the recommended way to add text to shapes. The above examples using `add_hline`, `add_vrect`, `add_hrect`, and `add_vline` that add annotations can be rewritten to use `label`.
+
+
+```python
+import plotly.express as px
+
+df = px.data.stocks(indexed=True)
+fig = px.line(df)
+fig.add_hline(
+    y=1,
+    line_dash="dot",
+    label=dict(
+        text="Jan 1 2018 Baseline",
+        textposition="end",
+        font=dict(size=20, color="blue"),
+        yanchor="top",
+    ),
+)
+fig.add_vrect(
+    x0="2018-09-24",
+    x1="2018-12-18",
+    label=dict(
+        text="Decline",
+        textposition="top center",
+        font=dict(size=20, family="Times New Roman"),
+    ),
+    fillcolor="green",
+    opacity=0.25,
+    line_width=0,
+)
+fig.show()
+
+```
+
+With [text labels on shapes](/python/shapes/#addingtextlabelstoshapes), you can also add text labels to shapes other than lines and rectangles, and the labels can be added automatically to shapes drawn by the user. 
+
+
 ### Reference
 
 More details are available about [layout shapes](/python/shapes/) and [annotations](/python/text-and-annotations).