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

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,
+            )

bidviz_polars/transformers/kpi.py

@@ -0,0 +1,60 @@
+"""KPI Cards transformer for Polars DataFrames."""
+
+from typing import Any, Dict
+
+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
+
+
+class KPICardsTransformer(BaseChartTransformer):
+    """Transform single-row Polars DataFrame into KPI cards."""
+
+    def transform(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
+        """
+        try:
+            if len(df) == 0:
+                return {"chart_type": "kpi_cards", "data": []}
+
+            if len(df) > 1:
+                raise TransformationError(
+                    "KPI cards expect a single-row DataFrame",
+                    chart_type="kpi_cards",
+                    df_shape=df.shape,
+                )
+
+            row = df.row(0, named=True)
+            cards = []
+
+            for column in df.columns:
+                cards.append(
+                    {
+                        "key": column,
+                        "label": format_label(column),
+                        "value": safe_get_value(row[column]),
+                    }
+                )
+
+            return {"chart_type": "kpi_cards", "data": cards}
+
+        except Exception as e:
+            if isinstance(e, TransformationError):
+                raise
+            raise TransformationError(
+                f"Failed to transform KPI cards: {str(e)}",
+                chart_type="kpi_cards",
+                df_shape=df.shape,
+            )

bidviz_polars/transformers/line.py

@@ -0,0 +1,126 @@
+"""Line chart 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, safe_get_value, validate_columns
+
+
+class LineChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into line chart data."""
+
+    def transform(
+        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
+        """
+        try:
+            validate_columns(df, [x_column, y_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]),
+                    }
+                )
+
+            return {
+                "chart_type": "line_chart",
+                "data": data,
+                "series_name": series_name or format_label(y_column),
+                "x_label": format_label(x_column),
+                "y_label": format_label(y_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="line_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform line chart: {str(e)}",
+                chart_type="line_chart",
+                df_shape=df.shape,
+            )
+
+
+class MultiLineChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into multi-line chart data."""
+
+    def transform(
+        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
+        """
+        try:
+            validate_columns(df, [x_column] + y_columns)
+
+            if series_names and len(series_names) != len(y_columns):
+                raise TransformationError(
+                    "Number of series_names must match number of y_columns",
+                    chart_type="multi_line_chart",
+                )
+
+            series = []
+            for idx, y_col in enumerate(y_columns):
+                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_col]),
+                        }
+                    )
+
+                series.append(
+                    {
+                        "name": series_names[idx] if series_names else format_label(y_col),
+                        "data": data,
+                    }
+                )
+
+            return {
+                "chart_type": "multi_line_chart",
+                "series": series,
+                "x_label": format_label(x_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="multi_line_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform multi-line chart: {str(e)}",
+                chart_type="multi_line_chart",
+                df_shape=df.shape,
+            )

bidviz_polars/transformers/other.py

@@ -0,0 +1,108 @@
+"""Funnel and stacked bar chart 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, safe_get_value, validate_columns
+
+
+class FunnelChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into funnel chart data."""
+
+    def transform(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
+        """
+        try:
+            validate_columns(df, [stage_column, value_column])
+
+            data = []
+            for row in df.iter_rows(named=True):
+                data.append(
+                    {
+                        "stage": str(safe_get_value(row[stage_column])),
+                        "value": safe_get_value(row[value_column]),
+                    }
+                )
+
+            return {"chart_type": "funnel_chart", "data": data}
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="funnel_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform funnel chart: {str(e)}",
+                chart_type="funnel_chart",
+                df_shape=df.shape,
+            )
+
+
+class StackedBarChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into stacked bar chart data."""
+
+    def transform(
+        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
+        """
+        try:
+            validate_columns(df, [x_column] + y_columns)
+
+            if category_names and len(category_names) != len(y_columns):
+                raise TransformationError(
+                    "Number of category_names must match number of y_columns",
+                    chart_type="stacked_bar_chart",
+                )
+
+            data = []
+            for row in df.iter_rows(named=True):
+                point = {"x": str(safe_get_value(row[x_column]))}
+                for y_col in y_columns:
+                    point[y_col] = safe_get_value(row[y_col])
+                data.append(point)
+
+            categories = [
+                category_names[i] if category_names else format_label(y_col)
+                for i, y_col in enumerate(y_columns)
+            ]
+
+            return {
+                "chart_type": "stacked_bar_chart",
+                "data": data,
+                "categories": categories,
+                "x_label": format_label(x_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="stacked_bar_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform stacked bar chart: {str(e)}",
+                chart_type="stacked_bar_chart",
+                df_shape=df.shape,
+            )

bidviz_polars/transformers/pie.py

@@ -0,0 +1,57 @@
+"""Pie chart transformer for Polars DataFrames."""
+
+from typing import Any, Dict
+
+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 PieChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into pie chart data."""
+
+    def transform(
+        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
+
+        Raises:
+            TransformationError: If required columns are missing
+        """
+        try:
+            validate_columns(df, [label_column, value_column])
+
+            data = []
+            for row in df.iter_rows(named=True):
+                data.append(
+                    {
+                        "label": str(safe_get_value(row[label_column])),
+                        "value": safe_get_value(row[value_column]),
+                    }
+                )
+
+            return {
+                "chart_type": "pie_chart",
+                "data": data,
+                "label": format_label(label_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="pie_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform pie chart: {str(e)}",
+                chart_type="pie_chart",
+                df_shape=df.shape,
+            )

bidviz_polars/transformers/table.py

@@ -0,0 +1,48 @@
+"""Data table transformer for Polars DataFrames."""
+
+from typing import Any, Dict
+
+import polars as pl
+
+from bidviz.exceptions import TransformationError
+from bidviz_polars.core.base import BaseChartTransformer
+from bidviz_polars.utils import format_label, paginate_dataframe, safe_get_value
+
+
+class DataTableTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into paginated data table."""
+
+    def transform(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
+        """
+        try:
+            paginated_df, metadata = paginate_dataframe(df, page, page_size)
+
+            columns = []
+            for col in df.columns:
+                columns.append({"key": col, "label": format_label(col)})
+
+            rows = []
+            for row in paginated_df.iter_rows(named=True):
+                row_data = {}
+                for col in df.columns:
+                    row_data[col] = safe_get_value(row[col])
+                rows.append(row_data)
+
+            return {"chart_type": "data_table", "columns": columns, "rows": rows, **metadata}
+
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform data table: {str(e)}",
+                chart_type="data_table",
+                df_shape=df.shape,
+            )