Skills › Scientific Agent Skills › seaborn › grids_and_levels.md

grids_and_levels.md

87 lines · skills/seaborn/references/grids_and_levels.md at 5f2bc03

1# Multi-Plot Grids, Figure-Level vs Axes-Level

3`FacetGrid`, `PairGrid`, and `JointGrid`, and how figure-level and axes-level functions

4differ in what they return and how they are composed with Matplotlib.

Multi-Plot Grids, Figure-Level vs Axes-Level

FacetGrid, PairGrid, and JointGrid, and how figure-level and axes-level functions differ in what they return and how they are composed with Matplotlib.

Raw lines 1 to 5

6## Multi-Plot Grids

8Seaborn provides grid objects for creating complex multi-panel figures:

Multi-Plot Grids

Seaborn provides grid objects for creating complex multi-panel figures:

Raw lines 6 to 9

10### FacetGrid

12Create subplots based on categorical variables. Most useful when called through figure-level functions (`relplot`, `displot`, `catplot`), but can be used directly for custom plots.

14```python

15g = sns.FacetGrid(df, col='time', row='sex', hue='smoker')

16g.map_dataframe(sns.scatterplot, x='total_bill', y='tip')

17g.add_legend()

18```

FacetGrid

Create subplots based on categorical variables. Most useful when called through figure-level functions (relplot, displot, catplot), but can be used directly for custom plots.

g = sns.FacetGrid(df, col='time', row='sex', hue='smoker')
g.map_dataframe(sns.scatterplot, x='total_bill', y='tip')
g.add_legend()

Raw lines 10 to 19

20### PairGrid

22Show pairwise relationships between all variables in a dataset.

24```python

25g = sns.PairGrid(df, hue='species')

26g.map_upper(sns.scatterplot)

27g.map_lower(sns.kdeplot)

28g.map_diag(sns.histplot)

29g.add_legend()

30```

PairGrid

Show pairwise relationships between all variables in a dataset.

g = sns.PairGrid(df, hue='species')
g.map_upper(sns.scatterplot)
g.map_lower(sns.kdeplot)
g.map_diag(sns.histplot)
g.add_legend()

Raw lines 20 to 31

32### JointGrid

34Combine bivariate plot with marginal distributions.

36```python

37g = sns.JointGrid(data=df, x='total_bill', y='tip')

38g.plot_joint(sns.scatterplot)

39g.plot_marginals(sns.histplot)

40```

JointGrid

Combine bivariate plot with marginal distributions.

g = sns.JointGrid(data=df, x='total_bill', y='tip')
g.plot_joint(sns.scatterplot)
g.plot_marginals(sns.histplot)

Raw lines 32 to 41

42## Figure-Level vs Axes-Level Functions

44Understanding this distinction is crucial for effective seaborn usage:

Figure-Level vs Axes-Level Functions

Understanding this distinction is crucial for effective seaborn usage:

Raw lines 42 to 45

46### Axes-Level Functions

47- Plot to a single matplotlib `Axes` object

48- Integrate easily into complex matplotlib figures

49- Accept `ax=` parameter for precise placement

50- Return `Axes` object

51- Examples: `scatterplot`, `histplot`, `boxplot`, `regplot`, `heatmap`

53**When to use:**

54- Building custom multi-plot layouts

55- Combining different plot types

56- Need matplotlib-level control

57- Integrating with existing matplotlib code

59```python

60fig, axes = plt.subplots(2, 2, figsize=(10, 10))

61sns.scatterplot(data=df, x='x', y='y', ax=axes[0, 0])

62sns.histplot(data=df, x='x', ax=axes[0, 1])

63sns.boxplot(data=df, x='cat', y='y', ax=axes[1, 0])

64sns.kdeplot(data=df, x='x', y='y', ax=axes[1, 1])

65```

Axes-Level Functions

Plot to a single matplotlib Axes object
Integrate easily into complex matplotlib figures
Accept ax= parameter for precise placement
Return Axes object
Examples: scatterplot, histplot, boxplot, regplot, heatmap

When to use:

Building custom multi-plot layouts
Combining different plot types
Need matplotlib-level control
Integrating with existing matplotlib code

fig, axes = plt.subplots(2, 2, figsize=(10, 10))
sns.scatterplot(data=df, x='x', y='y', ax=axes[0, 0])
sns.histplot(data=df, x='x', ax=axes[0, 1])
sns.boxplot(data=df, x='cat', y='y', ax=axes[1, 0])
sns.kdeplot(data=df, x='x', y='y', ax=axes[1, 1])

Raw lines 46 to 66

67### Figure-Level Functions

68- Manage entire figure including all subplots

69- `relplot`, `displot`, `catplot`, and `lmplot` facet via `col`/`row`; `jointplot`/`pairplot` use their own grid layouts

70- Return `FacetGrid`, `JointGrid`, or `PairGrid` objects

71- Use `height` and usually `aspect` for sizing; `jointplot` has square figure height and no `aspect`

72- Cannot be placed in existing figure

73- Examples: `relplot`, `displot`, `catplot`, `lmplot`, `jointplot`, `pairplot`

75**When to use:**

76- Faceted visualizations (small multiples)

77- Quick exploratory analysis

78- Consistent multi-panel layouts

79- Don't need to combine with other plot types

81```python

82# Automatic faceting

83sns.relplot(data=df, x='x', y='y', col='category', row='group',

84 hue='type', height=3, aspect=1.2)

85```

87For direct grids, set a shared `hue_order` and palette mapping when subsets could omit levels. Prefer `map_dataframe` for Seaborn keyword-oriented functions. See [FacetGrid](https://seaborn.pydata.org/generated/seaborn.FacetGrid.html) and [function overview](https://seaborn.pydata.org/tutorial/function_overview.html) (reviewed 2026-10-01).

Figure-Level Functions

Manage entire figure including all subplots
relplot, displot, catplot, and lmplot facet via col/row; jointplot/pairplot use their own grid layouts
Return FacetGrid, JointGrid, or PairGrid objects
Use height and usually aspect for sizing; jointplot has square figure height and no aspect
Cannot be placed in existing figure
Examples: relplot, displot, catplot, lmplot, jointplot, pairplot

When to use:

Faceted visualizations (small multiples)
Quick exploratory analysis
Consistent multi-panel layouts
Don't need to combine with other plot types

# Automatic faceting
sns.relplot(data=df, x='x', y='y', col='category', row='group',
            hue='type', height=3, aspect=1.2)

For direct grids, set a shared hue_order and palette mapping when subsets could omit levels. Prefer map_dataframe for Seaborn keyword-oriented functions. See FacetGrid and function overview (reviewed 2026-10-01).

Raw lines 67 to 87