8000 Merge branch 'master' into feature/update-json-funcs · plotly/plotly.py@76be0e9 · GitHub
[go: up one dir, main page]
Skip to content

Commit 76be0e9

Browse files
itsluketwistitsluketwist
authored
Merge branch 'master' into feature/update-json-funcs
2 parents 7ef805c + 83e5cfa commit 76be0e9

File tree

299 files changed

+6372
-2335
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

299 files changed

+6372
-2335
lines changed

‎CHANGELOG.md

Lines changed: 12 additions & 2 deletions
F438
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,24 @@
22
All notable changes to this project will be documented in this file.
33
This project adheres to [Semantic Versioning](http://semver.org/).
44

5+
## [5.16.1] - 2023-08-16
56

6-
## UNRELEASED
7+
### Fixed
8+
- Fixed issue with necessary columns from complex arguments dropped when interchanging dataframes [[#4324](https://github.com/plotly/plotly.py/pull/4324)]
9+
10+
## [5.16.0] - 2023-08-11
711

812
### Updated
9-
- Updated Plotly.js from version 2.24.1 to version 2.24.2. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2242----2023-06-09) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module.
13+
- Updated Plotly.js from version 2.24.1 to version 2.25.2. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2252----2023-08-11) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
14+
- Add "Equal Earth" projection to geo subplots [[#6670](https://github.com/plotly/plotly.js/pull/6670)],
15+
with thanks to @apparebit for the contribution!
16+
- Add options to include legends for shapes and `newshape` [[#6653](https://github.com/plotly/plotly.js/pull/6653)]
1017
- `px` methods now accept data-frame-like objects that support a [dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), such as polars, vaex, modin etc. This protocol has priority on `to_pandas` call, but will only be used if pandas>=2.0.2 is installed in the environment.
1118
- `px` methods now accept data-frame-like objects that support a `toPandas()` method, such as Spark DataFrames, or a `to_pandas_df()` method, such as Vaex DataFrames.
1219

20+
### Fixed
21+
- Fixed Pandas performance warning issue caused by multiple `frame.insert` [[#4246](https://github.com/plotly/plotly.py/pull/4246)]
22+
1323
## [5.15.0] - 2023-06-08
1424

1525
### Updated

‎README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333

3434
## Quickstart
3535

36-
`pip install plotly==5.15.0`
36+
`pip install plotly==5.16.1`
3737

3838
Inside [Jupyter](https://jupyter.org/install) (installable with `pip install "jupyterlab>=3" "ipywidgets>=7.6"`):
3939

@@ -78,13 +78,13 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is
7878
plotly.py may be installed using pip...
7979

8080
```
81-
pip install plotly==5.15.0
81+
pip install plotly==5.16.1
8282
```
8383

8484
or conda.
8585

8686
```
87-
conda install -c plotly plotly=5.15.0
87+
conda install -c plotly plotly=5.16.1
8888
```
8989

9090
### JupyterLab Support
@@ -106,7 +106,7 @@ The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**,
106106

107107
```
108108
# JupyterLab 2.x renderer support
109-
jupyter labextension install jupyterlab-plotly@5.15.0 @jupyter-widgets/jupyterlab-manager
109+
jupyter labextension install jupyterlab-plotly@5.16.1 @jupyter-widgets/jupyterlab-manager
110110
```
111111

112112
Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.

‎binder/requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
jupytext
2-
plotly==5.15.0
2+
plotly==5.16.1
33
jupyter
44
notebook
55
pandas==1.0.3

‎doc/apidoc/conf.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
# The short X.Y version
2929
version = ""
3030
# The full version, including alpha/beta/rc tags
31-
release = "5.15.0"
31+
release = "5.16.1"
3232

3333

3434
# -- General configuration ---------------------------------------------------

‎doc/python/animations.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ jupyter:
3737

3838
Several [Plotly Express](/python/plotly-express/) functions support the creation of animated figures through the `animation_frame` and `animation_group` arguments.
3939

40-
Here is an example of an animated scatter plot creating using Plotly Express. Note that you should always fix the `x_range` and `y_range` to ensure that your data remains visible throughout the animation.
40+
Here is an example of an animated scatter plot created with Plotly Express. Note that you should always fix the `x_range` and `y_range` to ensure that your data remains visible throughout the animation.
4141

4242
```python
4343
import plotly.express as px

‎doc/python/getting-started.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,13 +58,13 @@ We also encourage you to join the [Plotly Community Forum](http://community.plot
5858
`plotly` may be installed using `pip`:
5959

6060
```
61-
$ pip install plotly==5.15.0
61+
$ pip install plotly==5.16.1
6262
```
6363

6464
or `conda`:
6565

6666
```
67-
$ conda install -c plotly plotly=5.15.0
67+
$ conda install -c plotly plotly=5.16.1
6868
```
6969
This package contains everything you need to write figures to standalone HTML files.
7070

@@ -152,7 +152,7 @@ The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**,
152152

153153
```
154154
# JupyterLab 2.x renderer support
155-
jupyter labextension install jupyterlab-plotly@5.15.0 @jupyter-widgets/jupyterlab-manager
155+
jupyter labextension install jupyterlab-plotly@5.16.1 @jupyter-widgets/jupyterlab-manager
156156
```
157157

158158
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.

‎doc/python/interactive-html-export.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Any figure can be saved as an HTML file using the `write_html` method. These HTM
4646
```python
4747
import plotly.express as px
4848

49-
fig =px.scatter(x=range(10), y=range(10))
49+
fig = px.scatter(x=range(10), y=range(10))
5050
fig.write_html("path/to/file.html")
5151
```
5252
<!-- #endregion -->

‎doc/python/legend.md

Lines changed: 86 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ jupyter:
66
extension: .md
77
format_name: markdown
88
format_version: '1.3'
9-
jupytext_version: 1.14.6
9+
jupytext_version: 1.14.7
1010
kernelspec:
1111
display_name: Python 3 (ipykernel)
1212
language: python
@@ -20,7 +20,7 @@ jupyter:
2020
name: python
2121
nbconvert_exporter: python
2222
pygments_lexer: ipython3
23-
version: 3.10.11
23+
version: 3.10.4
2424
plotly:
2525
description: How to configure and style the legend in Plotly with Python.
2626
display_as: file_settings
@@ -35,7 +35,7 @@ jupyter:
3535

3636
### Trace Types, Legends and Color Bars
3737

38-
[Traces](/python/figure-structure) of most types can be optionally associated with a single legend item in the [legend](/python/legend/). Whether or not a given trace appears in the legend is controlled via the `showlegend` attribute. Traces which are their own subplots (see above) do not support this, with the exception of traces of type `pie` and `funnelarea` for which every distinct color represented in the trace gets a separate legend item. Users may show or hide traces by clicking or double-clicking on their associated legend item. Traces that support legend ite 10000 ms also support the `legendgroup` attribute, and all traces with the same legend group are treated the same way during click/double-click interactions.
38+
[Traces](/python/figure-structure) of most types and shapes can be optionally associated with a single legend item in the [legend](/python/legend/). Whether or not a given trace or shape appears in the legend is controlled via the `showlegend` attribute. Traces which are their own subplots (see above) do not support this, with the exception of traces of type `pie` and `funnelarea` for which every distinct color represented in the trace gets a separate legend item. Users may show or hide traces by clicking or double-clicking on their associated legend item. Traces that support legend items and shapes also support the `legendgroup` attribute, and all traces and shapes with the same legend group are treated the same way during click/double-click interactions.
3939

4040
The fact that legend items are linked to traces means that when using [discrete color](/python/discrete-color/), a figure must have one trace per color in order to get a meaningful legend. [Plotly Express has robust support for discrete color](/python/discrete-color/) to make this easy.
4141

@@ -97,26 +97,66 @@ fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2,1]))
9797
fig.show()
9898
```
9999

100-
*New in v5.0*
100+
*New in 5.16*
101101

102-
The `legendrank` attribute of a trace can be used to control its placement within the legend, without regard for its placement in the `data` list.
102+
If you have shapes that are configured to appear in a legend, these are displayed after all traces:
103103

104-
The default `legendrank` for traces is 1000 and ties are broken as described above, meaning that any trace can be pulled up to the top if it is the only one with a legend rank less than 1000 and pushed to the bottom if it is the only one with a rank greater than 1000.
104+
```python
105+
import plotly.graph_objects as go
106+
107+
fig = go.Figure()
108+
fig.add_trace(go.Bar(name="first", x=["a", "b"], y=[1, 2]))
109+
fig.add_trace(go.Bar(name="second", x=["a", "b"], y=[2, 1]))
110+
fig.add_shape(
111+
name="first shape",
112+
showlegend=True,
113+
type="rect",
114+
xref="paper",
115+
line=dict(dash="dash"),
116+
x0=0.85,
117+
x1=0.95,
118+
y0=0,
119+
y1=1.5,
120+
)
121+
fig.add_trace(go.Bar(name="third", x=["a", "b"], y=[1, 2]))
122+
fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2, 1]))
123+
124+
fig.show()
125+
126+
```
127+
128+
The `legendrank` attribute of a trace or shape can be used to control its placement in the legend.
129+
The default `legendrank` for traces and shapes is 1000. When all traces and shapes have the same `legendrank`, traces appear in the order they appear in the data, followed by shapes in the order they are defined.
130+
131+
Any trace or shape can be pulled up to the top of the legend if it is the only one with a legend rank less than 1000 and pushed to the bottom if it is the only one with a rank greater than 1000.
132+
133+
In this example, we add a `legendrank` for each trace and shape, giving the shape the lowest rank so it appears first, and moving the first trace defined to the bottom of the legend by giving it the highest rank.
105134

106135
```python
107136
import plotly.graph_objects as go
108137

109138
fig = go.Figure()
110-
fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2,1], legendrank=4))
111-
fig.add_trace(go.Bar(name="second", x=["a", "b"], y=[2,1], legendrank=2))
112-
fig.add_trace(go.Bar(name="first", x=["a", "b"], y=[1,2], legendrank=1))
139+
fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2,1], legendrank=5))
140+
fig.add_trace(go.Bar(name="second", x=["a", "b"], y=[2,1], legendrank=4))
141+
fig.add_trace(go.Bar(name="first", x=["a", "b"], y=[1,2], legendrank=2))
113142
fig.add_trace(go.Bar(name="third", x=["a", "b"], y=[1,2], legendrank=3))
143+
fig.add_shape(
144+
legendrank=1,
145+
showlegend=True,
146+
type="line",
147+
xref="paper",
148+
line=dict(dash="5px"),
149+
x0=0.05,
150+
x1=0.45,
151+
y0=1.5,
152+
y1=1.5,
153+
)
114154
fig.show()
115155
```
116156

117157
#### Showing and Hiding the Legend
118158

119-
By default the legend is displayed on Plotly charts with multiple traces, and this can be explicitly set with the `layout.showlegend` attribute:
159+
By default the legend is displayed on Plotly charts with multiple traces, and this can be explicitly set with the `layout.showlegend` attribute.
120160

121161
```python
122162
import plotly.express as px
@@ -193,7 +233,7 @@ fig.show()
193233

194234
*New in 5.11*
195235

196-
Set the width of horizontal legend entries by setting `entrywidth`. Here we set it to `70` pixels. Pixels is the default unit for `entrywidth`, but you can set it to be a fraction of the plot width using `entrywidthmode='fraction`.
236+
Set the width of horizontal legend entries by setting `entrywidth`. Here we set it to `70` pixels. Pixels is the default unit for `entrywidth`, but you can set it to be a fraction of the plot width using `entrywidthmode='fraction'`.
197237

198238
```python
199239
import plotly.express as px
@@ -253,7 +293,30 @@ When creating figures using [graph objects](/python/graph-objects/) without usin
253293

254294
#### Legend Item Names
255295

256-
Legend items appear per trace, and the legend item name is taken from the trace's `name` attribute.
296+
For traces, legend items appear per trace, and the legend item name is taken from the trace's `name` attribute.
297+
298+
```python
299+
import plotly.graph_objects as go
300+
301+
fig = go.Figure()
302+
303+
fig.add_trace(go.Scatter(
304+
x=[1, 2, 3, 4, 5],
305+
y=[1, 2, 3, 4, 5],
306+
name="Positive"
307+
))
308+
309+
fig.add_trace(go.Scatter(
310+
x=[1, 2, 3, 4, 5],
311+
y=[5, 4, 3, 2, 1],
312+
name="Negative"
313+
))
314+
315+
fig.show()
316+
```
317+
318+
By default, for shapes, legend items are disabled. Set `showlegend=True` on a shape for it to display a legend item.
319+
The name that appears for the shape in the legend is the shape's `name` if it is provided. If no `name` is provided, the shape label's `text` is used. If neither is provided, the legend item appears as "shape \<shape number>". For example, "shape 1".
257320

258321
```python
259322
import plotly.graph_objects as go
@@ -272,6 +335,15 @@ fig.add_trace(go.Scatter(
272335
name="Negative"
273336
))
274337

338+
fig.add_shape(
339+
showlegend=True,
340+
type="rect",
341+
x0=2,
342+
x1=4,
343+
y0=4.5,
344+
y1=5,
345+
)
346+
275347
fig.show()
276348
```
277349

@@ -324,7 +396,7 @@ fig.show()
324396

325397
#### Hiding the Trace Initially
326398

327-
Traces have a `visible` attribute. If set to `legendonly`, the trace is hidden from the graph implicitly. Click on the name in the legend to display the hidden trace.
399+
Traces and shapes have a `visible` attribute. If set to `legendonly`, the trace or shape is hidden from the graph implicitly. Click on the name in the legend to display the hidden trace or shape.
328400

329401
```python
330402
import plotly.graph_objects as go
@@ -578,7 +650,7 @@ fig.show()
578650

579651
*New in 5.15*
580652

581-
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.
653+
By default, all traces and shapes appear on one legend. To have multiple legends, specify an alternative legend for a trace or shape using the `legend` property. For a second legend, set `legend="legend2"`. Specify more legends with `legend="legend3"`, `legend="legend4"` and so on.
582654

583655
In this example, the last two scatter traces display on the second legend, "legend2". On the figure's layout, we then position and style each legend.
584656

‎doc/python/px-arguments.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ jupyter:
3535

3636
### Plotly Express works with Column-oriented, Matrix or Geographic Data
3737

38-
[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which operates on a variety of types of data and produces [easy-to-style figures](/python/styling-plotly-express/).
38+
[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
3939

4040
Plotly Express provides functions to visualize a variety of types of data. Most functions such as `px.bar` or `px.scatter` expect to operate on column-oriented data of the type you might store in a `DataFrame` (in either "long" or "wide" format, see below). These functions use Pandas internally to process the data, but also accept other types of DataFrames as arguments. See the **Input Data as Non-Pandas DataFrames** section below for more details.
4141

@@ -170,14 +170,12 @@ fig.show()
170170

171171
### Input Data as Non-Pandas `DataFrame`s
172172

173-
**New in 5.16**
173+
*New in 5.15*
174174

175-
In the examples above, we've used Pandas DataFrames. You can also provide another type of DataFrame to the `data_frame` argument if that DataFrame has a `to_pandas` method or supports the [Python dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), for example, a [Polars](https://www.pola.rs/) DataFrame.
175+
In the examples above, we've used Pandas DataFrames. You can also provide another type of DataFrame to the `data_frame` argument if that DataFrame has a `to_pandas` method, for example, a [Polars](https://www.pola.rs/) DataFrame.
176176

177177
Plotly Express uses Pandas internally to process the data. When you provide a Non-Pandas DataFrame to the `data_frame` argument of a Plotly Express function, the entire DataFrame is converted to a Pandas DataFrame.
178178

179-
If you are using a type of DataFrame that doesn't have a `to_pandas` method, but supports the Python dataframe interchange protocol, you'll need to have Pandas version 2.0.3 or later installed.
180-
181179
In this example, we use a Polars DataFrame. If you are using Polars, you'll need to install `pyarrow`, which is used by its [`to_pandas` method](
182180
https://pola-rs.github.io/polars/py-polars/html/reference/dataframe/api/polars.DataFrame.to_pandas.html)
183181

@@ -198,6 +196,13 @@ fig = px.bar(wide_df, x="nation", y=["gold", "silver", "bronze"], title="Wide-Fo
198196
fig.show()
199197
```
200198

199+
*New in 5.16*
200+
201+
As of version 5.16, you can also provide another type of DataFrame to the `data_frame` argument if that DataFrame supports the [Python dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), or has a `toPandas` or `to_pandas_df` method.
202+
203+
Even if the DataFrame that you are using supports the Python dataframe interchange protocol, you'll need to have Pandas version 2.0.3 or later installed. If you are using an earlier version of Pandas, Plotly Express will look for a `to_pandas`, `toPandas`, and `to_pandas_df` method, and use whichever one is available.
204+
205+
201206
### Input Data as array-like columns: NumPy arrays, lists...
202207

203208
`px` arguments can also be array-like objects such as lists, NumPy arrays, in both long-form or wide-form (for certain functions).

0 commit comments

Comments
 (0)
0