Histogram vs Bar Graph — The $500 Bucket Revenue Trap

import numpy as np
from typing import List, Dict, Tuple, Optional
from dataclasses import dataclass


@dataclass
class HistogramConfig:
    """
    Configuration for histogram generation.

    Produced by HistogramBuilder.build() — not intended for manual construction.
    Bin edges and centers are derived from the data, not chosen arbitrarily.
    """
    bins: int
    bin_width: float
    bin_edges: np.ndarray
    bin_counts: np.ndarray
    bin_centers: np.ndarray


class HistogramBuilder:
    """
    Builds histograms with automatic bin selection and
    distribution analysis.

    Bin selection method defaults to Freedman-Diaconis, which adapts
    to data spread and sample size. Use Sturges only for small datasets
    (<200 observations) where IQR-based methods can overfit.
    """

    @staticmethod
    def freedman_diaconis_bins(data: np.ndarray) -> int:
        """
        Calculate optimal bin count using the Freedman-Diaconis rule.

        bin_width = 2 * IQR * n^(-1/3)

        This adapts to both the spread of the data (via IQR) and the
        number of observations (via n^(-1/3)), producing narrower bins
        for larger datasets and wider bins for small or sparse samples.

        Falls back to 10 bins if IQR is zero (e.g., all observations
        are identical, which itself indicates a data quality problem
        worth investigating separately).
        """
        n = len(data)
        iqr = np.percentile(data, 75) - np.percentile(data, 25)
        bin_width = 2 * iqr * (n ** (-1 / 3))

        if bin_width <= 0:
            return 10  # fallback — IQR of zero means degenerate data

        data_range = np.max(data) - np.min(data)
        return max(1, int(np.ceil(data_range / bin_width)))

    @staticmethod
    def sturges_bins(data: np.ndarray) -> int:
        """
        Calculate bin count using Sturges' rule.

        bins = 1 + log2(n)

        Appropriate for small, roughly normal datasets. Tends to
        underbin for large or skewed distributions — prefer
        Freedman-Diaconis in those cases.
        """
        return max(1, int(np.ceil(1 + np.log2(len(data)))))

    @staticmethod
    def build(data: np.ndarray, method: str = "freedman_diaconis") -> HistogramConfig:
        """
        Build a histogram configuration from raw data.

        Args:
            data:   1-D array of continuous numeric observations.
            method: Bin selection strategy — 'freedman_diaconis' (default),
                    'sturges', or an integer string for a fixed bin count.

        Returns:
            HistogramConfig with bin edges, counts, and centers populated.
        """
        if method == "freedman_diaconis":
            n_bins = HistogramBuilder.freedman_diaconis_bins(data)
        elif method == "sturges":
            n_bins = HistogramBuilder.sturges_bins(data)
        else:
            n_bins = int(method)

        counts, edges = np.histogram(data, bins=n_bins)
        bin_width = edges[1] - edges[0]
        centers = (edges[:-1] + edges[1:]) / 2

        return HistogramConfig(
            bins=n_bins,
            bin_width=bin_width,
            bin_edges=edges,
            bin_counts=counts,
            bin_centers=centers,
        )

    @staticmethod
    def analyze_distribution(data: np.ndarray) -> Dict:
        """
        Analyze the shape of the distribution represented by a histogram.

        Returns skewness, kurtosis, IQR, and key percentiles alongside
        a plain-English shape classification. This output is intended
        for annotating histograms in dashboards — not as a replacement
        for formal statistical testing.
        """
        from scipy import stats

        mean = np.mean(data)
        median = np.median(data)
        std = np.std(data)
        skewness = stats.skew(data)
        kurtosis = stats.kurtosis(data)

        if abs(skewness) < 0.5:
            shape = "approximately normal"
        elif skewness > 0.5:
            shape = "right-skewed (long tail to the right — mean exceeds median)"
        else:
            shape = "left-skewed (long tail to the left — mean falls below median)"

        return {
            "mean": round(mean, 2),
            "median": round(median, 2),
            "std": round(std, 2),
            "skewness": round(skewness, 3),
            "kurtosis": round(kurtosis, 3),
            "shape": shape,
            "iqr": round(np.percentile(data, 75) - np.percentile(data, 25), 2),
            "p5": round(np.percentile(data, 5), 2),
            "p95": round(np.percentile(data, 95), 2),
            "p99": round(np.percentile(data, 99), 2),
        }


# Example: API response time distribution
# Simulates a realistic bimodal distribution — fast path and slow path requests
np.random.seed(42)
response_times = np.concatenate([
    np.random.lognormal(mean=5.0, sigma=0.8, size=9000),  # fast path: ~150ms median
    np.random.lognormal(mean=7.0, sigma=0.5, size=1000),  # slow path: ~1100ms median
])

config = HistogramBuilder.build(response_times)
print(f"Optimal bins (Freedman-Diaconis): {config.bins}")
print(f"Bin width: {config.bin_width:.2f}ms")

analysis = HistogramBuilder.analyze_distribution(response_times)
print(f"Distribution shape: {analysis['shape']}")
print(f"Median: {analysis['median']}ms | Mean: {analysis['mean']}ms")
print(f"P5: {analysis['p5']}ms | P95: {analysis['p95']}ms | P99: {analysis['p99']}ms")
print(f"IQR: {analysis['iqr']}ms")

# In a right-skewed response time distribution:
# - Median is your honest central tendency
# - Mean is inflated by tail outliers
# - P99 is what your slowest 1% of users actually experience
# Always report all three — never just the mean

import numpy as np
from typing import List, Dict, Tuple, Optional
from dataclasses import dataclass, field


@dataclass
class BarCategory:
    """
    A single category in a bar graph.

    error_low and error_high represent the lower and upper bounds
    of a confidence interval relative to the bar value — not raw
    data bounds. Populated by add_confidence_intervals().
    """
    label: str
    value: float
    error_low: float = 0.0
    error_high: float = 0.0
    color: Optional[str] = None


@dataclass
class BarGraphConfig:
    """
    Configuration for bar graph generation.

    orientation: 'vertical' for standard bar charts, 'horizontal'
    when category labels are long (>3 words) or when there are
    more than 8 categories — horizontal layouts prevent label overlap
    without requiring 45-degree rotation hacks.
    """
    title: str
    x_label: str
    y_label: str
    categories: List[BarCategory]
    orientation: str = "vertical"
    show_error_bars: bool = False
    sort_by_value: bool = False


class BarGraphBuilder:
    """
    Builds bar graphs for categorical data comparison.

    Two primary entry points:
    - from_dict(): when data is already aggregated
    - from_aggregation(): when raw row-level data needs grouping first
    """

    @staticmethod
    def from_dict(
        data: Dict[str, float],
        title: str = "",
        x_label: str = "Category",
        y_label: str = "Value",
        sort_by_value: bool = False,
    ) -> BarGraphConfig:
        """
        Create a bar graph configuration from a pre-aggregated dictionary.

        Use this when the aggregation has already been done upstream
        (e.g., fetched from a metrics API that returns category totals).
        """
        categories = [BarCategory(label=k, value=v) for k, v in data.items()]

        if sort_by_value:
            categories.sort(key=lambda c: c.value, reverse=True)

        return BarGraphConfig(
            title=title,
            x_label=x_label,
            y_label=y_label,
            categories=categories,
            sort_by_value=sort_by_value,
        )

    @staticmethod
    def from_aggregation(
        data: List[Dict],
        category_key: str,
        value_key: str,
        aggregation: str = "sum",
        title: str = "",
        x_label: str = "",
        y_label: str = "",
    ) -> BarGraphConfig:
        """
        Create a bar graph from raw row-level data by aggregating per category.

        Supported aggregations: sum, mean, count, max, median.
        Median is calculated without scipy — useful in environments with
        minimal dependencies.
        """
        grouped: Dict[str, List[float]] = {}
        for row in data:
            cat = str(row[category_key])
            val = float(row[value_key])
            if cat not in grouped:
                grouped[cat] = []
            grouped[cat].append(val)

        categories = []
        for cat, values in grouped.items():
            if aggregation == "sum":
                agg_value = sum(values)
            elif aggregation == "mean":
                agg_value = sum(values) / len(values)
            elif aggregation == "count":
                agg_value = len(values)
            elif aggregation == "max":
                agg_value = max(values)
            elif aggregation == "median":
                sorted_vals = sorted(values)
                n = len(sorted_vals)
                agg_value = (
                    sorted_vals[n // 2]
                    if n % 2
                    else (sorted_vals[n // 2 - 1] + sorted_vals[n // 2]) / 2
                )
            else:
                agg_value = sum(values)  # default to sum for unknown methods

            categories.append(BarCategory(
                label=cat,
                value=round(agg_value, 2),
            ))

        # Default to descending sort — audiences compare fastest when
        # the longest bar is at the top or left
        categories.sort(key=lambda c: c.value, reverse=True)

        return BarGraphConfig(
            title=title,
            x_label=x_label or category_key,
            y_label=y_label or f"{aggregation.title()} of {value_key}",
            categories=categories,
        )

    @staticmethod
    def add_confidence_intervals(
        config: BarGraphConfig,
        data: List[Dict],
        category_key: str,
        value_key: str,
        confidence: float = 0.95,
    ) -> BarGraphConfig:
        """
        Add error bars representing confidence intervals to each bar.

        A bar without error bars implies false precision — especially
        when the underlying distribution has high variance. Call this
        whenever sample sizes differ across categories, which is almost
        always in production data.
        """
        from scipy import stats

        grouped: Dict[str, List[float]] = {}
        for row in data:
            cat = str(row[category_key])
            val = float(row[value_key])
            if cat not in grouped:
                grouped[cat] = []
            grouped[cat].append(val)

        for cat in config.categories:
            values = grouped.get(cat.label, [])
            if len(values) > 1:
                mean = np.mean(values)
                se = stats.sem(values)
                ci = stats.t.interval(confidence, len(values) - 1, loc=mean, scale=se)
                cat.error_low = mean - ci[0]
                cat.error_high = ci[1] - mean

        config.show_error_bars = True
        return config


# Example: Revenue by product category — typical executive dashboard use case
revenue_data = {
    "Electronics": 2450000,
    "Clothing": 1830000,
    "Home & Garden": 1200000,
    "Sports": 890000,
    "Books": 450000,
}

config = BarGraphBuilder.from_dict(
    revenue_data,
    title="Q4 Revenue by Product Category",
    x_label="Product Category",
    y_label="Revenue ($)",
    sort_by_value=True,
)

print(f"Categories: {len(config.categories)}")
for cat in config.categories:
    print(f"  {cat.label}: ${cat.value:,.0f}")

# Example: Aggregation from raw row-level data
# Simulates pulling order records from a data warehouse
raw_orders = [
    {"region": "North", "revenue": 150},
    {"region": "North", "revenue": 200},
    {"region": "South", "revenue": 300},
    {"region": "South", "revenue": 250},
    {"region": "East",  "revenue": 180},
    {"region": "East",  "revenue": 220},
]

agg_config = BarGraphBuilder.from_aggregation(
    raw_orders,
    category_key="region",
    value_key="revenue",
    aggregation="mean",
    title="Average Order Value by Region",
)

for cat in agg_config.categories:
    print(f"  {cat.label}: ${cat.value:.2f}")

from dataclasses import dataclass
from typing import Dict, List, Optional
from enum import Enum


class ChartType(Enum):
    HISTOGRAM = "histogram"
    BAR_GRAPH = "bar_graph"
    UNKNOWN = "unknown"


class DataType(Enum):
    CONTINUOUS = "continuous"
    CATEGORICAL = "categorical"
    ORDINAL = "ordinal"
    TEMPORAL = "temporal"


@dataclass
class ChartSelectionResult:
    recommended_chart: ChartType
    data_type: DataType
    reasoning: str
    warnings: List[str]


class ChartSelector:
    """
    Determines the correct chart type based on data characteristics.

    Uses unique value ratio as a proxy for data type classification.
    High cardinality numeric data (unique ratio > 0.5) is almost always
    continuous. Low cardinality numeric data is often ordinal or categorical.
    String data is always categorical.

    This heuristic handles the 80% case cleanly. Edge cases — like numeric
    IDs that look continuous but are categorical — still require human judgment.
    """

    @staticmethod
    def classify_data(values: List) -> DataType:
        """
        Classify data as continuous, categorical, ordinal, or temporal.

        Classification logic:
        - Mostly numeric + high unique ratio (>50%) → continuous
        - Mostly numeric + low unique ratio (<=10%) → ordinal
        - String or mixed types → categorical
        """
        numeric_count = sum(1 for v in values if isinstance(v, (int, float)))
        total = len(values)

        if total == 0:
            return DataType.CATEGORICAL

        unique_ratio = len(set(values)) / total

        if numeric_count / total > 0.8 and unique_ratio > 0.5:
            return DataType.CONTINUOUS

        if numeric_count / total > 0.8 and unique_ratio <= 0.1:
            return DataType.ORDINAL

        return DataType.CATEGORICAL

    @staticmethod
    def recommend(
        values: List,
        x_label: str = "",
        context: str = "",
    ) -> ChartSelectionResult:
        """
        Recommend histogram or bar graph based on data characteristics.

        Returns a ChartSelectionResult with the recommended chart type,
        a plain-English reasoning string, and any warnings about edge cases.
        Intended to run at pipeline validation time, not just at render time.
        """
        data_type = ChartSelector.classify_data(values)
        warnings = []

        if data_type == DataType.CONTINUOUS:
            return ChartSelectionResult(
                recommended_chart=ChartType.HISTOGRAM,
                data_type=data_type,
                reasoning="Continuous numeric data with high cardinality is best visualized as a histogram. Bins reveal the distribution shape that individual bars cannot.",
                warnings=warnings,
            )

        if data_type in (DataType.CATEGORICAL, DataType.ORDINAL):
            return ChartSelectionResult(
                recommended_chart=ChartType.BAR_GRAPH,
                data_type=data_type,
                reasoning="Categorical or ordinal data is best visualized as a bar graph. Each category gets a separate bar for direct comparison.",
                warnings=warnings,
            )

        return ChartSelectionResult(
            recommended_chart=ChartType.UNKNOWN,
            data_type=data_type,
            reasoning="Data type could not be determined from values alone. Inspect the data manually before choosing a chart type.",
            warnings=["Ambiguous data type — manual inspection required before publishing"],
        )

    @staticmethod
    def validate_chart_choice(
        chart_type: ChartType,
        values: List,
    ) -> List[str]:
        """
        Validate that the chosen chart type matches the data.

        Returns a list of warnings if a mismatch is detected.
        An empty list means the selection passed validation.
        Designed to run as a pre-publish check in dashboard pipelines.
        """
        warnings = []
        data_type = ChartSelector.classify_data(values)

        if chart_type == ChartType.HISTOGRAM and data_type == DataType.CATEGORICAL:
            warnings.append(
                "WARNING: Histogram selected for categorical data. "
                "Bars will touch but categories have no numeric relationship. "
                "Use a bar graph with gaps between bars instead."
            )

        if chart_type == ChartType.BAR_GRAPH and data_type == DataType.CONTINUOUS:
            unique_count = len(set(values))
            if unique_count > 20:
                warnings.append(
                    f"WARNING: Bar graph selected for continuous data with {unique_count} unique values. "
                    "Each unique value becomes a separate bar, producing an unreadable chart that hides the distribution. "
                    "Use a histogram with calculated bin widths instead."
                )

        return warnings


# Comparison table — all properties where histogram and bar graph differ
comparison = {
    "Property": [
        "Data type",
        "X-axis meaning",
        "Bar spacing",
        "Bar order",
        "Y-axis meaning",
        "Primary use",
        "Distribution shape",
        "Bin width",
        "Sorting",
        "Error bars",
    ],
    "Histogram": [
        "Continuous (numeric)",
        "Numeric ranges (bins)",
        "No gaps — bars touch",
        "Fixed by bin edges — cannot reorder",
        "Frequency or density",
        "Show distribution shape",
        "Visible: normal, skewed, bimodal",
        "Calculated via Freedman-Diaconis or Sturges",
        "Not applicable — bin order is inherent",
        "Not standard — use KDE overlay instead",
    ],
    "Bar Graph": [
        "Categorical (named groups)",
        "Category labels (names)",
        "Intentional gaps between bars",
        "Arbitrary — sort by value or name",
        "Measured value: count, revenue, rate",
        "Compare categories",
        "Not applicable",
        "Not applicable",
        "Sort by value or alphabetically",
        "95% confidence intervals recommended",
    ],
}

print("Histogram vs Bar Graph — Property Comparison:")
for i, prop in enumerate(comparison["Property"]):
    print(f"\n  {prop}:")
    print(f"    Histogram:  {comparison['Histogram'][i]}")
    print(f"    Bar Graph:  {comparison['Bar Graph'][i]}")

# Validation examples — run these in your pipeline before publishing dashboards
import numpy as np

continuous_data = np.random.normal(100, 15, 1000).tolist()
categorical_data = ["North", "South", "East", "West"] * 50

# These should produce zero warnings
hist_warnings = ChartSelector.validate_chart_choice(ChartType.HISTOGRAM, continuous_data)
bar_warnings  = ChartSelector.validate_chart_choice(ChartType.BAR_GRAPH, categorical_data)

print(f"\nHistogram + continuous data: {len(hist_warnings)} warnings (expected 0)")
print(f"Bar graph + categorical data: {len(bar_warnings)} warnings (expected 0)")

# This should produce a warning — wrong chart for the data type
wrong_hist = ChartSelector.validate_chart_choice(ChartType.HISTOGRAM, categorical_data)
print(f"Histogram + categorical data: {len(wrong_hist)} warnings (expected 1)")
for w in wrong_hist:
    print(f"  {w}")

from enum import Enum
from typing import List, Dict


class Question(Enum):
    DISTRIBUTION = "What does the distribution look like?"
    COMPARISON   = "Which category has the highest value?"
    TREND        = "How does the value change over time?"
    COMPOSITION  = "What are the parts of the whole?"


class DataType(Enum):
    CONTINUOUS   = "continuous"
    CATEGORICAL  = "categorical"
    ORDINAL      = "ordinal"
    TEMPORAL     = "temporal"


class ChartDecisionEngine:
    """
    Decision engine for selecting the right chart type.

    Maps (DataType, Question) pairs to chart recommendations with
    plain-English reasoning and concrete examples.

    This is the reference implementation of the two-question framework:
    1. What is the data type?
    2. What question are you answering?
    The intersection determines the chart.
    """

    DECISION_MATRIX = {
        (DataType.CONTINUOUS, Question.DISTRIBUTION): {
            "chart": "histogram",
            "reason": "Histograms reveal distribution shape — normal, skewed, bimodal — and tail behavior that bar graphs cannot show",
            "example": "API response time distribution, salary ranges, memory usage per pod, transaction amounts",
        },
        (DataType.CONTINUOUS, Question.COMPARISON): {
            "chart": "box_plot",
            "reason": "Box plots compare distributions across groups using medians and quartiles — more honest than comparing means alone",
            "example": "Response time comparison across microservices, revenue distribution by customer segment",
        },
        (DataType.CATEGORICAL, Question.COMPARISON): {
            "chart": "bar_graph",
            "reason": "Bar graphs compare values across discrete named categories — each bar is independent, gaps signal separation",
            "example": "Revenue by product category, error count by service, active users by region",
        },
        (DataType.CATEGORICAL, Question.COMPOSITION): {
            "chart": "stacked_bar_graph",
            "reason": "Stacked bars show both individual component values and the total per category simultaneously",
            "example": "Revenue breakdown by product and quarter, support tickets by type and team",
        },
        (DataType.TEMPORAL, Question.TREND): {
            "chart": "line_chart",
            "reason": "Line charts show continuous change over time — the connecting line encodes the direction and rate of change",
            "example": "Daily active users over 90 days, P99 latency trend over a deployment window",
        },
        (DataType.TEMPORAL, Question.COMPARISON): {
            "chart": "bar_graph",
            "reason": "Bar graphs compare aggregated values across discrete time periods — each period is treated as a category",
            "example": "Monthly revenue comparison, quarterly error count, year-over-year signups",
        },
        (DataType.ORDINAL, Question.COMPARISON): {
            "chart": "bar_graph",
            "reason": "Ordinal categories have a natural order but remain discrete groups — bar graphs preserve order while enabling comparison",
            "example": "Customer satisfaction ratings 1-5, NPS score distribution by segment, support ticket severity levels",
        },
        (DataType.ORDINAL, Question.DISTRIBUTION): {
            "chart": "histogram",
            "reason": "Histograms show how values distribute across the ordinal range — shape reveals whether the population skews positive or negative",
            "example": "Age distribution of active users, review rating distribution, bug severity distribution",
        },
    }

    @staticmethod
    def decide(data_type: DataType, question: Question) -> Dict:
        """
        Return the recommended chart type for a data type and question pair.

        Returns a dict with keys: chart, reason, example.
        Returns an 'unknown' entry if the combination is not in the matrix —
        this signals a genuinely ambiguous case that needs manual judgment.
        """
        key = (data_type, question)
        result = ChartDecisionEngine.DECISION_MATRIX.get(key)

        if not result:
            return {
                "chart": "unknown",
                "reason": f"No standard recommendation for {data_type.value} data with '{question.value}'",
                "example": "Inspect the data and question manually before choosing a chart type",
            }

        return result

    @staticmethod
    def get_use_cases() -> Dict[str, List[str]]:
        """
        Return concrete production use cases for each chart type.

        These are real-world examples, not synthetic textbook scenarios.
        Each one maps to a situation where the wrong chart type
        caused a misread in a production dashboard.
        """
        return {
            "histogram": [
                "API response time distribution — reveals tail latency hidden by averages",
                "User age distribution — shows whether audience skews young or old",
                "Memory usage distribution across pods — bimodal shape reveals two workload profiles",
                "Error rate distribution across endpoints — shows concentration vs. uniform spread",
                "Salary distribution within a role — right skew signals senior outliers pulling mean up",
                "Transaction amount distribution — bimodal shape suggests two distinct customer behaviors",
            ],
            "bar_graph": [
                "Revenue by product category — compare which category leads",
                "Error count by service — identify which microservice has the most incidents",
                "Active users by region — compare geographic distribution",
                "Monthly signups comparison — period-over-period view of a discrete metric",
                "Customer satisfaction by department — compare NPS across internal teams",
                "Deployment frequency by team — compare engineering cadence across squads",
            ],
        }


# Decision engine in action — covering the most common production scenarios
engine = ChartDecisionEngine()

scenarios = [
    (DataType.CONTINUOUS,  Question.DISTRIBUTION, "API response times"),
    (DataType.CATEGORICAL, Question.COMPARISON,   "Revenue by region"),
    (DataType.TEMPORAL,    Question.COMPARISON,   "Monthly revenue"),
    (DataType.ORDINAL,     Question.DISTRIBUTION, "User satisfaction ratings"),
    (DataType.TEMPORAL,    Question.TREND,        "Daily active users over 90 days"),
    (DataType.CATEGORICAL, Question.COMPOSITION,  "Revenue by product and quarter"),
]

for data_type, question, context in scenarios:
    result = engine.decide(data_type, question)
    print(f"{context}:")
    print(f"  Recommended chart: {result['chart']}")
    print(f"  Why: {result['reason']}")
    print(f"  Similar example: {result['example']}")
    print()

import numpy as np
from typing import List, Dict


class ChartValidation:
    """
    Validates chart type selections and detects common visualization mistakes.

    Designed to run as a pre-publish validation step in dashboard pipelines.
    Each method returns a structured result dict rather than raising exceptions
    so that callers can decide whether to block publishing or log a warning.
    """

    @staticmethod
    def detect_bar_graph_on_continuous(data: List[float], threshold: int = 20) -> Dict:
        """
        Detect when a bar graph is being used on continuous numeric data.

        High unique value ratio (>50%) combined with more than `threshold`
        unique values is a strong signal that the data is continuous.
        In that case, a bar graph produces one bar per unique value —
        visually unreadable and analytically misleading.
        """
        unique_values = len(set(data))
        total_values  = len(data)
        unique_ratio  = unique_values / total_values

        is_continuous = unique_ratio > 0.5 and unique_values > threshold

        return {
            "mistake_detected": is_continuous,
            "unique_values": unique_values,
            "total_values": total_values,
            "unique_ratio": round(unique_ratio, 3),
            "recommendation": (
                "Use a histogram instead of a bar graph — bin the continuous data to reveal its distribution"
                if is_continuous
                else "Bar graph is appropriate for this data"
            ),
            "reason": (
                f"{unique_values} unique values will create {unique_values} separate bars, "
                f"hiding the distribution and making the chart unreadable"
                if is_continuous
                else ""
            ),
        }

    @staticmethod
    def detect_histogram_on_categorical(data: List[str]) -> Dict:
        """
        Detect when a histogram is being used on categorical string data.

        Touching bars on categorical data imply numeric adjacency between
        categories — a relationship that does not exist between, say,
        'Electronics' and 'Clothing'. The histogram framing communicates
        a false structure that misleads the audience.
        """
        unique_categories = len(set(data))
        is_categorical    = all(isinstance(v, str) for v in data)

        return {
            "mistake_detected": is_categorical and unique_categories <= 20,
            "unique_categories": unique_categories,
            "recommendation": (
                "Use a bar graph with gaps between bars — categorical data has no numeric adjacency"
                if is_categorical
                else "Histogram is appropriate for this data"
            ),
            "reason": (
                f"{unique_categories} string categories have no numeric relationship — "
                "touching bars imply a continuous scale that does not exist"
                if is_categorical
                else ""
            ),
        }

    @staticmethod
    def detect_truncated_y_axis(values: List[float], chart_type: str = "bar_graph") -> Dict:
        """
        Detect when a bar graph y-axis would be truncated above zero.

        A ratio of min_value / max_value above 0.5 means the y-axis
        starting at the minimum value would show bars at roughly 50-100%
        of chart height, exaggerating differences by compressing the scale.

        This check is only relevant for bar graphs — line charts sometimes
        legitimately start above zero when trend direction matters more
        than absolute magnitude.
        """
        if not values:
            return {"warning": False, "reason": "No values to analyze"}

        min_value  = min(values)
        max_value  = max(values)
        value_range = max_value - min_value

        if value_range == 0:
            return {"warning": False, "reason": "All values are identical — chart would be uninformative regardless of axis start"}

        ratio = min_value / max_value if max_value != 0 else 0

        return {
            "warning": ratio > 0.5 and chart_type == "bar_graph",
            "min_value": min_value,
            "max_value": max_value,
            "min_to_max_ratio": round(ratio, 3),
            "recommendation": (
                f"Start the y-axis at zero. A ratio of {ratio:.1%} means bars will fill "
                f"{(1 - ratio) * 100:.0f}% of the chart height, exaggerating proportional differences."
                if ratio > 0.5 and chart_type == "bar_graph"
                else ""
            ),
        }

    @staticmethod
    def detect_misleading_ordering(categories: List[str], values: List[float]) -> Dict:
        """
        Detect when bar graph bars are in a non-meaningful order.

        Bars in arbitrary default order force the audience to scan the entire
        chart before they can identify the highest or lowest category.
        Sort by value (descending) for comparison-focused charts, or
        by category name for lookup-focused charts. Never leave in
        insertion or alphabetical-by-accident order.
        """
        n = len(values)
        if n < 2:
            return {"warning": False, "recommendation": "Only one category — ordering is not applicable"}

        is_sorted_desc = all(values[i] >= values[i + 1] for i in range(n - 1))
        is_sorted_asc  = all(values[i] <= values[i + 1] for i in range(n - 1))
        is_sorted_name = categories == sorted(categories)

        has_meaningful_order = is_sorted_desc or is_sorted_asc or is_sorted_name

        return {
            "warning": not has_meaningful_order and n > 3,
            "recommendation": (
                "Sort bars by value descending for comparison clarity, "
                "or alphabetically if the audience uses the chart for lookup"
                if not has_meaningful_order
                else "Bar order is meaningful — no change needed"
            ),
        }


# Run validation against example datasets
continuous_data  = np.random.exponential(scale=200, size=1000).tolist()
categorical_data = ["North", "South", "East", "West"] * 250

result1 = ChartValidation.detect_bar_graph_on_continuous(continuous_data)
print(f"Bar graph on continuous data:")
print(f"  Mistake detected: {result1['mistake_detected']}")
print(f"  Recommendation: {result1['recommendation']}")

result2 = ChartValidation.detect_histogram_on_categorical(categorical_data)
print(f"\nHistogram on categorical data:")
print(f"  Mistake detected: {result2['mistake_detected']}")
print(f"  Recommendation: {result2['recommendation']}")

# Truncated y-axis — values clustered between 450K and 550K
revenue_values = [480000, 495000, 512000, 503000, 487000]
result3 = ChartValidation.detect_truncated_y_axis(revenue_values, chart_type="bar_graph")
print(f"\nTruncated y-axis check:")
print(f"  Warning: {result3['warning']}")
if result3['warning']:
    print(f"  {result3['recommendation']}")

# Ordering check — arbitrary insertion order
regions = ["East", "North", "South", "West"]
revenue = [220000, 480000, 310000, 150000]  # no meaningful sort order
result4 = ChartValidation.detect_misleading_ordering(regions, revenue)
print(f"\nOrdering check:")
print(f"  Warning: {result4['warning']}")
print(f"  Recommendation: {result4['recommendation']}")