Merge pull request #4239 from plotly/master

Merge master back in to doc-prod to deploy updated docs

Author: LiamConnors

Diff for: .circleci/config.yml

@@ -52,3 +52,6 @@ doc/check-or-enforce-order.py
 packages/javascript/jupyterlab-plotly/lib/
 packages/python/plotly/jupyterlab_plotly/labextension/
 packages/python/plotly/jupyterlab_plotly/nbextension/index.js*
+
+test/percy/*.html
+test/percy/pandas2/*.html

Diff for: .gitignore

@@ -2,6 +2,34 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [5.15.0] - 2023-06-08
+
+### 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.
+  - `px` methods now accept data-frame-like objects that support a `to_pandas()` method, such as polars, cudf, vaex etc
+
+### 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)]
+  - Added some rounding to the `make_subplots` function to handle situations where the user-input specs cause the domain to exceed 1 by small amounts [[#4153](https://github.com/plotly/plotly.py/pull/4153)]
+  - Sanitize JSON output to prevent an XSS vector when graphs are inserted directly into HTML [[#4196](https://github.com/plotly/plotly.py/pull/4196)]
+  - Fixed issue with shapes and annotations plotting on the wrong y axis when supplied with a specific axis in the `yref` parameter [[#4177](https://github.com/plotly/plotly.py/pull/4177)]
+  - Remove `use_2to3` setuptools arg, which is invalid in the latest Python and setuptools versions [[#4206](https://github.com/plotly/plotly.py/pull/4206)]
+  - Fix [#4066](https://github.com/plotly/plotly.py/issues/4066) JupyterLab v4 giving tiny default graph height [[#4227](https://github.com/plotly/plotly.py/pull/4227)]
+  - Fixed issue with `colors.n_colors` where generated RGB color values were not being constrained to stay between 0 and 255 [[#4110](https://github.com/plotly/plotly.py/pull/4110)]
+  - Fix streamline figure factory with recent versions of Numpy
+  - Fix issue with shapes and annotations not drawing on correct axis [[#4177](https://github.com/plotly/plotly.py/pull/4177)]
+
 ## [5.14.1] - 2023-04-05
 
 ### Fixed
@@ -10,7 +38,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [5.14.0] - 2023-03-29
 
 ### 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:
+  - Updated Plotly.js 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!

Diff for: CHANGELOG.md

@@ -33,7 +33,7 @@
 
 ## Quickstart
 
-`pip install plotly==5.14.1`
+`pip install plotly==5.15.0`
 
 Inside [Jupyter](https://jupyter.org/install) (installable with `pip install "jupyterlab>=3" "ipywidgets>=7.6"`):
 
@@ -78,13 +78,13 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is
 plotly.py may be installed using pip...
 
 ```
-pip install plotly==5.14.1
+pip install plotly==5.15.0
 ```
 
 or conda.
 
 ```
-conda install -c plotly plotly=5.14.1
+conda install -c plotly plotly=5.15.0
 ```
 
 ### JupyterLab Support
@@ -106,7 +106,7 @@ The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**,
 
 ```
 # JupyterLab 2.x renderer support
-jupyter labextension install jupyterlab-plotly@5.14.1 @jupyter-widgets/jupyterlab-manager
+jupyter labextension install jupyterlab-plotly@5.15.0 @jupyter-widgets/jupyterlab-manager
 ```
 
 Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.

Diff for: README.md

@@ -1,5 +1,5 @@
 jupytext
-plotly==5.14.1
+plotly==5.15.0
 jupyter
 notebook
 pandas==1.0.3

Diff for: binder/requirements.txt

@@ -28,7 +28,7 @@
 # The short X.Y version
 version = ""
 # The full version, including alpha/beta/rc tags
-release = "5.14.1"
+release = "5.15.0"
 
 
 # -- General configuration ---------------------------------------------------

Diff for: doc/apidoc/conf.py

@@ -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/colorscales.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/funnel-charts.md

@@ -58,13 +58,13 @@ We also encourage you to join the [Plotly Community Forum](http://community.plot
 `plotly` may be installed using `pip`:
 
 ```
-$ pip install plotly==5.14.1
+$ pip install plotly==5.15.0
 ```
 
 or `conda`:
 
 ```
-$ conda install -c plotly plotly=5.14.1
+$ conda install -c plotly plotly=5.15.0
 ```
 This package contains everything you need to write figures to standalone HTML files.
 
@@ -152,7 +152,7 @@ The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**,
 
 ```
 # JupyterLab 2.x renderer support
-jupyter labextension install jupyterlab-plotly@5.14.1 @jupyter-widgets/jupyterlab-manager
+jupyter labextension install jupyterlab-plotly@5.15.0 @jupyter-widgets/jupyterlab-manager
 ```
 
 Please check out our [Troubleshooting guide](/python/troubleshooting/) if you run into any problems with JupyterLab, particularly if you are using multiple python environments inside Jupyter.

Diff for: doc/python/getting-started.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/icicle-charts.md

@@ -6,7 +6,7 @@ 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 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.0
+    version: 3.10.11
   plotly:
     description: How to configure and style the legend in Plotly with Python.
     display_as: file_settings
@@ -574,6 +574,107 @@ fig.update_layout(width=600, title_text='Exploration of a vector field using sev
 fig.show()
 ```
 
+### Adding Multiple Legends
+
+*New in 5.15*
+
+By default, all traces appear on one legend. To have multiple legends, specify an alternative legend for a trace using the `legend` property. For a second legend, set `legend="legend2"`. Specify more legends with `legend="legend3"`, `legend="legend4"` and so on.
+
+In this example, the last two scatter traces display on the second legend, "legend2". On the figure's layout, we then position and style this legend to display on the right of the graph below the first legend.
+
+
+```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"]))]
+
+
+df_averages_europe = (
+    df.loc[(df.continent.isin(["Europe"]))].groupby(by="year").mean(numeric_only=True)
+)
+df_averages_americas = (
+    df.loc[(df.continent.isin(["Americas"]))].groupby(by="year").mean(numeric_only=True)
+)
+
+
+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"),
+        go.Scatter(
+            x=df_averages_europe.index,
+            y=df_averages_europe.gdpPercap,
+            name="Europe",
+            legend="legend2",
+        ),
+        go.Scatter(
+            x=df_averages_americas.index,
+            y=df_averages_americas.gdpPercap,
+            name="Americas",
+            legend="legend2",
+        ),
+    ],
+    layout=dict(
+        title="GDP Per Capita",
+        legend={"title": "By country", "bgcolor": "Orange",},
+        legend2={
+            "x": 1.155,
+            "y": 0.55,
+            "xanchor": "right",
+            "yanchor": "middle",
+            "bgcolor": "Gold",
+            "title": {"text": "By continent"},
+        },
+    ),
+)
+
+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!