0
# Visualization Grammar
1
2
Core Vega grammar components for building custom visualizations. These classes provide direct access to the underlying Vega specification elements, enabling full control over visualization structure and behavior.
3
4
## Capabilities
5
6
### Visualization Container
7
8
The top-level container class that holds the complete Vega specification and manages all visualization components.
9
10
```python { .api }
11
class Visualization(GrammarClass):
12
"""Visualization container class for complete Vega specifications"""
13
14
def __init__(self, *args, **kwargs):
15
"""
16
Initialize a Visualization
17
18
Sets data, marks, scales, and axes properties to empty KeyedLists
19
if not defined by arguments. Legends are set to empty list.
20
"""
21
22
def to_json(self):
23
"""
24
Export complete Vega specification as JSON
25
26
Returns:
27
str: JSON string containing complete Vega specification
28
"""
29
30
@property
31
def data(self):
32
"""KeyedList of Data objects (keyed by 'name')"""
33
34
@property
35
def scales(self):
36
"""KeyedList of Scale objects (keyed by 'name')"""
37
38
@property
39
def marks(self):
40
"""KeyedList of Mark objects (keyed by 'type')"""
41
42
@property
43
def axes(self):
44
"""KeyedList of Axis objects (keyed by 'type')"""
45
46
@property
47
def legends(self):
48
"""List of Legend objects"""
49
```
50
51
### Scales
52
53
Maps data values to visual properties like position, color, and size. Supports all Vega scale types with comprehensive configuration options.
54
55
```python { .api }
56
class Scale(GrammarClass):
57
"""Definitions for mapping from data space to visual space"""
58
59
@property
60
def name(self):
61
"""
62
Unique name for the scale
63
64
Returns:
65
str: Scale name used for referencing by other components
66
"""
67
68
@property
69
def type(self):
70
"""
71
Type of the scale
72
73
Valid types:
74
- 'ordinal': Ordinal scale for categorical data
75
- 'linear': Linear scale for continuous quantitative data
76
- 'log': Logarithmic scale
77
- 'pow': Power scale with configurable exponent
78
- 'sqrt': Square root scale (power scale with exponent 0.5)
79
- 'quantile': Quantile scale for statistical distributions
80
- 'quantize': Quantizing scale for binning continuous data
81
- 'threshold': Threshold scale for custom breakpoints
82
83
Returns:
84
str: Scale type name
85
"""
86
87
@property
88
def domain(self):
89
"""
90
Input domain for the scale
91
92
Can be:
93
- DataRef object referencing data fields
94
- List of explicit values
95
- Dict with min/max values for continuous scales
96
97
Returns:
98
DataRef, list, or dict: Domain specification
99
"""
100
101
@property
102
def range(self):
103
"""
104
Output range for the scale
105
106
Can be:
107
- List of explicit output values
108
- String specifying range type ('width', 'height', 'category10', etc.)
109
- Dict with min/max values
110
111
Returns:
112
list, str, or dict: Range specification
113
"""
114
115
@property
116
def reverse(self):
117
"""Whether to reverse the scale output (bool, default False)"""
118
119
@property
120
def round(self):
121
"""Whether to round scale output to integers (bool, default False)"""
122
```
123
124
### Marks
125
126
Visual mark definitions that render data as geometric shapes and graphical elements.
127
128
```python { .api }
129
class Mark(GrammarClass):
130
"""Visual mark definitions for rendering data"""
131
132
@property
133
def type(self):
134
"""
135
Type of mark to render
136
137
Valid types:
138
- 'rect': Rectangles (for bar charts, heatmaps)
139
- 'symbol': Symbols/points (for scatter plots)
140
- 'line': Lines (for line charts)
141
- 'area': Filled areas (for area charts)
142
- 'arc': Arcs (for pie charts)
143
- 'text': Text labels
144
- 'path': Custom paths
145
- 'image': Images
146
- 'group': Grouped marks
147
148
Returns:
149
str: Mark type name
150
"""
151
152
@property
153
def from_(self):
154
"""
155
Data source reference for the mark
156
157
Returns:
158
MarkRef: Reference to data source and transforms
159
"""
160
161
@property
162
def properties(self):
163
"""
164
Visual properties for different mark states
165
166
Returns:
167
MarkProperties: Properties for enter, exit, update, hover states
168
"""
169
170
@property
171
def key(self):
172
"""Key field for object constancy during updates (str or None)"""
173
174
@property
175
def delay(self):
176
"""Animation delay specification (ValueRef or None)"""
177
178
@property
179
def ease(self):
180
"""Animation easing function (str or None)"""
181
182
class MarkRef(GrammarClass):
183
"""Data source references for marks"""
184
185
@property
186
def data(self):
187
"""Name of the source Data (str)"""
188
189
@property
190
def transform(self):
191
"""List of Transform objects to apply to data (list)"""
192
```
193
194
### Axes
195
196
Visual axis definitions for interpreting marks and providing coordinate system context.
197
198
```python { .api }
199
class Axis(GrammarClass):
200
"""Definitions for visualization axes"""
201
202
@property
203
def type(self):
204
"""
205
Type of axis
206
207
Valid values: 'x' or 'y'
208
209
Returns:
210
str: Axis type
211
"""
212
213
@property
214
def scale(self):
215
"""
216
Name of the scale this axis represents
217
218
Returns:
219
str: Scale name reference
220
"""
221
222
@property
223
def orient(self):
224
"""
225
Axis orientation
226
227
Valid values: 'top', 'bottom', 'left', 'right'
228
229
Returns:
230
str: Orientation specification
231
"""
232
233
@property
234
def title(self):
235
"""Axis title text (str or None)"""
236
237
@property
238
def titleOffset(self):
239
"""Offset for axis title positioning (int or None)"""
240
241
@property
242
def format(self):
243
"""Number/date format string for axis labels (str or None)"""
244
245
@property
246
def ticks(self):
247
"""Approximate number of tick marks (int or None)"""
248
249
@property
250
def values(self):
251
"""Explicit tick values (list or None)"""
252
253
@property
254
def subdivide(self):
255
"""Number of minor ticks between major ticks (int or None)"""
256
257
@property
258
def tickPadding(self):
259
"""Padding between ticks and labels (int or None)"""
260
261
@property
262
def tickSize(self):
263
"""Size of tick marks (int or None)"""
264
265
@property
266
def tickSizeMajor(self):
267
"""Size of major tick marks (int or None)"""
268
269
@property
270
def tickSizeMinor(self):
271
"""Size of minor tick marks (int or None)"""
272
273
@property
274
def tickSizeEnd(self):
275
"""Size of end tick marks (int or None)"""
276
277
@property
278
def offset(self):
279
"""Axis offset from chart area (int or None)"""
280
281
@property
282
def layer(self):
283
"""Rendering layer ('front' or 'back', str or None)"""
284
285
@property
286
def grid(self):
287
"""Whether to show grid lines (bool or None)"""
288
289
@property
290
def properties(self):
291
"""Axis styling properties (AxisProperties or None)"""
292
293
class AxisProperties(GrammarClass):
294
"""Styling properties for axes"""
295
296
@property
297
def major_ticks(self):
298
"""PropertySet for major tick mark styling"""
299
300
@property
301
def minor_ticks(self):
302
"""PropertySet for minor tick mark styling"""
303
304
@property
305
def labels(self):
306
"""PropertySet for axis label styling"""
307
308
@property
309
def title(self):
310
"""PropertySet for axis title styling"""
311
312
@property
313
def axis(self):
314
"""PropertySet for axis line styling"""
315
```
316
317
### Legends
318
319
Legend definitions for visualizing scales and providing data interpretation context.
320
321
```python { .api }
322
class Legend(GrammarClass):
323
"""Definition for Vega Legends"""
324
325
@property
326
def size(self):
327
"""Scale name for legend size encoding (str or None)"""
328
329
@property
330
def shape(self):
331
"""Scale name for legend shape encoding (str or None)"""
332
333
@property
334
def fill(self):
335
"""Scale name for legend fill color encoding (str or None)"""
336
337
@property
338
def stroke(self):
339
"""Scale name for legend stroke color encoding (str or None)"""
340
341
@property
342
def orient(self):
343
"""
344
Legend orientation
345
346
Valid values: 'left', 'right', 'top', 'bottom'
347
348
Returns:
349
str: Orientation specification or None
350
"""
351
352
@property
353
def title(self):
354
"""Legend title text (str or None)"""
355
356
@property
357
def format(self):
358
"""Format string for legend labels (str or None)"""
359
360
@property
361
def values(self):
362
"""Explicit legend values (list or None)"""
363
364
@property
365
def properties(self):
366
"""Legend styling properties (LegendProperties or None)"""
367
368
class LegendProperties(GrammarClass):
369
"""Styling properties for legends"""
370
371
@property
372
def title(self):
373
"""PropertySet for legend title styling"""
374
375
@property
376
def labels(self):
377
"""PropertySet for legend label styling"""
378
379
@property
380
def symbols(self):
381
"""PropertySet for legend symbol styling"""
382
383
@property
384
def gradient(self):
385
"""PropertySet for continuous color gradient styling"""
386
387
@property
388
def legend(self):
389
"""PropertySet for overall legend styling"""
390
```
391
392
## Core Grammar Classes
393
394
```python { .api }
395
class GrammarClass(object):
396
"""Base class for all Vincent grammar components"""
397
398
def to_json(self):
399
"""Export object as JSON string"""
400
401
def validate(self):
402
"""Validate object properties and structure"""
403
404
class KeyedList(list):
405
"""List subclass supporting keyed access for grammar elements"""
406
407
def __init__(self, attr_name='name'):
408
"""Initialize with attribute name for keying (str)"""
409
410
class ValidationError(Exception):
411
"""Exception raised when validation fails"""
412
413
class LoadError(Exception):
414
"""Exception raised when loading fails"""
415
```