Visualization

class BaseViz:
    """
    Base class for all visualization implementations.
    
    Key Properties:
    - viz_type: str, unique visualization type identifier
    - verbose_name: str, human-readable display name
    - is_timeseries: bool, indicates time-series visualization
    - default_fillna: mixed, default value for null/missing data
    - cache_type: str, cache storage type ('df' for dataframe, 'json' for serialized)
    - enforce_numerical_metrics: bool, requires numeric metrics only
    """
    
    def __init__(self, datasource, form_data, force=False):
        """
        Initialize visualization with datasource and configuration.
        
        Parameters:
        - datasource: BaseDatasource, data source instance
        - form_data: dict, chart configuration parameters
        - force: bool, bypass cache when True
        """
    
    def process_metrics(self):
        """
        Process and validate metric definitions.
        Converts metric specifications into executable SQL expressions
        with proper aggregation and formatting.
        
        Returns:
        List of processed metric objects with SQL expressions
        """
    
    def get_df(self):
        """
        Get result DataFrame for visualization.
        Executes query and returns pandas DataFrame with processed data.
        
        Returns:
        pandas.DataFrame with query results and applied transformations
        """
    
    def cache_key(self):
        """
        Generate unique cache key for this visualization.
        
        Returns:
        String cache key based on datasource, query, and parameters
        """
    
    def get_json_data(self):
        """
        Get JSON representation of visualization data.
        
        Returns:
        Dictionary with chart data, metadata, and configuration
        """
    
    def json_dumps(self):
        """
        Serialize visualization to JSON string.
        
        Returns:
        JSON string representation suitable for frontend consumption
        """

class TableViz(BaseViz):
    """
    Tabular data display with advanced formatting.
    
    Features:
    - Column sorting and filtering
    - Pagination for large datasets
    - Conditional formatting rules
    - Cell-level styling and links
    - Aggregation row display
    """

class TimeTableViz(BaseViz):
    """
    Time series table display with temporal organization.
    
    Features:
    - Time-based row organization
    - Sparkline chart integration
    - Period-over-period comparisons
    - Time grain aggregation display
    """

class PivotTableViz(BaseViz):
    """
    Cross-tabulation table with dynamic grouping.
    
    Features:
    - Multi-level row and column grouping
    - Aggregation method selection
    - Subtotal and grand total calculations
    - Interactive pivot configuration
    """

class NVD3Viz(BaseViz):
    """
    Base class for NVD3.js chart implementations.
    Provides common functionality for interactive SVG-based charts.
    """

class BoxPlotViz(NVD3Viz):
    """
    Box and whisker plot for statistical distribution display.
    
    Features:
    - Quartile and outlier visualization
    - Multiple series comparison
    - Custom percentile configuration
    """

class BubbleViz(NVD3Viz):
    """
    Bubble chart for three-dimensional data display.
    
    Features:
    - X/Y positioning with size encoding
    - Color-coded categories
    - Interactive zoom and pan
    - Custom bubble size scaling
    """

class BulletViz(NVD3Viz):
    """
    Bullet chart for performance indicator display.
    
    Features:
    - Target vs. actual comparison
    - Performance range indicators
    - Compact dashboard-friendly format
    """

class MultiLineViz(NVD3Viz):
    """
    Multi-line chart for time series comparison.
    
    Features:
    - Multiple metric overlay
    - Interactive legend control
    - Zoom and brush selection
    - Custom line styling
    """

class NVD3DualLineViz(NVD3Viz):
    """
    Dual-axis line chart for different scale metrics.
    
    Features:
    - Independent Y-axis scaling
    - Left and right axis assignment
    - Synchronized time navigation
    """

class NVD3TimeSeriesViz(NVD3Viz):
    """
    Time series line chart with temporal focus.
    
    Features:
    - Time-based X-axis formatting
    - Interactive time range selection
    - Annotation layer support
    - Real-time data updates
    """

class NVD3TimeSeriesBarViz(NVD3Viz):
    """
    Time series bar chart for temporal categorical data.
    
    Features:
    - Time-grouped bar display
    - Stacked and grouped modes
    - Custom time grain selection
    """

class NVD3TimePivotViz(NVD3Viz):
    """
    Time pivot visualization for temporal comparison.
    
    Features:
    - Period-over-period analysis
    - Configurable time comparison windows
    - Percentage change indicators
    """

class NVD3CompareTimeSeriesViz(NVD3Viz):
    """
    Comparative time series with percentage change.
    
    Features:
    - Baseline comparison calculation
    - Percentage or absolute difference display
    - Multiple baseline options
    """

class NVD3TimeSeriesStackedViz(NVD3Viz):
    """
    Stacked area chart for cumulative time series.
    
    Features:
    - Proportional and absolute stacking
    - Interactive layer toggling
    - Stream graph mode
    """

class DistributionPieViz(NVD3Viz):
    """
    Pie chart for categorical distribution display.
    
    Features:
    - Interactive slice selection
    - Donut chart mode
    - Custom color schemes
    - Value and percentage labels
    """

class DistributionBarViz(NVD3Viz):
    """
    Bar chart for categorical value comparison.
    
    Features:
    - Horizontal and vertical orientation
    - Grouped and stacked modes
    - Custom bar spacing and colors
    """

class HorizonViz(NVD3Viz):
    """
    Horizon chart for dense time series display.
    
    Features:
    - Space-efficient multi-series layout
    - Color-coded value ranges
    - Interactive series highlighting
    """

class RoseViz(NVD3Viz):
    """
    Rose/radar chart for multi-dimensional comparison.
    
    Features:
    - Polar coordinate system
    - Multiple metric overlay
    - Custom axis scaling
    """

class PartitionViz(NVD3Viz):
    """
    Partition chart for hierarchical data display.
    
    Features:
    - Nested proportion visualization
    - Interactive drill-down navigation
    - Custom partition algorithms
    """

class BigNumberViz(BaseViz):
    """
    Large single number display for KPI visualization.
    
    Features:
    - Prominent metric value display
    - Custom number formatting
    - Conditional color coding
    - Trend indicator arrows
    """

class BigNumberTotalViz(BaseViz):
    """
    Big number with change indication and context.
    
    Features:
    - Current vs. previous period comparison
    - Percentage and absolute change display
    - Trend direction indicators
    - Configurable comparison periods
    """

class HistogramViz(BaseViz):
    """
    Histogram for distribution analysis.
    
    Features:
    - Configurable bin count and width
    - Normal distribution overlay
    - Statistical summary display
    - Interactive bin selection
    """

class BoxPlotViz(BaseViz):
    """
    Box plot for statistical distribution summary.
    
    Features:
    - Quartile and median indicators
    - Outlier identification and display
    - Multiple group comparison
    - Custom whisker calculation methods
    """

class PairedTTestViz(BaseViz):
    """
    Paired t-test statistical visualization.
    
    Features:
    - Statistical significance testing
    - Confidence interval display
    - P-value and effect size calculation
    - Before/after comparison visualization
    """

class CountryMapViz(BaseViz):
    """
    Country-level choropleth map visualization.
    
    Features:
    - World map with country boundaries
    - Color-coded value mapping
    - Interactive country selection
    - Custom color scale configuration
    """

class WorldMapViz(BaseViz):
    """
    World map visualization for global data display.
    
    Features:
    - Configurable projection systems
    - Zoom and pan interaction
    - Custom boundary datasets
    - Overlay layer support
    """

class MapboxViz(BaseViz):
    """
    Mapbox-based interactive mapping.
    
    Features:
    - High-quality base maps
    - Custom styling and themes
    - Vector tile rendering
    - Real-time data updates
    
    Requirements:
    - MAPBOX_API_KEY configuration
    """

class BaseDeckGLViz(BaseViz):
    """
    Base class for deck.gl WebGL visualizations.
    Provides common functionality for high-performance map layers.
    """

class DeckScatterViz(BaseDeckGLViz):
    """
    Scatter plot layer for point data visualization.
    
    Features:
    - GPU-accelerated point rendering
    - Size and color encoding
    - Interactive selection and filtering
    - Custom point shapes and styles
    """

class DeckScreengrid(BaseDeckGLViz):
    """
    Screen-space grid aggregation for point density.
    
    Features:
    - Dynamic grid size adjustment
    - Color-coded density mapping
    - Real-time aggregation updates
    - Custom aggregation functions
    """

class DeckGrid(BaseDeckGLViz):
    """
    Geographic grid aggregation for spatial analysis.
    
    Features:
    - Hexagonal and square grid options
    - Multiple aggregation methods
    - 3D height encoding
    - Interactive grid configuration
    """

class DeckPathViz(BaseDeckGLViz):
    """
    Path and line visualization for routing data.
    
    Features:
    - Multi-segment path rendering
    - Width and color encoding
    - Animation along paths
    - Custom path styling
    """

class DeckPolygon(BaseDeckGLViz):
    """
    Polygon visualization for area data.
    
    Features:
    - Filled and outlined polygons
    - Height extrusion for 3D effect
    - Color and opacity mapping
    - Interactive polygon selection
    """

class DeckHex(BaseDeckGLViz):
    """
    Hexagonal binning for spatial aggregation.
    
    Features:
    - Automatic hexagon size calculation
    - Color and height encoding
    - Interactive bin exploration
    - Custom aggregation metrics
    """

class DeckGeoJson(BaseDeckGLViz):
    """
    GeoJSON layer for complex geographic features.
    
    Features:
    - Multi-geometry type support
    - Feature property mapping
    - Interactive feature selection
    - Custom styling rules
    """

class DeckArc(BaseDeckGLViz):
    """
    Arc visualization for connection and flow data.
    
    Features:
    - Origin-destination arc rendering
    - Width and color encoding
    - Animation effects
    - Great circle path calculation
    """

class DeckGLMultiLayer(BaseDeckGLViz):
    """
    Multiple layer composition for complex visualizations.
    
    Features:
    - Layer stacking and ordering
    - Independent layer configuration
    - Coordinated interaction handling
    - Performance optimization
    """

class TreemapViz(BaseViz):
    """
    Treemap for hierarchical data visualization.
    
    Features:
    - Nested rectangle layout
    - Size-based proportional display
    - Color coding for categories
    - Interactive drill-down navigation
    """

class SunburstViz(BaseViz):
    """
    Sunburst chart for radial hierarchy display.
    
    Features:
    - Circular nested layout
    - Interactive segment selection
    - Multi-level drill-down
    - Custom color schemes
    """

class SankeyViz(BaseViz):
    """
    Sankey diagram for flow visualization.
    
    Features:
    - Node and link flow representation
    - Proportional flow width
    - Interactive node manipulation
    - Custom flow colors and labels
    """

class DirectedForceViz(BaseViz):
    """
    Force-directed network graph visualization.
    
    Features:
    - Physics-based layout simulation
    - Node and edge interaction
    - Dynamic layout adjustment
    - Custom force parameters
    """

class ChordViz(BaseViz):
    """
    Chord diagram for relationship matrix display.
    
    Features:
    - Circular relationship layout
    - Proportional chord thickness
    - Interactive chord highlighting
    - Custom color mapping
    """

class CalHeatmapViz(BaseViz):
    """
    Calendar heatmap for temporal pattern analysis.
    
    Features:
    - Year/month/day grid layout
    - Color-coded value intensity
    - Interactive date selection
    - Custom time period display
    """

class MarkupViz(BaseViz):
    """
    HTML/Markdown content display.
    
    Features:
    - Rich text and HTML rendering
    - Markdown syntax support
    - Custom CSS styling
    - Dynamic content updates
    """

class SeparatorViz(BaseViz):
    """
    Visual separator for dashboard layout.
    
    Features:
    - Customizable separator styles
    - Text label support
    - Flexible sizing options
    """

class WordCloudViz(BaseViz):
    """
    Word cloud for text frequency visualization.
    
    Features:
    - Font size-based frequency encoding
    - Custom color schemes
    - Interactive word selection
    - Layout optimization algorithms
    """

class FilterBoxViz(BaseViz):
    """
    Interactive filter control panel.
    
    Features:
    - Multiple filter type support
    - Date range and dropdown filters
    - Real-time filter application
    - Custom filter layouts
    """

class IFrameViz(BaseViz):
    """
    Embedded iframe for external content.
    
    Features:
    - External website embedding
    - Responsive iframe sizing
    - Security considerations
    - Custom iframe parameters
    """

class ParallelCoordinatesViz(BaseViz):
    """
    Parallel coordinates for multi-dimensional data.
    
    Features:
    - Multiple axis display
    - Interactive axis reordering
    - Brushing and filtering
    - Custom axis scaling
    """

class HeatmapViz(BaseViz):
    """
    Correlation heatmap for matrix data.
    
    Features:
    - Color-coded value matrix
    - Custom color scales
    - Interactive cell selection
    - Hierarchical clustering options
    """

class EventFlowViz(BaseViz):
    """
    Event flow visualization for sequence analysis.
    
    Features:
    - Timeline-based event display
    - Flow path highlighting
    - Interactive event filtering
    - Custom event styling
    """

viz_types = {
    'table': TableViz,
    'time_table': TimeTableViz,
    'pivot_table': PivotTableViz,
    'line': NVD3TimeSeriesViz,
    'bar': DistributionBarViz,
    'pie': DistributionPieViz,
    'area': NVD3TimeSeriesStackedViz,
    'box_plot': BoxPlotViz,
    'bubble': BubbleViz,
    'big_number': BigNumberViz,
    'big_number_total': BigNumberTotalViz,
    'histogram': HistogramViz,
    'country_map': CountryMapViz,
    'world_map': WorldMapViz,
    'mapbox': MapboxViz,
    'deck_scatter': DeckScatterViz,
    'deck_screengrid': DeckScreengrid,
    'deck_grid': DeckGrid,
    'deck_path': DeckPathViz,
    'deck_polygon': DeckPolygon,
    'deck_hex': DeckHex,
    'deck_geojson': DeckGeoJson,
    'deck_arc': DeckArc,
    'deck_multi': DeckGLMultiLayer,
    'treemap': TreemapViz,
    'sunburst': SunburstViz,
    'sankey': SankeyViz,
    'directed_force': DirectedForceViz,
    'chord': ChordViz,
    'cal_heatmap': CalHeatmapViz,
    'markup': MarkupViz,
    'separator': SeparatorViz,
    'word_cloud': WordCloudViz,
    'filter_box': FilterBoxViz,
    'iframe': IFrameViz,
    'para': ParallelCoordinatesViz,
    'heatmap': HeatmapViz,
    'event_flow': EventFlowViz
}
"""
Complete registry of available visualization types.
Maps visualization type identifiers to implementation classes.
"""

# Create a visualization instance
viz = TableViz(datasource, form_data)

# Get visualization data
chart_data = viz.get_json_data()

# Cache the results
cache_key = viz.cache_key()

class CustomViz(BaseViz):
    """Custom visualization implementation."""
    
    viz_type = 'custom_chart'
    verbose_name = 'Custom Chart'
    is_timeseries = False
    
    def get_df(self):
        # Custom data processing
        return super().get_df()
    
    def get_json_data(self):
        # Custom JSON formatting
        return {
            'data': self.get_df().to_dict('records'),
            'config': self.form_data
        }

# Register custom visualization
viz_types['custom_chart'] = CustomViz