0
# Aesthetic Mappings
1

2
Aesthetic mappings connect data variables to visual properties like position, color, size, and shape. They form the foundation of the Grammar of Graphics by defining how data is represented visually. Plotnine provides flexible mapping functions that support both direct data mapping and computed values from statistical transformations and scales.
3

4
## Capabilities
5

6
### Basic Aesthetic Mapping
7

8
The aes function creates mappings between data variables and visual aesthetics, defining how data values are converted to visual properties.
9

10
```python { .api }
11
def aes(x=None, y=None, **kwargs):
12
    """
13
    Create aesthetic mappings between data variables and visual properties.
14
    
15
    Common aesthetic parameters:
16
    - x, y: str, column names for position aesthetics
17
    - color/colour: str, column name for color aesthetic
18
    - fill: str, column name for fill color aesthetic  
19
    - size: str, column name for size aesthetic
20
    - alpha: str, column name for transparency aesthetic
21
    - shape: str, column name for point shape aesthetic
22
    - linetype: str, column name for line type aesthetic
23
    - stroke: str, column name for stroke width aesthetic
24
    - group: str, column name for grouping aesthetic
25
    
26
    Returns:
27
    aes object (extends dict) containing aesthetic mappings
28
    """
29
```
30

31
Usage example:
32
```python
33
from plotnine import ggplot, aes, geom_point
34
import pandas as pd
35

36
data = pd.DataFrame({
37
    'x': [1, 2, 3, 4, 5],
38
    'y': [2, 5, 3, 8, 7], 
39
    'color_var': ['A', 'B', 'A', 'B', 'A'],
40
    'size_var': [1, 3, 2, 4, 2]
41
})
42

43
# Basic position mapping
44
ggplot(data, aes(x='x', y='y'))
45

46
# Multiple aesthetic mappings
47
ggplot(data, aes(x='x', y='y', color='color_var', size='size_var'))
48
```
49

50
### Computed Value Mappings
51

52
Functions for mapping to values computed during the plotting process, allowing access to statistical transformations and scale mappings.
53

54
```python { .api }
55
def after_stat(x):
56
    """
57
    Reference values computed by statistical transformations.
58
    
59
    Parameters:
60
    - x: str, name of computed statistic
61
    
62
    Common computed statistics:
63
    - count: number of observations
64
    - density: density values
65
    - prop: proportions  
66
    - level: contour levels
67
    - quantile: quantile values
68
    
69
    Returns:
70
    after_stat object for use in aesthetic mappings
71
    """
72

73
def after_scale(x):
74
    """
75
    Reference values after scale transformation.
76
    
77
    Parameters:
78
    - x: str, name of aesthetic after scaling
79
    
80
    Returns:
81
    after_scale object for use in aesthetic mappings
82
    """
83

84
def stage(start=None, after_stat=None, after_scale=None):
85
    """
86
    Control evaluation timing of aesthetic mappings.
87
    
88
    Parameters:
89
    - start: expression evaluated on original data
90
    - after_stat: expression evaluated after statistical transformation
91
    - after_scale: expression evaluated after scale transformation
92
    
93
    Returns:
94
    stage object that evaluates expressions at appropriate times
95
    """
96
```
97

98
Usage examples:
99
```python
100
# Map fill to computed count in histogram
101
ggplot(data, aes(x='value')) + geom_histogram(aes(fill=after_stat('count')))
102

103
# Map color to density values
104
ggplot(data, aes(x='x', y='y')) + geom_density_2d(aes(color=after_stat('level')))
105

106
# Access scaled values
107
ggplot(data, aes(x='x', y='y')) + geom_point(aes(size=after_scale('x')))
108

109
# Stage different computations
110
ggplot(data, aes(x='value')) + geom_histogram(
111
    aes(fill=stage(start='group', after_stat='count'))
112
)
113
```
114

115
## Common Aesthetics
116

117
### Position Aesthetics
118
```python
119
# Primary position
120
aes(x='column_name', y='column_name')
121

122
# Secondary position (for range geoms)
123
aes(xmin='min_col', xmax='max_col', ymin='min_col', ymax='max_col')
124

125
# Positioning for specific geoms
126
aes(xend='end_x', yend='end_y')  # For segments
127
aes(slope='slope_col', intercept='intercept_col')  # For ablines
128
```
129

130
### Color and Fill Aesthetics
131
```python
132
# Color (for points, lines, text)
133
aes(color='group_column')
134
aes(colour='group_column')  # British spelling also supported
135

136
# Fill (for areas, bars, polygons)
137
aes(fill='category_column')
138

139
# Both color and fill
140
aes(color='group', fill='category')
141
```
142

143
### Size and Shape Aesthetics
144
```python
145
# Size (for points and lines)
146
aes(size='numeric_column')
147

148
# Shape (for points)
149
aes(shape='category_column')
150

151
# Stroke width
152
aes(stroke='width_column')
153
```
154

155
### Transparency and Line Aesthetics
156
```python
157
# Alpha (transparency)
158
aes(alpha='transparency_column')
159

160
# Line type
161
aes(linetype='line_category')
162

163
# Grouping (important for line plots)
164
aes(group='grouping_column')
165
```
166

167
## Usage Patterns
168

169
### Global vs Local Aesthetics
170
```python
171
# Global aesthetics (apply to all layers)
172
ggplot(data, aes(x='x', y='y', color='group')) + \
173
    geom_point() + \
174
    geom_line()
175

176
# Local aesthetics (apply to specific layer)
177
ggplot(data, aes(x='x', y='y')) + \
178
    geom_point(aes(color='group')) + \
179
    geom_line(color='blue')  # Fixed value, not mapped
180
```
181

182
### Mapping vs Setting Values
183
```python
184
# Mapping variable to aesthetic (inside aes())
185
ggplot(data, aes(x='x', y='y')) + geom_point(aes(color='group'))
186

187
# Setting fixed value (outside aes())
188
ggplot(data, aes(x='x', y='y')) + geom_point(color='blue', size=3)
189

190
# Mixed approach
191
ggplot(data, aes(x='x', y='y')) + geom_point(aes(color='group'), size=3)
192
```
193

194
### Statistical Aesthetic Mappings
195
```python
196
# Histogram with fill mapped to computed count
197
ggplot(data, aes(x='value')) + \
198
    geom_histogram(aes(fill=after_stat('count')), bins=20)
199

200
# Bar plot with proportion instead of count
201
ggplot(data, aes(x='category')) + \
202
    geom_bar(aes(y=after_stat('prop')))
203

204
# Density plot with color mapped to computed density
205
ggplot(data, aes(x='value')) + \
206
    geom_density(aes(color=after_stat('density')))
207
```
208

209
### Expression-Based Mappings
210
```python
211
# Transform data in aesthetic mapping
212
ggplot(data, aes(x='x', y='y**2'))  # Square the y values
213

214
# Conditional mapping
215
ggplot(data, aes(x='x', y='y', color='value > 5'))
216

217
# String concatenation
218
ggplot(data, aes(x='x', y='y', label='name + ": " + str(value)'))
219
```