0
# Plotnine
1

2
A comprehensive Python implementation of the Grammar of Graphics inspired by R's ggplot2. Plotnine enables developers and data scientists to create sophisticated data visualizations through a declarative and layered approach, building complex plots incrementally by explicitly mapping data variables to visual aesthetics and combining geometric objects, statistical transformations, coordinate systems, scales, and themes.
3

4
## Package Information
5

6
- **Package Name**: plotnine
7
- **Language**: Python
8
- **Installation**: `pip install plotnine`
9
- **Documentation**: https://plotnine.readthedocs.io/en/stable
10

11
## Core Imports
12

13
```python
14
import plotnine as p9
15
```
16

17
Most common import pattern:
18

19
```python
20
from plotnine import ggplot, aes, geom_point, theme_minimal
21
```
22

23
Full wildcard import (brings all functions into namespace):
24

25
```python
26
from plotnine import *
27
```
28

29
Sample datasets:
30

31
```python
32
from plotnine.data import mtcars, diamonds, economics
33
```
34

35
## Basic Usage
36

37
```python
38
import pandas as pd
39
from plotnine import ggplot, aes, geom_point, scale_x_continuous, theme_minimal, labs
40

41
# Create sample data
42
data = pd.DataFrame({
43
    'x': [1, 2, 3, 4, 5],
44
    'y': [2, 5, 3, 8, 7],
45
    'category': ['A', 'B', 'A', 'B', 'A']
46
})
47

48
# Create a basic scatter plot
49
plot = (ggplot(data, aes(x='x', y='y', color='category')) +
50
        geom_point(size=3) +
51
        scale_x_continuous(limits=(0, 6)) +
52
        theme_minimal() +
53
        labs(title='Basic Scatter Plot', x='X values', y='Y values'))
54

55
# Display the plot
56
print(plot)
57

58
# Save the plot
59
plot.save('my_plot.png', width=8, height=6, dpi=300)
60
```
61

62
## Architecture
63

64
Plotnine follows the Grammar of Graphics layered approach where plots are built by combining these core components:
65

66
- **Data**: The pandas DataFrame containing the data to visualize
67
- **Aesthetics (aes)**: Mappings between data variables and visual properties (x, y, color, size, etc.)
68
- **Geometries (geom_*)**: Visual representations of data (points, lines, bars, etc.)
69
- **Statistics (stat_*)**: Data transformations (binning, smoothing, summarizing)
70
- **Scales (scale_*)**: Control mappings from data space to aesthetic space
71
- **Coordinates (coord_*)**: Coordinate system transformations
72
- **Faceting (facet_*)**: Subplots based on data groupings
73
- **Themes (theme_*)**: Non-data plot appearance (colors, fonts, layout)
74

75
This modular design allows for infinite plot customization by composing these elements using the `+` operator.
76

77
## Capabilities
78

79
### Core Plot Construction
80

81
The foundation for all plotnine visualizations, including the main ggplot class, quick plotting functions, and save functionality.
82

83
```python { .api }
84
class ggplot:
85
    def __init__(self, data=None, mapping=None): ...
86

87
def qplot(x=None, y=None, data=None, facets="", margins=False, geom="auto", 
88
          xlim=None, ylim=None, log=None, main=None, xlab=None, ylab=None, 
89
          asp=None, **kwargs): ...
90

91
def ggsave(filename, plot=None, width=6.4, height=4.8, dpi=100, **kwargs): ...
92

93
def save_as_pdf_pages(plots, filename=None, **kwargs): ...
94
```
95

96
[Core Plotting](./core-plotting.md)
97

98
### Aesthetic Mappings
99

100
Map data variables to visual properties like position, color, size, and shape. Essential for connecting your data to the visual representation.
101

102
```python { .api }
103
def aes(x=None, y=None, **kwargs): ...
104

105
def after_stat(x): ...
106

107
def after_scale(x): ...
108

109
def stage(start=None, after_stat=None, after_scale=None): ...
110
```
111

112
[Aesthetic Mappings](./aesthetic-mappings.md)
113

114
### Geometric Objects
115

116
Visual representations that render your data as points, lines, bars, areas, and other shapes. Choose from over 50 geometric objects.
117

118
```python { .api }
119
def geom_point(**kwargs): ...
120
def geom_line(**kwargs): ...
121
def geom_bar(**kwargs): ...
122
def geom_histogram(**kwargs): ...
123
def geom_boxplot(**kwargs): ...
124
def geom_smooth(**kwargs): ...
125
```
126

127
[Geometric Objects](./geometric-objects.md)
128

129
### Statistical Transformations
130

131
Transform your data before visualization through binning, smoothing, density estimation, and other statistical operations.
132

133
```python { .api }
134
def stat_count(**kwargs): ...
135
def stat_bin(**kwargs): ...
136
def stat_density(**kwargs): ...
137
def stat_smooth(**kwargs): ...
138
def stat_boxplot(**kwargs): ...
139
```
140

141
[Statistical Transformations](./statistical-transformations.md)
142

143
### Scales and Axes
144

145
Control how data values map to visual properties, including axis transformations, color palettes, and aesthetic ranges.
146

147
```python { .api }
148
def scale_x_continuous(**kwargs): ...
149
def scale_y_continuous(**kwargs): ...
150
def scale_color_manual(**kwargs): ...
151
def scale_fill_gradient(**kwargs): ...
152
def xlim(*args): ...
153
def ylim(*args): ...
154
```
155

156
[Scales and Axes](./scales-and-axes.md)
157

158
### Coordinate Systems
159

160
Transform the coordinate system for specialized plot types like flipped axes, fixed aspect ratios, and polar coordinates.
161

162
```python { .api }
163
def coord_cartesian(**kwargs): ...
164
def coord_flip(**kwargs): ...
165
def coord_fixed(**kwargs): ...
166
def coord_equal(**kwargs): ...
167
def coord_trans(**kwargs): ...
168
```
169

170
[Coordinate Systems](./coordinate-systems.md)
171

172
### Faceting
173

174
Create multiple panels to show different subsets of your data based on categorical variables.
175

176
```python { .api }
177
def facet_wrap(facets, **kwargs): ...
178
def facet_grid(rows=None, cols=None, **kwargs): ...
179
def facet_null(): ...
180
```
181

182
[Faceting](./faceting.md)
183

184
### Position Adjustments
185

186
Adjust the position of geometric objects to handle overlapping data points or create specialized layouts.
187

188
```python { .api }
189
def position_identity(): ...
190
def position_dodge(**kwargs): ...
191
def position_stack(**kwargs): ...
192
def position_fill(**kwargs): ...
193
def position_jitter(**kwargs): ...
194
```
195

196
[Position Adjustments](./position-adjustments.md)
197

198
### Themes and Styling
199

200
Control the non-data aspects of your plot including colors, fonts, grid lines, and overall appearance.
201

202
```python { .api }
203
def theme(**kwargs): ...
204
def theme_minimal(): ...
205
def theme_classic(): ...
206
def theme_dark(): ...
207
def element_text(**kwargs): ...
208
def element_line(**kwargs): ...
209
```
210

211
[Themes and Styling](./themes-and-styling.md)
212

213
### Labels and Annotations
214

215
Add titles, axis labels, legends, and text annotations to enhance plot clarity and communication.
216

217
```python { .api }
218
def labs(**kwargs): ...
219
def ggtitle(title, subtitle=None): ...
220
def xlab(label): ...
221
def ylab(label): ...
222
def annotate(geom, **kwargs): ...
223
```
224

225
[Labels and Annotations](./labels-and-annotations.md)
226

227
### Guides and Legends
228

229
Control the appearance and behavior of legends, color bars, and other plot guides.
230

231
```python { .api }
232
def guides(**kwargs): ...
233
def guide_legend(**kwargs): ...
234
def guide_colorbar(**kwargs): ...
235
```
236

237
[Guides and Legends](./guides-and-legends.md)
238

239
### Watermarks
240

241
Add image watermarks to plots for branding and attribution purposes.
242

243
```python { .api }
244
def watermark(filename, xo=None, yo=None, alpha=0.5, **kwargs): ...
245
```
246

247
[Watermarks](./watermarks.md)
248

249
### Sample Datasets
250

251
Built-in datasets for examples, tutorials, and data exploration. Includes automotive, economic, biological, and statistical datasets commonly used in data visualization.
252

253
```python { .api }
254
# Automotive data
255
mtcars: pandas.DataFrame  # Motor Trend car data
256
mpg: pandas.DataFrame     # Fuel economy data
257

258
# Economic data  
259
economics: pandas.DataFrame      # US economic time series
260
economics_long: pandas.DataFrame # Same data in long format
261

262
# Jewelry data
263
diamonds: pandas.DataFrame  # ~54,000 diamond prices and attributes
264

265
# Biological data
266
penguins: pandas.DataFrame  # Palmer penguins dataset
267
msleep: pandas.DataFrame    # Mammal sleep data
268
```
269

270
[Sample Datasets](./sample-datasets.md)
271

272
## Common Data Types
273

274
```python { .api }
275
# DataFrame expected structure
276
DataFrame = pandas.DataFrame  # With columns mappable to aesthetics
277

278
# Aesthetic mapping object
279
class aes(dict):
280
    """Aesthetic mappings between data and visual properties"""
281
    
282
# Plot object
283
class ggplot:
284
    """Main plot object that supports + operator for adding layers"""
285
    
286
# Layer components
287
class geom: """Base class for geometric objects"""
288
class stat: """Base class for statistical transformations"""  
289
class scale: """Base class for scales"""
290
class coord: """Base class for coordinate systems"""
291
class facet: """Base class for faceting"""
292
class theme: """Base class for themes"""
293
```