dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/decisions.py

@@ -0,0 +1,358 @@
+"""Chart decisions pipeline stage.
+
+Stage: between EXECUTE and RENDER (layout/sizing)
+Purpose: Enrich charts with data-aware defaults before rendering.
+
+This module analyzes query result data and enriches Chart objects
+with smarter defaults for axis domains and field assignment.
+It runs for ALL charts (not just type: auto).
+
+Pipeline position:
+    compile → execute → CHART DECISIONS → layout/sizing → render
+
+Key principle: every auto-decision is overridable by explicit YAML.
+If the user sets scale/fields, those win over any auto-detection.
+
+Format defaults come from the theme cascade (axis_quantitative.format in stark.yaml),
+not from column-name inference. Authors override per-chart via chart.format or
+style.axis_y.format.
+
+Dependencies:
+    - chart_type_detection (for column classification, reused here)
+
+Note on database driver compatibility:
+    The type_code mapping in db_type_to_dtype works for DuckDB (which uses
+    string type names like "INTEGER", "TIMESTAMP"). Other DB-API drivers use
+    opaque type codes (psycopg2 uses integer OIDs, sqlite3 returns None).
+    When type_code can't be mapped, the stage falls back to data-value heuristics.
+"""
+
+import math
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any
+
+from dataface.core.compile.models.chart.compiled import Chart
+from dataface.core.compile.models.style.authored import ChartStylePatch
+
+# Chart types that use x/y axes (not KPI, table, pie)
+_AXIS_CHART_TYPES = frozenset({"bar", "line", "area", "scatter", "heatmap"})
+
+# Chart types where zero anchoring is optional; the smart-auto heuristic applies.
+# Bar and area/heatmap fall through to the legacy ratio > 0.8 rule below.
+_OPTIONAL_ZERO_CHART_TYPES = frozenset({"line", "scatter"})
+
+# Threshold for smart-auto zero extension.  When data_min/data_max <= this value,
+# data starts in the bottom 25% of [0, max] and extending to zero adds honest
+# context without crushing the data.  Above the threshold, keep the data-fitted
+# domain.
+_ZERO_EXTEND_THRESHOLD = 0.25
+
+# PEP 249 cursor.description index constants
+_DESC_TYPE_CODE = 1
+
+# Database type strings → our dtype categories
+_NUMERIC_DB_TYPES = frozenset(
+    {
+        "BIGINT",
+        "INTEGER",
+        "INT",
+        "SMALLINT",
+        "TINYINT",
+        "DOUBLE",
+        "FLOAT",
+        "REAL",
+        "DECIMAL",
+        "NUMERIC",
+        "HUGEINT",
+        "UBIGINT",
+        "UINTEGER",
+        "USMALLINT",
+        "UTINYINT",
+        "NUMBER",
+        "MONEY",
+    }
+)
+_TEMPORAL_DB_TYPES = frozenset(
+    {
+        "DATE",
+        "TIME",
+        "DATETIME",
+        "TIMESTAMP",
+        "TIMESTAMPTZ",
+        "TIMESTAMP WITH TIME ZONE",
+        "TIMESTAMP WITHOUT TIME ZONE",
+        "INTERVAL",
+    }
+)
+_BOOLEAN_DB_TYPES = frozenset({"BOOLEAN", "BOOL"})
+
+
+@dataclass
+class ColumnProfile:
+    """Lightweight profile of a query result column."""
+
+    name: str
+    dtype: str  # "numeric", "temporal", "categorical"
+    min_val: float | None = None
+    max_val: float | None = None
+
+
+def db_type_to_dtype(db_type: str) -> str | None:
+    """Map a database type string to our dtype classification."""
+    upper = db_type.upper().split("(")[0].strip()
+    if upper in _NUMERIC_DB_TYPES:
+        return "numeric"
+    if upper in _TEMPORAL_DB_TYPES:
+        return "temporal"
+    if upper in _BOOLEAN_DB_TYPES:
+        return "categorical"
+    if upper.startswith("VARCHAR") or upper in ("TEXT", "CHAR", "STRING"):
+        return "categorical"
+    return None
+
+
+def enrich_chart(
+    chart: Chart,
+    data: list[dict[str, Any]],
+    column_descriptions: dict[str, tuple] | None = None,
+) -> Chart:
+    """Enrich chart with data-aware defaults.
+
+    Runs for ALL chart types. Layers applied in order (later override earlier):
+    1. Data value analysis (always available)
+    2. Database column metadata from cursor.description (when available; type_code
+       mapping works reliably for DuckDB which uses string type names; other drivers
+       fall back to value-based heuristics)
+    3. User YAML annotations (always win — never overridden)
+
+    Format defaults come from the theme cascade (axis_quantitative.format) —
+    not from inference here. Authors override via chart.format or style.axis_y.format.
+    """
+    if not data:
+        return chart
+
+    col_profiles = _profile_columns(data, column_descriptions)
+    updates: dict[str, Any] = {}
+
+    effective_type = chart.type
+
+    # Field assignment: only for chart types that use x/y axes
+    if effective_type in _AXIS_CHART_TYPES:
+        field_updates = _pick_fields(chart, col_profiles)
+        updates.update(field_updates)
+
+    effective_y = updates.get("y", chart.y)
+
+    # Only enrich axis-based charts with format/scale decisions
+    if effective_type in _AXIS_CHART_TYPES and effective_y:
+        y_field = effective_y[0] if isinstance(effective_y, list) else effective_y
+        y_profile = col_profiles.get(y_field)
+
+        if y_profile and y_profile.dtype == "numeric":
+            style_updates = _pick_axis_style(chart, y_profile)
+            if style_updates:
+                from dataface.core.compile.normalize_charts import (
+                    _AUTHORED_FAMILY_TO_MONOLITHIC_KEY,
+                )
+
+                family_key = _AUTHORED_FAMILY_TO_MONOLITHIC_KEY.get(effective_type)
+                existing = (
+                    chart.style.model_dump(exclude_none=True) if chart.style else {}
+                )
+                if family_key is not None:
+                    existing_fam = existing.get(family_key, {})
+                    existing_fam.update(style_updates)
+                    existing[family_key] = existing_fam
+                updates["style"] = ChartStylePatch.model_validate(existing)
+
+    if updates:
+        return chart.model_copy(update=updates)
+    return chart
+
+
+def _profile_columns(
+    data: list[dict[str, Any]],
+    column_descriptions: dict[str, tuple] | None = None,
+) -> dict[str, ColumnProfile]:
+    """Profile each column from query result data.
+
+    Uses two layers:
+    - Layer 1: Data value analysis (always available)
+    - Layer 2: Database column descriptions from cursor.description (when available)
+      Provides type for more confident classification.
+    """
+    if not data:
+        return {}
+
+    from dataface.core.compile.chart_type_detection import classify_column_type
+
+    columns = list(data[0].keys())
+    profiles: dict[str, ColumnProfile] = {}
+
+    for col in columns:
+        sample_values = [row.get(col) for row in data[:100] if row.get(col) is not None]
+        if not sample_values:
+            profiles[col] = ColumnProfile(name=col, dtype="categorical")
+            continue
+
+        # Layer 2: Use database description if available
+        desc = column_descriptions.get(col) if column_descriptions else None
+        db_type_str = (
+            str(desc[_DESC_TYPE_CODE])
+            if desc and desc[_DESC_TYPE_CODE] is not None
+            else None
+        )
+        db_dtype = db_type_to_dtype(db_type_str) if db_type_str else None
+
+        # Layer 1: Fall back to value-based classification
+        dtype = db_dtype or classify_column_type(col, sample_values, db_type_str)
+
+        profile = ColumnProfile(name=col, dtype=dtype)
+
+        if dtype == "numeric":
+            numeric_vals = [
+                float(v)
+                for v in sample_values
+                if isinstance(v, (int, float, Decimal))
+                and not isinstance(v, bool)
+                and math.isfinite(float(v))
+            ]
+            if numeric_vals:
+                profile.min_val = min(numeric_vals)
+                profile.max_val = max(numeric_vals)
+
+        profiles[col] = profile
+
+    return profiles
+
+
+def _pick_fields(
+    chart: Chart,
+    col_profiles: dict[str, ColumnProfile],
+) -> dict[str, Any]:
+    """Pick best x/y fields when not user-specified."""
+    updates: dict[str, Any] = {}
+
+    if chart.x and chart.y:
+        return updates
+
+    numeric_cols = [p for p in col_profiles.values() if p.dtype == "numeric"]
+    temporal_cols = [p for p in col_profiles.values() if p.dtype == "temporal"]
+    categorical_cols = [p for p in col_profiles.values() if p.dtype == "categorical"]
+
+    if not chart.x and not chart.y:
+        if temporal_cols:
+            updates["x"] = temporal_cols[0].name
+        elif categorical_cols:
+            updates["x"] = categorical_cols[0].name
+
+        if numeric_cols:
+            updates["y"] = numeric_cols[0].name
+
+    elif chart.x and not chart.y:
+        if numeric_cols:
+            updates["y"] = numeric_cols[0].name
+
+    elif chart.y and not chart.x:
+        if temporal_cols:
+            updates["x"] = temporal_cols[0].name
+        elif categorical_cols:
+            updates["x"] = categorical_cols[0].name
+
+    return updates
+
+
+def _pick_axis_style(
+    chart: Chart,
+    y_profile: ColumnProfile,
+) -> dict[str, Any]:
+    """Pick y-axis scale style updates.
+
+    Format defaults come from the theme cascade (axis_quantitative.format in stark.yaml).
+    This function only handles the zero-baseline heuristic.
+
+    Returns flat dict with a ``scale`` key when a scale override is needed — the caller
+    wraps it into the family sub-patch key before building the updated ChartStylePatch.
+    """
+    updates: dict[str, Any] = {}
+
+    from dataface.core.compile.normalize_charts import (
+        _AUTHORED_FAMILY_TO_MONOLITHIC_KEY,
+    )
+
+    family_key = _AUTHORED_FAMILY_TO_MONOLITHIC_KEY.get(chart.type)
+    existing_patch = (
+        getattr(chart.style, family_key, None) if chart.style and family_key else None
+    )
+    existing_scale = getattr(existing_patch, "scale", None) if existing_patch else None
+    existing_axis_y = (
+        getattr(existing_patch, "axis_y", None) if existing_patch else None
+    )
+    existing_axis_y_scale = (
+        getattr(existing_axis_y, "scale", None) if existing_axis_y else None
+    )
+
+    has_zero = (existing_scale is not None and existing_scale.zero is not None) or (
+        existing_axis_y_scale is not None and existing_axis_y_scale.zero is not None
+    )
+    if not has_zero:
+        scale = _pick_scale(y_profile, chart_type=chart.type)
+        if scale:
+            scale_data = (
+                existing_scale.model_dump(exclude_none=True) if existing_scale else {}
+            )
+            scale_data.update(scale)
+            updates["scale"] = scale_data
+
+    return updates
+
+
+def _pick_scale(
+    profile: ColumnProfile, chart_type: str | None = None
+) -> dict[str, Any] | None:
+    """Decide the explicit zero setting for the y-axis scale.
+
+    Returns ``{"zero": False}`` to keep the domain data-fitted, ``{"zero": True}``
+    to extend to zero, or ``None`` when zero is not relevant (data spans or
+    touches zero, or no data profiled).
+
+    Optional-zero chart types (line, scatter): smart-auto heuristic.
+    Extend to zero when data_min/data_max <= 0.25 (data starts in the bottom
+    quarter of [0, max]).  Return zero:False when data lives far from zero.
+
+    Non-optional-zero types (bar, area, …): always extend to zero for
+    all-positive data — bar marks encode absolute magnitude and suppressing
+    zero produces truncated bars (a known misleading chart pattern).
+
+    Returning an explicit True/False here means resolved_chart.zero carries
+    the full intent; callers (profile.py) do not need to know chart-type
+    defaults in VL.
+
+    All-negative data (max < 0): out of scope — skip the heuristic.
+    """
+    if profile.min_val is None or profile.max_val is None:
+        return None
+    if profile.max_val == 0:
+        return None
+    # Negative-spanning or all-negative: zero already in domain, or out of scope.
+    if profile.min_val < 0:
+        return None
+
+    if chart_type in _OPTIONAL_ZERO_CHART_TYPES:
+        # Smart-auto: keep data-fitted when data lives too far from zero.
+        ratio = profile.min_val / profile.max_val
+        if ratio > _ZERO_EXTEND_THRESHOLD:
+            return {"zero": False}
+        # Data is close to zero — let VL's zero=true default extend naturally.
+        # No explicit True needed: blank space is negligible and we preserve
+        # the tick range from the pre-existing behaviour.
+        return None
+
+    # Non-optional-zero types (bar, area, …) with all-positive data: return
+    # explicit True so resolved_chart.zero carries the intent and callers
+    # (profile.py) need no chart-type knowledge to decide domain pinning.
+    if profile.min_val > 0:
+        return {"zero": True}
+
+    return None