0
# Distribution Plots
1

2
Analyze and visualize statistical distributions using histograms, kernel density estimation, empirical cumulative distribution functions, and rug plots. These functions support both univariate and bivariate distribution analysis with flexible styling and statistical options.
3

4
## Capabilities
5

6
### Figure-level Distribution Plotting
7

8
Create multi-panel figures with distribution plots across subsets of data.
9

10
```python { .api }
11
def displot(
12
    data,
13
    *,
14
    x=None,
15
    y=None,
16
    hue=None,
17
    row=None,
18
    col=None,
19
    weights=None,
20
    kind="hist",
21
    rug=False,
22
    rug_kws=None,
23
    log_scale=None,
24
    legend=True,
25
    palette=None,
26
    hue_order=None,
27
    hue_norm=None,
28
    color=None,
29
    col_wrap=None,
30
    row_order=None,
31
    col_order=None,
32
    height=5,
33
    aspect=1,
34
    facet_kws=None,
35
    **kwargs
36
):
37
    """
38
    Figure-level interface for drawing distribution plots onto a FacetGrid.
39
    
40
    Parameters:
41
    - data: DataFrame, dict, or array of data
42
    - x, y: str, names of variables in data
43
    - hue: str, grouping variable for color mapping
44
    - row, col: str, variables for faceting into subplots
45
    - kind: str, plot type ("hist", "kde", "ecdf")
46
    - rug: bool, add marginal rug plot
47
    - weights: str, variable for observation weights
48
    - height: float, height of each facet in inches
49
    - aspect: float, aspect ratio of each facet
50
    
51
    Returns:
52
    FacetGrid object
53
    """
54
```
55

56
### Histograms
57

58
Plot univariate or bivariate histograms to show data distributions.
59

60
```python { .api }
61
def histplot(
62
    data=None,
63
    *,
64
    x=None,
65
    y=None,
66
    hue=None,
67
    weights=None,
68
    stat="count",
69
    bins="auto",
70
    binwidth=None,
71
    binrange=None,
72
    discrete=None,
73
    cumulative=False,
74
    common_bins=True,
75
    common_norm=True,
76
    multiple="layer",
77
    element="bars",
78
    fill=True,
79
    shrink=1,
80
    kde=False,
81
    kde_kws=None,
82
    line_kws=None,
83
    thresh=0,
84
    pthresh=None,
85
    pmax=None,
86
    cbar=False,
87
    cbar_ax=None,
88
    cbar_kws=None,
89
    palette=None,
90
    hue_order=None,
91
    hue_norm=None,
92
    color=None,
93
    log_scale=None,
94
    legend=True,
95
    ax=None,
96
    **kwargs
97
):
98
    """
99
    Plot univariate or bivariate histograms to show distributions of datasets.
100
    
101
    Parameters:
102
    - data: DataFrame, dict, or array of data
103
    - x, y: str or array-like, input data variables
104
    - hue: str, grouping variable for color mapping
105
    - stat: str, statistic to compute ("count", "frequency", "probability", "proportion", "percent", "density")
106
    - bins: int, str, or sequence, binning specification
107
    - binwidth: float, width of bins
108
    - cumulative: bool, compute cumulative statistic
109
    - multiple: str, approach for multiple hue levels ("layer", "dodge", "stack", "fill")
110
    - element: str, visual representation ("bars", "step", "poly")
111
    - kde: bool, overlay kernel density estimate
112
    
113
    Returns:
114
    matplotlib Axes object
115
    """
116
```
117

118
### Kernel Density Estimation
119

120
Plot univariate or bivariate distributions using kernel density estimation.
121

122
```python { .api }
123
def kdeplot(
124
    data=None,
125
    *,
126
    x=None,
127
    y=None,
128
    hue=None,
129
    weights=None,
130
    palette=None,
131
    hue_order=None,
132
    hue_norm=None,
133
    color=None,
134
    fill=None,
135
    multiple="layer",
136
    common_norm=True,
137
    common_grid=False,
138
    cumulative=False,
139
    bw_method="scott",
140
    bw_adjust=1,
141
    warn_singular=True,
142
    log_scale=None,
143
    levels=10,
144
    thresh=0.05,
145
    gridsize=200,
146
    cut=3,
147
    clip=None,
148
    legend=True,
149
    cbar=False,
150
    cbar_ax=None,
151
    cbar_kws=None,
152
    ax=None,
153
    **kwargs
154
):
155
    """
156
    Plot univariate or bivariate distributions using kernel density estimation.
157
    
158
    Parameters:
159
    - data: DataFrame, dict, or array of data
160
    - x, y: str or array-like, input data variables
161
    - hue: str, grouping variable for color mapping
162
    - fill: bool, fill area under univariate curves
163
    - bw_method: str or scalar, bandwidth estimation method
164
    - bw_adjust: float, bandwidth scaling factor
165
    - levels: int or sequence, contour levels for bivariate plots
166
    - thresh: float, density threshold for contours
167
    - gridsize: int, evaluation grid size
168
    - cut: float, distance to extend beyond data extremes
169
    - clip: tuple, data range to clip density
170
    
171
    Returns:
172
    matplotlib Axes object
173
    """
174
```
175

176
### Empirical Cumulative Distribution Functions
177

178
Plot empirical cumulative distribution functions (ECDFs).
179

180
```python { .api }
181
def ecdfplot(
182
    data=None,
183
    *,
184
    x=None,
185
    y=None,
186
    hue=None,
187
    weights=None,
188
    stat="proportion",
189
    complementary=False,
190
    palette=None,
191
    hue_order=None,
192
    hue_norm=None,
193
    log_scale=None,
194
    legend=True,
195
    ax=None,
196
    **kwargs
197
):
198
    """
199
    Plot empirical cumulative distribution functions.
200
    
201
    Parameters:
202
    - data: DataFrame, dict, or array of data
203
    - x, y: str or array-like, input data variables
204
    - hue: str, grouping variable for color mapping
205
    - stat: str, statistic to compute ("proportion" or "count")
206
    - complementary: bool, plot complementary CDF (1 - CDF)
207
    - weights: str or array-like, observation weights
208
    
209
    Returns:
210
    matplotlib Axes object
211
    """
212
```
213

214
### Rug Plots
215

216
Plot marginal distributions as tick marks along axes.
217

218
```python { .api }
219
def rugplot(
220
    data=None,
221
    *,
222
    x=None,
223
    y=None,
224
    hue=None,
225
    height=0.025,
226
    expand_margins=True,
227
    palette=None,
228
    hue_order=None,
229
    hue_norm=None,
230
    legend=True,
231
    ax=None,
232
    **kwargs
233
):
234
    """
235
    Plot marginal distributions by drawing ticks along the x and y axes.
236
    
237
    Parameters:
238
    - data: DataFrame, dict, or array of data
239
    - x, y: str or array-like, input data variables
240
    - hue: str, grouping variable for color mapping
241
    - height: float, height of ticks as proportion of total
242
    - expand_margins: bool, expand axis margins to fit ticks
243
    
244
    Returns:
245
    matplotlib Axes object
246
    """
247
```
248

249
### Deprecated Distribution Plot
250

251
Legacy function for flexible univariate distribution plotting (deprecated in favor of histplot/kdeplot).
252

253
```python { .api }
254
def distplot(
255
    a,
256
    bins=None,
257
    hist=True,
258
    kde=True,
259
    rug=False,
260
    fit=None,
261
    hist_kws=None,
262
    kde_kws=None,
263
    rug_kws=None,
264
    fit_kws=None,
265
    color=None,
266
    vertical=False,
267
    norm_hist=False,
268
    axlabel=None,
269
    label=None,
270
    ax=None,
271
    x=None
272
):
273
    """
274
    DEPRECATED - Flexibly plot a univariate distribution of observations.
275
    
276
    Note: This function is deprecated. Use histplot() and/or kdeplot() instead.
277
    
278
    Parameters:
279
    - a: array-like, observed data
280
    - bins: int or sequence, histogram bins
281
    - hist: bool, plot histogram
282
    - kde: bool, plot kernel density estimate
283
    - rug: bool, plot rug plot
284
    - fit: distribution, fit parametric distribution
285
    
286
    Returns:
287
    matplotlib Axes object
288
    """
289
```
290

291
## Usage Examples
292

293
### Basic Histogram
294

295
```python
296
import seaborn as sns
297
import matplotlib.pyplot as plt
298

299
tips = sns.load_dataset("tips")
300

301
# Basic histogram
302
sns.histplot(data=tips, x="total_bill")
303
plt.show()
304
```
305

306
### Histogram with Grouping
307

308
```python
309
# Histogram with hue grouping
310
sns.histplot(data=tips, x="total_bill", hue="smoker", multiple="stack")
311
plt.show()
312
```
313

314
### Kernel Density Plot
315

316
```python
317
# KDE plot with fill
318
sns.kdeplot(data=tips, x="total_bill", fill=True)
319
plt.show()
320
```
321

322
### Bivariate Distribution
323

324
```python
325
# 2D histogram
326
sns.histplot(data=tips, x="total_bill", y="tip")
327
plt.show()
328

329
# 2D KDE with contours
330
sns.kdeplot(data=tips, x="total_bill", y="tip")
331
plt.show()
332
```
333

334
### ECDF Plot
335

336
```python
337
# Empirical cumulative distribution
338
sns.ecdfplot(data=tips, x="total_bill", hue="smoker")
339
plt.show()
340
```
341

342
### Multi-Panel Distribution Plot
343

344
```python
345
# Create subplots by time
346
sns.displot(
347
    data=tips,
348
    x="total_bill", hue="smoker",
349
    col="time", kind="hist"
350
)
351
plt.show()
352
```
353

354
### Combined Plot with Rug
355

356
```python
357
# Histogram with KDE overlay and rug plot
358
sns.histplot(data=tips, x="total_bill", kde=True)
359
sns.rugplot(data=tips, x="total_bill")
360
plt.show()
361
```