0
# Scales and Axes
1

2
Scales control how data values map to visual properties, including axis transformations, color palettes, size ranges, and aesthetic mappings. Plotnine provides comprehensive scale functions for all aesthetic types, supporting continuous and discrete data, custom color palettes, axis transformations, and fine-grained control over legends and guides.
3

4
## Capabilities
5

6
### Position Scales (X and Y Axes)
7

8
Control the mapping of data to x and y positions, including transformations, limits, and formatting.
9

10
```python { .api }
11
def scale_x_continuous(name=None, breaks=None, labels=None, limits=None,
12
                       expand=None, trans=None, **kwargs):
13
    """
14
    Continuous x-axis scale.
15
    
16
    Parameters:
17
    - name: str, axis label
18
    - breaks: list or function, axis tick positions
19
    - labels: list or function, axis tick labels
20
    - limits: tuple, axis limits (min, max)
21
    - expand: tuple, expansion around data range
22
    - trans: str or transformer, axis transformation
23
    - **kwargs: additional scale parameters
24
    """
25

26
def scale_y_continuous(name=None, breaks=None, labels=None, limits=None,
27
                       expand=None, trans=None, **kwargs):
28
    """
29
    Continuous y-axis scale.
30
    
31
    Parameters: Same as scale_x_continuous
32
    """
33

34
def scale_x_discrete(name=None, breaks=None, labels=None, limits=None,
35
                     expand=None, **kwargs):
36
    """
37
    Discrete x-axis scale.
38
    
39
    Parameters:
40
    - name: str, axis label
41
    - breaks: list, which levels to display
42
    - labels: list or dict, custom labels for levels
43
    - limits: list, order and subset of levels to display
44
    - expand: tuple, expansion around discrete values
45
    """
46

47
def scale_y_discrete(name=None, breaks=None, labels=None, limits=None,
48
                     expand=None, **kwargs):
49
    """
50
    Discrete y-axis scale.
51
    
52
    Parameters: Same as scale_x_discrete
53
    """
54
```
55

56
### Transformed Position Scales
57

58
Apply mathematical transformations to axes including logarithmic, square root, and reverse scaling.
59

60
```python { .api }
61
def scale_x_log10(name=None, **kwargs):
62
    """
63
    Log10 transformed x-axis.
64
    
65
    Applies log10 transformation with appropriate breaks and labels.
66
    """
67

68
def scale_y_log10(name=None, **kwargs):
69
    """
70
    Log10 transformed y-axis.
71
    """
72

73
def scale_x_sqrt(name=None, **kwargs):
74
    """
75
    Square root transformed x-axis.
76
    """
77

78
def scale_y_sqrt(name=None, **kwargs):
79
    """
80
    Square root transformed y-axis.
81
    """
82

83
def scale_x_reverse(name=None, **kwargs):
84
    """
85
    Reversed x-axis (high to low).
86
    """
87

88
def scale_y_reverse(name=None, **kwargs):
89
    """
90
    Reversed y-axis (high to low).
91
    """
92

93
def scale_x_symlog(name=None, **kwargs):
94
    """
95
    Symmetric log transformed x-axis.
96
    
97
    Combines linear and logarithmic scaling.
98
    """
99

100
def scale_y_symlog(name=None, **kwargs):
101
    """
102
    Symmetric log transformed y-axis.
103
    """
104
```
105

106
### Date and Time Scales
107

108
Handle temporal data with appropriate formatting and breaks.
109

110
```python { .api }
111
def scale_x_date(name=None, breaks=None, labels=None, limits=None, **kwargs):
112
    """
113
    Date x-axis scale.
114
    
115
    Parameters:
116
    - breaks: str, date_breaks format ('1 day', '2 weeks', '1 month', etc.)
117
    - labels: str or function, date label format
118
    """
119

120
def scale_y_date(name=None, breaks=None, labels=None, limits=None, **kwargs):
121
    """
122
    Date y-axis scale.
123
    """
124

125
def scale_x_datetime(name=None, breaks=None, labels=None, limits=None, **kwargs):
126
    """
127
    Datetime x-axis scale.
128
    """
129

130
def scale_y_datetime(name=None, breaks=None, labels=None, limits=None, **kwargs):
131
    """
132
    Datetime y-axis scale.
133
    """
134

135
def scale_x_timedelta(name=None, **kwargs):
136
    """
137
    Timedelta x-axis scale.
138
    """
139

140
def scale_y_timedelta(name=None, **kwargs):
141
    """
142
    Timedelta y-axis scale.
143
    """
144
```
145

146
### Color Scales
147

148
Control color mappings for both continuous and discrete data with various palette options.
149

150
```python { .api }
151
def scale_color_continuous(name=None, low=None, high=None, **kwargs):
152
    """
153
    Default continuous color scale.
154
    
155
    Parameters:
156
    - name: str, legend title
157
    - low, high: str, colors for low and high values
158
    """
159

160
def scale_color_discrete(name=None, **kwargs):
161
    """
162
    Default discrete color scale.
163
    """
164

165
def scale_color_manual(name=None, values=None, breaks=None, **kwargs):
166
    """
167
    Manual color scale with specified colors.
168
    
169
    Parameters:
170
    - values: dict or list, color mappings
171
    - breaks: list, order of legend items
172
    """
173

174
def scale_color_gradient(name=None, low='#132B43', high='#56B1F7', **kwargs):
175
    """
176
    Two-color gradient scale.
177
    
178
    Parameters:
179
    - low, high: str, endpoint colors
180
    """
181

182
def scale_color_gradient2(name=None, low='#832424', mid='white', high='#3A3A98',
183
                          midpoint=0, **kwargs):
184
    """
185
    Three-color gradient scale.
186
    
187
    Parameters:
188
    - low, mid, high: str, gradient colors
189
    - midpoint: float, data value for middle color
190
    """
191

192
def scale_color_gradientn(name=None, colors=None, values=None, **kwargs):
193
    """
194
    Multi-color gradient scale.
195
    
196
    Parameters:
197
    - colors: list, gradient colors
198
    - values: list, data values corresponding to colors (0-1 scale)
199
    """
200
```
201

202
### Color Palette Scales
203

204
Use predefined color palettes including ColorBrewer, matplotlib colormaps, and custom palettes.
205

206
```python { .api }
207
def scale_color_brewer(name=None, type='seq', palette=1, direction=1, **kwargs):
208
    """
209
    ColorBrewer color scales.
210
    
211
    Parameters:
212
    - type: str, palette type ('seq', 'div', 'qual')
213
    - palette: str or int, palette name or number
214
    - direction: int, 1 for normal, -1 for reversed
215
    """
216

217
def scale_color_hue(name=None, h=None, c=80, l=65, h_start=0, direction=1,
218
                    **kwargs):
219
    """
220
    Evenly spaced hues around color wheel.
221
    
222
    Parameters:
223
    - h: tuple, hue range in degrees
224
    - c: float, chroma (colorfulness)
225
    - l: float, luminance (lightness)
226
    - h_start: float, starting hue
227
    - direction: int, direction around color wheel
228
    """
229

230
def scale_color_grey(name=None, start=0.2, end=0.8, **kwargs):
231
    """
232
    Grayscale color palette.
233
    
234
    Parameters:
235
    - start, end: float, gray levels (0=black, 1=white)
236
    """
237

238
def scale_color_cmap(name=None, cmap=None, **kwargs):
239
    """
240
    Matplotlib colormap scale.
241
    
242
    Parameters:
243
    - cmap: str, matplotlib colormap name
244
    """
245

246
def scale_color_distiller(name=None, type='seq', palette=1, direction=1,
247
                          **kwargs):
248
    """
249
    ColorBrewer palettes for continuous data.
250
    """
251

252
def scale_color_desaturate(name=None, prop=0, **kwargs):
253
    """
254
    Desaturated color scale.
255
    
256
    Parameters:
257
    - prop: float, proportion of desaturation (0-1)  
258
    """
259
```
260

261
### Fill Scales
262

263
All color scales have corresponding fill versions for area-based geoms.
264

265
```python { .api }
266
def scale_fill_continuous(name=None, **kwargs):
267
    """Default continuous fill scale."""
268

269
def scale_fill_discrete(name=None, **kwargs):
270
    """Default discrete fill scale."""
271

272
def scale_fill_manual(name=None, values=None, **kwargs):
273
    """Manual fill scale."""
274

275
def scale_fill_gradient(name=None, low='#132B43', high='#56B1F7', **kwargs):
276
    """Two-color fill gradient."""
277

278
def scale_fill_gradient2(name=None, low='#832424', mid='white', high='#3A3A98',
279
                         midpoint=0, **kwargs):
280
    """Three-color fill gradient."""
281

282
def scale_fill_gradientn(name=None, colors=None, values=None, **kwargs):
283
    """Multi-color fill gradient."""
284

285
def scale_fill_brewer(name=None, type='seq', palette=1, direction=1, **kwargs):
286
    """ColorBrewer fill scales."""
287

288
def scale_fill_hue(name=None, **kwargs):
289
    """Hue-based fill scale."""
290

291
def scale_fill_grey(name=None, start=0.2, end=0.8, **kwargs):
292
    """Grayscale fill scale."""
293

294
def scale_fill_cmap(name=None, cmap=None, **kwargs):
295
    """Matplotlib colormap fill scale."""
296

297
def scale_fill_distiller(name=None, type='seq', palette=1, direction=1, **kwargs):
298
    """ColorBrewer continuous fill scale."""
299
```
300

301
### Size Scales
302

303
Control the mapping of data to size aesthetics for points and lines.
304

305
```python { .api }
306
def scale_size(name=None, range=None, **kwargs):
307
    """
308
    Size scale for points and lines.
309
    
310
    Parameters:
311
    - range: tuple, size range (min_size, max_size)
312
    """
313

314
def scale_size_continuous(name=None, range=None, **kwargs):
315
    """Continuous size scale."""
316

317
def scale_size_discrete(name=None, range=None, **kwargs):
318
    """Discrete size scale."""
319

320
def scale_size_manual(name=None, values=None, **kwargs):
321
    """Manual size scale."""
322

323
def scale_size_identity(name=None, **kwargs):
324
    """Identity size scale (use data values directly)."""
325

326
def scale_size_area(name=None, max_size=6, **kwargs):
327
    """
328
    Area-based size scale.
329
    
330
    Maps data to point area rather than radius.
331
    """
332

333
def scale_size_radius(name=None, range=None, **kwargs):
334
    """
335
    Radius-based size scale.
336
    
337
    Maps data to point radius (default behavior).
338
    """
339
```
340

341
### Shape and Line Type Scales
342

343
Control point shapes and line types.
344

345
```python { .api }
346
def scale_shape(name=None, **kwargs):
347
    """
348
    Shape scale for points.
349
    
350
    Maps discrete data to different point shapes.
351
    """
352

353
def scale_shape_discrete(name=None, **kwargs):
354
    """Discrete shape scale."""
355

356
def scale_shape_manual(name=None, values=None, **kwargs):
357
    """
358
    Manual shape scale.
359
    
360
    Parameters:
361
    - values: dict or list, shape mappings (use matplotlib marker codes)
362
    """
363

364
def scale_shape_identity(name=None, **kwargs):
365
    """Identity shape scale."""
366

367
def scale_linetype(name=None, **kwargs):
368
    """
369
    Line type scale.
370
    
371
    Maps discrete data to different line styles.
372
    """
373

374
def scale_linetype_discrete(name=None, **kwargs):
375
    """Discrete line type scale."""
376

377
def scale_linetype_manual(name=None, values=None, **kwargs):
378
    """
379
    Manual line type scale.
380
    
381
    Parameters:
382
    - values: dict or list, line type mappings
383
    """
384

385
def scale_linetype_identity(name=None, **kwargs):
386
    """Identity line type scale."""
387
```
388

389
### Alpha (Transparency) Scales
390

391
Control transparency mappings.
392

393
```python { .api }
394
def scale_alpha(name=None, range=None, **kwargs):
395
    """
396
    Alpha (transparency) scale.
397
    
398
    Parameters:
399
    - range: tuple, alpha range (min_alpha, max_alpha) from 0-1
400
    """
401

402
def scale_alpha_continuous(name=None, range=None, **kwargs):
403
    """Continuous alpha scale."""
404

405
def scale_alpha_discrete(name=None, range=None, **kwargs):
406
    """Discrete alpha scale."""
407

408
def scale_alpha_manual(name=None, values=None, **kwargs):
409
    """Manual alpha scale."""
410

411
def scale_alpha_identity(name=None, **kwargs):
412
    """Identity alpha scale."""
413
```
414

415
### Limit and Expansion Functions
416

417
Convenient functions for setting axis limits and controlling plot expansion.
418

419
```python { .api }
420
def xlim(*args):
421
    """
422
    Set x-axis limits.
423
    
424
    Parameters:
425
    - *args: min, max values or single tuple/list
426
    
427
    Usage: xlim(0, 10) or xlim([0, 10])
428
    """
429

430
def ylim(*args):
431
    """
432
    Set y-axis limits.
433
    
434
    Usage: ylim(0, 10) or ylim([0, 10])
435
    """
436

437
def lims(**kwargs):
438
    """
439
    Set limits for any aesthetic.
440
    
441
    Parameters:
442
    - **kwargs: aesthetic limits (x=(0, 10), y=(0, 5), color=['A', 'B'])
443
    """
444

445
def expand_limits(**kwargs):
446
    """
447
    Expand plot limits to include specific values.
448
    
449
    Parameters:
450
    - **kwargs: values to include (x=0, y=[0, 10])
451
    """
452
```
453

454
### Identity Scales
455

456
Use data values directly without transformation.
457

458
```python { .api }
459
def scale_color_identity(name=None, **kwargs):
460
    """Use data values as colors directly."""
461

462
def scale_fill_identity(name=None, **kwargs):
463
    """Use data values as fill colors directly."""
464

465
def scale_size_identity(name=None, **kwargs):
466
    """Use data values as sizes directly."""
467

468
def scale_alpha_identity(name=None, **kwargs):
469
    """Use data values as alpha values directly."""
470

471
def scale_shape_identity(name=None, **kwargs):
472
    """Use data values as shapes directly."""
473

474
def scale_linetype_identity(name=None, **kwargs):
475
    """Use data values as line types directly."""
476
```
477

478
## Usage Patterns
479

480
### Customizing Axis Appearance
481
```python
482
# Custom axis labels and limits
483
ggplot(data, aes(x='x', y='y')) + \
484
    geom_point() + \
485
    scale_x_continuous(name='Custom X Label', limits=(0, 10), 
486
                       breaks=[0, 2.5, 5, 7.5, 10]) + \
487
    scale_y_continuous(name='Custom Y Label', trans='log10')
488
```
489

490
### Color Customization
491
```python
492
# Manual color specification
493
ggplot(data, aes(x='x', y='y', color='group')) + \
494
    geom_point() + \
495
    scale_color_manual(values={'A': 'red', 'B': 'blue', 'C': 'green'})
496

497
# ColorBrewer palette
498
ggplot(data, aes(x='x', y='y', fill='category')) + \
499
    geom_point(shape='o') + \
500
    scale_fill_brewer(type='qual', palette='Set1')
501
```
502

503
### Gradient Scales
504
```python
505
# Two-color gradient
506
ggplot(data, aes(x='x', y='y', color='value')) + \
507
    geom_point() + \
508
    scale_color_gradient(low='blue', high='red')
509

510
# Three-color diverging gradient
511
ggplot(data, aes(x='x', y='y', fill='zscore')) + \
512
    geom_point(shape='s') + \
513
    scale_fill_gradient2(low='blue', mid='white', high='red', midpoint=0)
514
```
515

516
### Date and Time Axes
517
```python
518
# Date axis with custom breaks
519
ggplot(data, aes(x='date', y='value')) + \
520
    geom_line() + \
521
    scale_x_date(breaks='1 month', labels='%b %Y')
522
```