bidviz 1.0.0__py3-none-any.whl

bidviz/transformers/kpi.py

@@ -0,0 +1,60 @@
+"""KPI Cards transformer."""
+
+from typing import Any, Dict
+
+import pandas as pd
+
+from bidviz.core.base import BaseChartTransformer
+from bidviz.exceptions import TransformationError
+from bidviz.utils import format_label, safe_get_value
+
+
+class KPICardsTransformer(BaseChartTransformer):
+    """Transform single-row DataFrame into KPI cards."""
+
+    def transform(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
+        """
+        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.iloc[0]
+            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/transformers/line.py

@@ -0,0 +1,126 @@
+"""Line chart 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, safe_get_value, validate_columns
+
+
+class LineChartTransformer(BaseChartTransformer):
+    """Transform DataFrame into line chart data."""
+
+    def transform(
+        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
+        """
+        try:
+            validate_columns(df, [x_column, y_column])
+
+            data = []
+            for _, row in df.iterrows():
+                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 DataFrame into multi-line chart data."""
+
+    def transform(
+        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
+        """
+        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.iterrows():
+                    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/transformers/other.py

@@ -0,0 +1,108 @@
+"""Funnel and stacked bar chart 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, safe_get_value, validate_columns
+
+
+class FunnelChartTransformer(BaseChartTransformer):
+    """Transform DataFrame into funnel chart data."""
+
+    def transform(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
+        """
+        try:
+            validate_columns(df, [stage_column, value_column])
+
+            data = []
+            for _, row in df.iterrows():
+                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 DataFrame into stacked bar chart data."""
+
+    def transform(
+        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
+        """
+        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.iterrows():
+                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/transformers/pie.py

@@ -0,0 +1,48 @@
+"""Pie and donut chart transformers."""
+
+from typing import Any, Dict
+
+import pandas as pd
+
+from bidviz.core.base import BaseChartTransformer
+from bidviz.exceptions import TransformationError
+from bidviz.utils import safe_get_value, validate_columns
+
+
+class PieChartTransformer(BaseChartTransformer):
+    """Transform DataFrame into pie chart data."""
+
+    def transform(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
+        """
+        try:
+            validate_columns(df, [label_column, value_column])
+
+            data = []
+            for _, row in df.iterrows():
+                data.append(
+                    {
+                        "label": str(safe_get_value(row[label_column])),
+                        "value": safe_get_value(row[value_column]),
+                    }
+                )
+
+            return {"chart_type": "pie_chart", "data": data}
+
+        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/transformers/table.py

@@ -0,0 +1,48 @@
+"""Data table transformer."""
+
+from typing import Any, Dict
+
+import pandas as pd
+
+from bidviz.core.base import BaseChartTransformer
+from bidviz.exceptions import TransformationError
+from bidviz.utils import format_label, paginate_dataframe, safe_get_value
+
+
+class DataTableTransformer(BaseChartTransformer):
+    """Transform DataFrame into paginated data table."""
+
+    def transform(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
+        """
+        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.iterrows():
+                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,
+            )

bidviz/utils.py

@@ -0,0 +1,187 @@
+"""
+Utility functions for data transformation and formatting.
+"""
+
+from typing import Any, List, Optional
+
+import numpy as np
+import pandas as pd
+
+
+def safe_get_value(value: Any) -> Any:
+    """
+    Safely extract a value from pandas objects, converting NaN to None.
+
+    Args:
+        value: Value to extract (can be pandas scalar, numpy type, or Python type)
+
+    Returns:
+        Python-native value with NaN converted to None
+
+    Examples:
+        >>> safe_get_value(pd.NA)
+        None
+        >>> safe_get_value(np.nan)
+        None
+        >>> safe_get_value(42)
+        42
+    """
+    if pd.isna(value):
+        return None
+    if isinstance(value, (np.integer, np.floating)):
+        return float(value) if isinstance(value, np.floating) else int(value)
+    if isinstance(value, np.bool_):
+        return bool(value)
+    if isinstance(value, (pd.Timestamp, np.datetime64)):
+        return str(value)
+    return value
+
+
+def format_label(column_name: str) -> str:
+    """
+    Convert snake_case column name to Title Case label.
+
+    Args:
+        column_name: Column name in snake_case format
+
+    Returns:
+        Formatted label in Title Case
+
+    Examples:
+        >>> format_label('total_gmv')
+        'Total Gmv'
+        >>> format_label('customer_id')
+        'Customer Id'
+        >>> format_label('avg_days_to_ship')
+        'Avg Days To Ship'
+    """
+    return column_name.replace("_", " ").title()
+
+
+def validate_columns(df: pd.DataFrame, required_columns: List[str]) -> None:
+    """
+    Validate that required columns exist in the DataFrame.
+
+    Args:
+        df: DataFrame to validate
+        required_columns: List of required column names
+
+    Raises:
+        ValueError: If any required columns are missing
+
+    Examples:
+        >>> df = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
+        >>> validate_columns(df, ['a', 'b'])  # No error
+        >>> validate_columns(df, ['a', 'c'])  # Raises ValueError
+        Traceback (most recent call last):
+        ...
+        ValueError: Missing required columns: c
+    """
+    missing = [col for col in required_columns if col not in df.columns]
+    if missing:
+        raise ValueError(f"Missing required columns: {', '.join(missing)}")
+
+
+def safe_convert_to_numeric(series: pd.Series) -> pd.Series:
+    """
+    Safely convert a pandas Series to numeric type.
+
+    Args:
+        series: Series to convert
+
+    Returns:
+        Numeric series with errors coerced to NaN
+
+    Examples:
+        >>> s = pd.Series(['1', '2', 'abc'])
+        >>> safe_convert_to_numeric(s)
+        0    1.0
+        1    2.0
+        2    NaN
+        dtype: float64
+    """
+    return pd.to_numeric(series, errors="coerce")
+
+
+def clean_dataframe(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Clean DataFrame column names by converting to lowercase and replacing spaces.
+
+    Args:
+        df: DataFrame to clean
+
+    Returns:
+        DataFrame with cleaned column names
+
+    Examples:
+        >>> df = pd.DataFrame({'Total GMV': [100], 'Customer Name': ['John']})
+        >>> clean_df = clean_dataframe(df)
+        >>> list(clean_df.columns)
+        ['total_gmv', 'customer_name']
+    """
+    df = df.copy()
+    df.columns = df.columns.str.lower().str.replace(" ", "_")
+    return df
+
+
+def get_numeric_columns(df: pd.DataFrame) -> List[str]:
+    """
+    Get list of numeric column names from DataFrame.
+
+    Args:
+        df: DataFrame to analyze
+
+    Returns:
+        List of numeric column names
+
+    Examples:
+        >>> df = pd.DataFrame({'a': [1, 2], 'b': ['x', 'y'], 'c': [1.5, 2.5]})
+        >>> get_numeric_columns(df)
+        ['a', 'c']
+    """
+    return df.select_dtypes(include=[np.number]).columns.tolist()
+
+
+def paginate_dataframe(
+    df: pd.DataFrame, page: int = 1, page_size: int = 50
+) -> tuple[pd.DataFrame, dict]:
+    """
+    Paginate a DataFrame and return pagination metadata.
+
+    Args:
+        df: DataFrame to paginate
+        page: Page number (1-indexed)
+        page_size: Number of rows per page
+
+    Returns:
+        Tuple of (paginated DataFrame, pagination metadata dict)
+
+    Examples:
+        >>> df = pd.DataFrame({'a': range(100)})
+        >>> page_df, meta = paginate_dataframe(df, page=2, page_size=25)
+        >>> len(page_df)
+        25
+        >>> meta['total']
+        100
+        >>> meta['page']
+        2
+    """
+    total = len(df)
+    total_pages = (total + page_size - 1) // page_size  # Ceiling division
+
+    # Ensure page is within valid range
+    page = max(1, min(page, total_pages if total_pages > 0 else 1))
+
+    start_idx = (page - 1) * page_size
+    end_idx = start_idx + page_size
+
+    paginated_df = df.iloc[start_idx:end_idx]
+
+    metadata = {
+        "total": total,
+        "page": page,
+        "page_size": page_size,
+        "total_pages": total_pages,
+    }
+
+    return paginated_df, metadata