Merge pull request #4627 from plotly/update-plotly-js-version

Update plotly.js to v2.34.0 + add docs

Author: LiamConnors

CHANGELOG.md

@@ -5,9 +5,21 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [5.23.0] - TBD
 
 ### Updated
+- Updated Plotly.js from version 2.32.0 to version 2.34.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2340----2024-07-18) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+  - Add `subtitle` attribute to `layout.title` to enable adding subtitles to plots [[#7012](https://github.com/plotly/plotly.js/pull/7012)]
+  - Introduce "u" and "s" pseudo html tags to add partial underline and strike-through styles to SVG text elements [[#7043](https://github.com/plotly/plotly.js/pull/7043)]
+  - Add geometric mean functionality and 'geometric mean ascending' + 'geometric mean descending' to `category_order` on cartesian axes [[#6223](https://github.com/plotly/plotly.js/pull/6223)],
+   with thanks to @acxz and @prabhathc for the contribution!
+  - Add axis property `ticklabelindex` for drawing the label for each minor tick n positions away from a major tick,
+   with thanks to @my-tien for the contribution! [[#7036](https://github.com/plotly/plotly.js/pull/7036)]
+  - Add property `ticklabelstandoff` and `ticklabelshift` to cartesian axes to adjust positioning of tick labels,
+   with thanks to @my-tien for the contribution! [[#7006](https://github.com/plotly/plotly.js/pull/7006)]
+  - Add `x0shift`, `x1shift`, `y0shift`, `y1shift` to shapes to add control over positioning of shape vertices on (multi-)category axes,
+   with thanks to @my-tien for the contribution! [[#7005](https://github.com/plotly/plotly.js/pull/7005)]
 - Specify Python version 3.8-3.11 for development virtual environments and pin `pytest` at version 8.1.1 to match.
 - Update `IntegerValidator` to handle `extras` option to allow supporting additional keyword values. For example, 'bold' and 'normal' as well as integers as used in font weights [#4612].
 
+
 ## [5.22.0] - 2024-05-01
 
 ### Updated

doc/python/axes.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.1
+      jupytext_version: 1.16.3
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.10.14
   plotly:
     description: How to adjust axes properties in Python - axes titles, styling and
       coloring axes and grid lines, ticks, tick labels and more.
@@ -448,6 +448,62 @@ fig.update_yaxes(minor_ticks="inside")
 fig.show()
 ```
 
+#### Adjust Tick Label Positions
+
+*New in 5.23*
+
+You can adjust tick label positions by moving them a number of pixels away from the axis using `ticklabelstandoff` or along the axis using `ticklabelshift`.
+ 
+In this example, `ticklabelshift=25` shifts the labels 25 pixels to the right along the x-axis. By providing a negative value, we could move the labels 25 pixels to the left, (`ticklabelshift=-25`).
+
+Here, `ticklabelstandoff=15` moves the labels further 15 pixels away from the x-axis. A negative value here would move them close to the axis. 
+
+```python
+import plotly.express as px
+
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
+
+fig = px.line(df, x='Date', y='AAPL.High')
+
+fig.update_layout(
+    xaxis=dict(
+        ticks='outside',
+        ticklen=10,
+        ticklabelshift=25,
+        ticklabelstandoff=15
+    )
+)
+
+fig.show()
+```
+
+#### Use Minor Tick for Label
+
+*New in 5.23*
+
+On date or linear axes, use `ticklabelindex` to draw a label for a minor tick instead of a major tick.
+
+To draw the label for the minor tick before each major tick, set `ticklabelindex` -1, like in the following example. 
+
+```python
+import plotly.express as px
+
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
+
+fig = px.line(df, x='Date', y='AAPL.High')
+
+fig.update_layout(
+    xaxis=dict(
+        minor=dict(ticks='outside'),
+        ticks='outside',
+        ticklen=10,
+        ticklabelindex=-1
+    )
+)
+
+fig.show()
+```
+
 ### Axis lines: grid and zerolines
 
 ##### Toggling Axis grid lines

doc/python/figure-labels.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.1
+      jupytext_version: 1.16.3
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.10.14
   plotly:
     description: How to set the global font, title, legend-entries, and axis-titles
       in python.
@@ -236,5 +236,44 @@ fig.update_layout(
 fig.show()
 ```
 
+### Adding a Plot Subtitle
+
+*New in 5.23*
+
+Add a subtitle to a plot with `layout.title.subtitle`. In the following example, we set the subtitle's `text`, and configure the `font` `color` and `size`. By default, if you don't set a font size for the subtitle, it will be `0.7` of the `title` font size.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.gapminder().query("continent == 'Europe' and (year == 1952 or year == 2002)")
+
+df_pivot = df.pivot(index="country", columns="year", values="lifeExp")
+
+fig = go.Figure(
+    [
+        go.Bar(
+            x=df_pivot.index, y=df_pivot[1952], name="1952", marker_color="IndianRed"
+        ),
+        go.Bar(
+            x=df_pivot.index, y=df_pivot[2002], name="2002", marker_color="LightSalmon"
+        ),
+    ],
+    layout=dict(
+        title=dict(
+            text="Life Expectancy",
+            subtitle=dict(
+                text="Life expectancy by European country in 1952 and in 2002",
+                font=dict(color="gray", size=13),
+            ),
+        )
+    ),
+)
+
+
+fig.show()
+
+```
+
 #### Reference
 See https://plotly.com/python/reference/layout/ for more information!

doc/python/scattermapbox.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.16.2
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.0
+    version: 3.10.0
   plotly:
     description: How to make scatter plots on Mapbox maps in Python.
     display_as: maps
@@ -265,6 +265,65 @@ fig.show()
 
 ```
 
+#### Font Customization
+
+You can customize the font on `go.Scattermapbox` traces with `textfont`. For example, you can set the font `family`.
+
+```python
+import plotly.graph_objects as go
+
+token = open(".mapbox_token").read() # you need your own token
+
+fig = go.Figure(go.Scattermapbox(
+    mode = "markers+text+lines",
+    lon = [-75, -80, -50], lat = [45, 20, -20],
+    marker = {'size': 20, 'symbol': ["bus", "harbor", "airport"]},
+    text = ["Bus", "Harbor", "airport"], textposition = "bottom right",
+    textfont = dict(size=18, color="black", family="Open Sans Bold")
+    ))
+
+fig.update_layout(
+    mapbox = {
+        'accesstoken': token,
+        'style': "outdoors", 'zoom': 0.7},
+    showlegend = False,)
+
+fig.show()
+```
+
+`go.Scattermapbox` supports the following values for `textfont.family`: 
+
+'Metropolis Black Italic', 'Metropolis Black', 'Metropolis Bold Italic', 'Metropolis Bold', 'Metropolis Extra Bold Italic', 'Metropolis Extra Bold', 'Metropolis Extra Light Italic', 'Metropolis Extra Light', 'Metropolis Light Italic', 'Metropolis Light', 'Metropolis Medium Italic', 'Metropolis Medium', 'Metropolis Regular Italic', 'Metropolis Regular', 'Metropolis Semi Bold Italic', 'Metropolis Semi Bold', 'Metropolis Thin Italic', 'Metropolis Thin', 'Open Sans Bold Italic', 'Open Sans Bold', 'Open Sans Extrabold Italic', 'Open Sans Extrabold', 'Open Sans Italic', 'Open Sans Light Italic', 'Open Sans Light', 'Open Sans Regular', 'Open Sans Semibold Italic', 'Open Sans Semibold', 'Klokantech Noto Sans Bold', 'Klokantech Noto Sans CJK Bold', 'Klokantech Noto Sans CJK Regular', 'Klokantech Noto Sans Italic', and 'Klokantech Noto Sans Regular'.
+
+
+##### Font Weight
+
+*New in 5.23*
+
+You can specify a numeric font weight on `go.Scattermapbox` with `textfont.weight`.
+
+```python
+import plotly.graph_objects as go
+
+token = open(".mapbox_token").read() # you need your own token
+
+fig = go.Figure(go.Scattermapbox(
+    mode = "markers+text+lines",
+    lon = [-75, -80, -50], lat = [45, 20, -20],
+    marker = dict(size=20, symbol=["bus", "harbor", "airport"]),
+    text = ["Bus", "Harbor", "airport"], textposition = "bottom right",
+    textfont = dict(size=18, color="black", weight=900)
+    ))
+
+fig.update_layout(
+    mapbox = dict(
+        accesstoken=token,
+        style="outdoors", zoom=0.7),
+    showlegend = False,)
+
+fig.show()
+```
+
 #### Reference
 
 See [function reference for `px.(scatter_mapbox)`](https://plotly.com/python-api-reference/generated/plotly.express.scatter_mapbox) or https://plotly.com/python/reference/scattermapbox/ for more information and options!

doc/python/shapes.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.1
+      jupytext_version: 1.16.3
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.10.14
   plotly:
     description: How to make SVG shapes in python. Examples of lines, circle, rectangle,
       and path.
@@ -579,6 +579,72 @@ fig.update_layout(
 fig.show()
 ```
 
+#### Shifting Shapes on Categorical Axes
+
+*New in 5.23*
+
+When drawing shapes where `xref` or `yref` reference axes of type category or multicategory, you can shift `x0`, `x1`, `y0`, and `y1` away from the center of the category using `x0shift`, `x1shift`, `y0shift`, and `y1shift` by specifying a value between -1 and 1. 
+
+-1 is the center of the previous category, 0 is the center of the referenced category, and 1 is the center of the next category.
+
+In the following example, the `x0` and `x1` values for both shapes reference category values on the x-axis.
+
+In this example, the first shape:
+- Shifts `x0` half way between the center of category "Germany" and the center of the previous category by setting `x0shift=-0.5`
+- Shifts `x1`half way between the center of category "Germany" and the center of the next category by setting `x1shift=0.5`
+
+The second shape:
+- Shifts `x0` back to the center of the previous category by setting `x0shift=-1`
+- Shifts `x1`forward to the center of the next category by setting `x1shift=1`
+
+```python
+import plotly.graph_objects as go
+import plotly.express as px
+
+df = px.data.gapminder().query("continent == 'Europe' and year == 1952")
+
+fig = go.Figure(
+    data=go.Bar(x=df["country"], y=df["lifeExp"], marker_color="LightSalmon"),
+    layout=dict(
+        shapes=[
+            dict(
+                type="rect",
+                x0="Germany",
+                y0=0,
+                x1="Germany",
+                y1=0.5,
+                xref="x",
+                yref="paper",
+                x0shift=-0.5,
+                x1shift=0.5,
+                line=dict(color="LightGreen", width=4),
+            ),
+            dict(
+                type="rect",
+                x0="Spain",
+                y0=0,
+                x1="Spain",
+                y1=0.5,
+                xref="x",
+                yref="paper",
+                x0shift=-1,
+                x1shift=1,
+                line=dict(color="MediumTurquoise", width=4),
+            ),
+        ]
+    ),
+)
+
+fig.update_layout(
+    title="GDP per Capita in Europe (1972)",
+    xaxis_title="Country",
+    yaxis_title="GDP per Capita",
+)
+
+fig.show()
+
+```
+
 ### Drawing shapes with a Mouse on Cartesian plots
 
 _introduced in plotly 4.7_