0
# Chart Construction
1

2
High-level chart constructors for common visualization types. All chart classes extend the base Chart class and provide intuitive APIs for creating specific chart types while generating complete Vega specifications.
3

4
## Capabilities
5

6
### Base Chart Class
7

8
The foundational Chart class that all specific chart types inherit from. Provides common functionality for data handling, sizing, and Vega specification generation.
9

10
```python { .api }
11
class Chart(Visualization):
12
    """Abstract Base Class for all Chart types"""
13
    
14
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
15
                 width=960, height=500, grouped=False, no_data=False,
16
                 *args, **kwargs):
17
        """
18
        Create a Vega Chart
19
        
20
        Parameters:
21
        - data: Input data (pandas DataFrame/Series, list, tuple, dict, or None)
22
        - columns: Column names for DataFrame data (list or None)
23
        - key_on: Key field name for data indexing (str, default 'idx')
24
        - iter_idx: Iterator index for multiple data sources (str or None)
25
        - width: Chart width in pixels (int, default 960)
26
        - height: Chart height in pixels (int, default 500)
27
        - grouped: Whether data should be grouped (bool, default False)
28
        - no_data: Whether to create chart without data (bool, default False)
29
        """
30
```
31

32
### Line Charts
33

34
Creates line plots connecting data points with lines, ideal for showing trends over continuous data.
35

36
```python { .api }
37
class Line(Chart):
38
    """Line chart for showing trends over continuous data"""
39
    
40
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
41
                 width=960, height=500, grouped=False, no_data=False,
42
                 *args, **kwargs):
43
        """
44
        Create a line chart
45
        
46
        Inherits all parameters from Chart base class.
47
        Automatically configures marks as 'line' type with appropriate scales.
48
        """
49
```
50

51
**Usage Example:**
52

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

57
# From list data
58
data = [10, 20, 15, 30, 25]
59
line = vincent.Line(data)
60

61
# From pandas DataFrame
62
df = pd.DataFrame({'x': range(5), 'y': [10, 20, 15, 30, 25]})
63
line = vincent.Line(df, columns=['x', 'y'])
64
```
65

66
### Scatter Plots
67

68
Creates scatter plots for showing correlation between two variables, with support for color and size encoding.
69

70
```python { .api }
71
class Scatter(Chart):
72
    """Scatter plot for showing correlation between two variables"""
73
    
74
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
75
                 width=960, height=500, grouped=False, no_data=False,
76
                 *args, **kwargs):
77
        """
78
        Create a scatter plot
79
        
80
        Inherits all parameters from Chart base class.
81
        Automatically configures marks as 'symbol' type with point symbols.
82
        """
83
```
84

85
### Bar Charts
86

87
Creates bar charts for categorical data comparison, with support for both vertical and horizontal orientations.
88

89
```python { .api }
90
class Bar(Chart):
91
    """Bar chart for categorical data comparison"""
92
    
93
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
94
                 width=960, height=500, grouped=False, no_data=False,
95
                 *args, **kwargs):
96
        """
97
        Create a bar chart
98
        
99
        Inherits all parameters from Chart base class.
100
        Automatically configures marks as 'rect' type with appropriate scales.
101
        """
102

103
# Alias for stacked bar charts
104
StackedBar = Bar
105
```
106

107
**Usage Example:**
108

109
```python
110
import vincent
111

112
# Simple bar chart
113
data = [('A', 10), ('B', 20), ('C', 15)]
114
bar = vincent.Bar(data)
115

116
# Stacked bar chart (same as Bar)
117
stacked = vincent.StackedBar(data, grouped=True)
118
```
119

120
### Area Charts
121

122
Creates area charts for showing cumulative data over time, with support for stacked areas.
123

124
```python { .api }
125
class Area(Chart):
126
    """Area chart for showing cumulative data over time"""
127
    
128
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
129
                 width=960, height=500, grouped=False, no_data=False,
130
                 *args, **kwargs):
131
        """
132
        Create an area chart
133
        
134
        Inherits all parameters from Chart base class.
135
        Automatically configures marks as 'area' type with filled regions.
136
        """
137

138
# Alias for stacked area charts  
139
StackedArea = Area
140
```
141

142
### Grouped Bar Charts
143

144
Creates bar charts with grouped categories, useful for comparing multiple series across categories.
145

146
```python { .api }
147
class GroupedBar(Chart):
148
    """Bar chart with grouped categories"""
149
    
150
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
151
                 width=960, height=500, grouped=False, no_data=False,
152
                 *args, **kwargs):
153
        """
154
        Create a grouped bar chart
155
        
156
        Inherits all parameters from Chart base class.
157
        Automatically configures for grouped data visualization.
158
        """
159
```
160

161
### Geographic Maps
162

163
Creates geographic visualizations with map projections and spatial data support.
164

165
```python { .api }
166
class Map(Chart):
167
    """Geographic visualization chart"""
168
    
169
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
170
                 width=960, height=500, grouped=False, no_data=False,
171
                 *args, **kwargs):
172
        """
173
        Create a geographic map chart
174
        
175
        Inherits all parameters from Chart base class.
176
        Supports geographic data and map projections.
177
        """
178
```
179

180
### Pie Charts
181

182
Creates pie charts for showing proportional data as circular segments.
183

184
```python { .api }
185
class Pie(Chart):
186
    """Pie chart for showing proportional data"""
187
    
188
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
189
                 width=960, height=500, grouped=False, no_data=False,
190
                 *args, **kwargs):
191
        """
192
        Create a pie chart
193
        
194
        Inherits all parameters from Chart base class.
195
        Automatically applies pie transform to data.
196
        """
197
```
198

199
### Word Clouds
200

201
Creates word cloud visualizations showing text frequency through font size variation.
202

203
```python { .api }
204
class Word(Chart):
205
    """Word cloud visualization"""
206
    
207
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
208
                 width=960, height=500, grouped=False, no_data=False,
209
                 *args, **kwargs):
210
        """
211
        Create a word cloud chart
212
        
213
        Inherits all parameters from Chart base class.
214
        Automatically applies wordcloud transform to text data.
215
        """
216
```
217

218
## Data Type Handling
219

220
```python { .api }
221
def data_type(data, grouped=False, columns=None, key_on='idx', iter_idx=None):
222
    """
223
    Automatic data type detection and conversion for chart data.
224
    
225
    Parameters:
226
    - data: Input data (pandas DataFrame/Series, list, tuple, dict)
227
    - grouped: Whether data should be treated as grouped (bool, default False)
228
    - columns: Column specification for DataFrame data (list or None)
229
    - key_on: Key field name for data indexing (str, default 'idx')
230
    - iter_idx: Iterator index for multiple data sources (str or None)
231
    
232
    Returns:
233
    Data: Vincent Data object with appropriate format
234
    
235
    Raises:
236
    ValueError: If data type is not supported
237
    """
238
```
239

240
This function automatically detects and converts various Python data types:
241
- pandas DataFrame and Series objects
242
- Python lists, tuples, and dictionaries
243
- Multiple iterator patterns for complex data structures