0
# Themes and Styling
1

2
Themes control the non-data aspects of your plot including colors, fonts, grid lines, backgrounds, and overall appearance. Plotnine provides built-in themes for common styles and comprehensive theming functions for fine-grained customization. Theme elements allow precise control over every visual aspect of your plots.
3

4
## Capabilities
5

6
### Built-in Themes
7

8
Ready-to-use themes that provide consistent, professional styling for different contexts.
9

10
```python { .api }
11
def theme_gray():
12
    """
13
    Default gray theme with gray background and white grid lines.
14
    
15
    Professional appearance suitable for most contexts.
16
    """
17

18
def theme_grey():
19
    """
20
    Alias for theme_gray() (British spelling).
21
    """
22

23
def theme_bw():
24
    """
25
    Black and white theme with white background and gray grid lines.
26
    
27
    Clean, high-contrast appearance ideal for publications.
28
    """
29

30
def theme_minimal():
31
    """
32
    Minimal theme with white background and minimal grid lines.
33
    
34
    Clean, modern appearance that emphasizes the data.
35
    """
36

37
def theme_classic():
38
    """
39
    Classic theme with white background and no grid lines.
40
    
41
    Traditional statistical plot appearance.
42
    """
43

44
def theme_void():
45
    """
46
    Empty theme with no background, grid, or axes.
47
    
48
    Useful for specialized plots or custom annotations.
49
    """
50

51
def theme_dark():
52
    """
53
    Dark theme with dark background and light text.
54
    
55
    Suitable for presentations and digital displays.
56
    """
57

58
def theme_light():
59
    """
60
    Light theme with light gray background.
61
    
62
    Soft appearance that reduces visual fatigue.
63
    """
64

65
def theme_linedraw():
66
    """
67
    Theme with black lines and white background.
68
    
69
    High contrast with prominent grid lines and axes.
70
    """
71
```
72

73
### Style-Specific Themes
74

75
Themes that emulate popular visualization styles and publications.
76

77
```python { .api }
78
def theme_matplotlib():
79
    """
80
    Theme that mimics matplotlib's default style.
81
    
82
    Familiar appearance for matplotlib users.
83
    """
84

85
def theme_seaborn():
86
    """
87
    Theme inspired by seaborn's default style.
88
    
89
    Modern statistical visualization appearance.
90
    """
91

92
def theme_538():
93
    """
94
    Theme inspired by FiveThirtyEight website style.
95
    
96
    Bold, journalistic appearance with strong grid lines.
97
    """
98

99
def theme_tufte():
100
    """
101
    Theme inspired by Edward Tufte's principles.
102
    
103
    Minimalist design that maximizes data-ink ratio.
104
    """
105

106
def theme_xkcd():
107
    """
108
    Theme that mimics hand-drawn/XKCD comic style.
109
    
110
    Playful, informal appearance with irregular lines.
111
    """
112
```
113

114
### Theme Customization Functions
115

116
Functions for modifying and managing themes globally and locally.
117

118
```python { .api }
119
def theme(**kwargs):
120
    """
121
    Customize theme elements.
122
    
123
    Parameters accept theme element objects or None to remove elements.
124
    
125
    Text elements:
126
    - plot_title: plot title appearance
127
    - plot_subtitle: plot subtitle appearance  
128
    - plot_caption: plot caption appearance
129
    - axis_title: axis title appearance
130
    - axis_title_x, axis_title_y: specific axis titles
131
    - axis_text: axis tick labels
132
    - axis_text_x, axis_text_y: specific axis text
133
    - legend_title: legend title appearance
134
    - legend_text: legend text appearance
135
    - strip_text: facet strip text
136
    - strip_text_x, strip_text_y: specific strip text
137
    
138
    Line elements:
139
    - axis_line: axis lines
140
    - axis_line_x, axis_line_y: specific axis lines
141
    - axis_ticks: axis tick marks
142
    - axis_ticks_x, axis_ticks_y: specific axis ticks
143
    - panel_grid: panel grid lines
144
    - panel_grid_major, panel_grid_minor: major/minor grid
145
    - panel_grid_major_x, panel_grid_major_y: specific major grid
146
    - panel_grid_minor_x, panel_grid_minor_y: specific minor grid
147
    
148
    Rectangle elements:
149
    - plot_background: entire plot background
150
    - panel_background: plot panel background
151
    - legend_background: legend background
152
    - legend_key: legend key background
153
    - strip_background: facet strip background
154
    
155
    Spacing and positioning:
156
    - legend_position: legend position ('right', 'left', 'top', 'bottom', 'none')
157
    - legend_direction: legend direction ('horizontal', 'vertical')
158
    - legend_justification: legend anchor point
159
    - legend_margin: space around legend
160
    - panel_spacing: space between panels
161
    - plot_margin: space around entire plot
162
    """
163

164
def theme_get():
165
    """
166
    Get the current global theme.
167
    
168
    Returns:
169
    Current theme object
170
    """
171

172
def theme_set(new_theme):
173
    """
174
    Set a new global theme.
175
    
176
    Parameters:
177
    - new_theme: theme object to set as global default
178
    
179
    Returns:
180
    Previous theme object
181
    """
182

183
def theme_update(**kwargs):
184
    """
185
    Update the current global theme.
186
    
187
    Parameters:
188
    - **kwargs: theme elements to modify
189
    
190
    Returns:
191
    Updated theme object
192
    """
193
```
194

195
### Theme Elements
196

197
Building blocks for creating custom theme specifications.
198

199
```python { .api }
200
def element_text(family=None, style=None, colour=None, size=None, hjust=None,
201
                 vjust=None, angle=None, lineheight=None, color=None, **kwargs):
202
    """
203
    Text element for theme customization.
204
    
205
    Parameters:
206
    - family: str, font family
207
    - style: str, font style ('normal', 'italic')
208
    - colour/color: str, text color
209
    - size: float, text size in points
210
    - hjust: float, horizontal justification (0=left, 0.5=center, 1=right)
211
    - vjust: float, vertical justification (0=bottom, 0.5=middle, 1=top)
212
    - angle: float, text rotation angle in degrees
213
    - lineheight: float, line spacing multiplier
214
    - **kwargs: additional matplotlib text properties
215
    """
216

217
def element_line(colour=None, size=None, linetype=None, color=None, **kwargs):
218
    """
219
    Line element for theme customization.
220
    
221
    Parameters:
222
    - colour/color: str, line color
223
    - size: float, line width in points
224
    - linetype: str, line style ('solid', 'dashed', 'dotted', etc.)
225
    - **kwargs: additional matplotlib line properties
226
    """
227

228
def element_rect(fill=None, colour=None, size=None, linetype=None, color=None,
229
                 **kwargs):
230
    """
231
    Rectangle element for theme customization.
232
    
233
    Parameters:
234
    - fill: str, fill color
235
    - colour/color: str, border color
236
    - size: float, border width
237
    - linetype: str, border line style
238
    - **kwargs: additional matplotlib patch properties
239
    """
240

241
def element_blank():
242
    """
243
    Blank element that removes the theme component entirely.
244
    
245
    Use this to hide specific plot elements.
246
    """
247
```
248

249
## Usage Patterns
250

251
### Applying Built-in Themes
252
```python
253
# Apply a complete theme
254
ggplot(data, aes(x='x', y='y')) + \
255
    geom_point() + \
256
    theme_minimal()
257

258
# Multiple themes can be layered (later ones override earlier ones)
259
ggplot(data, aes(x='x', y='y')) + \
260
    geom_point() + \
261
    theme_bw() + \
262
    theme(legend_position='bottom')
263
```
264

265
### Customizing Text Elements
266
```python
267
# Customize plot title and axis labels
268
ggplot(data, aes(x='x', y='y')) + \
269
    geom_point() + \
270
    theme_minimal() + \
271
    theme(
272
        plot_title=element_text(size=16, hjust=0.5, colour='blue'),
273
        axis_title=element_text(size=12, colour='darkgray'),
274
        axis_text=element_text(size=10, angle=45)
275
    )
276
```
277

278
### Customizing Backgrounds and Grid Lines
279
```python
280
# Custom panel appearance
281
ggplot(data, aes(x='x', y='y')) + \
282
    geom_point() + \
283
    theme(
284
        panel_background=element_rect(fill='lightgray'),
285
        panel_grid_major=element_line(colour='white', size=0.5),
286
        panel_grid_minor=element_blank(),
287
        plot_background=element_rect(fill='white', colour='black', size=1)
288
    )
289
```
290

291
### Legend Customization
292
```python
293
# Control legend appearance and position
294
ggplot(data, aes(x='x', y='y', color='group')) + \
295
    geom_point() + \
296
    theme(
297
        legend_position='bottom',
298
        legend_direction='horizontal',
299
        legend_background=element_rect(fill='lightblue', colour='black'),
300
        legend_title=element_text(size=12, colour='darkblue'),
301
        legend_text=element_text(size=10)
302
    )
303

304
# Remove legend entirely
305
ggplot(data, aes(x='x', y='y', color='group')) + \
306
    geom_point() + \
307
    theme(legend_position='none')
308
```
309

310
### Removing Elements
311
```python
312
# Remove specific theme elements
313
ggplot(data, aes(x='x', y='y')) + \
314
    geom_point() + \
315
    theme_classic() + \
316
    theme(
317
        axis_line=element_blank(),      # Remove axis lines
318
        axis_ticks=element_blank(),     # Remove tick marks
319
        panel_grid=element_blank()      # Remove all grid lines
320
    )
321
```
322

323
### Facet Strip Customization
324
```python
325
# Customize facet strip appearance
326
ggplot(data, aes(x='x', y='y')) + \
327
    geom_point() + \
328
    facet_wrap('category') + \
329
    theme(
330
        strip_background=element_rect(fill='lightblue', colour='black'),
331
        strip_text=element_text(size=11, colour='darkblue', face='bold')
332
    )
333
```
334

335
### Global Theme Settings
336
```python
337
# Set a global theme for all subsequent plots
338
theme_set(theme_minimal())
339

340
# Update global theme with custom elements
341
theme_update(
342
    plot_title=element_text(hjust=0.5),
343
    legend_position='bottom'
344
)
345

346
# All plots will now use these settings by default
347
plot1 = ggplot(data1, aes(x='x', y='y')) + geom_point()
348
plot2 = ggplot(data2, aes(x='a', y='b')) + geom_line()
349
```
350

351
### Publication-Ready Themes
352
```python
353
# Clean theme for academic publications
354
publication_theme = theme_bw() + theme(
355
    text=element_text(family='Arial', size=11),
356
    plot_title=element_text(size=14, hjust=0.5),
357
    axis_title=element_text(size=12),
358
    legend_title=element_text(size=11),
359
    legend_text=element_text(size=10),
360
    strip_text=element_text(size=11),
361
    panel_grid_minor=element_blank()
362
)
363

364
ggplot(data, aes(x='x', y='y')) + \
365
    geom_point() + \
366
    publication_theme
367
```
368

369
### Presentation Themes
370
```python
371
# High-contrast theme for presentations
372
presentation_theme = theme_dark() + theme(
373
    text=element_text(colour='white', size=14),
374
    plot_title=element_text(size=18, hjust=0.5),
375
    axis_title=element_text(size=16),
376
    axis_text=element_text(size=12),
377
    legend_text=element_text(size=12),
378
    plot_background=element_rect(fill='black'),
379
    panel_background=element_rect(fill='gray20')
380
)
381
```
382

383
### Margin and Spacing Control
384
```python
385
# Control plot margins and panel spacing
386
ggplot(data, aes(x='x', y='y')) + \
387
    geom_point() + \
388
    facet_wrap('group') + \
389
    theme(
390
        plot_margin=(1, 1, 1, 1),  # top, right, bottom, left margins in cm
391
        panel_spacing=0.5,          # space between panels in cm
392
        legend_margin=10            # space around legend in points
393
    )
394
```