0
# Vincent
1

2
Vincent is a Python library that translates Python data structures into Vega visualization grammar. It enables developers to create interactive data visualizations by converting Python data (tuples, lists, dictionaries, and Pandas DataFrames) into Vega JSON specifications, bridging Python's data processing capabilities with JavaScript's visualization strengths.
3

4
## Package Information
5

6
- **Package Name**: vincent
7
- **Language**: Python
8
- **Installation**: `pip install vincent`
9
- **Dependencies**: pandas (required)
10

11
## Core Imports
12

13
```python
14
import vincent
15
```
16

17
Direct access to specific components:
18

19
```python
20
from vincent import (
21
    Chart, Bar, Line, Area, Scatter, StackedBar, StackedArea, 
22
    GroupedBar, Map, Pie, Word, Visualization, Data, Transform,
23
    PropertySet, ValueRef, DataRef, Scale, MarkProperties, 
24
    MarkRef, Mark, AxisProperties, Axis, initialize_notebook
25
)
26
```
27

28
## Basic Usage
29

30
```python
31
import vincent
32
import pandas as pd
33

34
# Create sample data
35
data = [10, 20, 30, 40, 50]
36

37
# Create a simple bar chart
38
bar = vincent.Bar(data)
39
bar.width = 400
40
bar.height = 200
41

42
# Output as Vega JSON specification
43
vega_spec = bar.to_json()
44

45
# For Jupyter notebooks
46
vincent.initialize_notebook()
47
bar  # Will display the visualization
48
```
49

50
Using with pandas DataFrames:
51

52
```python
53
import pandas as pd
54
import vincent
55

56
# Create DataFrame
57
df = pd.DataFrame({
58
    'x': range(10),
59
    'y': [i**2 for i in range(10)]
60
})
61

62
# Create line chart from DataFrame
63
line = vincent.Line(df, columns=['x', 'y'])
64
line.axis_titles(x='X Values', y='Y Values')
65
```
66

67
## Architecture
68

69
Vincent follows the Vega grammar specification with a hierarchical structure:
70

71
- **Visualization**: Top-level container for complete Vega specifications
72
- **Charts**: High-level chart constructors (Bar, Line, Area, etc.) that extend Visualization
73
- **Grammar Components**: Core Vega elements (Data, Scales, Marks, Axes, etc.)
74
- **Data Handling**: Automatic conversion between Python data structures and Vega data format
75
- **Property System**: Comprehensive styling and configuration through PropertySet and ValueRef
76

77
This design enables both simple chart creation for common use cases and full control over Vega grammar for advanced visualizations.
78

79
## Capabilities
80

81
### Chart Construction
82

83
High-level chart constructors for common visualization types including bar charts, line charts, scatter plots, area charts, pie charts, maps, and word clouds. These provide intuitive APIs while generating complete Vega specifications.
84

85
```python { .api }
86
class Chart(Visualization):
87
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
88
                 width=960, height=500, grouped=False, no_data=False, *args, **kwargs): ...
89

90
class Bar(Chart): ...
91
class Line(Chart): ...
92
class Area(Chart): ...
93
class Scatter(Chart): ...
94
class GroupedBar(Chart): ...
95
class Map(Chart): ...
96
class Pie(Chart): ...
97
class Word(Chart): ...
98

99
# Aliases for stacked charts
100
StackedBar = Bar
101
StackedArea = Area
102
```
103

104
[Charts](./charts.md)
105

106
### Data Management
107

108
Data handling and transformation capabilities including automatic data type detection, pandas integration, and support for multiple data formats. Enables seamless conversion between Python data structures and Vega data specifications.
109

110
```python { .api }
111
class Data(GrammarClass):
112
    def __init__(self, name=None, **kwargs): ...
113
    
114
    @classmethod
115
    def from_pandas(cls, data, columns=None, key_on='idx', name=None,
116
                    series_key='data', grouped=False, records=False, **kwargs): ...
117
    
118
    @classmethod
119
    def from_iter(cls, data, name=None): ...
120
    
121
    @classmethod
122
    def from_mult_iters(cls, name=None, idx=None, **kwargs): ...
123

124
class Transform(GrammarClass):
125
    # Supports transform types: array, copy, cross, facet, filter, flatten, 
126
    # fold, formula, slice, sort, stats, truncate, unique, window, zip,
127
    # force, geo, geopath, link, pie, stack, treemap, wordcloud
128
    pass
129
```
130

131
[Data Management](./data-management.md)
132

133
### Visualization Grammar
134

135
Core Vega grammar components for building custom visualizations including scales, marks, axes, legends, and property systems. Provides full access to Vega's visualization capabilities.
136

137
```python { .api }
138
class Visualization(GrammarClass):
139
    def __init__(self, *args, **kwargs): ...
140
    def to_json(self): ...
141

142
class Scale(GrammarClass):
143
    # Properties: name, type, domain, range, reverse, round
144
    # Types: ordinal, linear, log, pow, sqrt, quantile, quantize, threshold
145
    pass
146

147
class Mark(GrammarClass):
148
    # Properties: type, from_, properties, key, delay, ease
149
    pass
150

151
class Axis(GrammarClass):
152
    # Properties: type, scale, orient, title, format, ticks, etc.
153
    pass
154
```
155

156
[Visualization Grammar](./visualization-grammar.md)
157

158
### Styling and Properties
159

160
Comprehensive styling system using PropertySet and ValueRef for controlling visual appearance, animations, and interactions. Supports all Vega visual properties and value referencing patterns.
161

162
```python { .api }
163
class PropertySet(GrammarClass):
164
    # Position properties: x, x2, y, y2, width, height
165
    # Style properties: fill, fillOpacity, stroke, strokeOpacity, strokeWidth
166
    # Text properties: text, fontSize, fontWeight, fontStyle, align, baseline
167
    pass
168

169
class ValueRef(GrammarClass):
170
    # Properties: value, field, group, scale, mult, offset, band
171
    pass
172

173
class MarkProperties(GrammarClass):
174
    # Properties: enter, exit, update, hover (PropertySet for each)
175
    pass
176
```
177

178
[Styling and Properties](./styling-properties.md)
179

180
## Utility Functions
181

182
```python { .api }
183
def initialize_notebook():
184
    """Initialize IPython notebook display elements for Vincent visualizations."""
185

186
def data_type(data, grouped=False, columns=None, key_on='idx', iter_idx=None):
187
    """Automatic data type detection and conversion for various Python data structures."""
188
```
189

190
## Color Palettes
191

192
```python { .api }
193
from vincent.colors import brews
194

195
# brews is a dictionary containing ColorBrewer palettes:
196
# Sequential: YlGn, YlGnBu, GnBu, BuGn, PuBuGn, PuBu, BuPu, RdPu, PuRd, 
197
#            OrRd, YlOrRd, YlOrBr, Purples, Blues, Greens, Oranges, Reds, Greys
198
# Diverging: Spectral, RdYlGn, RdBu, PiYG, PRGn, RdYlBu, BrBG, RdGy, PuOr  
199
# Qualitative: Set2, Accent, Set1, Set3, Dark2, Paired, Pastel2, Pastel1
200
```