8000 Merge remote-tracking branch 'origin/master' into kaleido · plotly/plotly.py@b5fc3db · GitHub
[go: up one dir, main page]
Skip to content

Commit b5fc3db

Browse files
jonmmeasejonmmease
committed
Merge remote-tracking branch 'origin/master' into kaleido
2 parents 011ec72 + 29eee77 commit b5fc3db

File tree

18 files changed

+261
-22
lines changed

18 files changed

+261
-22
lines changed

‎CHANGELOG.md

Lines changed: 17 additions & 2 deletions
< 9E7A /table>

‎doc/python/facet-plots.md

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,25 @@
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-
## [4.9.0] - ???
5+
6+
## [4.9.0] - unreleased
67

78
### Added
8-
- Added image export support using Kaleido. The image export backend can be configured using the new `engine` argument to `plotly.io.to_image` and `plotly.io.write_image`. The `engine` argument may be set to `"kaleido"`, `"orca"`, or `"auto"`. The default is `engine="auto"`, in which case the Kaleido backend is enabled if the `kaleido` package from PyPI is installed, otherwise Orca is used. ([#2613](https://github.com/plotly/plotly.py/pull/2613)).
9+
10+
- Added image export support using Kaleido. The image export backend can be configured using the new `engine` argument to `plotly.io.to_image` and `plotly.io.write_image`. The `engine` argument may be set to `"kaleido"`, `"orca"`, or `"auto"`. The default is `engine="auto"`, in which case the Kaleido backend is enabled if the `kaleido` package from PyPI is installed, otherwise Orca is used. ([#2613](https://github.com/plotly/plotly.py/pull/2613)).
11+
- `px.NO_COLOR` constant to override wide-form color assignment in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
12+
- `facet_row_spacing` and `facet_col_spacing` added to Plotly Express cartesian 2d functions ([#2614](https://github.com/plotly/plotly.py/pull/2614))
13+
14+
### Fixed
15+
16+
- trendline traces are now of type `scattergl` when `render_mode="webgl"` in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
17+
18+
### Updated
19+
20+
- Added all cartesian-2d Plotly Express functions, plus `imshow` to Pandas backend with `kind` option
21+
- `plotly.express.imshow` now uses data frame index and columns names and values to populate axis parameters by default ([#2539](https://github.com/plotly/plotly.py/pull/2539))
22+
23+
924

1025
## [4.8.2] - 2020-06-26
1126

Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ jupyter:
66
extension: .md
77
format_name: markdown
88
format_version: '1.2'
9-
jupytext_version: 1.3.4
9+
jupytext_version: 1.4.2
1010
kernelspec:
1111
display_name: Python 3
1212
language: python
@@ -20,7 +20,7 @@ jupyter:
2020
name: python
2121
nbconvert_exporter: python
2222
pygments_lexer: ipython3
23-
version: 3.7.0
23+
version: 3.7.7
2424
plotly:
2525
description: How to make Facet and Trellis Plots in Python with Plotly.
2626
display_as: statistical
@@ -103,7 +103,7 @@ fig.show()
103103

104104
### Customize Subplot Figure Titles
105105

106-
Since subplot figure F438 titles are [annotations](https://plotly.com/python/text-and-annotations/#simple-annotation), you can use the `for_each_annotation` function to customize them.
106+
Since subplot figure titles are [annotations](https://plotly.com/python/text-and-annotations/#simple-annotation), you can use the `for_each_annotation` function to customize them, for example to remove the equal-sign (`=`).
107107

108108
In the following example, we pass a lambda function to `for_each_annotation` in order to change the figure subplot titles from `smoker=No` and `smoker=Yes` to just `No` and `Yes`.
109109

@@ -115,8 +115,25 @@ fig.for_each_annotation(lambda a: a.update(text=a.text.split("=")[-1]))
115115
fig.show()
116116
```
117117

118+
### Controlling Facet Spacing
119+
120+
The `facet_row_spacing` and `facet_col_spacing` arguments can be used to control the spacing between rows and columns. These values are specified in fractions of the plotting area in paper coordinates and not in pixels, so they will grow or shrink with the `width` and `height` of the figure.
121+
122+
The defaults work well with 1-4 rows or columns at the default figure size with the default font size, but need to be reduced to around 0.01 for very large figures or figures with many rows or columns. Conversely, if activating tick labels on all facets, the spacing will need to be increased.
123+
118124
```python
125+
import plotly.express as px
119126

127+
df = px.data.gapminder().query("continent == 'Africa'")
128+
129+
fig = px.line(df, x="year", y="lifeExp", facet_col="country", facet_col_wrap=7,
130+
facet_row_spacing=0.04, # default is 0.07 when facet_col_wrap is used
131+
facet_col_spacing=0.04, # default is 0.03
132+
height=600, width=800,
133+
title="Life Expectancy in Africa")
134+
fig.for_each_annotation(lambda a: a.update(text=a.text.split("=")[-1]))
135+
fig.update_yaxes(showticklabels=True)
136+
fig.show()
120137
```
121138

122139
### Synchronizing axes in subplots with `matches`
@@ -138,4 +155,4 @@ for i in range(1, 4):
138155
fig.add_trace(go.Scatter(x=x, y=np.random.random(N)), 1, i)
139156
fig.update_xaxes(matches='x')
140157
fig.show()
141-
```
158+
```

‎doc/python/heatmaps.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ jupyter:
3636

3737
### Heatmap with `plotly.express` and `px.imshow`
3838

39-
[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/). With `px.imshow`, each value of the input array is represented as a heatmap pixel.
39+
[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/). With `px.imshow`, each value of the input array or data frame is represented as a heatmap pixel.
4040

4141
For more examples using `px.imshow`, see the [tutorial on displaying image data with plotly](/python/imshow).
4242

@@ -49,6 +49,14 @@ fig = px.imshow([[1, 20, 30],
4949
fig.show()
5050
```
5151

52+
```python
53+
import plotly.express as px
54+
55+
df = px.data.medals_wide(indexed=True)
56+
fig = px.imshow(df)
57+
fig.show()
58+
```
59+
5260
### Customizing the axes and labels on a heatmap
5361

5462
You can use the `x`, `y` and `labels` arguments to customize the display of a heatmap, and use `.update_xaxes()` to move the x axis tick labels to the top:
@@ -182,4 +190,4 @@ Arrays of rasterized values build by datashader can be visualized using
182190
plotly's heatmaps, as shown in the [plotly and datashader tutorial](/python/datashader/).
183191

184192
#### Reference
185-
See https://plotly.com/python/reference/#heatmap for more information and chart attribute options!
193+
See https://plotly.com/python/reference/#heatmap for more information and chart attribute options!

‎doc/python/pandas-backend.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ fig.show()
9898

9999
### Supported Methods
100100

101-
The Plotly backend supports the following `kind`s of Pandas plots: `scatter`, `line`, `area`, `bar`, `barh`, `hist` and `box`, via the call pattern `df.plot(kind='scatter')` or `df.plot.scatter()`. These delegate to the corresponding Plotly Express functions.
101+
The Plotly backend supports the following `kind`s of Pandas plots: `scatter`, `line`, `area`, `bar`, `barh`, `hist` and `box`, via the call pattern `df.plot(kind='scatter')` or `df.plot.scatter()`. These delegate to the corresponding Plotly Express functions. In addition, the following are valid options to the `kind` argument of `df.plot()`: `violin`, `strip`, `funnel`, `density_heatmap`, `density_contour` and `imshow`, even though the call pattern `df.plot.violin()` is not supported for these kinds of charts, per the Pandas API.
102102

103103
```python
104104
import pandas as pd
@@ -198,4 +198,4 @@ fig.show()
198198

199199
### What about Cufflinks?
200200

201-
There also exists an independent third-party wrapper library around Plotly called [Cufflinks](https://github.com/santosjorge/cufflinks), which provides similar functionality (with an API closer to that of Pandas' default `matplotlib` backend) by adding a `.iplot()` method to Pandas dataframes, as it was developed before Pandas supported configurable backends. Issues and questions regarding Cufflinks should be [raised in the Cufflinks repository](https://github.com/santosjorge/cufflinks/issues/new).
201+
There also exists an independent third-party wrapper library around Plotly called [Cufflinks](https://github.com/santosjorge/cufflinks), which provides similar functionality (with an API closer to that of Pandas' default `matplotlib` backend) by adding a `.iplot()` method to Pandas dataframes, as it was developed before Pandas supported configurable backends. Issues and questions regarding Cufflinks should be [raised in the Cufflinks repository](https://github.com/santosjorge/cufflinks/issues/new).

‎doc/python/px-arguments.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ There are three common conventions for storing column-oriented data, usually in
4949
* **wide-form data** has one row per value of one of the first variable, and one column per value of the second variable. This is suitable for storing and displaying 2-dimensional data.
5050
* **mixed-form data** is a hybrid of long-form and wide-form data, with one row per value of one variable, and some columns representing values of another, and some columns representing more variables. See the [wide-form documentation](/python/wide-form/) for examples of how to use Plotly Express to visualize this kind of data.
5151

52-
Every Plotly Express function other than `imshow` can operate on long-form data, and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: `px.scatter`, `px.line`, `px.area`, `px.bar`, `px.histogram`, `px.violin`, `px.box`, `px.strip`, `px.funnel`, `px.density_heatmap` and `px.density_contour`.
52+
Every Plotly Express function can operate on long-form data (other than `px.imshow` which operates only on wide-form input), and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: `px.scatter`, `px.line`, `px.area`, `px.bar`, `px.histogram`, `px.violin`, `px.box`, `px.strip`, `px.funnel`, `px.density_heatmap` and `px.density_contour`.
5353

5454
By way of example here is the same data, represented in long-form first, and then in wide-form:
5555

@@ -241,4 +241,4 @@ fig = px.bar(df, x='year', y=gdp, color='continent', labels={'y':'log gdp'},
241241
hover_data=['country'],
242242
title='Evolution of world GDP')
243243
fig.show()
244-
```
244+
```

‎doc/python/wide-form.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ There are three common conventions for storing column-oriented data, usually in
4848
* **wide-form data** has one row per value of one of the first variable, and one column per value of the second variable. This is suitable for storing and displaying 2-dimensional data.
4949
* **mixed-form data** is a hybrid of long-form and wide-form data, with one row per value of one variable, and some columns representing values of another, and some columns representing more variables.
5050

51-
Every Plotly Express function other than `imshow` can operate on long-form data, and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: `px.scatter`, `px.line`, `px.area`, `px.bar`, `px.histogram`, `px.violin`, `px.box`, `px.strip`, `px.funnel`, `px.density_heatmap` and `px.density_contour`.
51+
Every Plotly Express function can operate on long-form data (other than `px.imshow` which operates only on wide-form input), and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: `px.scatter`, `px.line`, `px.area`, `px.bar`, `px.histogram`, `px.violin`, `px.box`, `px.strip`, `px.funnel`, `px.density_heatmap` and `px.density_contour`.
5252

5353
By way of example here is the same data, represented in long-form first, and then in wide-form:
5454

@@ -158,6 +158,16 @@ fig = px.bar(wide_df, x="nation", y=["gold", "silver", "bronze"], facet_col="var
158158
fig.show()
159159
```
160160

161+
You can also prevent `color` from getting assigned if you're mapping `variable` to some other argument:
162+
163+
```python
164+
import plotly.express as px
165+
wide_df = px.data.medals_wide(indexed=False)
166+
167+
fig = px.bar(wide_df, x="nation", y=["gold", "silver", "bronze"], facet_col="variable", color=px.NO_COLOR)
168+
fig.show()
169+
```
170+
161171
If using a data frame's named indexes, either explicitly or relying on the defaults, the row-index references (i.e. `df.index`) or column-index names (i.e. the value of `df.columns.name`) must be used:
162172

163173
```python
@@ -302,4 +312,4 @@ fig.show()
302312

303313
fig = px.box(wide_df, orientation="h")
304314
fig.show()
305-
```
315+
```

‎packages/python/plotly/plotly/__init__.py

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,20 @@ def plot(data_frame, kind, **kwargs):
8080
To activate, set pandas.options.plotting.backend="plotly"
8181
See https://github.com/pandas-dev/pandas/blob/master/pandas/plotting/__init__.py
8282
"""
83-
from .express import scatter, line, area, bar, box, histogram
83+
from .express import (
84+
scatter,
85+
line,
86+
area,
87+
bar,
88+
box,
89+
histogram,
90+
violin,
91+
strip,
92+
funnel,
93+
density_contour,
94+
density_heatmap,
95+
imshow,
96+
)
8497

8598
if kind == "scatter":
8699
new_kwargs = {k: kwargs[k] for k in kwargs if k not in ["s", "c"]}
@@ -96,9 +109,27 @@ def plot(data_frame, kind, **kwargs):
96109
if kind == "box":
97110
new_kwargs = {k: kwargs[k] for k in kwargs if k not in ["by"]}
98111
return box(data_frame, **new_kwargs)
99-
if kind in "hist":
112+
if kind in ["hist", "histogram"]:
100113
new_kwargs = {k: kwargs[k] for k in kwargs if k not in ["by", "bins"]}
101114
return histogram(data_frame, **new_kwargs)
115+
if kind == "violin":
116+
return violin(data_frame, **kwargs)
117+
if kind == "strip":
118+
return strip(data_frame, **kwargs)
119+
if kind == "funnel":
120+
return funnel(data_frame, **kwargs)
121+
if kind == "density_contour":
122+
return density_contour(data_frame, **kwargs)
123+
if kind == "density_heatmap":
124+
return density_heatmap(data_frame, **kwargs)
125+
if kind == "imshow":
126+
return imshow(data_frame, **kwargs)
127+
if kind == "heatmap":
128+
raise ValueError(
129+
"kind='heatmap' not supported plotting.backend='plotly'. "
130+
"Please use kind='imshow' or kind='density_heatmap'."
131+
)
132+
102133
raise NotImplementedError(
103134
"kind='%s' not yet supported for plotting.backend='plotly'" % kind
104135
)

‎packages/python/plotly/plotly/express/__init__.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@
5353
set_mapbox_access_token,
5454
defaults,
5555
get_trendline_results,
56+
NO_COLOR,
5657
)
5758

5859
from ._special_inputs import IdentityMap, Constant, Range # noqa: F401
@@ -100,4 +101,5 @@
100101
"IdentityMap",
101102
"Constant",
102103
"Range",
104+
"NO_COLOR",
103105
]

‎packages/python/plotly/plotly/express/_chart_types.py

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ def scatter(
2323
facet_row=None,
2424
facet_col=None,
2525
facet_col_wrap=0,
26+
facet_row_spacing=None,
27+
facet_col_spacing=None,
2628
error_x=None,
2729
error_x_minus=None,
2830
error_y=None,
@@ -74,6 +76,8 @@ def density_contour(
7476
facet_row=None,
7577
facet_col=None,
7678
facet_col_wrap=0,
79+
facet_row_spacing=None,
80+
facet_col_spacing=None,
7781
hover_name=None,
7882
hover_data=None,
7983
animation_frame=None,
@@ -141,6 +145,8 @@ def density_heatmap(
141145
facet_row=None,
142146
facet_col=None,
143147
facet_col_wrap=0,
148+
facet_row_spacing=None,
149+
facet_col_spacing=None,
144150
hover_name=None,
145151
hover_data=None,
146152
animation_frame=None,
@@ -213,6 +219,8 @@ def line(
213219
facet_row=None,
214220
facet_col=None,
215221
facet_col_wrap=0,
222+
facet_row_spacing=None,
223+
facet_col_spacing=None,
216224
error_x=None,
217225
error_x_minus=None,
218226
error_y=None,
@@ -260,6 +268,8 @@ def area(
260268
facet_row=None,
261269
facet_col=None,
262270
facet_col_wrap=0,
271+
facet_row_spacing=None,
272+
facet_col_spacing=None,
263273
animation_frame=None,
264274
animation_group=None,
265275
category_orders={},
@@ -301,6 +311,8 @@ def bar(
301311
facet_row=None,
302312
facet_col=None,
303313
facet_col_wrap=0,
314+
facet_row_spacing=None,
315+
facet_col_spacing=None,
304316
hover_name=None,
305317
hover_data=None,
306318
custom_data=None,
@@ -353,6 +365,8 @@ def histogram(
353365
facet_row=None,
354366
facet_col=None,
355367
facet_col_wrap=0,
368+
facet_row_spacing=None,
369+
facet_col_spacing=None,
356370
hover_name=None,
357371
hover_data=None,
358372
animation_frame=None,
@@ -417,6 +431,8 @@ def violin(
417431
facet_row=None,
418432
facet_col=None,
419433
facet_col_wrap=0,
434+
facet_row_spacing=None,
435+
facet_col_spacing=None,
420436
hover_name=None,
421437
hover_data=None,
422438
custom_data=None,
@@ -464,6 +480,8 @@ def box(
464480
facet_row=None,
465481
facet_col=None,
466482
facet_col_wrap=0,
483+
facet_row_spacing=None,
484+
facet_col_spacing=None,
467485
hover_name=None,
468486
hover_data=None,
469487
custom_data=None,
@@ -514,6 +532,8 @@ def strip(
514532
facet_row=None,
515533
facet_col=None,
516534
facet_col_wrap=0,
535+
facet_row_spacing=None,
536+
facet_col_spacing=None,
517537
hover_name=None,
518538
hover_data=None,
519539
custom_data=None,
@@ -1398,6 +1418,8 @@ def funnel(
13981418
facet_row=None,
13991419
facet_col=None,
14001420
facet_col_wrap=0,
1421+
facet_row_spacing=None,
1422+
facet_col_spacing=None,
14011423
hover_name=None,
14021424
hover_data=None,
14031425
custom_data=None,

0 commit comments

Comments
 (0)
0