Histogram vs Bar Graph: The Complete Guide to Choosing the Right Chart

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


@dataclass
class HistogramConfig:
    """
    Configuration for histogram generation.
    """
    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.
    """

    @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)
        """
        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

        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)
        """
        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.
        """
        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.
        """
        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)"
        else:
            shape = "left-skewed (long tail to the left)"

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


# Example: API response time distribution
np.random.seed(42)
response_times = np.concatenate([
    np.random.lognormal(mean=5.0, sigma=0.8, size=9000),
    np.random.lognormal(mean=7.0, sigma=0.5, size=1000),
])

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

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

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.
    """
    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.
    """
    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.
    """

    @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 dictionary.
        """
        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 data by aggregating values per category.
        """
        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)

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

        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.
        """
        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
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 data
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.
    """

    @staticmethod
    def classify_data(values: List) -> DataType:
        """
        Classify data as continuous, categorical, ordinal, or temporal.
        """
        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

        # Mostly numeric with high cardinality
        if numeric_count / total > 0.8 and unique_ratio > 0.5:
            return DataType.CONTINUOUS

        # Mostly numeric with low cardinality
        if numeric_count / total > 0.8 and unique_ratio <= 0.1:
            return DataType.ORDINAL

        # String or mixed types
        return DataType.CATEGORICAL

    @staticmethod
    def recommend(
        values: List,
        x_label: str = "",
        context: str = "",
    ) -> ChartSelectionResult:
        """
        Recommend histogram or bar graph based on data characteristics.
        """
        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.",
                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 comparison.",
                warnings=warnings,
            )

        return ChartSelectionResult(
            recommended_chart=ChartType.UNKNOWN,
            data_type=data_type,
            reasoning="Data type could not be determined. Inspect values manually to choose the correct chart type.",
            warnings=["Ambiguous data type — manual inspection required"],
        )

    @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 there is a mismatch.
        """
        warnings = []
        data_type = ChartSelector.classify_data(values)

        if chart_type == ChartType.HISTOGRAM and data_type == DataType.CATEGORICAL:
            warnings.append(
                "WARNING: Using histogram for categorical data. "
                "Bars will touch but categories are not continuous. "
                "Use a bar graph 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: Using bar graph for continuous data with {unique_count} unique values. "
                    "Each unique value becomes a separate bar, creating a misleading chart. "
                    "Use a histogram instead."
                )

        return warnings


# Comparison table
comparison = {
    "Property": [
        "Data type",
        "X-axis meaning",
        "Bar spacing",
        "Bar order",
        "Y-axis meaning",
        "Primary use",
        "Distribution shape",
        "Bin width",
    ],
    "Histogram": [
        "Continuous (numeric)",
        "Numeric ranges (bins)",
        "No gaps (bars touch)",
        "Fixed by bin edges",
        "Frequency or density",
        "Show distribution shape",
        "Visible (normal, skewed, bimodal)",
        "Calculated (Freedman-Diaconis)",
    ],
    "Bar Graph": [
        "Categorical (named groups)",
        "Category labels (names)",
        "Gaps between bars",
        "Arbitrary or sorted by value",
        "Measured value (count, revenue)",
        "Compare categories",
        "Not applicable",
        "Not applicable",
    ],
}

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

# Validation examples
import numpy as np

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

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")
print(f"Bar graph + categorical data: {len(bar_warnings)} warnings")

wrong_hist = ChartSelector.validate_chart_choice(ChartType.HISTOGRAM, categorical_data)
print(f"Histogram + categorical data: {len(wrong_hist)} warnings")
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.
    """

    DECISION_MATRIX = {
        (DataType.CONTINUOUS, Question.DISTRIBUTION): {
            "chart": "histogram",
            "reason": "Histograms reveal distribution shape — normal, skewed, bimodal",
            "example": "API response time distribution, salary ranges, temperature readings",
        },
        (DataType.CONTINUOUS, Question.COMPARISON): {
            "chart": "box_plot",
            "reason": "Box plots compare distributions across groups using medians and quartiles",
            "example": "Response time comparison across microservices",
        },
        (DataType.CATEGORICAL, Question.COMPARISON): {
            "chart": "bar_graph",
            "reason": "Bar graphs compare values across discrete named categories",
            "example": "Revenue by product category, errors by service, users by region",
        },
        (DataType.CATEGORICAL, Question.COMPOSITION): {
            "chart": "stacked_bar_graph",
            "reason": "Stacked bars show both individual and total values per category",
            "example": "Revenue breakdown by product and quarter",
        },
        (DataType.TEMPORAL, Question.TREND): {
            "chart": "line_chart",
            "reason": "Line charts show continuous change over time",
            "example": "Daily active users, monthly revenue trend",
        },
        (DataType.TEMPORAL, Question.COMPARISON): {
            "chart": "bar_graph",
            "reason": "Bar graphs compare aggregated values across time periods",
            "example": "Monthly revenue comparison, quarterly error counts",
        },
        (DataType.ORDINAL, Question.COMPARISON): {
            "chart": "bar_graph",
            "reason": "Ordinal categories have a natural order but are still discrete groups",
            "example": "Customer satisfaction ratings (1-5), age group comparison",
        },
        (DataType.ORDINAL, Question.DISTRIBUTION): {
            "chart": "histogram",
            "reason": "Histograms show how values distribute across ordinal ranges",
            "example": "Age distribution of users, rating distribution of reviews",
        },
    }

    @staticmethod
    def decide(data_type: DataType, question: Question) -> Dict:
        """
        Return the recommended chart type for a data type and question.
        """
        key = (data_type, question)
        result = ChartDecisionEngine.DECISION_MATRIX.get(key)

        if not result:
            return {
                "chart": "unknown",
                "reason": f"No recommendation for {data_type.value} data with {question.value}",
                "example": "Inspect data manually",
            }

        return result

    @staticmethod
    def get_use_cases() -> Dict[str, List[str]]:
        """
        Return common use cases for each chart type.
        """
        return {
            "histogram": [
                "API response time distribution",
                "User age distribution",
                "Memory usage distribution across pods",
                "Error rate distribution across endpoints",
                "Salary distribution within a company",
                "Temperature readings over a year",
            ],
            "bar_graph": [
                "Revenue by product category",
                "Error count by service",
                "Active users by region",
                "Monthly signups comparison",
                "Customer satisfaction by department",
                "Deployment frequency by team",
            ],
        }


# Example: Decision engine in action
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 age groups"),
]

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

import numpy as np
from typing import List, Dict


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

    @staticmethod
    def detect_bar_graph_on_continuous(data: List[float], threshold: int = 20) -> Dict:
        """
        Detect when a bar graph is used on continuous data.
        """
        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" if is_continuous else "Bar graph is appropriate",
            "reason": f"{unique_values} unique values will create {unique_values} separate bars" if is_continuous else "",
        }

    @staticmethod
    def detect_histogram_on_categorical(data: List[str]) -> Dict:
        """
        Detect when a histogram is used on categorical data.
        """
        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 instead of a histogram" if is_categorical else "Histogram is appropriate",
            "reason": f"{unique_categories} categories have no numeric relationship between them" 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 does not start at zero.
        """
        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"}

        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,
            "ratio": round(ratio, 3),
            "recommendation": "Start y-axis at zero for bar graphs unless there is a documented reason" if ratio > 0.5 else "",
        }

    @staticmethod
    def detect_misleading_ordering(categories: List[str], values: List[float]) -> Dict:
        """
        Detect when bar graph ordering is misleading.
        """
        n = len(values)
        is_sorted = all(values[i] >= values[i + 1] for i in range(n - 1))

        return {
            "warning": not is_sorted and n > 3,
            "recommendation": "Sort bars by value (descending) for easier comparison, or by category name for lookup" if not is_sorted else "Bars are sorted by value",
        }


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

# Check for mistakes
result1 = ChartValidation.detect_bar_graph_on_continuous(continuous_data)
print(f"Bar graph on continuous data: {result1['recommendation']}")
print(f"  Unique values: {result1['unique_values']}")

result2 = ChartValidation.detect_histogram_on_categorical(categorical_data)
print(f"Histogram on categorical data: {result2['recommendation']}")

result3 = ChartValidation.detect_truncated_y_axis([45, 48, 52, 55, 49])
print(f"Truncated y-axis: warning={result3['warning']}")
if result3['warning']:
    print(f"  {result3['recommendation']}")