0
# Visualization Framework
1
2
Panoramix provides a comprehensive visualization framework with multiple chart types, dynamic form generation, and flexible rendering capabilities. The system supports both SQL and Druid data sources with consistent APIs.
3
4
## Capabilities
5
6
### Base Visualization System
7
8
The visualization framework is built around a pluggable architecture with a base class and specialized implementations for different chart types.
9
10
```python { .api }
11
class BaseViz:
12
"""
13
Base visualization class providing core functionality.
14
15
Attributes:
16
verbose_name (str): Human-readable visualization name
17
template (str): Jinja2 template for rendering
18
hidden_fields (list): Form fields to hide in UI
19
datasource (Datasource or Table): Data source instance
20
form_data (dict): Form data from user interface
21
"""
22
23
def bake_query(self):
24
"""
25
Prepare and validate query parameters.
26
27
Processes form data and prepares query parameters
28
for execution against the data source.
29
"""
30
31
def query_obj(self):
32
"""
33
Build query object for data source.
34
35
Returns:
36
dict: Query parameters formatted for data source
37
"""
38
39
def render(self):
40
"""
41
Execute query and render visualization.
42
43
Returns:
44
str: Rendered HTML/JSON for the visualization
45
"""
46
47
def render_no_data(self):
48
"""
49
Render visualization when no data is available.
50
51
Returns:
52
str: No-data state HTML/JSON
53
"""
54
55
def form_class(self):
56
"""
57
Generate dynamic form class for this visualization.
58
59
Returns:
60
class: WTForms form class with appropriate fields
61
"""
62
63
def query_filters(self):
64
"""
65
Extract filter conditions from form data.
66
67
Returns:
68
list: List of filter tuples (column, operator, value)
69
"""
70
```
71
72
### Chart Types
73
74
Panoramix supports multiple chart types through specialized visualization classes:
75
76
```python { .api }
77
# Available visualization types
78
viz_types = OrderedDict([
79
('table', TableViz),
80
('line', TimeSeriesViz),
81
('compare', TimeSeriesCompareViz),
82
('compare_value', TimeSeriesCompareValueViz),
83
('area', TimeSeriesAreaViz),
84
('bar', TimeSeriesBarViz),
85
('stacked_ts_bar', TimeSeriesStackedBarViz),
86
('dist_bar', DistributionBarViz),
87
('pie', DistributionPieViz),
88
('bubble', BubbleViz),
89
])
90
```
91
92
### Table Visualization
93
94
Display data in tabular format with sorting, pagination, and export capabilities.
95
96
```python { .api }
97
class TableViz(BaseViz):
98
"""
99
Table visualization for displaying raw data.
100
101
Features:
102
- Sortable columns
103
- Pagination support
104
- Export to CSV/Excel
105
- Cell formatting
106
- Search and filtering
107
"""
108
verbose_name = "Table View"
109
template = "panoramix/viz_table.html"
110
```
111
112
### Time Series Visualizations
113
114
Various time-based chart types for temporal data analysis.
115
116
```python { .api }
117
class TimeSeriesViz(BaseViz):
118
"""
119
Line chart for time series data.
120
121
Features:
122
- Multiple metrics on same chart
123
- Interactive tooltips
124
- Zoom and pan
125
- Time range selection
126
"""
127
verbose_name = "Time Series - Line Chart"
128
129
class TimeSeriesAreaViz(BaseViz):
130
"""
131
Stacked area chart for time series data.
132
133
Features:
134
- Stacked area visualization
135
- Multiple metrics stacking
136
- Hover interactions
137
"""
138
verbose_name = "Time Series - Stacked"
139
140
class TimeSeriesBarViz(BaseViz):
141
"""
142
Bar chart for time series data.
143
144
Features:
145
- Time-based bar charts
146
- Multiple series support
147
- Grouping capabilities
148
"""
149
verbose_name = "Time Series - Bar Chart"
150
151
class TimeSeriesCompareViz(BaseViz):
152
"""
153
Time series comparison showing percentage change.
154
155
Features:
156
- Period-over-period comparison
157
- Percentage change calculation
158
- Trend indicators
159
"""
160
verbose_name = "Time Series - Percent Change"
161
```
162
163
### Distribution Visualizations
164
165
Charts for showing data distributions and proportions.
166
167
```python { .api }
168
class DistributionPieViz(BaseViz):
169
"""
170
Pie chart for categorical data distribution.
171
172
Features:
173
- Interactive pie slices
174
- Legend display
175
- Percentage labels
176
"""
177
verbose_name = "Distribution - Pie Chart"
178
179
class DistributionBarViz(BaseViz):
180
"""
181
Horizontal bar chart for distributions.
182
183
Features:
184
- Horizontal bar layout
185
- Category comparison
186
- Value labels
187
"""
188
verbose_name = "Distribution - Bar Chart"
189
```
190
191
### Advanced Visualizations
192
193
Specialized chart types for complex data analysis.
194
195
```python { .api }
196
class BubbleViz(BaseViz):
197
"""
198
Bubble chart for multi-dimensional data.
199
200
Features:
201
- X/Y positioning
202
- Bubble size mapping
203
- Color coding
204
- Interactive tooltips
205
"""
206
verbose_name = "Bubble Chart"
207
```
208
209
## Dynamic Form Generation
210
211
The visualization framework includes dynamic form generation for chart configuration.
212
213
```python { .api }
214
def form_factory(datasource, form_args, extra_fields_dict):
215
"""
216
Generate dynamic forms for visualization configuration.
217
218
Args:
219
datasource (Datasource or Table): Data source instance
220
form_args (dict): Base form arguments
221
extra_fields_dict (dict): Additional form fields
222
223
Returns:
224
OmgWtForm: Generated WTForms form class
225
"""
226
227
class OmgWtForm(Form):
228
"""Base WTForms form class for visualizations"""
229
```
230
231
## Usage Examples
232
233
### Creating a Line Chart
234
235
```python
236
from panoramix.viz import TimeSeriesViz
237
238
# Form data from user interface
239
form_data = {
240
'datasource': 'events',
241
'viz_type': 'line',
242
'metrics': ['count'],
243
'groupby': [],
244
'granularity': 'day',
245
'since': '7 days ago',
246
'until': 'now'
247
}
248
249
# Create visualization
250
viz = TimeSeriesViz(datasource, form_data)
251
252
# Render chart
253
chart_html = viz.render()
254
```
255
256
### Creating a Pie Chart
257
258
```python
259
from panoramix.viz import DistributionPieViz
260
261
form_data = {
262
'datasource': 'sales',
263
'viz_type': 'pie',
264
'metrics': ['sum__revenue'],
265
'groupby': ['product_category'],
266
'row_limit': 10
267
}
268
269
viz = DistributionPieViz(datasource, form_data)
270
pie_chart = viz.render()
271
```
272
273
### Bubble Chart Analysis
274
275
```python
276
from panoramix.viz import BubbleViz
277
278
form_data = {
279
'datasource': 'campaigns',
280
'viz_type': 'bubble',
281
'x': 'impressions',
282
'y': 'clicks',
283
'size': 'spend',
284
'entity': 'campaign_name',
285
'limit': 50
286
}
287
288
viz = BubbleViz(datasource, form_data)
289
bubble_chart = viz.render()
290
```
291
292
## Highcharts Integration
293
294
Panoramix integrates with Highcharts for rich, interactive visualizations.
295
296
```python { .api }
297
class HighchartsViz(BaseViz):
298
"""Base class for Highcharts-powered visualizations"""
299
300
def get_df(self):
301
"""Get pandas DataFrame from query results"""
302
303
def to_series(self, df, classed=''):
304
"""Convert DataFrame to Highcharts series format"""
305
```
306
307
## Chart Configuration
308
309
```python { .api }
310
# Default chart configuration
311
CHART_ARGS = {
312
'height': 700,
313
'title': None,
314
'target_div': 'chart'
315
}
316
```
317
318
## Error Handling
319
320
The visualization framework includes comprehensive error handling for common scenarios:
321
322
- Invalid data source configurations
323
- Missing required fields
324
- Query execution failures
325
- Rendering errors
326
- No data conditions
327
328
Each visualization type gracefully handles these conditions and provides meaningful error messages to users.