bidviz 1.0.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

bidviz/__init__.py

@@ -3,6 +3,8 @@ BidViz - Backend Visualization Data Transformation Library
 
 A powerful, configurable backend visualization data transformation library designed to bridge
 the gap between raw data and frontend charting libraries.
+
+Supports both pandas and Polars backends for high-performance data transformation.
 """
 
 __version__ = "1.0.0"

bidviz/polars/__init__.py

@@ -0,0 +1,51 @@
+"""
+BidViz Polars - High-performance chart data transformation using Polars.
+
+This module provides Polars-based transformers for converting Polars DataFrames
+into JSON-serializable formats optimized for frontend charting libraries.
+
+Polars offers superior performance compared to pandas, especially for larger datasets,
+with lazy evaluation, parallel processing, and memory efficiency.
+
+Main Classes:
+    ChartTransformer: Facade for all Polars-based chart transformations
+    TransformationError: Exception for transformation failures
+    ValidationError: Exception for validation failures
+
+Example:
+    >>> import polars as pl
+    >>> from bidviz.polars import ChartTransformer
+    >>>
+    >>> transformer = ChartTransformer()
+    >>> df = pl.DataFrame({'vendor': ['A', 'B'], 'revenue': [100, 200]})
+    >>> result = transformer.transform_to_bar_chart(df, 'vendor', 'revenue')
+"""
+
+from bidviz.exceptions import TransformationError, ValidationError
+from bidviz.polars.transformer import ChartTransformer
+from bidviz.polars.utils import (
+    clean_dataframe,
+    dataframe_to_dicts,
+    format_label,
+    get_numeric_columns,
+    paginate_dataframe,
+    safe_convert_to_numeric,
+    safe_get_value,
+    validate_columns,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ChartTransformer",
+    "TransformationError",
+    "ValidationError",
+    "clean_dataframe",
+    "dataframe_to_dicts",
+    "format_label",
+    "get_numeric_columns",
+    "paginate_dataframe",
+    "safe_convert_to_numeric",
+    "safe_get_value",
+    "validate_columns",
+]

bidviz/polars/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core base classes for Polars transformers."""
+
+from bidviz.polars.core.base import BaseChartTransformer
+
+__all__ = ["BaseChartTransformer"]

bidviz/polars/core/base.py

@@ -0,0 +1,43 @@
+"""Base transformer class for all Polars chart transformations."""
+
+from typing import Any, Dict
+
+import polars as pl
+
+
+class BaseChartTransformer:
+    """
+    Base class for Polars chart transformers.
+
+    All specific chart transformers should inherit from this class
+    and implement the transform method.
+    """
+
+    def transform(self, df: pl.DataFrame, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Transform a Polars DataFrame into chart-ready format.
+
+        Args:
+            df: Input Polars DataFrame
+            **kwargs: Additional transformation parameters
+
+        Returns:
+            Dictionary containing chart data and metadata
+
+        Raises:
+            NotImplementedError: If not implemented by subclass
+        """
+        raise NotImplementedError("Subclasses must implement transform method")
+
+    def _validate_dataframe(self, df: pl.DataFrame) -> None:
+        """
+        Validate that DataFrame is not None and has data.
+
+        Args:
+            df: Polars DataFrame to validate
+
+        Raises:
+            ValueError: If DataFrame is None
+        """
+        if df is None:
+            raise ValueError("DataFrame cannot be None")

bidviz/polars/transformer.py

@@ -0,0 +1,337 @@
+"""
+Core chart transformation service for Polars - facade for all chart transformers.
+
+This module provides high-performance data transformations using Polars,
+offering significantly better performance than pandas for larger datasets.
+"""
+
+from typing import Any, Dict, List, Optional
+
+import polars as pl
+
+from bidviz.polars.transformers import (
+    BarChartTransformer,
+    CorrelationHeatmapTransformer,
+    DataTableTransformer,
+    FunnelChartTransformer,
+    HeatmapTransformer,
+    KPICardsTransformer,
+    LineChartTransformer,
+    MultiLineChartTransformer,
+    PieChartTransformer,
+    StackedBarChartTransformer,
+)
+
+
+class ChartTransformer:
+    """
+    Main facade for transforming Polars DataFrames into chart-ready data structures.
+
+    This class provides a unified interface to all chart transformers,
+    converting raw Polars DataFrames into JSON-serializable formats optimized
+    for various charting libraries (Chart.js, D3, Plotly, Recharts, etc.).
+
+    Polars provides superior performance compared to pandas through:
+    - Lazy evaluation and query optimization
+    - Parallel execution on all available cores
+    - Memory-efficient columnar storage
+    - Zero-copy operations where possible
+
+    The actual transformation logic is delegated to specialized transformer
+    classes for maintainability and modularity.
+
+    Supported chart types:
+        - KPI Cards
+        - Bar Chart
+        - Line Chart
+        - Multi-Line Chart
+        - Pie Chart
+        - Heatmap
+        - Funnel Chart
+        - Stacked Bar Chart
+        - Data Table (with pagination)
+        - Correlation Heatmap
+
+    Examples:
+        >>> import polars as pl
+        >>> transformer = ChartTransformer()
+        >>> df = pl.DataFrame({'vendor': ['A', 'B'], 'revenue': [100, 200]})
+        >>> result = transformer.transform_to_bar_chart(df, 'vendor', 'revenue')
+        >>> result['chart_type']
+        'bar_chart'
+    """
+
+    def __init__(self) -> None:
+        """Initialize the chart transformer with all specialized transformers."""
+        self._kpi_transformer = KPICardsTransformer()
+        self._bar_transformer = BarChartTransformer()
+        self._line_transformer = LineChartTransformer()
+        self._multi_line_transformer = MultiLineChartTransformer()
+        self._pie_transformer = PieChartTransformer()
+        self._heatmap_transformer = HeatmapTransformer()
+        self._funnel_transformer = FunnelChartTransformer()
+        self._stacked_bar_transformer = StackedBarChartTransformer()
+        self._table_transformer = DataTableTransformer()
+        self._correlation_transformer = CorrelationHeatmapTransformer()
+
+    def transform_to_kpi_cards(self, df: pl.DataFrame) -> Dict[str, Any]:
+        """
+        Transform a single-row Polars DataFrame into KPI cards for dashboard metrics.
+
+        Args:
+            df: Single-row Polars DataFrame containing metrics
+
+        Returns:
+            Dict with chart_type='kpi_cards' and list of card data
+
+        Raises:
+            TransformationError: If DataFrame has more than one row
+
+        Examples:
+            >>> df = pl.DataFrame({'total_orders': [150], 'revenue': [45000.50]})
+            >>> result = transformer.transform_to_kpi_cards(df)
+            >>> len(result['data'])
+            2
+        """
+        return self._kpi_transformer.transform(df)
+
+    def transform_to_bar_chart(
+        self,
+        df: pl.DataFrame,
+        x_column: str,
+        y_column: str,
+        label_column: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into bar chart data structure.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis (categorical)
+            y_column: Column name for y-axis (numeric)
+            label_column: Optional column for custom labels
+
+        Returns:
+            Dict with chart_type='bar_chart', data points, and axis labels
+
+        Examples:
+            >>> df = pl.DataFrame({'vendor': ['A', 'B'], 'revenue': [1000, 1500]})
+            >>> result = transformer.transform_to_bar_chart(df, 'vendor', 'revenue')
+            >>> result['chart_type']
+            'bar_chart'
+        """
+        return self._bar_transformer.transform(df, x_column, y_column, label_column)
+
+    def transform_to_line_chart(
+        self,
+        df: pl.DataFrame,
+        x_column: str,
+        y_column: str,
+        series_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into line chart data for time series or trends.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis
+            y_column: Column name for y-axis
+            series_name: Optional custom name for the data series
+
+        Returns:
+            Dict with chart_type='line_chart', data points, and labels
+
+        Examples:
+            >>> df = pl.DataFrame({
+            ...     'date': ['2024-01-01', '2024-01-02', '2024-01-03'],
+            ...     'orders': [10, 15, 12]
+            ... })
+            >>> result = transformer.transform_to_line_chart(df, 'date', 'orders')
+            >>> result['series_name']
+            'Orders'
+        """
+        return self._line_transformer.transform(df, x_column, y_column, series_name)
+
+    def transform_to_multi_line_chart(
+        self,
+        df: pl.DataFrame,
+        x_column: str,
+        y_columns: List[str],
+        series_names: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into multi-line chart for comparing multiple series.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis
+            y_columns: List of column names for y-axis
+            series_names: Optional custom names for each series
+
+        Returns:
+            Dict with chart_type='multi_line_chart' and series data
+
+        Examples:
+            >>> df = pl.DataFrame({
+            ...     'date': ['2024-01-01', '2024-01-02'],
+            ...     'vendor_a': [10, 15],
+            ...     'vendor_b': [12, 18]
+            ... })
+            >>> result = transformer.transform_to_multi_line_chart(
+            ...     df, 'date', ['vendor_a', 'vendor_b'])
+            >>> len(result['series'])
+            2
+        """
+        return self._multi_line_transformer.transform(df, x_column, y_columns, series_names)
+
+    def transform_to_pie_chart(
+        self, df: pl.DataFrame, label_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into pie chart data for part-to-whole relationships.
+
+        Args:
+            df: Polars DataFrame containing the data
+            label_column: Column name for slice labels
+            value_column: Column name for slice values
+
+        Returns:
+            Dict with chart_type='pie_chart' and data points
+
+        Examples:
+            >>> df = pl.DataFrame({'category': ['A', 'B'], 'sales': [45000, 32000]})
+            >>> result = transformer.transform_to_pie_chart(df, 'category', 'sales')
+            >>> len(result['data'])
+            2
+        """
+        return self._pie_transformer.transform(df, label_column, value_column)
+
+    def transform_to_heatmap(
+        self, df: pl.DataFrame, x_column: str, y_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into heatmap data for 2D intensity visualization.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis
+            y_column: Column name for y-axis
+            value_column: Column name for cell values
+
+        Returns:
+            Dict with chart_type='heatmap', data points, and labels
+
+        Examples:
+            >>> df = pl.DataFrame({
+            ...     'hour': [0, 1],
+            ...     'day': ['Mon', 'Mon'],
+            ...     'count': [12, 8]
+            ... })
+            >>> result = transformer.transform_to_heatmap(df, 'hour', 'day', 'count')
+            >>> result['chart_type']
+            'heatmap'
+        """
+        return self._heatmap_transformer.transform(df, x_column, y_column, value_column)
+
+    def transform_to_funnel_chart(
+        self, df: pl.DataFrame, stage_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into funnel chart data for conversion pipelines.
+
+        Args:
+            df: Polars DataFrame containing the data
+            stage_column: Column name for funnel stages
+            value_column: Column name for stage values
+
+        Returns:
+            Dict with chart_type='funnel_chart' and data points
+
+        Examples:
+            >>> df = pl.DataFrame({
+            ...     'stage': ['Visits', 'Sign-ups'],
+            ...     'count': [1000, 300]
+            ... })
+            >>> result = transformer.transform_to_funnel_chart(df, 'stage', 'count')
+            >>> len(result['data'])
+            2
+        """
+        return self._funnel_transformer.transform(df, stage_column, value_column)
+
+    def transform_to_stacked_bar_chart(
+        self,
+        df: pl.DataFrame,
+        x_column: str,
+        y_columns: List[str],
+        category_names: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into stacked bar chart for composed comparisons.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis
+            y_columns: List of column names for stacked values
+            category_names: Optional custom names for each stack
+
+        Returns:
+            Dict with chart_type='stacked_bar_chart' and data
+
+        Examples:
+            >>> df = pl.DataFrame({
+            ...     'month': ['Jan', 'Feb'],
+            ...     'product_a': [100, 150],
+            ...     'product_b': [200, 180]
+            ... })
+            >>> result = transformer.transform_to_stacked_bar_chart(
+            ...     df, 'month', ['product_a', 'product_b'])
+            >>> len(result['categories'])
+            2
+        """
+        return self._stacked_bar_transformer.transform(df, x_column, y_columns, category_names)
+
+    def transform_to_data_table(
+        self, df: pl.DataFrame, page: int = 1, page_size: int = 50
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into paginated data table structure.
+
+        Args:
+            df: Polars DataFrame containing the data
+            page: Page number (1-indexed)
+            page_size: Number of rows per page
+
+        Returns:
+            Dict with chart_type='data_table', columns, rows, and pagination
+
+        Examples:
+            >>> df = pl.DataFrame({'id': [1, 2, 3], 'name': ['A', 'B', 'C']})
+            >>> result = transformer.transform_to_data_table(df, page=1, page_size=2)
+            >>> len(result['rows'])
+            2
+        """
+        return self._table_transformer.transform(df, page, page_size)
+
+    def transform_to_correlation_heatmap(
+        self, df: pl.DataFrame, metrics: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into correlation heatmap for statistical analysis.
+
+        Args:
+            df: Polars DataFrame containing numeric columns
+            metrics: Optional list of column names to correlate
+
+        Returns:
+            Dict with chart_type='heatmap' and correlation data
+
+        Examples:
+            >>> df = pl.DataFrame({
+            ...     'revenue': [100, 200, 150],
+            ...     'orders': [10, 20, 15]
+            ... })
+            >>> result = transformer.transform_to_correlation_heatmap(df)
+            >>> result['chart_type']
+            'heatmap'
+        """
+        return self._correlation_transformer.transform(df, metrics)

bidviz/polars/transformers/__init__.py

@@ -0,0 +1,31 @@
+"""Chart transformers for Polars DataFrames."""
+
+from bidviz.polars.transformers.bar import BarChartTransformer
+from bidviz.polars.transformers.heatmap import (
+    CorrelationHeatmapTransformer,
+    HeatmapTransformer,
+)
+from bidviz.polars.transformers.kpi import KPICardsTransformer
+from bidviz.polars.transformers.line import (
+    LineChartTransformer,
+    MultiLineChartTransformer,
+)
+from bidviz.polars.transformers.pie import PieChartTransformer
+from bidviz.polars.transformers.table import DataTableTransformer
+from bidviz.polars.transformers.other import (
+    FunnelChartTransformer,
+    StackedBarChartTransformer,
+)
+
+__all__ = [
+    "BarChartTransformer",
+    "LineChartTransformer",
+    "MultiLineChartTransformer",
+    "PieChartTransformer",
+    "KPICardsTransformer",
+    "HeatmapTransformer",
+    "CorrelationHeatmapTransformer",
+    "FunnelChartTransformer",
+    "StackedBarChartTransformer",
+    "DataTableTransformer",
+]

bidviz/polars/transformers/bar.py

@@ -0,0 +1,68 @@
+"""Bar chart transformer for Polars DataFrames."""
+
+from typing import Any, Dict, Optional
+
+import polars as pl
+
+from bidviz.exceptions import TransformationError
+from bidviz.polars.core.base import BaseChartTransformer
+from bidviz.polars.utils import format_label, safe_get_value, validate_columns
+
+
+class BarChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into bar chart data."""
+
+    def transform(
+        self,
+        df: pl.DataFrame,
+        x_column: str,
+        y_column: str,
+        label_column: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into bar chart data structure.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis (categorical)
+            y_column: Column name for y-axis (numeric)
+            label_column: Optional column for custom labels
+
+        Returns:
+            Dict with chart_type='bar_chart', data points, and axis labels
+
+        Raises:
+            TransformationError: If required columns are missing
+        """
+        try:
+            validate_columns(df, [x_column, y_column])
+            if label_column:
+                validate_columns(df, [label_column])
+            else:
+                label_column = x_column
+
+            data = []
+            for row in df.iter_rows(named=True):
+                data.append(
+                    {
+                        "x": str(safe_get_value(row[x_column])),
+                        "y": safe_get_value(row[y_column]),
+                        "label": str(safe_get_value(row[label_column])),
+                    }
+                )
+
+            return {
+                "chart_type": "bar_chart",
+                "data": data,
+                "x_label": format_label(x_column),
+                "y_label": format_label(y_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="bar_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform bar chart: {str(e)}",
+                chart_type="bar_chart",
+                df_shape=df.shape,
+            )

bidviz/polars/transformers/heatmap.py

@@ -0,0 +1,120 @@
+"""Heatmap transformers for Polars DataFrames."""
+
+from typing import Any, Dict, List, Optional
+
+import polars as pl
+
+from bidviz.exceptions import TransformationError
+from bidviz.polars.core.base import BaseChartTransformer
+from bidviz.polars.utils import format_label, get_numeric_columns, safe_get_value, validate_columns
+
+
+class HeatmapTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into heatmap data."""
+
+    def transform(
+        self, df: pl.DataFrame, x_column: str, y_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into heatmap data for 2D intensity visualization.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis
+            y_column: Column name for y-axis
+            value_column: Column name for cell values
+
+        Returns:
+            Dict with chart_type='heatmap', data points, and labels
+        """
+        try:
+            validate_columns(df, [x_column, y_column, value_column])
+
+            data = []
+            for row in df.iter_rows(named=True):
+                data.append(
+                    {
+                        "x": str(safe_get_value(row[x_column])),
+                        "y": str(safe_get_value(row[y_column])),
+                        "value": safe_get_value(row[value_column]),
+                    }
+                )
+
+            return {
+                "chart_type": "heatmap",
+                "data": data,
+                "x_label": format_label(x_column),
+                "y_label": format_label(y_column),
+                "value_label": format_label(value_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="heatmap", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform heatmap: {str(e)}",
+                chart_type="heatmap",
+                df_shape=df.shape,
+            )
+
+
+class CorrelationHeatmapTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into correlation heatmap."""
+
+    def transform(self, df: pl.DataFrame, metrics: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into correlation heatmap for statistical analysis.
+
+        Args:
+            df: Polars DataFrame containing numeric columns
+            metrics: Optional list of column names to correlate
+
+        Returns:
+            Dict with chart_type='heatmap' and correlation data
+        """
+        try:
+            if metrics is None:
+                metrics = get_numeric_columns(df)
+
+            if len(metrics) < 2:
+                raise TransformationError(
+                    "Need at least 2 numeric columns for correlation",
+                    chart_type="correlation_heatmap",
+                    df_shape=df.shape,
+                )
+
+            validate_columns(df, metrics)
+
+            # Polars uses corr() method on DataFrame
+            corr_matrix = df.select(metrics).corr()
+
+            data = []
+            for i, x_metric in enumerate(metrics):
+                for j, y_metric in enumerate(metrics):
+                    # Access correlation value from the matrix
+                    value = corr_matrix.row(j)[i]
+                    data.append(
+                        {
+                            "x": x_metric,
+                            "y": y_metric,
+                            "value": safe_get_value(value),
+                        }
+                    )
+
+            return {
+                "chart_type": "heatmap",
+                "data": data,
+                "metrics": metrics,
+                "x_label": "Metrics",
+                "y_label": "Metrics",
+                "value_label": "Correlation Coefficient",
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="correlation_heatmap", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform correlation heatmap: {str(e)}",
+                chart_type="correlation_heatmap",
+                df_shape=df.shape,
+            )