Skip to content

Commit 327f1c7

Browse files
mwaskommwaskom
committed
Convert PairGrid docstring to notebook and update
1 parent 1b501f6 commit 327f1c7

File tree

2 files changed

+274
-92
lines changed

2 files changed

+274
-92
lines changed

‎doc/docstrings/PairGrid.ipynb‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "code",
5+
"execution_count": null,
6+
"metadata": {
7+
"tags": [
8+
"hide"
9+
]
10+
},
11+
"outputs": [],
12+
"source": [
13+
"import seaborn as sns; sns.set()\n",
14+
"import matplotlib.pyplot as plt"
15+
]
16+
},
17+
{
18+
"cell_type": "raw",
19+
"metadata": {},
20+
"source": [
21+
"Calling the constructor sets up a blank grid of subplots with each row and one column corresponding to a numeric variable in the dataset:"
22+
]
23+
},
24+
{
25+
"cell_type": "code",
26+
"execution_count": null,
27+
"metadata": {},
28+
"outputs": [],
29+
"source": [
30+
"penguins = sns.load_dataset(\"penguins\")\n",
31+
"g = sns.PairGrid(penguins)"
32+
]
33+
},
34+
{
35+
"cell_type": "raw",
36+
"metadata": {},
37+
"source": [
38+
"Passing a bivariate function to :meth:`PairGrid.map` will draw a bivariate plot on every axes:"
39+
]
40+
},
41+
{
42+
"cell_type": "code",
43+
"execution_count": null,
44+
"metadata": {},
45+
"outputs": [],
46+
"source": [
47+
"g = sns.PairGrid(penguins)\n",
48+
"g.map(sns.scatterplot)"
49+
]
50+
},
51+
{
52+
"cell_type": "raw",
53+
"metadata": {},
54+
"source": [
55+
"Passing separate functions to :meth:`PairGrid.map_diag` and :meth:`PairGrid.map_offdiag` will show each variable's marginal distribution on the diagonal:"
56+
]
57+
},
58+
{
59+
"cell_type": "code",
60+
"execution_count": null,
61+
"metadata": {},
62+
"outputs": [],
63+
"source": [
64+
"g = sns.PairGrid(penguins)\n",
65+
"g.map_diag(sns.histplot)\n",
66+
"g.map_offdiag(sns.scatterplot)"
67+
]
68+
},
69+
{
70+
"cell_type": "raw",
71+
"metadata": {},
72+
"source": [
73+
"It's also possible to use different functions on the upper and lower triangles of the plot (which are otherwise redundant):"
74+
]
75+
},
76+
{
77+
"cell_type": "code",
78+
"execution_count": null,
79+
"metadata": {},
80+
"outputs": [],
81+
"source": [
82+
"g = sns.PairGrid(penguins, diag_sharey=False)\n",
83+
"g.map_upper(sns.scatterplot)\n",
84+
"g.map_lower(sns.kdeplot)\n",
85+
"g.map_diag(sns.kdeplot)"
86+
]
87+
},
88+
{
89+
"cell_type": "raw",
90+
"metadata": {},
91+
"source": [
92+
"Or to avoid the redundancy altogether:"
93+
]
94+
},
95+
{
96+
"cell_type": "code",
97+
"execution_count": null,
98+
"metadata": {},
99+
"outputs": [],
100+
"source": [
101+
"g = sns.PairGrid(penguins, diag_sharey=False, corner=True)\n",
102+
"g.map_lower(sns.scatterplot)\n",
103+
"g.map_diag(sns.kdeplot)"
104+
]
105+
},
106+
{
107+
"cell_type": "raw",
108+
"metadata": {},
109+
"source": [
110+
"The :class:`PairGrid` constructor accepts a ``hue`` variable. This variable is passed directly to functions that understand it:"
111+
]
112+
},
113+
{
114+
"cell_type": "code",
115+
"execution_count": null,
116+
"metadata": {},
117+
"outputs": [],
118+
"source": [
119+
"g = sns.PairGrid(penguins, hue=\"species\")\n",
120+
"g.map_diag(sns.histplot)\n",
121+
"g.map_offdiag(sns.scatterplot)\n",
122+
"g.add_legend()"
123+
]
124+
},
125+
{
126+
"cell_type": "raw",
127+
"metadata": {},
128+
"source": [
129+
"But you can also pass matplotlib functions, in which case a groupby is performed internally and a separate plot is drawn for each level:"
130+
]
131+
},
132+
{
133+
"cell_type": "code",
134+
"execution_count": null,
135+
"metadata": {},
136+
"outputs": [],
137+
"source": [
138+
"g = sns.PairGrid(penguins, hue=\"species\")\n",
139+
"g.map_diag(plt.hist)\n",
140+
"g.map_offdiag(plt.scatter)\n",
141+
"g.add_legend()"
142+
]
143+
},
144+
{
145+
"cell_type": "raw",
146+
"metadata": {},
147+
"source": [
148+
"Additional semantic variables can be assigned by passing data vectors directly while mapping the function:"
149+
]
150+
},
151+
{
152+
"cell_type": "code",
153+
"execution_count": null,
154+
"metadata": {},
155+
"outputs": [],
156+
"source": [
157+
"g = sns.PairGrid(penguins, hue=\"species\")\n",
158+
"g.map_diag(sns.histplot)\n",
159+
"g.map_offdiag(sns.scatterplot, size=penguins[\"sex\"])\n",
160+
"g.add_legend(title=\"\", adjust_subtitles=True)"
161+
]
162+
},
163+
{
164+
"cell_type": "raw",
165+
"metadata": {},
166+
"source": [
167+
"When using seaborn functions that can implement a numeric hue mapping, you will want to disable mapping of the variable on the diagonal axes. Note that the ``hue`` variable is excluded from the list of variables shown by default:"
168+
]
169+
},
170+
{
171+
"cell_type": "code",
172+
"execution_count": null,
173+
"metadata": {},
174+
"outputs": [],
175+
"source": [
176+
"g = sns.PairGrid(penguins, hue=\"body_mass_g\")\n",
177+
"g.map_diag(sns.histplot, hue=None, color=\".3\")\n",
178+
"g.map_offdiag(sns.scatterplot)\n",
179+
"g.add_legend()"
180+
]
181+
},
182+
{
183+
"cell_type": "raw",
184+
"metadata": {},
185+
"source": [
186+
"The ``vars`` parameter can be used to control exactly which variables are used:"
187+
]
188+
},
189+
{
190+
"cell_type": "code",
191+
"execution_count": null,
192+
"metadata": {},
193+
"outputs": [],
194+
"source": [
195+
"variables = [\"body_mass_g\", \"bill_length_mm\", \"flipper_length_mm\"]\n",
196+
"g = sns.PairGrid(penguins, hue=\"body_mass_g\", vars=variables)\n",
197+
"g.map_diag(sns.histplot, hue=None, color=\".3\")\n",
198+
"g.map_offdiag(sns.scatterplot)\n",
199+
"g.add_legend()"
200+
]
201+
},
202+
{
203+
"cell_type": "raw",
204+
"metadata": {},
205+
"source": [
206+
"The plot need not be square: separate variables can be used to define the rows and columns:"
207+
]
208+
},
209+
{
210+
"cell_type": "code",
211+
"execution_count": null,
212+
"metadata": {},
213+
"outputs": [],
214+
"source": [
215+
"x_vars = [\"body_mass_g\", \"bill_length_mm\", \"bill_depth_mm\", \"flipper_length_mm\"]\n",
216+
"y_vars = [\"body_mass_g\"]\n",
217+
"g = sns.PairGrid(penguins, hue=\"species\", x_vars=x_vars, y_vars=y_vars)\n",
218+
"g.map_diag(sns.histplot, color=\".3\")\n",
219+
"g.map_offdiag(sns.scatterplot)\n",
220+
"g.add_legend()"
221+
]
222+
},
223+
{
224+
"cell_type": "raw",
225+
"metadata": {},
226+
"source": [
227+
"It can be useful to explore different approaches to resolving multiple distributions on the diagonal axes:"
228+
]
229+
},
230+
{
231+
"cell_type": "code",
232+
"execution_count": null,
233+
"metadata": {},
234+
"outputs": [],
235+
"source": [
236+
"g = sns.PairGrid(penguins, hue=\"species\")\n",
237+
"g.map_diag(sns.histplot, multiple=\"stack\", element=\"step\")\n",
238+
"g.map_offdiag(sns.scatterplot)\n",
239+
"g.add_legend()"
240+
]
241+
},
242+
{
243+
"cell_type": "code",
244+
"execution_count": null,
245+
"metadata": {},
246+
"outputs": [],
247+
"source": []
248+
}
249+
],
250+
"metadata": {
251+
"kernelspec": {
252+
"display_name": "seaborn-py38-latest",
253+
"language": "python",
254+
"name": "seaborn-py38-latest"
255+
},
256+
"language_info": {
257+
"codemirror_mode": {
258+
"name": "ipython",
259+
"version": 3
260+
},
261+
"file_extension": ".py",
262+
"mimetype": "text/x-python",
263+
"name": "python",
264+
"nbconvert_exporter": "python",
265+
"pygments_lexer": "ipython3",
266+
"version": "3.8.5"
267+
}
268+
},
269+
"nbformat": 4,
270+
"nbformat_minor": 4
271+
}

‎seaborn/axisgrid.py‎

Lines changed: 3 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1261,96 +1261,7 @@ def __init__(
12611261
Examples
12621262
--------
12631263
1264-
Draw a scatterplot for each pairwise relationship:
1265-
1266-
.. plot::
1267-
:context: close-figs
1268-
1269-
>>> import matplotlib.pyplot as plt
1270-
>>> import seaborn as sns; sns.set()
1271-
>>> iris = sns.load_dataset("iris")
1272-
>>> g = sns.PairGrid(iris)
1273-
>>> g = g.map(sns.scatterplot)
1274-
1275-
Show a univariate distribution on the diagonal:
1276-
1277-
.. plot::
1278-
:context: close-figs
1279-
1280-
>>> g = sns.PairGrid(iris)
1281-
>>> g = g.map_diag(plt.hist)
1282-
>>> g = g.map_offdiag(sns.scatterplot)
1283-
1284-
(It's not actually necessary to catch the return value every time,
1285-
as it is the same object, but it makes it easier to deal with the
1286-
doctests).
1287-
1288-
Color the points using a categorical variable:
1289-
1290-
.. plot::
1291-
:context: close-figs
1292-
1293-
>>> g = sns.PairGrid(iris, hue="species")
1294-
>>> g = g.map_diag(plt.hist)
1295-
>>> g = g.map_offdiag(sns.scatterplot)
1296-
>>> g = g.add_legend()
1297-
1298-
Use a different style to show multiple histograms:
1299-
1300-
.. plot::
1301-
:context: close-figs
1302-
1303-
>>> g = sns.PairGrid(iris, hue="species")
1304-
>>> g = g.map_diag(plt.hist, histtype="step", linewidth=3)
1305-
>>> g = g.map_offdiag(sns.scatterplot)
1306-
>>> g = g.add_legend()
1307-
1308-
Plot a subset of variables
1309-
1310-
.. plot::
1311-
:context: close-figs
1312-
1313-
>>> g = sns.PairGrid(iris, vars=["sepal_length", "sepal_width"])
1314-
>>> g = g.map(sns.scatterplot)
1315-
1316-
Pass additional keyword arguments to the functions
1317-
1318-
.. plot::
1319-
:context: close-figs
1320-
1321-
>>> g = sns.PairGrid(iris)
1322-
>>> g = g.map_diag(plt.hist, edgecolor="w")
1323-
>>> g = g.map_offdiag(sns.scatterplot)
1324-
1325-
Use different variables for the rows and columns:
1326-
1327-
.. plot::
1328-
:context: close-figs
1329-
1330-
>>> g = sns.PairGrid(iris,
1331-
... x_vars=["sepal_length", "sepal_width"],
1332-
... y_vars=["petal_length", "petal_width"])
1333-
>>> g = g.map(sns.scatterplot)
1334-
1335-
Use different functions on the upper and lower triangles:
1336-
1337-
.. plot::
1338-
:context: close-figs
1339-
1340-
>>> g = sns.PairGrid(iris)
1341-
>>> g = g.map_upper(sns.scatterplot)
1342-
>>> g = g.map_lower(sns.kdeplot, color="C0")
1343-
>>> g = g.map_diag(sns.kdeplot, lw=2)
1344-
1345-
Use different colors and markers for each categorical level:
1346-
1347-
.. plot::
1348-
:context: close-figs
1349-
1350-
>>> g = sns.PairGrid(iris, hue="species", palette="Set2",
1351-
... hue_kws={"marker": ["o", "s", "D"]})
1352-
>>> g = g.map(sns.scatterplot)
1353-
>>> g = g.add_legend()
1264+
.. include:: ../docstrings/PairGrid.rst
13541265
13551266
"""
13561267

@@ -1438,7 +1349,7 @@ def __init__(
14381349
self.hue_kws = hue_kws if hue_kws is not None else {}
14391350

14401351
self._orig_palette = palette
1441-
self._hue_order = hue_order
1352+
self._hue_order = hue_order
14421353
self.palette = self._get_palette(data, hue, hue_order, palette)
14431354
self._legend_data = {}
14441355

@@ -1660,7 +1571,7 @@ def _plot_bivariate(self, x_var, y_var, ax, func, kw_color, **kwargs):
16601571
else:
16611572
axes_vars = [x_var, y_var]
16621573

1663-
if self._hue_var is not None:
1574+
if self._hue_var is not None and self._hue_var not in axes_vars:
16641575
axes_vars.append(self._hue_var)
16651576

16661577
data = self.data[axes_vars]

0 commit comments

Comments
 (0)