0
# Charts
1
2
Create and manage charts within worksheets with various chart types and customization options for data visualization.
3
4
## Capabilities
5
6
### Creating Charts
7
8
Add charts to worksheets with data ranges and customization options.
9
10
```python { .api }
11
class Worksheet:
12
def add_chart(self, data, start=None, end=None, chart_type=ChartType.COLUMN, **kwargs) -> Chart:
13
"""
14
Add chart to worksheet.
15
16
Parameters:
17
- data: Data range for chart (Address, GridRange, or string)
18
- start (str): Start cell for chart placement
19
- end (str): End cell for chart placement
20
- chart_type (ChartType): Type of chart to create
21
- **kwargs: Additional chart options (title, domain, ranges, etc.)
22
23
Returns:
24
Chart: New chart object
25
"""
26
27
def get_charts(self) -> list:
28
"""
29
Get all charts in worksheet.
30
31
Returns:
32
list: List of Chart objects
33
"""
34
```
35
36
### Chart Properties and Management
37
38
Access and modify chart properties, appearance, and data sources.
39
40
```python { .api }
41
class Chart:
42
def __init__(self, worksheet, chart_data=None):
43
"""
44
Initialize chart object.
45
46
Parameters:
47
- worksheet (Worksheet): Parent worksheet
48
- chart_data (dict): Chart data from API
49
"""
50
51
@property
52
def id(self) -> int:
53
"""Chart ID."""
54
55
@property
56
def title(self) -> str:
57
"""Chart title."""
58
59
@title.setter
60
def title(self, title):
61
"""Set chart title."""
62
63
@property
64
def chart_type(self) -> str:
65
"""Chart type."""
66
67
@chart_type.setter
68
def chart_type(self, chart_type):
69
"""Set chart type."""
70
71
@property
72
def domain(self) -> dict:
73
"""Chart domain (x-axis) range."""
74
75
@domain.setter
76
def domain(self, domain):
77
"""Set chart domain range."""
78
79
@property
80
def ranges(self) -> list:
81
"""Chart data series ranges."""
82
83
@ranges.setter
84
def ranges(self, ranges):
85
"""Set chart data series ranges."""
86
87
@property
88
def anchor_cell(self) -> str:
89
"""Chart anchor cell position."""
90
91
@anchor_cell.setter
92
def anchor_cell(self, cell):
93
"""Set chart anchor cell position."""
94
95
@property
96
def legend_position(self) -> str:
97
"""Chart legend position."""
98
99
@legend_position.setter
100
def legend_position(self, position):
101
"""Set chart legend position."""
102
```
103
104
### Chart Customization
105
106
Customize chart appearance including fonts, colors, and layout options.
107
108
```python { .api }
109
class Chart:
110
@property
111
def title_font_family(self) -> str:
112
"""Chart title font family."""
113
114
@title_font_family.setter
115
def title_font_family(self, font_family):
116
"""Set chart title font family."""
117
118
@property
119
def font_name(self) -> str:
120
"""Chart font name."""
121
122
@font_name.setter
123
def font_name(self, font_name):
124
"""Set chart font name."""
125
126
def update_chart(self):
127
"""
128
Update chart by applying any changes made to chart properties.
129
"""
130
131
def refresh(self):
132
"""Refresh chart data from API."""
133
134
def delete(self):
135
"""Delete chart from worksheet."""
136
```
137
138
### Chart Data Management
139
140
Manage chart data sources and series configuration.
141
142
```python { .api }
143
class Chart:
144
def get_json(self) -> dict:
145
"""
146
Get chart configuration as JSON.
147
148
Returns:
149
dict: Complete chart configuration
150
"""
151
152
def set_json(self, chart_json):
153
"""
154
Set chart configuration from JSON.
155
156
Parameters:
157
- chart_json (dict): Chart configuration JSON
158
"""
159
```
160
161
## Usage Examples
162
163
### Basic Chart Creation
164
165
```python
166
import pygsheets
167
168
# Get worksheet with data
169
gc = pygsheets.authorize()
170
sh = gc.open('Sales Data')
171
wks = sh.sheet1
172
173
# Add sample data
174
data = [
175
['Month', 'Sales', 'Profit'],
176
['Jan', 1000, 200],
177
['Feb', 1200, 250],
178
['Mar', 1100, 220],
179
['Apr', 1300, 280]
180
]
181
wks.update_values('A1', data)
182
183
# Create column chart
184
chart = wks.add_chart(
185
data=pygsheets.GridRange.create('A1', 'C5'),
186
chart_type=pygsheets.ChartType.COLUMN,
187
title='Monthly Sales and Profit'
188
)
189
190
# Position chart
191
chart.anchor_cell = 'E2'
192
```
193
194
### Chart Customization
195
196
```python
197
# Create line chart with customization
198
chart = wks.add_chart(
199
data='A1:C5',
200
chart_type=pygsheets.ChartType.LINE,
201
title='Sales Trend'
202
)
203
204
# Customize appearance
205
chart.title = 'Monthly Sales Trend Analysis'
206
chart.title_font_family = 'Arial'
207
chart.font_name = 'Arial'
208
chart.legend_position = 'RIGHT_LEGEND'
209
210
# Set domain (x-axis) and ranges (y-axis series)
211
chart.domain = pygsheets.GridRange.create('A2', 'A5') # Month column
212
chart.ranges = [
213
pygsheets.GridRange.create('B2', 'B5'), # Sales data
214
pygsheets.GridRange.create('C2', 'C5') # Profit data
215
]
216
217
# Apply updates
218
chart.update_chart()
219
```
220
221
### Multiple Chart Types
222
223
```python
224
# Create different chart types
225
data_range = 'A1:C5'
226
227
# Bar chart
228
bar_chart = wks.add_chart(
229
data=data_range,
230
chart_type=pygsheets.ChartType.BAR,
231
title='Horizontal Bar Chart'
232
)
233
bar_chart.anchor_cell = 'E2'
234
235
# Area chart
236
area_chart = wks.add_chart(
237
data=data_range,
238
chart_type=pygsheets.ChartType.AREA,
239
title='Area Chart'
240
)
241
area_chart.anchor_cell = 'E15'
242
243
# Scatter plot
244
scatter_chart = wks.add_chart(
245
data='B1:C5', # Sales vs Profit
246
chart_type=pygsheets.ChartType.SCATTER,
247
title='Sales vs Profit Correlation'
248
)
249
scatter_chart.anchor_cell = 'E28'
250
251
# Combo chart
252
combo_chart = wks.add_chart(
253
data=data_range,
254
chart_type=pygsheets.ChartType.COMBO,
255
title='Combo Chart'
256
)
257
combo_chart.anchor_cell = 'H2'
258
```
259
260
### Chart Management
261
262
```python
263
# Get all charts in worksheet
264
charts = wks.get_charts()
265
print(f"Found {len(charts)} charts")
266
267
# Update existing chart
268
if charts:
269
chart = charts[0]
270
chart.title = 'Updated Chart Title'
271
chart.chart_type = pygsheets.ChartType.LINE
272
chart.update_chart()
273
274
# Export chart configuration
275
chart_config = chart.get_json()
276
print("Chart configuration:", chart_config)
277
278
# Clone chart configuration
279
new_chart_config = chart_config.copy()
280
new_chart_config['title'] = 'Cloned Chart'
281
282
# Delete charts
283
for chart in charts[1:]: # Keep first chart, delete others
284
chart.delete()
285
```
286
287
### Advanced Chart Configuration
288
289
```python
290
# Create combo chart with mixed chart types
291
combo_chart = wks.add_chart(
292
data='A1:C5',
293
chart_type=pygsheets.ChartType.COMBO,
294
title='Sales (Columns) and Profit (Line)'
295
)
296
297
# Configure combo chart series
298
combo_config = {
299
'title': 'Mixed Chart Types',
300
'series': [
301
{'type': 'COLUMN', 'targetAxis': 'LEFT_AXIS'},
302
{'type': 'LINE', 'targetAxis': 'RIGHT_AXIS'}
303
]
304
}
305
combo_chart.set_json(combo_config)
306
307
# Stepped area chart
308
stepped_chart = wks.add_chart(
309
data='A1:B5',
310
chart_type=pygsheets.ChartType.STEPPED_AREA,
311
title='Stepped Area Chart'
312
)
313
```
314
315
## Types
316
317
### Chart Types
318
319
```python { .api }
320
class ChartType:
321
BAR = 'BAR'
322
LINE = 'LINE'
323
AREA = 'AREA'
324
COLUMN = 'COLUMN'
325
SCATTER = 'SCATTER'
326
COMBO = 'COMBO'
327
STEPPED_AREA = 'STEPPED_AREA'
328
```
329
330
### Legend Positions
331
332
```python { .api }
333
class LegendPosition:
334
BOTTOM_LEGEND = 'BOTTOM_LEGEND'
335
LEFT_LEGEND = 'LEFT_LEGEND'
336
RIGHT_LEGEND = 'RIGHT_LEGEND'
337
TOP_LEGEND = 'TOP_LEGEND'
338
NO_LEGEND = 'NO_LEGEND'
339
```