bidviz 1.0.0__py3-none-any.whl

bidviz/__init__.py

@@ -0,0 +1,14 @@
+"""
+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.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Mohammad Amin Khara"
+
+from bidviz.exceptions import TransformationError, ValidationError
+from bidviz.transformer import ChartTransformer
+
+__all__ = ["ChartTransformer", "TransformationError", "ValidationError"]

bidviz/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core module initialization."""
+
+from bidviz.core.base import BaseChartTransformer
+
+__all__ = ["BaseChartTransformer"]

bidviz/core/base.py

@@ -0,0 +1,43 @@
+"""Base transformer class for all chart transformations."""
+
+from typing import Any, Dict
+
+import pandas as pd
+
+
+class BaseChartTransformer:
+    """
+    Base class for chart transformers.
+
+    All specific chart transformers should inherit from this class
+    and implement the transform method.
+    """
+
+    def transform(self, df: pd.DataFrame, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Transform a DataFrame into chart-ready format.
+
+        Args:
+            df: Input 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: pd.DataFrame) -> None:
+        """
+        Validate that DataFrame is not None and has data.
+
+        Args:
+            df: DataFrame to validate
+
+        Raises:
+            ValueError: If DataFrame is None
+        """
+        if df is None:
+            raise ValueError("DataFrame cannot be None")

bidviz/exceptions.py

@@ -0,0 +1,69 @@
+"""
+Custom exceptions for BidViz library.
+"""
+
+
+class BidVizError(Exception):
+    """Base exception for all BidViz errors."""
+
+    pass
+
+
+class TransformationError(BidVizError):
+    """
+    Exception raised when data transformation fails.
+
+    Attributes:
+        message (str): Explanation of the error
+        chart_type (str): Type of chart being transformed
+        df_shape (tuple): Shape of the DataFrame (rows, columns)
+        missing_columns (list): List of missing column names
+    """
+
+    def __init__(
+        self,
+        message: str,
+        chart_type: str = None,
+        df_shape: tuple = None,
+        missing_columns: list = None,
+    ):
+        self.message = message
+        self.chart_type = chart_type
+        self.df_shape = df_shape
+        self.missing_columns = missing_columns or []
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        details = [self.message]
+        if self.chart_type:
+            details.append(f"Chart Type: {self.chart_type}")
+        if self.df_shape:
+            details.append(f"DataFrame Shape: {self.df_shape}")
+        if self.missing_columns:
+            details.append(f"Missing Columns: {', '.join(self.missing_columns)}")
+        return " | ".join(details)
+
+
+class ValidationError(BidVizError):
+    """
+    Exception raised when data validation fails.
+
+    Attributes:
+        message (str): Explanation of the validation error
+        column (str): Column name that failed validation
+        validation_type (str): Type of validation that failed
+    """
+
+    def __init__(self, message: str, column: str = None, validation_type: str = None):
+        self.message = message
+        self.column = column
+        self.validation_type = validation_type
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        details = [self.message]
+        if self.column:
+            details.append(f"Column: {self.column}")
+        if self.validation_type:
+            details.append(f"Validation Type: {self.validation_type}")
+        return " | ".join(details)

bidviz/transformer.py

@@ -0,0 +1,312 @@
+"""
+Core chart transformation service - facade for all chart transformers.
+"""
+
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+from bidviz.transformers import (
+    BarChartTransformer,
+    CorrelationHeatmapTransformer,
+    DataTableTransformer,
+    FunnelChartTransformer,
+    HeatmapTransformer,
+    KPICardsTransformer,
+    LineChartTransformer,
+    MultiLineChartTransformer,
+    PieChartTransformer,
+    StackedBarChartTransformer,
+)
+
+
+class ChartTransformer:
+    """
+    Main facade for transforming pandas DataFrames into chart-ready data structures.
+
+    This class provides a unified interface to all chart transformers,
+    converting raw DataFrames into JSON-serializable formats optimized
+    for various charting libraries (Chart.js, D3, Plotly, Recharts, etc.).
+
+    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:
+        >>> transformer = ChartTransformer()
+        >>> df = pd.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: pd.DataFrame) -> Dict[str, Any]:
+        """
+        Transform a single-row DataFrame into KPI cards for dashboard metrics.
+
+        Args:
+            df: Single-row 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 = pd.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: pd.DataFrame,
+        x_column: str,
+        y_column: str,
+        label_column: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into bar chart data structure.
+
+        Args:
+            df: 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 = pd.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: pd.DataFrame,
+        x_column: str,
+        y_column: str,
+        series_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into line chart data for time series or trends.
+
+        Args:
+            df: 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 = pd.DataFrame({'date': pd.date_range('2024-01-01', periods=3),
+            ...                    '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: pd.DataFrame,
+        x_column: str,
+        y_columns: List[str],
+        series_names: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into multi-line chart for comparing multiple series.
+
+        Args:
+            df: 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 = pd.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: pd.DataFrame, label_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into pie chart data for part-to-whole relationships.
+
+        Args:
+            df: 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 = pd.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: pd.DataFrame, x_column: str, y_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into heatmap data for 2D intensity visualization.
+
+        Args:
+            df: 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 = pd.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: pd.DataFrame, stage_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into funnel chart data for conversion pipelines.
+
+        Args:
+            df: 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 = pd.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: pd.DataFrame,
+        x_column: str,
+        y_columns: List[str],
+        category_names: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into stacked bar chart for composed comparisons.
+
+        Args:
+            df: 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 = pd.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: pd.DataFrame, page: int = 1, page_size: int = 50
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into paginated data table structure.
+
+        Args:
+            df: 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 = pd.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: pd.DataFrame, metrics: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into correlation heatmap for statistical analysis.
+
+        Args:
+            df: DataFrame containing numeric columns
+            metrics: Optional list of column names to correlate
+
+        Returns:
+            Dict with chart_type='heatmap' and correlation data
+
+        Examples:
+            >>> df = pd.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/transformers/__init__.py

@@ -0,0 +1,22 @@
+"""Transformers module initialization."""
+
+from bidviz.transformers.bar import BarChartTransformer
+from bidviz.transformers.heatmap import CorrelationHeatmapTransformer, HeatmapTransformer
+from bidviz.transformers.kpi import KPICardsTransformer
+from bidviz.transformers.line import LineChartTransformer, MultiLineChartTransformer
+from bidviz.transformers.other import FunnelChartTransformer, StackedBarChartTransformer
+from bidviz.transformers.pie import PieChartTransformer
+from bidviz.transformers.table import DataTableTransformer
+
+__all__ = [
+    "KPICardsTransformer",
+    "BarChartTransformer",
+    "LineChartTransformer",
+    "MultiLineChartTransformer",
+    "PieChartTransformer",
+    "HeatmapTransformer",
+    "FunnelChartTransformer",
+    "StackedBarChartTransformer",
+    "DataTableTransformer",
+    "CorrelationHeatmapTransformer",
+]

bidviz/transformers/bar.py

@@ -0,0 +1,68 @@
+"""Bar chart transformer."""
+
+from typing import Any, Dict, Optional
+
+import pandas as pd
+
+from bidviz.core.base import BaseChartTransformer
+from bidviz.exceptions import TransformationError
+from bidviz.utils import format_label, safe_get_value, validate_columns
+
+
+class BarChartTransformer(BaseChartTransformer):
+    """Transform DataFrame into bar chart data."""
+
+    def transform(
+        self,
+        df: pd.DataFrame,
+        x_column: str,
+        y_column: str,
+        label_column: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into bar chart data structure.
+
+        Args:
+            df: 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.iterrows():
+                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/transformers/heatmap.py

@@ -0,0 +1,116 @@
+"""Heatmap transformers."""
+
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+from bidviz.core.base import BaseChartTransformer
+from bidviz.exceptions import TransformationError
+from bidviz.utils import format_label, get_numeric_columns, safe_get_value, validate_columns
+
+
+class HeatmapTransformer(BaseChartTransformer):
+    """Transform DataFrame into heatmap data."""
+
+    def transform(
+        self, df: pd.DataFrame, x_column: str, y_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform DataFrame into heatmap data for 2D intensity visualization.
+
+        Args:
+            df: 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.iterrows():
+                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 DataFrame into correlation heatmap."""
+
+    def transform(self, df: pd.DataFrame, metrics: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        Transform DataFrame into correlation heatmap for statistical analysis.
+
+        Args:
+            df: 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)
+            corr_matrix = df[metrics].corr()
+
+            data = []
+            for x_metric in metrics:
+                for y_metric in metrics:
+                    data.append(
+                        {
+                            "x": x_metric,
+                            "y": y_metric,
+                            "value": safe_get_value(corr_matrix.loc[y_metric, x_metric]),
+                        }
+                    )
+
+            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,
+            )