0
# Visualization
1

2
Comprehensive visualization system with 50+ chart types including tables, time series, geospatial maps, statistical plots, and specialized visualizations. Built on D3.js, NVD3, deck.gl, and other modern visualization libraries for interactive and publication-quality charts.
3

4
## Capabilities
5

6
### Base Visualization Framework
7

8
Core visualization infrastructure providing common functionality for all chart types.
9

10
```python { .api }
11
class BaseViz:
12
    """
13
    Base class for all visualization implementations.
14
    
15
    Key Properties:
16
    - viz_type: str, unique visualization type identifier
17
    - verbose_name: str, human-readable display name
18
    - is_timeseries: bool, indicates time-series visualization
19
    - default_fillna: mixed, default value for null/missing data
20
    - cache_type: str, cache storage type ('df' for dataframe, 'json' for serialized)
21
    - enforce_numerical_metrics: bool, requires numeric metrics only
22
    """
23
    
24
    def __init__(self, datasource, form_data, force=False):
25
        """
26
        Initialize visualization with datasource and configuration.
27
        
28
        Parameters:
29
        - datasource: BaseDatasource, data source instance
30
        - form_data: dict, chart configuration parameters
31
        - force: bool, bypass cache when True
32
        """
33
    
34
    def process_metrics(self):
35
        """
36
        Process and validate metric definitions.
37
        Converts metric specifications into executable SQL expressions
38
        with proper aggregation and formatting.
39
        
40
        Returns:
41
        List of processed metric objects with SQL expressions
42
        """
43
    
44
    def get_df(self):
45
        """
46
        Get result DataFrame for visualization.
47
        Executes query and returns pandas DataFrame with processed data.
48
        
49
        Returns:
50
        pandas.DataFrame with query results and applied transformations
51
        """
52
    
53
    def cache_key(self):
54
        """
55
        Generate unique cache key for this visualization.
56
        
57
        Returns:
58
        String cache key based on datasource, query, and parameters
59
        """
60
    
61
    def get_json_data(self):
62
        """
63
        Get JSON representation of visualization data.
64
        
65
        Returns:
66
        Dictionary with chart data, metadata, and configuration
67
        """
68
    
69
    def json_dumps(self):
70
        """
71
        Serialize visualization to JSON string.
72
        
73
        Returns:
74
        JSON string representation suitable for frontend consumption
75
        """
76
```
77

78
### Table Visualizations
79

80
Tabular data display with sorting, pagination, and formatting capabilities.
81

82
```python { .api }
83
class TableViz(BaseViz):
84
    """
85
    Tabular data display with advanced formatting.
86
    
87
    Features:
88
    - Column sorting and filtering
89
    - Pagination for large datasets
90
    - Conditional formatting rules
91
    - Cell-level styling and links
92
    - Aggregation row display
93
    """
94

95
class TimeTableViz(BaseViz):
96
    """
97
    Time series table display with temporal organization.
98
    
99
    Features:
100
    - Time-based row organization
101
    - Sparkline chart integration
102
    - Period-over-period comparisons
103
    - Time grain aggregation display
104
    """
105

106
class PivotTableViz(BaseViz):
107
    """
108
    Cross-tabulation table with dynamic grouping.
109
    
110
    Features:
111
    - Multi-level row and column grouping
112
    - Aggregation method selection
113
    - Subtotal and grand total calculations
114
    - Interactive pivot configuration
115
    """
116
```
117

118
### Chart Visualizations
119

120
Traditional charts and statistical visualizations using NVD3.js and D3.js.
121

122
```python { .api }
123
class NVD3Viz(BaseViz):
124
    """
125
    Base class for NVD3.js chart implementations.
126
    Provides common functionality for interactive SVG-based charts.
127
    """
128

129
class BoxPlotViz(NVD3Viz):
130
    """
131
    Box and whisker plot for statistical distribution display.
132
    
133
    Features:
134
    - Quartile and outlier visualization
135
    - Multiple series comparison
136
    - Custom percentile configuration
137
    """
138

139
class BubbleViz(NVD3Viz):
140
    """
141
    Bubble chart for three-dimensional data display.
142
    
143
    Features:
144
    - X/Y positioning with size encoding
145
    - Color-coded categories
146
    - Interactive zoom and pan
147
    - Custom bubble size scaling
148
    """
149

150
class BulletViz(NVD3Viz):
151
    """
152
    Bullet chart for performance indicator display.
153
    
154
    Features:
155
    - Target vs. actual comparison
156
    - Performance range indicators
157
    - Compact dashboard-friendly format
158
    """
159

160
class MultiLineViz(NVD3Viz):
161
    """
162
    Multi-line chart for time series comparison.
163
    
164
    Features:
165
    - Multiple metric overlay
166
    - Interactive legend control
167
    - Zoom and brush selection
168
    - Custom line styling
169
    """
170

171
class NVD3DualLineViz(NVD3Viz):
172
    """
173
    Dual-axis line chart for different scale metrics.
174
    
175
    Features:
176
    - Independent Y-axis scaling
177
    - Left and right axis assignment
178
    - Synchronized time navigation
179
    """
180

181
class NVD3TimeSeriesViz(NVD3Viz):
182
    """
183
    Time series line chart with temporal focus.
184
    
185
    Features:
186
    - Time-based X-axis formatting
187
    - Interactive time range selection
188
    - Annotation layer support
189
    - Real-time data updates
190
    """
191

192
class NVD3TimeSeriesBarViz(NVD3Viz):
193
    """
194
    Time series bar chart for temporal categorical data.
195
    
196
    Features:
197
    - Time-grouped bar display
198
    - Stacked and grouped modes
199
    - Custom time grain selection
200
    """
201

202
class NVD3TimePivotViz(NVD3Viz):
203
    """
204
    Time pivot visualization for temporal comparison.
205
    
206
    Features:
207
    - Period-over-period analysis
208
    - Configurable time comparison windows
209
    - Percentage change indicators
210
    """
211

212
class NVD3CompareTimeSeriesViz(NVD3Viz):
213
    """
214
    Comparative time series with percentage change.
215
    
216
    Features:
217
    - Baseline comparison calculation
218
    - Percentage or absolute difference display
219
    - Multiple baseline options
220
    """
221

222
class NVD3TimeSeriesStackedViz(NVD3Viz):
223
    """
224
    Stacked area chart for cumulative time series.
225
    
226
    Features:
227
    - Proportional and absolute stacking
228
    - Interactive layer toggling
229
    - Stream graph mode
230
    """
231

232
class DistributionPieViz(NVD3Viz):
233
    """
234
    Pie chart for categorical distribution display.
235
    
236
    Features:
237
    - Interactive slice selection
238
    - Donut chart mode
239
    - Custom color schemes
240
    - Value and percentage labels
241
    """
242

243
class DistributionBarViz(NVD3Viz):
244
    """
245
    Bar chart for categorical value comparison.
246
    
247
    Features:
248
    - Horizontal and vertical orientation
249
    - Grouped and stacked modes
250
    - Custom bar spacing and colors
251
    """
252

253
class HorizonViz(NVD3Viz):
254
    """
255
    Horizon chart for dense time series display.
256
    
257
    Features:
258
    - Space-efficient multi-series layout
259
    - Color-coded value ranges
260
    - Interactive series highlighting
261
    """
262

263
class RoseViz(NVD3Viz):
264
    """
265
    Rose/radar chart for multi-dimensional comparison.
266
    
267
    Features:
268
    - Polar coordinate system
269
    - Multiple metric overlay
270
    - Custom axis scaling
271
    """
272

273
class PartitionViz(NVD3Viz):
274
    """
275
    Partition chart for hierarchical data display.
276
    
277
    Features:
278
    - Nested proportion visualization
279
    - Interactive drill-down navigation
280
    - Custom partition algorithms
281
    """
282
```
283

284
### Big Number Visualizations
285

286
Single metric display with emphasis and trend indication.
287

288
```python { .api }
289
class BigNumberViz(BaseViz):
290
    """
291
    Large single number display for KPI visualization.
292
    
293
    Features:
294
    - Prominent metric value display
295
    - Custom number formatting
296
    - Conditional color coding
297
    - Trend indicator arrows
298
    """
299

300
class BigNumberTotalViz(BaseViz):
301
    """
302
    Big number with change indication and context.
303
    
304
    Features:
305
    - Current vs. previous period comparison
306
    - Percentage and absolute change display
307
    - Trend direction indicators
308
    - Configurable comparison periods
309
    """
310
```
311

312
### Statistical Visualizations
313

314
Advanced statistical charts for data analysis and exploration.
315

316
```python { .api }
317
class HistogramViz(BaseViz):
318
    """
319
    Histogram for distribution analysis.
320
    
321
    Features:
322
    - Configurable bin count and width
323
    - Normal distribution overlay
324
    - Statistical summary display
325
    - Interactive bin selection
326
    """
327

328
class BoxPlotViz(BaseViz):
329
    """
330
    Box plot for statistical distribution summary.
331
    
332
    Features:
333
    - Quartile and median indicators
334
    - Outlier identification and display
335
    - Multiple group comparison
336
    - Custom whisker calculation methods
337
    """
338

339
class PairedTTestViz(BaseViz):
340
    """
341
    Paired t-test statistical visualization.
342
    
343
    Features:
344
    - Statistical significance testing
345
    - Confidence interval display
346
    - P-value and effect size calculation
347
    - Before/after comparison visualization
348
    """
349
```
350

351
### Geospatial Visualizations
352

353
Map-based visualizations for geographic data analysis.
354

355
```python { .api }
356
class CountryMapViz(BaseViz):
357
    """
358
    Country-level choropleth map visualization.
359
    
360
    Features:
361
    - World map with country boundaries
362
    - Color-coded value mapping
363
    - Interactive country selection
364
    - Custom color scale configuration
365
    """
366

367
class WorldMapViz(BaseViz):
368
    """
369
    World map visualization for global data display.
370
    
371
    Features:
372
    - Configurable projection systems
373
    - Zoom and pan interaction
374
    - Custom boundary datasets
375
    - Overlay layer support
376
    """
377

378
class MapboxViz(BaseViz):
379
    """
380
    Mapbox-based interactive mapping.
381
    
382
    Features:
383
    - High-quality base maps
384
    - Custom styling and themes
385
    - Vector tile rendering
386
    - Real-time data updates
387
    
388
    Requirements:
389
    - MAPBOX_API_KEY configuration
390
    """
391
```
392

393
### Deck.gl Visualizations
394

395
High-performance WebGL-based geospatial visualizations.
396

397
```python { .api }
398
class BaseDeckGLViz(BaseViz):
399
    """
400
    Base class for deck.gl WebGL visualizations.
401
    Provides common functionality for high-performance map layers.
402
    """
403

404
class DeckScatterViz(BaseDeckGLViz):
405
    """
406
    Scatter plot layer for point data visualization.
407
    
408
    Features:
409
    - GPU-accelerated point rendering
410
    - Size and color encoding
411
    - Interactive selection and filtering
412
    - Custom point shapes and styles
413
    """
414

415
class DeckScreengrid(BaseDeckGLViz):
416
    """
417
    Screen-space grid aggregation for point density.
418
    
419
    Features:
420
    - Dynamic grid size adjustment
421
    - Color-coded density mapping
422
    - Real-time aggregation updates
423
    - Custom aggregation functions
424
    """
425

426
class DeckGrid(BaseDeckGLViz):
427
    """
428
    Geographic grid aggregation for spatial analysis.
429
    
430
    Features:
431
    - Hexagonal and square grid options
432
    - Multiple aggregation methods
433
    - 3D height encoding
434
    - Interactive grid configuration
435
    """
436

437
class DeckPathViz(BaseDeckGLViz):
438
    """
439
    Path and line visualization for routing data.
440
    
441
    Features:
442
    - Multi-segment path rendering
443
    - Width and color encoding
444
    - Animation along paths
445
    - Custom path styling
446
    """
447

448
class DeckPolygon(BaseDeckGLViz):
449
    """
450
    Polygon visualization for area data.
451
    
452
    Features:
453
    - Filled and outlined polygons
454
    - Height extrusion for 3D effect
455
    - Color and opacity mapping
456
    - Interactive polygon selection
457
    """
458

459
class DeckHex(BaseDeckGLViz):
460
    """
461
    Hexagonal binning for spatial aggregation.
462
    
463
    Features:
464
    - Automatic hexagon size calculation
465
    - Color and height encoding
466
    - Interactive bin exploration
467
    - Custom aggregation metrics
468
    """
469

470
class DeckGeoJson(BaseDeckGLViz):
471
    """
472
    GeoJSON layer for complex geographic features.
473
    
474
    Features:
475
    - Multi-geometry type support
476
    - Feature property mapping
477
    - Interactive feature selection
478
    - Custom styling rules
479
    """
480

481
class DeckArc(BaseDeckGLViz):
482
    """
483
    Arc visualization for connection and flow data.
484
    
485
    Features:
486
    - Origin-destination arc rendering
487
    - Width and color encoding
488
    - Animation effects
489
    - Great circle path calculation
490
    """
491

492
class DeckGLMultiLayer(BaseDeckGLViz):
493
    """
494
    Multiple layer composition for complex visualizations.
495
    
496
    Features:
497
    - Layer stacking and ordering
498
    - Independent layer configuration
499
    - Coordinated interaction handling
500
    - Performance optimization
501
    """
502
```
503

504
### Specialized Visualizations
505

506
Unique visualization types for specific use cases and data patterns.
507

508
```python { .api }
509
class TreemapViz(BaseViz):
510
    """
511
    Treemap for hierarchical data visualization.
512
    
513
    Features:
514
    - Nested rectangle layout
515
    - Size-based proportional display
516
    - Color coding for categories
517
    - Interactive drill-down navigation
518
    """
519

520
class SunburstViz(BaseViz):
521
    """
522
    Sunburst chart for radial hierarchy display.
523
    
524
    Features:
525
    - Circular nested layout
526
    - Interactive segment selection
527
    - Multi-level drill-down
528
    - Custom color schemes
529
    """
530

531
class SankeyViz(BaseViz):
532
    """
533
    Sankey diagram for flow visualization.
534
    
535
    Features:
536
    - Node and link flow representation
537
    - Proportional flow width
538
    - Interactive node manipulation
539
    - Custom flow colors and labels
540
    """
541

542
class DirectedForceViz(BaseViz):
543
    """
544
    Force-directed network graph visualization.
545
    
546
    Features:
547
    - Physics-based layout simulation
548
    - Node and edge interaction
549
    - Dynamic layout adjustment
550
    - Custom force parameters
551
    """
552

553
class ChordViz(BaseViz):
554
    """
555
    Chord diagram for relationship matrix display.
556
    
557
    Features:
558
    - Circular relationship layout
559
    - Proportional chord thickness
560
    - Interactive chord highlighting
561
    - Custom color mapping
562
    """
563

564
class CalHeatmapViz(BaseViz):
565
    """
566
    Calendar heatmap for temporal pattern analysis.
567
    
568
    Features:
569
    - Year/month/day grid layout
570
    - Color-coded value intensity
571
    - Interactive date selection
572
    - Custom time period display
573
    """
574

575
class MarkupViz(BaseViz):
576
    """
577
    HTML/Markdown content display.
578
    
579
    Features:
580
    - Rich text and HTML rendering
581
    - Markdown syntax support
582
    - Custom CSS styling
583
    - Dynamic content updates
584
    """
585

586
class SeparatorViz(BaseViz):
587
    """
588
    Visual separator for dashboard layout.
589
    
590
    Features:
591
    - Customizable separator styles
592
    - Text label support
593
    - Flexible sizing options
594
    """
595

596
class WordCloudViz(BaseViz):
597
    """
598
    Word cloud for text frequency visualization.
599
    
600
    Features:
601
    - Font size-based frequency encoding
602
    - Custom color schemes
603
    - Interactive word selection
604
    - Layout optimization algorithms
605
    """
606

607
class FilterBoxViz(BaseViz):
608
    """
609
    Interactive filter control panel.
610
    
611
    Features:
612
    - Multiple filter type support
613
    - Date range and dropdown filters
614
    - Real-time filter application
615
    - Custom filter layouts
616
    """
617

618
class IFrameViz(BaseViz):
619
    """
620
    Embedded iframe for external content.
621
    
622
    Features:
623
    - External website embedding
624
    - Responsive iframe sizing
625
    - Security considerations
626
    - Custom iframe parameters
627
    """
628

629
class ParallelCoordinatesViz(BaseViz):
630
    """
631
    Parallel coordinates for multi-dimensional data.
632
    
633
    Features:
634
    - Multiple axis display
635
    - Interactive axis reordering
636
    - Brushing and filtering
637
    - Custom axis scaling
638
    """
639

640
class HeatmapViz(BaseViz):
641
    """
642
    Correlation heatmap for matrix data.
643
    
644
    Features:
645
    - Color-coded value matrix
646
    - Custom color scales
647
    - Interactive cell selection
648
    - Hierarchical clustering options
649
    """
650

651
class EventFlowViz(BaseViz):
652
    """
653
    Event flow visualization for sequence analysis.
654
    
655
    Features:
656
    - Timeline-based event display
657
    - Flow path highlighting
658
    - Interactive event filtering
659
    - Custom event styling
660
    """
661
```
662

663
## Visualization Registry
664

665
Central registry system for managing available visualization types.
666

667
```python { .api }
668
viz_types = {
669
    'table': TableViz,
670
    'time_table': TimeTableViz,
671
    'pivot_table': PivotTableViz,
672
    'line': NVD3TimeSeriesViz,
673
    'bar': DistributionBarViz,
674
    'pie': DistributionPieViz,
675
    'area': NVD3TimeSeriesStackedViz,
676
    'box_plot': BoxPlotViz,
677
    'bubble': BubbleViz,
678
    'big_number': BigNumberViz,
679
    'big_number_total': BigNumberTotalViz,
680
    'histogram': HistogramViz,
681
    'country_map': CountryMapViz,
682
    'world_map': WorldMapViz,
683
    'mapbox': MapboxViz,
684
    'deck_scatter': DeckScatterViz,
685
    'deck_screengrid': DeckScreengrid,
686
    'deck_grid': DeckGrid,
687
    'deck_path': DeckPathViz,
688
    'deck_polygon': DeckPolygon,
689
    'deck_hex': DeckHex,
690
    'deck_geojson': DeckGeoJson,
691
    'deck_arc': DeckArc,
692
    'deck_multi': DeckGLMultiLayer,
693
    'treemap': TreemapViz,
694
    'sunburst': SunburstViz,
695
    'sankey': SankeyViz,
696
    'directed_force': DirectedForceViz,
697
    'chord': ChordViz,
698
    'cal_heatmap': CalHeatmapViz,
699
    'markup': MarkupViz,
700
    'separator': SeparatorViz,
701
    'word_cloud': WordCloudViz,
702
    'filter_box': FilterBoxViz,
703
    'iframe': IFrameViz,
704
    'para': ParallelCoordinatesViz,
705
    'heatmap': HeatmapViz,
706
    'event_flow': EventFlowViz
707
}
708
"""
709
Complete registry of available visualization types.
710
Maps visualization type identifiers to implementation classes.
711
"""
712
```
713

714
## Usage Examples
715

716
### Creating Visualizations
717

718
```python
719
# Create a visualization instance
720
viz = TableViz(datasource, form_data)
721

722
# Get visualization data
723
chart_data = viz.get_json_data()
724

725
# Cache the results
726
cache_key = viz.cache_key()
727
```
728

729
### Custom Visualization Development
730

731
```python
732
class CustomViz(BaseViz):
733
    """Custom visualization implementation."""
734
    
735
    viz_type = 'custom_chart'
736
    verbose_name = 'Custom Chart'
737
    is_timeseries = False
738
    
739
    def get_df(self):
740
        # Custom data processing
741
        return super().get_df()
742
    
743
    def get_json_data(self):
744
        # Custom JSON formatting
745
        return {
746
            'data': self.get_df().to_dict('records'),
747
            'config': self.form_data
748
        }
749

750
# Register custom visualization
751
viz_types['custom_chart'] = CustomViz
752
```
753

754
The visualization framework provides a comprehensive and extensible system for creating interactive data visualizations, supporting everything from simple tables to complex geospatial analytics with high-performance rendering capabilities.