Merge pull request #4210 from plotly/update-plotly-js

Update plotly.js to 2.24.1 and add docs for new features

Author: LiamConnors

Diff for: .circleci/config.yml

@@ -432,7 +432,7 @@ jobs:
     resource_class: xlarge
     docker:
       # specify the version you desire here
-      # use `-browsers` prefix for selenium tests, e.g. `3.6.1-browsers`
+      # use `-browsers` prefix for selenium tests, for example, `3.6.1-browsers`
       - image: cimg/python:3.7-browsers
 
     steps:

Diff for: CHANGELOG.md

@@ -4,6 +4,20 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [UNRELEASED]
 
+
+### Updated
+  - Updated Plotly.js from version 2.20.0 to version 2.24.1. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2241----2023-06-07) for more information. Notable changes include:
+    - Add pattern to pie, funnelarea, sunburst, icicle and treemap traces [[#6601](https://github.com/plotly/plotly.js/pull/6601), [#6619](https://github.com/plotly/plotly.js/pull/6619), [#6622](https://github.com/plotly/plotly.js/pull/6622), [#6626](https://github.com/plotly/plotly.js/pull/6626), [#6627](https://github.com/plotly/plotly.js/pull/6627), [#6628](https://github.com/plotly/plotly.js/pull/6628), [#6629](https://github.com/plotly/plotly.js/pull/6629)], with thanks to @thierryVergult for the contribution!
+    - Add `texttemplate` to shape.label for parametric shapes i.e. line, rect and circle [[#6527](https://github.com/plotly/plotly.js/pull/6527)],
+   with thanks to the [Volkswagen](https://www.volkswagenag.com) Center of Excellence for Battery Systems for sponsoring development!
+    - Add strict option to custom bundle command [[#6557](https://github.com/plotly/plotly.js/pull/6557)],
+   with thanks to @CallumNZ for the contribution!
+    - Add `legend` references to traces and `legend2`, `legend3`, etc. to layout,
+   also add `visible` to legend i.e. to allow positioning multiple legends on a graph [[#6535](https://github.com/plotly/plotly.js/pull/6535)],
+   this feature was anonymously sponsored: thank you to our sponsor!
+    - Add `legend.xref` and `legend.yref` to enable container-referenced positioning of legends [[#6589](https://github.com/plotly/plotly.js/pull/6589)], with thanks to [Gamma Technologies](https://www.gtisoft.com/) for sponsoring the related development.
+    - Add `colorbar.xref` and `colorbar.yref` to enable container-referenced positioning of colorbars [[#6593](https://github.com/plotly/plotly.js/pull/6593)], with thanks to [Gamma Technologies](https://www.gtisoft.com/) for sponsoring the related development.
+
 ### Fixed
   - Fixed another compatibility issue with Pandas 2.0, just affecting `px.*(line_close=True)` [[#4190](https://github.com/plotly/plotly.py/pull/4190)]
   - Empty pandas dataframe with facet row/column set no longer fails [[#4038](https://github.com/plotly/plotly.py/pull/4038)]

Diff for: doc/python/colorscales.md

@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.9
+    version: 3.10.11
   plotly:
     description: How to set, create and control continuous color scales and color
       bars in scatter, bar, map and heatmap figures.
@@ -632,6 +632,36 @@ fig = go.Figure(go.Heatmap(
 fig.show()
 ```
 
+### Positioning Colorbars
+
+Colorbars can be positioned by specifying x and y coordinates. By default, the x and y values are "paper" coordinates, which refer to the plot area. You can also use coordinates based on the "container" by setting `xref="container"` or `yref="container"`. The following example uses a container reference for the x position.
+
+See the positioning section of [the figure data structure page](/python/figure-structure/#positioning-with-paper-container-coordinates-or-axis-domain-coordinates) for more details on "paper" vs "container" coordinates.
+
+```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(go.Heatmap(
+    z=dataset["z"],
+    colorbar=dict(
+        x=0.2,
+        xref="container",
+        title="Surface Heat"
+    )
+))
+
+fig.show()
+```
+
 ### Reference
 
 See https://plotly.com/python/reference/ for more information and chart attribute options!

Diff for: doc/python/funnel-charts.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.3.0
+      format_version: '1.3'
+      jupytext_version: 1.14.6
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   plotly:
@@ -200,6 +200,28 @@ fig.update_layout(
 fig.show()
 ```
 
+### Pattern Fills
+
+*New in 5.15*
+
+Funnel area charts support [patterns](/python/pattern-hatching-texture/) (also known as hatching or texture) in addition to color. In this example, we add a pattern to the second stage of the funnel.
+
+```python
+from plotly import graph_objects as go
+
+colors = ["gold", "gold", "lightgreen", "lavender"]
+
+fig = go.Figure(
+    go.Funnelarea(
+        labels=["Interview 1", "Interview 2", "Test", "Final Stage"],
+        values=[100, 70, 40, 20],
+        textfont_size=20,
+        marker=dict(colors=colors, pattern=dict(shape=["", "/", "", ""])),
+    )
+)
+fig.show()
+```
+
 #### Reference
 
 See [function reference for `px.(funnel)`](https://plotly.com/python-api-reference/generated/plotly.express.funnel) or https://plotly.com/python/reference/funnel/ and https://plotly.com/python/reference/funnelarea/ for more information and chart attribute options!

Diff for: doc/python/icicle-charts.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.6
   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.10.11
   plotly:
     description: How to make Icicle Charts.
     display_as: basic
@@ -418,6 +418,30 @@ fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
 fig.show()
 ```
 
+### Pattern Fills
+
+*New in 5.15*
+
+Icicle charts support [patterns](/python/pattern-hatching-texture/) (also known as hatching or texture) in addition to color. In this example, we apply a pattern to all chart sections. We also configure the `size` and `solidity` of the pattern.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(
+    go.Icicle(
+        labels=["Eve", "Cain", "Seth", "Enos", "Noam", "Abel", "Awan", "Enoch", "Azura"],
+        parents=["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve"],
+        values=[10, 14, 12, 10, 2, 6, 6, 4, 4],
+        root_color="lightgrey",
+        textfont_size=20,
+        marker=dict(pattern=dict(shape="|", size=5, solidity=0.9)),
+    )
+)
+
+fig.update_layout(margin=dict(t=50, l=25, r=25, b=25))
+fig.show()
+```
+
 ### Set the Direction of Icicle charts
 
 As mentioned above, Icicle charts can grow in one of four directions. Icicle charts have a `tiling` attribute and this has two attributes: `orientation` and `flip`. `orientation` takes either `h` (horiztonal) or `v` (vertical) and `flip` takes either `x` or `y`. You can use these two attributes in combination to create each of the four cardinal directions: left, right, top, bottom.

Diff for: doc/python/legend.md

@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.8
+    version: 3.10.11
   plotly:
     description: How to configure and style the legend in Plotly with Python.
     display_as: file_settings
@@ -638,6 +638,43 @@ fig.show()
 
 ```
 
+### Positioning Legends
+
+In the previous example, we position the second legend by specifying x and y values. By default, these values are based on the width and height of the plot area. It is also possible to specify values that reference the container width and height by setting "xref=container" and "yref="container" (the default values are "xref=paper" and "yref="paper"). When set to "container", the margin grows so the legend and plot don't overlap.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.gapminder()
+
+df_germany = df.loc[(df.country.isin(["Germany"]))]
+df_france = df.loc[(df.country.isin(["France"]))]
+df_uk = df.loc[(df.country.isin(["United Kingdom"]))]
+
+fig = go.Figure(
+    data=[
+        go.Scatter(x=df_germany.year, y=df_germany.gdpPercap, name="Germany"),
+        go.Scatter(x=df_france.year, y=df_france.gdpPercap, name="France"),
+        go.Scatter(x=df_uk.year, y=df_uk.gdpPercap, name="UK"),
+    ],
+    layout=dict(
+        title="GDP Per Capita",
+        legend={
+            "x": 0.9,
+            "y": 0.9,
+            "xref": "container",
+            "yref": "container",
+            "bgcolor": "Gold",
+            "title": {"text": "By continent"},
+        },
+    ),
+)
+
+fig.show()
+
+```
+
 #### Reference
 
 See https://plotly.com/python/reference/layout/#layout-legend for more information!

Diff for: doc/python/pattern-hatching-texture.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.13.7
+      jupytext_version: 1.14.6
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.9.7
+    version: 3.10.11
   plotly:
     description: How to use patterns (also known as hatching or texture) with bar
       charts.
@@ -34,9 +34,9 @@ jupyter:
     thumbnail: thumbnail/pattern.png
 ---
 
-*New in v5.0*
+*New in 5.0, with support for pie, sunburst, icicle, funnelarea, and treemap charts in 5.15*
 
-[Bar charts](/python/bar-charts/), [histograms](/python/histograms/), [polar bar charts](/python/wind-rose-charts/) and [area charts](/python/filled-area-plots/) have large markers or areas which support not only a fill color, but also an optional **pattern** (also known as "hatching" or "texture"). This can be used for a variety of reasons:
+[Bar charts](/python/bar-charts/), [histograms](/python/histograms/), [polar bar charts](/python/wind-rose-charts/), [area charts](/python/filled-area-plots/), [pie charts](/python/pie-charts), [sunburst charts](/python/sunburst-charts), [funnelarea charts](/python/funnel-charts), [icicle charts](/python/icicle-charts/), and [treemap charts](/python/treemaps), have large markers or areas which support not only a fill color, but also an optional **pattern** (also known as "hatching" or "texture"). This can be used for a variety of reasons:
 
 * to double-encode variables (i.e. using both color and pattern) to improve accessibility for visually-impaired end-users
 * to encode an additional variable beyond just using color
@@ -79,7 +79,7 @@ In the charts above, the first value of the variable assigned `pattern_shape` ge
 
 Here we use `pattern_shape_sequence` to replace the defaults and include a pattern-shape for the first variable:
 
-```python tags=[]
+```python
 import plotly.express as px
 df = px.data.medals_long()
 

Diff for: doc/python/pie-charts.md

@@ -6,9 +6,9 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.14.6
   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.11
   plotly:
     description: How to make Pie Charts.
     display_as: basic
@@ -300,6 +300,33 @@ fig.update_layout(title_text='World GDP')
 fig.show()
 ```
 
+### Pattern Fills
+
+*New in 5.15*
+
+Pie charts support [patterns](/python/pattern-hatching-texture/) (also known as hatching or texture) in addition to color.
+
+```python
+import plotly.graph_objects as go
+
+labels = ["Oxygen", "Hydrogen", "Carbon_Dioxide", "Nitrogen"]
+values = [4500, 2500, 1053, 500]
+colors = ["gold", "mediumturquoise", "darkorange", "lightgreen"]
+
+fig = go.Figure(
+    data=[
+        go.Pie(
+            labels=labels,
+            values=values,
+            textfont_size=20,
+            marker=dict(colors=colors, pattern=dict(shape=[".", "x", "+", "-"]))
+        )
+    ]
+)
+
+fig.show()
+```
+
 ### See Also: Sunburst charts
 
 For multilevel pie charts representing hierarchical data, you can use the `Sunburst` chart. A simple example is given below, for more information see the [tutorial on Sunburst charts](/python/sunburst-charts/).

Diff for: doc/python/sunburst-charts.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.6
   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.10.11
   plotly:
     description: How to make Sunburst Charts.
     display_as: basic
@@ -300,6 +300,36 @@ fig.update_layout(uniformtext=dict(minsize=10, mode='hide'))
 fig.show()
 ```
 
+### Pattern Fills
+
+*New in 5.15*
+
+Sunburst charts support [patterns](/python/pattern-hatching-texture/) (also known as hatching or texture) in addition to color. In this example, we add a different pattern to each level of the hierarchy. We also specify the `solidity` of the pattern.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(
+    go.Sunburst(
+        labels=["Eve", "Cain", "Seth", "Enos", "Noam", "Abel", "Awan", "Enoch", "Azura"],
+        parents=["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve"],
+        values=[65, 14, 12, 10, 2, 6, 6, 4, 4],
+        branchvalues="total",
+        textfont_size=16,
+        marker=dict(
+            pattern=dict(
+                shape=["", "/", "/", ".", ".", "/", "/", ".", "/"], solidity=0.9
+            )
+        ),
+    )
+)
+
+fig.update_layout(margin=dict(t=0, l=0, r=0, b=0))
+
+fig.show()
+
+```
+
 ### Sunburst chart with a continuous colorscale
 
 The example below visualizes a breakdown of sales (corresponding to sector width) and call success rate (corresponding to sector color) by region, county and salesperson level. For example, when exploring the data you can see that although the East region is behaving poorly, the Tyler county is still above average -- however, its performance is reduced by the poor success rate of salesperson GT.