Skip to content

Commit 7f14f65

Browse files
nicolaskruchtennicolaskruchten
committed
PX and subplots
1 parent a1d3dec commit 7f14f65

9 files changed

+193
-20
lines changed

‎doc/python/facet-plots.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@ jupyter:
3939
### Facet and Trellis Plots
4040

4141
Facet plots, also known as trellis plots or small multiples, are figures made up of multiple subplots which have the same set of axes, where each subplot shows a subset of the data. While it is straightforward to use `plotly`'s
42-
[subplot capabilities](/python/subplots/) to make such figures, it's far easier to use the built-in `facet_row` and `facet_col` arguments in the various [Plotly Express](/python/plotly-express/) functions.
42+
[subplot capabilities](/python/subplots/) to make such figures, it's far easier to use the built-in `facet_row` and `facet_col` arguments in the various Plotly Express functions.
43+
44+
[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/).
4345

4446
### Scatter Plot Column Facets
4547

‎doc/python/graphing-multiple-chart-types.md

+27-4
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ jupyter:
55
text_representation:
66
extension: .md
77
format_name: markdown
8-
format_version: '1.1'
9-
jupytext_version: 1.1.7
8+
format_version: '1.2'
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.2
23+
version: 3.7.7
2424
plotly:
2525
description: How to design figures with multiple chart types in python.
2626
display_as: file_settings
@@ -33,6 +33,29 @@ jupyter:
3333
thumbnail: thumbnail/multiple-chart-type.jpg
3434
---
3535

36+
### Chart Types versus Trace Types
37+
38+
Plotly's [figure data structure](/python/figure-structure/) supports defining [subplots](/python/subplots/) of [various types](/python/mixed-subplots/) (e.g. [cartesian](/python/axes/), [polar](/python/polar-chart/), [3-dimensional](/python/3d-charts/), [maps](/python/maps/) etc) with attached traces of [various compatible types](/python/figure-structure/) (e.g. scatter, bar, choropleth, surface etc). This means that **Plotly figures are not constrained to representing a fixed set of "chart types"** such as scatter plots only or bar charts only or line charts only: any subplot can contain multiple traces of different types.
39+
40+
41+
### Multiple Trace Types with Plotly Express
42+
43+
[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/).
44+
45+
Plotly Express exposes a number of functions such as `px.scatter()` and `px.choropleth()` which generally speaking only contain traces of the same type, with exceptions made for [trendlines](/python/linear-fits/) and [marginal distribution plots](/python/marginal-plots/).
46+
47+
Figures produced with Plotly Express functions support the `add_trace()` method documented below, just like figures created with [graph objects](/python/graph-objects/) so it is easy to start with a Plotly Express figure containing only traces of a given type, and add traces of another type.
48+
49+
```python
50+
import plotly.express as px
51+
52+
fruits = ["apples", "oranges", "bananas"]
53+
fig = px.line(x=fruits, y=[1,3,2], color=px.Constant("This year"),
54+
labels=dict(x="Fruit", y="Amount", color="Time Period"))
55+
fig.add_bar(x=fruits, y=[2,1,3], name="Last year")
56+
fig.show()
57+
```
58+
3659
#### Line Chart and a Bar Chart
3760

3861
```python
@@ -98,4 +121,4 @@ fig.show()
98121
```
99122

100123
#### Reference
101-
See https://plotly.com/python/reference/ for more information and attribute options!
124+
See https://plotly.com/python/reference/ for more information and attribute options!

‎doc/python/line-and-scatter.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ jupyter:
55
text_representation:
66
extension: .md
77
format_name: markdown
8-
format_version: '1.1'
9-
jupytext_version: 1.1.1
8+
format_version: '1.2'
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.6.8
23+
version: 3.7.7
2424
plotly:
2525
description: How to make scatter plots in Python with Plotly.
2626
display_as: basic
@@ -276,4 +276,4 @@ fig.show()
276276

277277
### Reference
278278

279-
See https://plotly.com/python/reference/#scatter or https://plotly.com/python/reference/#scattergl for more information and chart attribute options!
279+
See https://plotly.com/python/reference/#scatter or https://plotly.com/python/reference/#scattergl for more information and chart attribute options!

‎doc/python/marginal-plots.md

+122
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
jupyter:
3+
jupytext:
4+
notebook_metadata_filter: all
5+
text_representation:
6+
extension: .md
7+
format_name: markdown
8+
format_version: '1.2'
9+
jupytext_version: 1.4.2
10+
kernelspec:
11+
display_name: Python 3
12+
language: python
13+
name: python3
14+
language_info:
15+
codemirror_mode:
16+
name: ipython
17+
version: 3
18+
file_extension: .py
19+
mimetype: text/x-python
20+
name: python
21+
nbconvert_exporter: python
22+
pygments_lexer: ipython3
23+
version: 3.7.7
24+
plotly:
25+
description: How to add marginal distribution plots.
26+
display_as: statistical
27+
language: python
28+
layout: base
29+
name: Marginal Distribution Plots
30+
order: 13
31+
page_type: u-guide
32+
permalink: python/marginal-plots/
33+
thumbnail: thumbnail/figure-labels.png
34+
---
35+
36+
### Overview
37+
38+
Marginal distribution plots are small subplots above or to the right of a main plot, which show the distribution of data along only one dimension. Marginal distribution plot capabilities are built into various Plotly Express functions such as `scatter` and `histogram`. [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/).
39+
40+
### Scatter Plot Marginals
41+
42+
The `marginal_x` and `marginal_y` arguments accept one of `"histogram"`, `"rug"`, `"box"`, or `"violin"` (see also how to create [histograms](/python/histograms/), [box plots](/python/box-plots/) and [violin plots](/python/violin-plots/) as the main figure).
43+
44+
Marginal plots are linked to the main plot: try zooming or panning on the main plot.
45+
46+
Marginal plots also support hover, including per-point hover as with the rug-plot on the right: try hovering over the points on the right marginal plot.
47+
48+
```python
49+
import plotly.express as px
50+
df = px.data.iris()
51+
fig = px.scatter(df, x="sepal_length", y="sepal_width", marginal_x="histogram", marginal_y="rug")
52+
fig.show()
53+
```
54+
55+
```python
56+
import plotly.express as px
57+
df = px.data.iris()
58+
fig = px.density_heatmap(df, x="sepal_length", y="sepal_width", marginal_x="box", marginal_y="violin")
59+
fig.show()
60+
```
61+
62+
### Marginal Plots and Color
63+
64+
Marginal plots respect the `color` argument as well, and are linked to the respective legend elements. Try clicking on the legend items.
65+
66+
```python
67+
import plotly.express as px
68+
df = px.data.iris()
69+
fig = px.scatter(df, x="sepal_length", y="sepal_width", color="species",
70+
marginal_x="box", marginal_y="violin",
71+
title="Click on the legend items!")
72+
fig.show()
73+
```
74+
75+
### Marginal Plots on Histograms
76+
77+
[Histograms](/python/histograms/) are often used to show the distribution of a variable, and they also support marginal plots in Plotly Express, with the `marginal` argument:
78+
79+
```python
80+
import plotly.express as px
81+
df = px.data.iris()
82+
fig = px.histogram(df, x="sepal_length", color="species", marginal="box")
83+
fig.show()
84+
```
85+
86+
Try hovering over the rug plot points to identify individual country values in the histogram below:
87+
88+
```python
89+
import plotly.express as px
90+
df = px.data.gapminder().query("year == 2007")
91+
fig = px.histogram(df, x="lifeExp", color="continent", marginal="rug", hover_name="country",
92+
title="Hover over the rug plot!")
93+
fig.show()
94+
```
95+
96+
### Marginal Plots and Facets
97+
98+
Marginal plots can be used in conjunction with [Plotly Express facets](/python/facet-plots/) so long as they go along different directions:
99+
100+
```python
101+
import plotly.express as px
102+
df = px.data.tips()
103+
fig = px.scatter(df, x="total_bill", y="tip", color="sex", facet_col="day",
104+
marginal_x="box")
105+
fig.show()
106+
```
107+
108+
```python
109+
import plotly.express as px
110+
df = px.data.tips()
111+
fig = px.scatter(df, x="total_bill", y="tip", color="sex", facet_row="time",
112+
marginal_y="box")
113+
fig.show()
114+
```
115+
116+
```python
117+
import plotly.express as px
118+
df = px.data.tips()
119+
fig = px.histogram(df, x="total_bill", y="tip", color="sex", facet_col="day",
120+
marginal="box")
121+
fig.show()
122+
```

‎doc/python/mixed-subplots.md

+10-3
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ jupyter:
55
text_representation:
66
extension: .md
77
format_name: markdown
8-
format_version: '1.1'
9-
jupytext_version: 1.1.6
8+
format_version: '1.2'
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.3
23+
version: 3.7.7
2424
plotly:
2525
description: How to make mixed subplots in Python with Plotly.
2626
display_as: multiple_axes
@@ -33,6 +33,13 @@ jupyter:
3333
thumbnail: thumbnail/mixed_subplot.JPG
3434
---
3535

36+
### Mixed Subplots and Plotly Express
37+
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/).
39+
40+
> *Note*: At this time, Plotly Express does not support creating figures with arbitrary mixed subplots i.e. figures with subplots of different types. Plotly Express only supports [facet plots](/python/facet-plots/) and [marginal distribution subplots](/python/marginal-plots/). To make a figure with mixed subplots, use the [`make_subplots()`](/python/subplots/) function in conjunction with [graph objects](/python/graph-objects/) as documented below.
41+
42+
3643
#### Mixed Subplot
3744

3845
```python

‎doc/python/multiple-axes.md

+12-4
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ jupyter:
55
text_representation:
66
extension: .md
77
format_name: markdown
8-
format_version: '1.1'
9-
jupytext_version: 1.1.7
8+
format_version: '1.2'
9+
jupytext_version: 1.4.2
1010
kernelspec:
1111
display_name: Python 3
1212
language: python
@@ -20,9 +20,10 @@ jupyter:
2020
name: python
2121
nbconvert_exporter: python
2222
pygments_lexer: ipython3
23-
version: 3.7.2
23+
version: 3.7.7
2424
plotly:
25-
description: How to make a graph with multiple axes (dual y-axis plots, plots with secondary axes) in python.
25+
description: How to make a graph with multiple axes (dual y-axis plots, plots
26+
with secondary axes) in python.
2627
display_as: file_settings
2728
language: python
2829
layout: base
@@ -32,6 +33,13 @@ jupyter:
3233
thumbnail: thumbnail/multiple-axes.jpg
3334
---
3435

36+
### Multiple Y Axes and Plotly Express
37+
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/).
39+
40+
> *Note*: At this time, Plotly Express does not support multiple Y axes on a single figure. To make such a figure, use the [`make_subplots()`](/python/subplots/) function in conjunction with [graph objects](/python/graph-objects/) as documented below.
41+
42+
3543
#### Two Y Axes
3644

3745
```python

‎doc/python/plotly-express.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ The Plotly Express API in general offers the following features:
6767
* **Styling Control**: PX functions [read styling information from the default figure template](/python/styling-plotly-express/), and support commonly-needed [cosmetic controls like `category_orders` and `color_discrete_map`](/python/styling-plotly-express/) to precisely control categorical variables.
6868
* **Uniform Color Handling**: PX functions automatically switch between [continuous](/python/colorscales/) and [categorical color](/python/discrete-color/) based on the input type.
6969
* **Faceting**: the 2D-cartesian plotting functions support [row, column and wrapped facetting with `facet_row`, `facet_col` and `facet_col_wrap` arguments](/python/facet-plots/).
70-
* **Marginal Plots**: the 2D-cartesian plotting functions support marginal distribution plots with the `marginal`, `marginal_x` and `marginal_y` arguments.
70+
* **Marginal Plots**: the 2D-cartesian plotting functions support [marginal distribution plots](/python/marginal-plots/) with the `marginal`, `marginal_x` and `marginal_y` arguments.
7171
* **A Pandas backend**: the 2D-cartesian plotting functions are available as [a Pandas plotting backend](/python/pandas-backend/) so you can call them via `df.plot()`.
7272
* **Trendlines**: `px.scatter` supports [built-in trendlines with accessible model output](/python/linear-fits/).
7373
* **Animations**: many PX functions support [simple animation support via the `animation_frame` and `animation_group` arguments](/python/animations/).

‎doc/python/px-arguments.md

+2
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ 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](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
39+
3840
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 Pandas `DataFrame` (in either "long" or "wide" format, see below). [`px.imshow` operates on matrix-like data](/python/imshow/) you might store in a `numpy` or `xarray` array and functions like [`px.choropleth` and `px.choropleth_mapbox` can operate on geographic data](/python/maps/) of the kind you might store in a GeoPandas `GeoDataFrame`. This page details how to provide column-oriented data to most Plotly Express functions.
3941

4042

‎doc/python/subplots.md

+12-3
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.2
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 subplots in with Plotly's Python graphing library. Examples
2626
of stacked, custom-sized, gridded, and annotated subplots.
@@ -35,6 +35,15 @@ jupyter:
3535
thumbnail: thumbnail/subplots.jpg
3636
---
3737

38+
### Subplots and Plotly Express
39+
40+
[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/).
41+
42+
Plotly Express does not support arbitrary subplot capabilities, instead it supports [faceting by a given data dimension](/python/facet-plots/), and it also supports [marginal charts to display distribution information](/python/marginal-plots/).
43+
44+
This page documents the usage of the lower-level `plotly.subplots` module and the `make_subplots` function it exposes to construct figures with arbitrary subplots. **Plotly Express faceting uses `make_subplots` internally** so adding traces to Plotly Express facets works just as documented here, with `fig.add_trace(..., row=<R>, col=<C>)`.
45+
46+
3847
#### Simple Subplot
3948

4049
Figures with subplots are created using the `make_subplots` function from the `plotly.subplots` module.
@@ -579,4 +588,4 @@ All of the y-axis properties are found here: https://plotly.com/python/reference
579588
```python
580589
from plotly.subplots import make_subplots
581590
help(make_subplots)
582-
```
591+
```

0 commit comments

Comments
 (0)