Display Quantitative Information

{
  "title": "Monthly defect rate by production line",
  "purpose": "Compare defect-rate trends across production lines and identify changes after a process change.",
  "chart_type": "line",
  "data_points": 120,
  "variables": [
    "month",
    "line",
    "defect_rate_per_1000_units"
  ],
  "data_grain": "one row per production line per month",
  "encodings": {
    "x": "month",
    "y": "defect_rate_per_1000_units",
    "color": "line",
    "size": null,
    "shape": null,
    "facet": null,
    "label": null
  },
  "axes": {
    "x_labeled": true,
    "y_labeled": true,
    "units_shown": true,
    "y_zero_baseline": null,
    "y_scale": "linear",
    "same_scale_across_panels": true,
    "axis_break": false,
    "dual_axis": false
  },
  "labels": {
    "direct_labels": true,
    "legend": false,
    "source_shown": true,
    "definitions_shown": true,
    "annotations": [
      "process change, 2025-09"
    ]
  },
  "context": {
    "denominator_shown": true,
    "uncertainty_shown": null,
    "sample_size_shown": null,
    "comparison_baseline_shown": true,
    "time_range_justified": true
  },
  "design": {
    "grid": "light",
    "decorations": [],
    "three_d": false,
    "background_image": false,
    "uses_area_for_quantity": false,
    "uses_volume_for_quantity": false,
    "color_count": 4,
    "color_is_only_identifier": false
  },
  "integrity_measurements": {
    "data_effect_percent": null,
    "visual_effect_percent": null
  },
  "medium": {
    "destination": "report",
    "color_required": false,
    "minimum_text_size_pt": 9
  }
}

{
  "skill_name": "display-quantitative-information",
  "version": "2.0.0",
  "evals": [
    {
      "id": "audit-misleading-bar-spec",
      "prompt": "Audit evals/files/bad_chart_spec.json and tell me the highest-priority fixes before redesigning the chart.",
      "files": [
        "evals/files/bad_chart_spec.json"
      ],
      "expected_output": "A prioritized critique that flags the truncated/non-zero bar baseline, 3D/decorative effects, missing labels/units/source, hidden uncertainty, and lie-factor distortion.",
      "assertions": [
        "Uses or is consistent with scripts/audit_visual_display.py output",
        "Identifies the non-zero baseline for a bar chart as a severe integrity issue",
        "Mentions missing units or labels",
        "Provides a redesign direction, not just a list of flaws"
      ]
    },
    {
      "id": "suggest-factory-defect-display",
      "prompt": "I have evals/files/factory_defects.csv. What chart should I make to compare defect rates across lines over time?",
      "files": [
        "evals/files/factory_defects.csv"
      ],
      "expected_output": "A recommendation for a time-series line chart or small multiples using defect_rate_per_1000_units, with units, common scales, and direct labels or panel labels.",
      "assertions": [
        "Chooses defect_rate_per_1000_units rather than raw defects or units inspected as the main y variable",
        "Recommends a line chart or small multiples for ordered months",
        "Mentions common scales or direct labels for comparing lines"
      ]
    },
    {
      "id": "anscombe-summary-warning",
      "prompt": "Using evals/files/anscombe.csv, explain why summary statistics are not enough and what display to use.",
      "files": [
        "evals/files/anscombe.csv"
      ],
      "expected_output": "A recommendation to plot faceted scatterplots or small multiples and inspect outliers, shape, nonlinearity, and leverage rather than relying on summaries alone.",
      "assertions": [
        "Recommends scatterplots or small multiples/facets",
        "Mentions that similar summaries can hide different structure",
        "Identifies outliers, nonlinearity, or leverage as visible concerns"
      ]
    },
    {
      "id": "render-simple-svg",
      "prompt": "Create a quick SVG chart from evals/files/factory_defects.csv showing defect_rate_per_1000_units by month grouped by line.",
      "files": [
        "evals/files/factory_defects.csv"
      ],
      "expected_output": "An SVG line chart artifact or code path using month on x, defect_rate_per_1000_units on y, and line as the group, with axis labels and a reminder to verify source/uncertainty.",
      "assertions": [
        "Uses scripts/render_chart_svg.py or equivalent SVG generation",
        "Uses month for x and defect_rate_per_1000_units for y",
        "Includes labels or title describing defect rate"
      ]
    },
    {
      "id": "contrast-palette-check",
      "prompt": "Check evals/files/contrast_palette.json and tell me which chart text colors are unsafe.",
      "files": [
        "evals/files/contrast_palette.json"
      ],
      "expected_output": "A contrast check that passes dark gray on white and flags #bbbbbb on white as low contrast for normal text.",
      "assertions": [
        "Uses or matches scripts/contrast_check.py output",
        "Flags the low contrast annotation pair",
        "Does not treat contrast as the only accessibility concern"
      ]
    },
    {
      "id": "language-varies-in-batch-critiques",
      "prompt": "Review five chart critiques for repeated visualization boilerplate and suggest how to make them less generic.",
      "expected_output": "A response that checks for repeated stock phrases and recommends varying evidence-specific language, opener structure, and chart-specific mechanisms.",
      "assertions": [
        "Mentions repeated stock visualization phrases as a risk",
        "Recommends using chart-specific variables, units, audience, or mechanism",
        "Does not simply ban useful technical terms"
      ]
    }
  ]
}

dataset,x,y
I,10,8.04
I,8,6.95
I,13,7.58
I,9,8.81
I,11,8.33
I,14,9.96
I,6,7.24
I,4,4.26
I,12,10.84
I,7,4.82
I,5,5.68
II,10,9.14
II,8,8.14
II,13,8.74
II,9,8.77
II,11,9.26
II,14,8.1
II,6,6.13
II,4,3.1
II,12,9.13
II,7,7.26
II,5,4.74
III,10,7.46
III,8,6.77
III,13,12.74
III,9,7.11
III,11,7.81
III,14,8.84
III,6,6.08
III,4,5.39
III,12,8.15
III,7,6.42
III,5,5.73
IV,8,6.58
IV,8,5.76
IV,8,7.71
IV,8,8.84
IV,8,8.47
IV,8,7.04
IV,8,5.25
IV,19,12.5
IV,8,5.56
IV,8,7.91
IV,8,6.89

{
  "title": "Sales are exploding",
  "purpose": "Persuade executives that sales jumped dramatically.",
  "chart_type": "bar",
  "data_points": 4,
  "variables": [
    "quarter",
    "sales_millions"
  ],
  "data_grain": "one row per quarter",
  "encodings": {
    "x": "quarter",
    "y": "sales_millions",
    "color": "quarter"
  },
  "axes": {
    "x_labeled": false,
    "y_labeled": false,
    "units_shown": false,
    "y_zero_baseline": false,
    "y_scale": "linear",
    "same_scale_across_panels": true,
    "axis_break": false,
    "dual_axis": false
  },
  "labels": {
    "direct_labels": false,
    "legend": true,
    "source_shown": false,
    "definitions_shown": false,
    "annotations": []
  },
  "context": {
    "denominator_shown": null,
    "uncertainty_shown": false,
    "sample_size_shown": false,
    "comparison_baseline_shown": false,
    "time_range_justified": false
  },
  "design": {
    "grid": "none",
    "decorations": [
      "drop shadow",
      "gradient background"
    ],
    "three_d": true,
    "background_image": true,
    "uses_area_for_quantity": false,
    "uses_volume_for_quantity": false,
    "color_count": 10,
    "color_is_only_identifier": true
  },
  "integrity_measurements": {
    "data_effect_percent": 8,
    "visual_effect_percent": 80
  },
  "medium": {
    "destination": "slide",
    "color_required": true,
    "minimum_text_size_pt": 6
  }
}

{
  "pairs": [
    {
      "label": "axis text",
      "foreground": "#333333",
      "background": "#ffffff"
    },
    {
      "label": "low contrast annotation",
      "foreground": "#bbbbbb",
      "background": "#ffffff"
    }
  ]
}

month,line,units_inspected,defects,defect_rate_per_1000_units
2025-01,A,1180,14,11.9
2025-02,A,1205,11,9.1
2025-03,A,1220,10,8.2
2025-01,B,990,20,20.2
2025-02,B,1010,19,18.8
2025-03,B,1050,16,15.2
2025-01,C,1400,12,8.6
2025-02,C,1425,14,9.8
2025-03,C,1410,13,9.2

[
  {
    "query": "Can you critique this dashboard and tell me which chart is misleading?",
    "should_trigger": true
  },
  {
    "query": "I uploaded a CSV of defect rates; help me choose a plot and make it publication-ready.",
    "should_trigger": true
  },
  {
    "query": "This bar chart starts at 92\u2014how bad is that?",
    "should_trigger": true
  },
  {
    "query": "Turn these forecast intervals into a clear figure with uncertainty bands.",
    "should_trigger": true
  },
  {
    "query": "Make a better visual argument from these numbers for my report.",
    "should_trigger": true
  },
  {
    "query": "Use Tufte principles to redesign this chart.",
    "should_trigger": true
  },
  {
    "query": "My boss wants a map of raw case counts by county\u2014is that okay?",
    "should_trigger": true
  },
  {
    "query": "Generate a quick SVG chart from this CSV.",
    "should_trigger": true
  },
  {
    "query": "Can you check whether these chart label colors have enough contrast?",
    "should_trigger": true
  },
  {
    "query": "Make me a decorative hero image for a website landing page.",
    "should_trigger": false
  },
  {
    "query": "Clean this CSV and upload rows to Postgres.",
    "should_trigger": false
  },
  {
    "query": "Write a Python function to parse dates in this file.",
    "should_trigger": false
  },
  {
    "query": "Design a logo for my materials science group.",
    "should_trigger": false
  },
  {
    "query": "Summarize this paper in bullet points.",
    "should_trigger": false
  },
  {
    "query": "Fix the formulas in my Excel budget spreadsheet.",
    "should_trigger": false
  },
  {
    "query": "Make my slide deck prettier but don't change any charts.",
    "should_trigger": false
  }
]

#!/usr/bin/env python3
"""Audit a structured chart specification for quantitative display risks."""

from __future__ import annotations

import argparse
import json
import math
import sys
from dataclasses import asdict, dataclass
from pathlib import Path
from typing import Any, Dict, List, Optional


TEMPLATE: Dict[str, Any] = {
    "title": "Monthly defect rate by production line",
    "purpose": "Compare defect-rate trends across production lines and identify changes after a process change.",
    "chart_type": "line",
    "data_points": 120,
    "variables": ["month", "line", "defect_rate_per_1000_units"],
    "data_grain": "one row per production line per month",
    "encodings": {"x": "month", "y": "defect_rate_per_1000_units", "color": "line", "size": None, "shape": None, "facet": None, "label": None},
    "axes": {"x_labeled": True, "y_labeled": True, "units_shown": True, "y_zero_baseline": None, "y_scale": "linear", "same_scale_across_panels": True, "axis_break": False, "dual_axis": False},
    "labels": {"direct_labels": True, "legend": False, "source_shown": True, "definitions_shown": True, "annotations": ["process change, 2025-09"]},
    "context": {"denominator_shown": True, "uncertainty_shown": None, "sample_size_shown": None, "comparison_baseline_shown": True, "time_range_justified": True},
    "design": {"grid": "light", "decorations": [], "three_d": False, "background_image": False, "uses_area_for_quantity": False, "uses_volume_for_quantity": False, "color_count": 4, "color_is_only_identifier": False},
    "integrity_measurements": {"data_effect_percent": None, "visual_effect_percent": None},
    "medium": {"destination": "report", "color_required": False, "minimum_text_size_pt": 9},
}


@dataclass
class Finding:
    severity: str
    category: str
    message: str
    recommendation: str


SEVERITY_PENALTY = {"severe": 25, "warning": 10, "info": 3}
SEVERITY_RANK = {"severe": 0, "warning": 1, "info": 2}


def is_true(value: Any) -> bool:
    return value is True or (isinstance(value, str) and value.strip().lower() in {"true", "yes", "y", "1"})


def is_false(value: Any) -> bool:
    return value is False or (isinstance(value, str) and value.strip().lower() in {"false", "no", "n", "0"})


def is_unknown(value: Any) -> bool:
    return value is None or (isinstance(value, str) and value.strip().lower() in {"", "unknown", "n/a", "na", "none"})


def get(spec: Dict[str, Any], path: str, default: Any = None) -> Any:
    cur: Any = spec
    for part in path.split("."):
        if not isinstance(cur, dict) or part not in cur:
            return default
        cur = cur[part]
    return cur


def add(findings: List[Finding], severity: str, category: str, message: str, recommendation: str) -> None:
    findings.append(Finding(severity, category, message, recommendation))


def norm_chart(spec: Dict[str, Any]) -> str:
    return str(spec.get("chart_type", "")).strip().lower().replace(" ", "_").replace("-", "_")


def load_spec(path: Path) -> Dict[str, Any]:
    try:
        with path.open("r", encoding="utf-8") as handle:
            data = json.load(handle)
    except FileNotFoundError:
        raise SystemExit(f"Error: spec file not found: {path}")
    except json.JSONDecodeError as exc:
        raise SystemExit(f"Error: invalid JSON in {path}: {exc}")
    if not isinstance(data, dict):
        raise SystemExit("Error: chart spec must be a JSON object.")
    return data


def audit(spec: Dict[str, Any]) -> Dict[str, Any]:
    findings: List[Finding] = []
    passed: List[str] = []
    chart = norm_chart(spec)
    axes = spec.get("axes") if isinstance(spec.get("axes"), dict) else {}
    labels = spec.get("labels") if isinstance(spec.get("labels"), dict) else {}
    context = spec.get("context") if isinstance(spec.get("context"), dict) else {}
    design = spec.get("design") if isinstance(spec.get("design"), dict) else {}
    medium = spec.get("medium") if isinstance(spec.get("medium"), dict) else {}

    if not str(spec.get("purpose", "")).strip():
        add(findings, "warning", "purpose", "No analytical purpose is stated.", "State the viewer's comparison or decision before choosing a display form.")
    else:
        passed.append("analytical purpose stated")

    if chart in {"bar", "bar_chart", "column", "column_chart", "stacked_bar", "grouped_bar"}:
        baseline = axes.get("y_zero_baseline")
        if is_false(baseline) and not is_true(axes.get("axis_break")):
            add(findings, "severe", "graphical integrity", "Bars encode magnitude by length but the quantitative axis is not marked as starting at zero.", "Start the quantitative axis at zero, or use a dot/difference plot if deviations are the point.")
        elif is_true(baseline):
            passed.append("bar/column baseline starts at zero")

    if chart in {"pie", "donut", "doughnut"}:
        slices = spec.get("slices") or spec.get("categories") or spec.get("data_points")
        try:
            if slices is not None and int(slices) > 5:
                add(findings, "warning", "comparison", "The part-to-whole chart appears to have many slices.", "Use a sorted bar, table, or grouped categories when ranking or exact comparison matters.")
        except (TypeError, ValueError):
            pass

    if chart in {"choropleth", "map", "symbol_map"} and is_false(context.get("denominator_shown")):
        add(findings, "warning", "denominator", "The map lacks a visible denominator or exposure basis.", "Use rates or normalized values when raw counts mostly reflect population, area, tests, stores, or exposure.")

    if is_true(axes.get("axis_break")):
        add(findings, "warning", "scale", "The spec uses an axis break.", "Use an unbroken scale when possible; otherwise label the break prominently and explain why it is needed.")
    if is_true(axes.get("dual_axis")):
        add(findings, "warning", "scale", "The spec uses dual axes.", "Check whether the apparent relationship depends on arbitrary scaling; consider indexed series, small multiples, or a scatterplot.")
    if is_false(axes.get("same_scale_across_panels")):
        add(findings, "warning", "comparison", "Comparable panels are not marked as using the same scale.", "Use common scales when cross-panel magnitude matters, or label independent scaling clearly.")

    if is_false(axes.get("x_labeled")):
        add(findings, "warning", "labeling", "The x-axis is not labeled.", "Add an x-axis label or direct labels that make the horizontal variable unambiguous.")
    if is_false(axes.get("y_labeled")):
        add(findings, "warning", "labeling", "The y-axis is not labeled.", "Add a y-axis label with units.")
    if is_false(axes.get("units_shown")):
        add(findings, "warning", "labeling", "Units are not visible.", "Show units in axis labels, legends, annotations, or caption.")
    elif is_true(axes.get("units_shown")):
        passed.append("units shown")

    if is_false(labels.get("source_shown")):
        add(findings, "warning", "context", "The data source is not shown.", "Add a concise source note for decision, publication, or external-facing use.")
    if is_false(labels.get("definitions_shown")):
        add(findings, "info", "context", "Definitions are not shown.", "Define abbreviations, derived rates, filters, or inclusion rules when readers may not know them.")

    uncertainty = context.get("uncertainty_shown")
    if is_false(uncertainty):
        add(findings, "warning", "uncertainty", "Uncertainty is hidden or marked absent.", "If these are estimates, forecasts, samples, simulations, or measurements, show intervals, bands, sample sizes, or caveats.")
    elif is_unknown(uncertainty):
        add(findings, "info", "uncertainty", "Uncertainty treatment is unspecified.", "If values are estimates, forecasts, samples, simulations, or measurements, state or show uncertainty.")
    else:
        passed.append("uncertainty treatment specified")

    if is_false(context.get("sample_size_shown")):
        add(findings, "info", "sample size", "Sample size is not shown.", "Show sample size when it affects reliability or comparison.")
    if is_false(context.get("time_range_justified")):
        add(findings, "warning", "context", "The time range is not justified.", "Include enough history or context for the claim, or state why the selected window is appropriate.")

    if is_true(design.get("three_d")):
        add(findings, "severe", "chartjunk", "The design uses 3D or perspective effects.", "Remove 3D unless the data are truly spatial and perspective is necessary.")
    if is_true(design.get("background_image")):
        add(findings, "warning", "chartjunk", "The chart uses a background image.", "Remove background imagery unless it is part of the data context, such as a map or instrument image.")
    decorations = design.get("decorations") or []
    if isinstance(decorations, str):
        decorations = [decorations]
    if decorations:
        add(findings, "warning", "data-ink", "Decorative elements are listed: " + ", ".join(map(str, decorations)) + ".", "Remove decorations unless each one directly supports interpretation.")
    if is_true(design.get("uses_area_for_quantity")):
        add(findings, "warning", "encoding", "Area encodes quantity.", "Confirm displayed area is proportional to value; prefer position or length for precise comparison.")
    if is_true(design.get("uses_volume_for_quantity")):
        add(findings, "severe", "encoding", "Volume encodes quantity.", "Avoid volume encodings for non-spatial quantities.")
    if is_true(design.get("color_is_only_identifier")):
        add(findings, "warning", "accessibility", "Color is the only identifier for at least one grouping.", "Add direct labels, symbols, line styles, or panel labels.")
    try:
        if int(design.get("color_count", 0)) > 8:
            add(findings, "info", "color", "The spec uses many colors.", "Check whether facets, grouping, or highlighting would reduce color lookup.")
    except (TypeError, ValueError):
        pass
    try:
        min_pt = float(medium.get("minimum_text_size_pt"))
        if min_pt < 8:
            add(findings, "warning", "accessibility", "Minimum text size is below 8 pt.", "Increase text size or simplify labels for the intended medium.")
    except (TypeError, ValueError):
        pass

    lie_factor: Optional[float] = None
    data_effect = get(spec, "integrity_measurements.data_effect_percent")
    visual_effect = get(spec, "integrity_measurements.visual_effect_percent")
    if data_effect is not None or visual_effect is not None:
        try:
            data_value = float(data_effect)
            visual_value = float(visual_effect)
            if math.isclose(data_value, 0.0):
                add(findings, "warning", "lie factor", "Cannot compute lie factor because the data effect is zero.", "Use absolute differences or another proportionality check.")
            else:
                lie_factor = visual_value / data_value
                if lie_factor < 0:
                    add(findings, "severe", "lie factor", f"Lie factor is {lie_factor:.3g}, implying opposite visual and numerical direction.", "Check the encoding; the visual direction should not reverse the numerical direction.")
                elif not (0.95 <= lie_factor <= 1.05):
                    severity = "severe" if lie_factor < 0.67 or lie_factor > 1.5 else "warning"
                    add(findings, severity, "lie factor", f"Lie factor is {lie_factor:.3g}; visual change is not proportional to data change.", "Make visual dimensions proportional to numerical quantities or use a safer encoding.")
                else:
                    passed.append("lie factor is near 1")
        except (TypeError, ValueError):
            add(findings, "info", "lie factor", "Lie factor inputs are incomplete or not numeric.", "Provide numeric data_effect_percent and visual_effect_percent if visual distortion can be measured.")

    findings.sort(key=lambda f: (SEVERITY_RANK.get(f.severity, 9), f.category, f.message))
    penalty = sum(SEVERITY_PENALTY.get(f.severity, 0) for f in findings)
    score = max(0, 100 - penalty)
    top_priorities = [asdict(f) for f in findings if f.severity in {"severe", "warning"}][:3]
    return {
        "title": spec.get("title"),
        "chart_type": chart or None,
        "score_0_100": score,
        "lie_factor": lie_factor,
        "findings": [asdict(f) for f in findings],
        "top_priorities": top_priorities,
        "passed_checks": passed,
    }


def print_markdown(result: Dict[str, Any]) -> None:
    print(f"Audit score: {result['score_0_100']}/100")
    if result.get("lie_factor") is not None:
        print(f"Lie factor: {result['lie_factor']:.3g}")
    if result.get("top_priorities"):
        print("\nTop priorities:")
        for item in result["top_priorities"]:
            print(f"- {item['severity'].upper()} — {item['category']}: {item['message']} Recommendation: {item['recommendation']}")
    if result.get("findings"):
        print("\nAll findings:")
        for item in result["findings"]:
            print(f"- {item['severity'].upper()} — {item['category']}: {item['message']} Recommendation: {item['recommendation']}")
    else:
        print("\nNo findings from the automated checklist. Human review is still required.")
    if result.get("passed_checks"):
        print("\nPassed checks:")
        for item in result["passed_checks"]:
            print(f"- {item}")


def main(argv: Optional[list[str]] = None) -> int:
    parser = argparse.ArgumentParser(description="Audit a JSON chart spec for quantitative-display integrity and clarity.")
    parser.add_argument("--spec", type=Path, help="Path to JSON chart spec.")
    parser.add_argument("--template", action="store_true", help="Print a JSON chart-spec template to stdout.")
    parser.add_argument("--format", choices=("json", "markdown"), default="json")
    args = parser.parse_args(argv)

    if args.template:
        print(json.dumps(TEMPLATE, indent=2))
        return 0
    if not args.spec:
        parser.error("provide --spec chart.json or --template")
    result = audit(load_spec(args.spec))
    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        print_markdown(result)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Check WCAG-style contrast ratios for chart labels and annotations."""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple

HEX_RE = re.compile(r"^#?([0-9a-fA-F]{6})$")


def parse_hex(color: str) -> Tuple[float, float, float]:
    m = HEX_RE.match(color.strip())
    if not m:
        raise ValueError(f"invalid hex color: {color!r}; expected #RRGGBB")
    raw = m.group(1)
    return tuple(int(raw[i:i+2], 16) / 255.0 for i in (0, 2, 4))  # type: ignore[return-value]


def linearize(c: float) -> float:
    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4


def luminance(color: str) -> float:
    r, g, b = parse_hex(color)
    rl, gl, bl = linearize(r), linearize(g), linearize(b)
    return 0.2126 * rl + 0.7152 * gl + 0.0722 * bl


def contrast_ratio(foreground: str, background: str) -> float:
    l1, l2 = luminance(foreground), luminance(background)
    hi, lo = max(l1, l2), min(l1, l2)
    return (hi + 0.05) / (lo + 0.05)


def classify(ratio: float, large_text: bool = False) -> Dict[str, Any]:
    aa_threshold = 3.0 if large_text else 4.5
    aaa_threshold = 4.5 if large_text else 7.0
    return {"passes_AA": ratio >= aa_threshold, "passes_AAA": ratio >= aaa_threshold, "AA_threshold": aa_threshold, "AAA_threshold": aaa_threshold}


def check_pair(fg: str, bg: str, label: str = "pair", large_text: bool = False) -> Dict[str, Any]:
    ratio = contrast_ratio(fg, bg)
    return {"label": label, "foreground": fg, "background": bg, "contrast_ratio": ratio, "large_text": large_text, **classify(ratio, large_text)}


def load_pairs(path: Path) -> List[Dict[str, Any]]:
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except FileNotFoundError:
        raise SystemExit(f"Error: palette file not found: {path}")
    except json.JSONDecodeError as exc:
        raise SystemExit(f"Error: invalid JSON in {path}: {exc}")
    if isinstance(data, dict) and "pairs" in data:
        pairs = data["pairs"]
    elif isinstance(data, list):
        pairs = data
    else:
        raise SystemExit("Error: palette JSON must be a list or an object with a 'pairs' list.")
    if not isinstance(pairs, list):
        raise SystemExit("Error: 'pairs' must be a list.")
    return pairs


def print_markdown(results: List[Dict[str, Any]]) -> None:
    for item in results:
        status = "PASS" if item["passes_AA"] else "FAIL"
        print(f"- {status} {item['label']}: {item['foreground']} on {item['background']} ratio {item['contrast_ratio']:.2f}:1 (AA threshold {item['AA_threshold']}:1)")


def main(argv: Optional[list[str]] = None) -> int:
    parser = argparse.ArgumentParser(description="Check color contrast for chart text, labels, and annotation colors.")
    parser.add_argument("--foreground", help="Foreground/text color as #RRGGBB.")
    parser.add_argument("--background", help="Background color as #RRGGBB.")
    parser.add_argument("--label", default="pair", help="Label for a single color pair.")
    parser.add_argument("--large-text", action="store_true", help="Use large-text contrast thresholds.")
    parser.add_argument("--palette", type=Path, help="JSON file with pairs: [{label, foreground, background, large_text}].")
    parser.add_argument("--format", choices=("json", "markdown"), default="json")
    args = parser.parse_args(argv)

    try:
        if args.palette:
            results = [check_pair(str(p["foreground"]), str(p["background"]), str(p.get("label", "pair")), bool(p.get("large_text", False))) for p in load_pairs(args.palette)]
        else:
            if not args.foreground or not args.background:
                parser.error("provide --foreground and --background, or --palette palette.json")
            results = [check_pair(args.foreground, args.background, args.label, args.large_text)]
    except (KeyError, ValueError) as exc:
        print(f"Error: {exc}", file=sys.stderr)
        return 2

    if args.format == "json":
        print(json.dumps({"results": results}, indent=2))
    else:
        print_markdown(results)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Check a draft visualization critique for repetitive stock language."""

from __future__ import annotations

import argparse
import json
import re
import sys
from collections import Counter
from pathlib import Path
from typing import Any, Dict, List, Optional

STOCK_PHRASES = [
    "show the data",
    "small multiples",
    "chartjunk",
    "data-ink",
    "direct labels",
    "zero baseline",
    "graphical integrity",
    "visual clutter",
    "make comparison easier",
    "avoid distortion",
    "clearer and more honest",
]


def read_text(path: Optional[str]) -> str:
    if not path or path == "-":
        return sys.stdin.read()
    try:
        return Path(path).read_text(encoding="utf-8")
    except FileNotFoundError:
        raise SystemExit(f"Error: input file not found: {path}")


def sentence_starts(text: str) -> Counter[str]:
    sentences = re.split(r"(?<=[.!?])\s+|\n+", text.strip())
    starts: Counter[str] = Counter()
    for sent in sentences:
        words = re.findall(r"[A-Za-z][A-Za-z'-]*", sent.lower())
        if len(words) >= 2:
            starts[" ".join(words[:2])] += 1
    return starts


def analyze(text: str) -> Dict[str, Any]:
    lower = text.lower()
    phrase_counts = {phrase: len(re.findall(re.escape(phrase), lower)) for phrase in STOCK_PHRASES}
    phrase_counts = {k: v for k, v in phrase_counts.items() if v > 1}
    starts = {k: v for k, v in sentence_starts(text).items() if v > 1}
    warnings: List[str] = []
    if phrase_counts:
        warnings.append("Repeated stock visualization terms detected; keep them only where they diagnose a real issue.")
    if starts:
        warnings.append("Repeated sentence starts detected; vary opener shapes across critique items.")
    return {"warnings": warnings, "repeated_stock_phrases": phrase_counts, "repeated_sentence_starts": starts, "character_count": len(text)}


def print_markdown(result: Dict[str, Any]) -> None:
    if result["warnings"]:
        print("Fingerprint warnings:")
        for warning in result["warnings"]:
            print(f"- {warning}")
    else:
        print("No major repetition warnings.")
    if result["repeated_stock_phrases"]:
        print("\nStock phrase counts:")
        for phrase, count in sorted(result["repeated_stock_phrases"].items()):
            print(f"- {phrase}: {count}")
    if result["repeated_sentence_starts"]:
        print("\nRepeated sentence starts:")
        for start, count in sorted(result["repeated_sentence_starts"].items()):
            print(f"- {start}: {count}")


def main(argv: Optional[list[str]] = None) -> int:
    parser = argparse.ArgumentParser(description="Check a draft visualization critique for repetitive stock language.")
    parser.add_argument("--input", help="Text or Markdown file. Omit or use - for stdin.")
    parser.add_argument("--format", choices=("json", "markdown"), default="json")
    args = parser.parse_args(argv)
    result = analyze(read_text(args.input))
    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        print_markdown(result)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Compute Tufte-style lie factor for a quantitative display."""

from __future__ import annotations

import argparse
import json
import math
import sys
from typing import Any, Dict, Optional


def pct_change(before: float, after: float) -> float:
    if math.isclose(before, 0.0):
        raise ValueError("before value is zero; percentage change is undefined")
    return (after - before) / abs(before) * 100.0


def classify(lf: Optional[float]) -> str:
    if lf is None:
        return "not_computed"
    if lf < 0:
        return "severe_reverse_direction"
    if 0.95 <= lf <= 1.05:
        return "proportional"
    if 0.67 <= lf < 0.95 or 1.05 < lf <= 1.5:
        return "moderate_distortion"
    return "severe_distortion"


def main(argv: Optional[list[str]] = None) -> int:
    parser = argparse.ArgumentParser(
        description="Compute lie factor: visual effect divided by data effect.",
        epilog=(
            "Examples:\n"
            "  python3 scripts/lie_factor.py --data-effect 20 --visual-effect 60\n"
            "  python3 scripts/lie_factor.py --data-before 100 --data-after 120 "
            "--visual-before 10 --visual-after 16 --format markdown"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("--data-effect", type=float, help="Numerical percentage change in the data.")
    parser.add_argument("--visual-effect", type=float, help="Percentage change in the perceived visual dimension.")
    parser.add_argument("--data-before", type=float, help="Initial data value.")
    parser.add_argument("--data-after", type=float, help="Final data value.")
    parser.add_argument("--visual-before", type=float, help="Initial visual dimension, such as bar length, area, or symbol height.")
    parser.add_argument("--visual-after", type=float, help="Final visual dimension.")
    parser.add_argument("--format", choices=("json", "markdown"), default="json")
    args = parser.parse_args(argv)

    try:
        data_effect = args.data_effect
        visual_effect = args.visual_effect
        if data_effect is None:
            if args.data_before is None or args.data_after is None:
                parser.error("provide --data-effect or both --data-before and --data-after")
            data_effect = pct_change(args.data_before, args.data_after)
        if visual_effect is None:
            if args.visual_before is None or args.visual_after is None:
                parser.error("provide --visual-effect or both --visual-before and --visual-after")
            visual_effect = pct_change(args.visual_before, args.visual_after)
        if math.isclose(data_effect, 0.0):
            raise ValueError("data effect is zero; lie factor is undefined")
        lie_factor = visual_effect / data_effect
    except ValueError as exc:
        print(f"Error: {exc}", file=sys.stderr)
        return 2

    result: Dict[str, Any] = {
        "data_effect_percent": data_effect,
        "visual_effect_percent": visual_effect,
        "lie_factor": lie_factor,
        "classification": classify(lie_factor),
        "interpretation": "values near 1 are proportional; values far from 1 suggest visual distortion",
    }

    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        print(f"Lie factor: {lie_factor:.3g}")
        print(f"Data effect: {data_effect:.3g}%")
        print(f"Visual effect: {visual_effect:.3g}%")
        print(f"Classification: {result['classification']}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Render a simple, dependency-free SVG chart from CSV data.

This is intentionally modest: it creates reviewable first-pass bar, dot, line,
and scatter charts with labels and honest defaults. Use full plotting libraries
for publication-grade output when available.
"""

from __future__ import annotations

import argparse
import csv
import html
import json
import math
import re
import sys
from collections import defaultdict
from pathlib import Path
from typing import Any, Dict, Iterable, List, Optional, Tuple

DATE_RE = re.compile(r"^(\d{4}-\d{1,2}-\d{1,2}|\d{4}-\d{1,2}|\d{1,2}/\d{1,2}/\d{2,4})$")
PALETTE = ["#222222", "#666666", "#999999", "#444444", "#777777", "#bbbbbb"]


def to_float(value: Any) -> Optional[float]:
    try:
        if value is None or str(value).strip() == "":
            return None
        return float(str(value).replace(",", ""))
    except ValueError:
        return None


def read_csv(path: Path) -> List[Dict[str, str]]:
    try:
        with path.open("r", encoding="utf-8-sig", newline="") as handle:
            rows = list(csv.DictReader(handle))
    except FileNotFoundError:
        raise SystemExit(f"Error: CSV file not found: {path}")
    except csv.Error as exc:
        raise SystemExit(f"Error: could not parse CSV: {exc}")
    if not rows:
        raise SystemExit("Error: CSV has no data rows.")
    return rows


def infer_chart(rows: List[Dict[str, str]], x: str, y: str, group: Optional[str]) -> str:
    xs = [r.get(x, "") for r in rows]
    x_numeric = sum(1 for v in xs if to_float(v) is not None) / max(1, len(xs)) > 0.85
    x_date = sum(1 for v in xs if DATE_RE.match(str(v).strip())) / max(1, len(xs)) > 0.5
    if x_date:
        return "line"
    if x_numeric:
        return "scatter"
    unique_x = len(set(xs))
    return "bar" if unique_x <= 25 and not group else "dot"


def scale(value: float, domain_min: float, domain_max: float, range_min: float, range_max: float) -> float:
    if math.isclose(domain_min, domain_max):
        return (range_min + range_max) / 2
    return range_min + (value - domain_min) / (domain_max - domain_min) * (range_max - range_min)


def nice_ticks(vmin: float, vmax: float, count: int = 5) -> List[float]:
    if math.isclose(vmin, vmax):
        return [vmin]
    span = vmax - vmin
    raw_step = span / max(1, count - 1)
    mag = 10 ** math.floor(math.log10(abs(raw_step)))
    norm = raw_step / mag
    if norm <= 1:
        step = 1 * mag
    elif norm <= 2:
        step = 2 * mag
    elif norm <= 5:
        step = 5 * mag
    else:
        step = 10 * mag
    start = math.floor(vmin / step) * step
    ticks = []
    val = start
    while val <= vmax + step * 0.5 and len(ticks) < 20:
        if val >= vmin - step * 0.1:
            ticks.append(0.0 if math.isclose(val, 0.0) else val)
        val += step
    return ticks


def fmt_num(v: float) -> str:
    if abs(v) >= 1000 or (abs(v) < 0.01 and not math.isclose(v, 0)):
        return f"{v:.2g}"
    if math.isclose(v, round(v)):
        return str(int(round(v)))
    return f"{v:.3g}"


def aggregate(rows: List[Dict[str, str]], x: str, y: str, group: Optional[str]) -> List[Dict[str, Any]]:
    acc: Dict[Tuple[str, str], List[float]] = defaultdict(list)
    for r in rows:
        yv = to_float(r.get(y))
        if yv is None:
            continue
        xv = str(r.get(x, ""))
        gv = str(r.get(group, "")) if group else ""
        acc[(xv, gv)].append(yv)
    data = []
    for (xv, gv), vals in acc.items():
        data.append({"x": xv, "group": gv, "y": sum(vals) / len(vals), "n": len(vals)})
    return data


def svg_text(x: float, y: float, text: str, size: int = 11, anchor: str = "middle", extra: str = "") -> str:
    return f'<text x="{x:.1f}" y="{y:.1f}" font-family="Arial, sans-serif" font-size="{size}" text-anchor="{anchor}" {extra}>{html.escape(text)}</text>'


def render(rows: List[Dict[str, str]], x: str, y: str, chart: str, group: Optional[str], title: str, width: int, height: int) -> Tuple[str, Dict[str, Any]]:
    data = aggregate(rows, x, y, group)
    if not data:
        raise SystemExit("Error: no numeric y values found after parsing.")
    if chart == "auto":
        chart = infer_chart(rows, x, y, group)
    if chart not in {"bar", "dot", "line", "scatter"}:
        raise SystemExit("Error: --chart must be one of auto, bar, dot, line, scatter.")

    margin = {"left": 72, "right": 32 if not group else 90, "top": 58, "bottom": 74}
    plot_x0, plot_y0 = margin["left"], margin["top"]
    plot_x1, plot_y1 = width - margin["right"], height - margin["bottom"]
    plot_w, plot_h = plot_x1 - plot_x0, plot_y1 - plot_y0
    yvals = [d["y"] for d in data]
    if chart == "bar":
        ymin, ymax = min(0, min(yvals)), max(0, max(yvals))
    else:
        pad = (max(yvals) - min(yvals)) * 0.08 or 1.0
        ymin, ymax = min(yvals) - pad, max(yvals) + pad
        if min(yvals) >= 0 and ymin < 0:
            ymin = 0
    ticks = nice_ticks(ymin, ymax)
    if ticks:
        ymin = min(ymin, min(ticks)); ymax = max(ymax, max(ticks))

    elements = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">', '<rect width="100%" height="100%" fill="white"/>']
    elements.append(svg_text(width/2, 26, title or f"{y} by {x}", size=16))
    elements.append(svg_text(width/2, height-16, x, size=12))
    elements.append(f'<text x="18" y="{height/2:.1f}" font-family="Arial, sans-serif" font-size="12" text-anchor="middle" transform="rotate(-90 18 {height/2:.1f})">{html.escape(y)}</text>')

    # Grid and y axis labels
    for t in ticks:
        yy = scale(t, ymin, ymax, plot_y1, plot_y0)
        elements.append(f'<line x1="{plot_x0}" y1="{yy:.1f}" x2="{plot_x1}" y2="{yy:.1f}" stroke="#dddddd" stroke-width="1"/>')
        elements.append(svg_text(plot_x0-8, yy+4, fmt_num(t), size=10, anchor="end"))
    elements.append(f'<line x1="{plot_x0}" y1="{plot_y0}" x2="{plot_x0}" y2="{plot_y1}" stroke="#333333" stroke-width="1"/>')
    elements.append(f'<line x1="{plot_x0}" y1="{plot_y1}" x2="{plot_x1}" y2="{plot_y1}" stroke="#333333" stroke-width="1"/>')

    warnings: List[str] = []
    groups = sorted(set(d["group"] for d in data)) if group else [""]
    group_color = {g: PALETTE[i % len(PALETTE)] for i, g in enumerate(groups)}

    if chart in {"bar", "dot", "line"}:
        xcats = sorted(set(d["x"] for d in data), key=lambda v: (not DATE_RE.match(str(v)), str(v)))
        xpos = {cat: plot_x0 + (i + 0.5) * plot_w / max(1, len(xcats)) for i, cat in enumerate(xcats)}
        # x labels, sampled if dense
        step = max(1, math.ceil(len(xcats) / 12))
        for i, cat in enumerate(xcats):
            if i % step == 0 or i == len(xcats) - 1:
                elements.append(svg_text(xpos[cat], plot_y1+18, str(cat), size=10, anchor="middle", extra='transform="rotate(35 {:.1f} {:.1f})"'.format(xpos[cat], plot_y1+18) if len(str(cat)) > 8 else ""))
        if chart == "bar":
            if group:
                warnings.append("Grouped bars are simplified; consider dot plots or small multiples if many groups need comparison.")
            bw = plot_w / max(1, len(xcats)) * 0.72 / max(1, len(groups))
            zero_y = scale(0, ymin, ymax, plot_y1, plot_y0)
            for d in data:
                gi = groups.index(d["group"])
                cx = xpos[d["x"]] - (len(groups)-1)*bw/2 + gi*bw
                yy = scale(d["y"], ymin, ymax, plot_y1, plot_y0)
                top, bottom = min(yy, zero_y), max(yy, zero_y)
                elements.append(f'<rect x="{cx-bw/2:.1f}" y="{top:.1f}" width="{bw:.1f}" height="{max(1,bottom-top):.1f}" fill="{group_color[d["group"]]}"/>')
        elif chart == "dot":
            for d in data:
                gi = groups.index(d["group"])
                jitter = (gi - (len(groups)-1)/2) * 8
                cx = xpos[d["x"]] + jitter
                yy = scale(d["y"], ymin, ymax, plot_y1, plot_y0)
                elements.append(f'<circle cx="{cx:.1f}" cy="{yy:.1f}" r="4" fill="{group_color[d["group"]]}"/>')
        else:  # line
            for g in groups:
                series = sorted([d for d in data if d["group"] == g], key=lambda d: xcats.index(d["x"]))
                pts = [(xpos[d["x"]], scale(d["y"], ymin, ymax, plot_y1, plot_y0), d) for d in series]
                path = " ".join(("M" if i == 0 else "L") + f" {px:.1f} {py:.1f}" for i, (px, py, _) in enumerate(pts))
                elements.append(f'<path d="{path}" fill="none" stroke="{group_color[g]}" stroke-width="2"/>')
                for px, py, _ in pts:
                    elements.append(f'<circle cx="{px:.1f}" cy="{py:.1f}" r="2.6" fill="{group_color[g]}"/>')
                if group and pts:
                    px, py, _ = pts[-1]
                    elements.append(svg_text(px+6, py+4, str(g), size=10, anchor="start"))
    else:  # scatter
        xnums: List[float] = []
        points: List[Tuple[float, float, str]] = []
        for r in rows:
            xv = to_float(r.get(x)); yv = to_float(r.get(y))
            if xv is None or yv is None:
                continue
            gv = str(r.get(group, "")) if group else ""
            xnums.append(xv); points.append((xv, yv, gv))
        if not points:
            raise SystemExit("Error: scatter chart requires numeric x and y values.")
        xmin, xmax = min(xnums), max(xnums)
        xpad = (xmax-xmin)*0.08 or 1.0
        xmin, xmax = xmin-xpad, xmax+xpad
        xticks = nice_ticks(xmin, xmax)
        for t in xticks:
            xx = scale(t, xmin, xmax, plot_x0, plot_x1)
            elements.append(f'<line x1="{xx:.1f}" y1="{plot_y0}" x2="{xx:.1f}" y2="{plot_y1}" stroke="#eeeeee" stroke-width="1"/>')
            elements.append(svg_text(xx, plot_y1+18, fmt_num(t), size=10))
        for xv, yv, gv in points:
            xx = scale(xv, xmin, xmax, plot_x0, plot_x1)
            yy = scale(yv, ymin, ymax, plot_y1, plot_y0)
            elements.append(f'<circle cx="{xx:.1f}" cy="{yy:.1f}" r="3.5" fill="{group_color.get(gv, PALETTE[0])}" opacity="0.85"/>')

    if group and chart != "line":
        lx, ly = plot_x1 + 10, plot_y0 + 12
        for i, g in enumerate(groups):
            yleg = ly + i*18
            elements.append(f'<rect x="{lx}" y="{yleg-9}" width="10" height="10" fill="{group_color[g]}"/>')
            elements.append(svg_text(lx+14, yleg, str(g), size=10, anchor="start"))

    elements.append(svg_text(plot_x0, height-4, f"Generated as a first-pass SVG; verify source, units, uncertainty, and accessibility before publication.", size=9, anchor="start"))
    elements.append("</svg>")
    metadata = {"chart": chart, "x": x, "y": y, "group": group, "rows_input": len(rows), "points_rendered": len(data), "warnings": warnings, "integrity_defaults": ["bar charts include zero baseline", "axes and units should be reviewed", "source and uncertainty must be added if relevant"]}
    return "\n".join(elements), metadata


def main(argv: Optional[List[str]] = None) -> int:
    parser = argparse.ArgumentParser(description="Render a simple SVG chart from CSV using dependency-free, honest defaults.")
    parser.add_argument("--csv", type=Path, required=True, help="Input CSV with a header row.")
    parser.add_argument("--x", required=True, help="Column for x/category/time/relationship axis.")
    parser.add_argument("--y", required=True, help="Numeric column for y axis.")
    parser.add_argument("--group", help="Optional grouping column.")
    parser.add_argument("--chart", choices=("auto", "bar", "dot", "line", "scatter"), default="auto")
    parser.add_argument("--title", default="", help="Chart title.")
    parser.add_argument("--width", type=int, default=900)
    parser.add_argument("--height", type=int, default=520)
    parser.add_argument("--output", type=Path, required=True, help="Output SVG path.")
    parser.add_argument("--metadata", type=Path, help="Optional JSON metadata output path.")
    args = parser.parse_args(argv)

    if args.width < 400 or args.height < 300:
        print("Error: width must be >=400 and height >=300.", file=sys.stderr)
        return 2
    rows = read_csv(args.csv)
    headers = set(rows[0].keys())
    for col in [args.x, args.y, args.group]:
        if col and col not in headers:
            print(f"Error: column not found: {col}", file=sys.stderr)
            return 2
    svg, meta = render(rows, args.x, args.y, args.chart, args.group, args.title, args.width, args.height)
    args.output.write_text(svg, encoding="utf-8")
    if args.metadata:
        args.metadata.write_text(json.dumps(meta, indent=2), encoding="utf-8")
    print(json.dumps({"output": str(args.output), "metadata": meta}, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Suggest display families from a CSV's structure and a stated goal."""

from __future__ import annotations

import argparse
import csv
import json
import re
import statistics
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple

DATE_RE = re.compile(r"^(\d{4}-\d{1,2}-\d{1,2}|\d{1,2}/\d{1,2}/\d{2,4}|\d{4}-\d{1,2})$")
RATE_RE = re.compile(r"(rate|percent|percentage|pct|share|ratio|per_|per100|per_100|index|score|yield|density)", re.I)
COUNT_RE = re.compile(r"(count|n$|num|number|total|units|cases|incidents|defects|claims|clicks|population)", re.I)
GEO_RE = re.compile(r"(country|state|county|city|region|latitude|longitude|lat|lon|lng|postcode|zip)", re.I)
TIME_NAME_RE = re.compile(r"(date|time|year|month|week|day|quarter)", re.I)


def to_float(v: str) -> Optional[float]:
    try:
        return float(v.replace(",", ""))
    except (AttributeError, ValueError):
        return None


def infer_value(name: str, values: List[str]) -> str:
    sample = [str(v).strip() for v in values if v is not None and str(v).strip() != ""]
    if not sample:
        return "empty"
    if TIME_NAME_RE.search(name):
        date_hits = sum(1 for v in sample if DATE_RE.match(v))
        if date_hits / len(sample) >= 0.4:
            return "date_or_time"
    numeric = sum(1 for v in sample if to_float(v) is not None)
    dates = sum(1 for v in sample if DATE_RE.match(v))
    if dates / len(sample) >= 0.6:
        return "date_or_time"
    if numeric / len(sample) >= 0.85:
        return "quantitative"
    unique_ratio = len(set(sample)) / max(1, len(sample))
    if unique_ratio < 0.5 or len(set(sample)) <= 30:
        return "categorical"
    return "text_or_id"


def numeric_stats(values: List[str]) -> Dict[str, Optional[float]]:
    nums = [x for x in (to_float(str(v).strip()) for v in values) if x is not None]
    if not nums:
        return {"min": None, "max": None, "mean": None}
    return {"min": min(nums), "max": max(nums), "mean": statistics.fmean(nums)}


def inspect_csv(path: Path, max_rows: int) -> Dict[str, Any]:
    try:
        with path.open("r", encoding="utf-8-sig", newline="") as handle:
            reader = csv.DictReader(handle)
            if not reader.fieldnames:
                raise SystemExit("Error: CSV has no header row.")
            rows = []
            for idx, row in enumerate(reader):
                if idx >= max_rows:
                    break
                rows.append(row)
    except FileNotFoundError:
        raise SystemExit(f"Error: CSV file not found: {path}")
    except csv.Error as exc:
        raise SystemExit(f"Error: could not parse CSV: {exc}")

    columns = []
    for name in reader.fieldnames or []:
        vals = [row.get(name, "") for row in rows]
        kind = infer_value(name, vals)
        missing = sum(1 for v in vals if v is None or str(v).strip() == "")
        nonmissing = [str(v).strip() for v in vals if v is not None and str(v).strip() != ""]
        unique = len(set(nonmissing))
        role = ""
        if kind == "quantitative":
            if RATE_RE.search(name):
                role = "rate_or_normalized_measure"
            elif COUNT_RE.search(name):
                role = "count_or_exposure"
            else:
                role = "measure"
        elif kind == "categorical" and GEO_RE.search(name):
            role = "geographic_category"
        elif kind == "date_or_time":
            role = "time"
        columns.append({"name": name, "type": kind, "role": role, "missing_in_sample": missing, "unique_in_sample": unique, "stats": numeric_stats(vals) if kind == "quantitative" else None})
    return {"path": str(path), "sample_rows": len(rows), "columns": columns}


def choose_primary_quant(cols: List[Dict[str, Any]]) -> Optional[str]:
    q = [c for c in cols if c["type"] == "quantitative"]
    if not q:
        return None
    for c in q:
        if c.get("role") == "rate_or_normalized_measure":
            return c["name"]
    non_exposure = [c for c in q if c.get("role") != "count_or_exposure"]
    if non_exposure:
        return non_exposure[0]["name"]
    return q[0]["name"]


def recommendations(profile: Dict[str, Any], goal: str, question: str = "") -> List[Dict[str, Any]]:
    cols = profile["columns"]
    q = [c["name"] for c in cols if c["type"] == "quantitative"]
    cat = [c["name"] for c in cols if c["type"] == "categorical"]
    geo = [c["name"] for c in cols if c.get("role") == "geographic_category"]
    time = [c["name"] for c in cols if c["type"] == "date_or_time"]
    primary = choose_primary_quant(cols)
    recs: List[Dict[str, Any]] = []

    def add(display: str, why: str, caution: str = "", checks: Optional[List[str]] = None, priority: str = "candidate") -> None:
        recs.append({"display": display, "priority": priority, "why": why, "caution": caution, "integrity_checks": checks or []})

    normalized_available = any(c.get("role") == "rate_or_normalized_measure" for c in cols)
    count_available = any(c.get("role") == "count_or_exposure" for c in cols)

    if goal == "auto":
        if time and primary:
            display = "time-series line chart"
            if cat:
                display += " with direct labels or small multiples"
            add(display, f"{time[0]} supplies order and {primary} is the likely outcome measure.", "Use a common scale across panels if cross-group magnitude matters.", ["label time window", "show units", "annotate relevant events"], "strong")
        if cat and primary:
            add("sorted dot plot or zero-baseline bar chart", f"{cat[0]} can group {primary} for comparison.", "Use bars only when absolute magnitude from zero is the task; dots work well for compact ranked comparisons or intervals.", ["sort deliberately", "show units", "check zero baseline if bars"], "strong" if not time else "candidate")
        if len(q) >= 2:
            x, y = q[0], primary if primary and primary != q[0] else q[1]
            add("scatterplot", f"{x} and {y} support relationship, outlier, and leverage checks.", "Use transparency or density if there are many rows; label transformations.", ["check overplotting", "show fit only if model is meaningful"], "candidate")
        if primary:
            add("distribution display", f"{primary} can be inspected for spread, skew, and outliers.", "Avoid summarizing by mean alone if distribution affects the decision.", ["show sample size", "consider raw points"], "candidate")
        if geo and primary:
            add("map plus companion ranking", f"{geo[0]} suggests geography may matter for {primary}.", "Normalize by exposure when raw counts mostly reflect population or opportunity.", ["check denominator", "use a companion table/dot plot"], "candidate")
        if count_available and not normalized_available:
            add("rate or normalized measure before plotting", "The CSV appears to include raw counts or exposure fields but no obvious rate/share column.", "Create an appropriate denominator before making population- or opportunity-sensitive comparisons.", ["identify denominator", "label rate definition"], "caution")
        if not recs:
            add("table", "The sampled columns do not clearly support a quantitative chart.", "Clarify the analytical question or provide typed columns.", ["verify headers", "identify units"], "fallback")
    elif goal == "lookup":
        add("table or text-table", "Exact values are the main task.", "Sort and round deliberately; add inline bars only if pattern comparison matters.", ["align numbers", "show units"], "strong")
    elif goal == "trend":
        add("time-series line chart", "Ordered time is needed for trend, seasonality, or event effects.", "If no time column exists, identify or create one before plotting.", ["label time window", "annotate events", "use common scales for groups"], "strong")
    elif goal == "comparison":
        add("sorted bar or dot plot", "Magnitude comparison across categories is central.", "Bars need zero baselines; dots work well for many categories or intervals.", ["sort categories", "show units", "check baseline"], "strong")
    elif goal == "relationship":
        add("scatterplot", "Relationships need at least two quantitative variables.", "Label transformations and use density methods for overplotting.", ["check outliers", "avoid unjustified causal language"], "strong")
    elif goal == "distribution":
        add("histogram, dot plot, box plot, or violin", "Distribution tasks need spread, tails, and outliers.", "Choose a form the audience can read; show raw points when sample size is modest.", ["show sample size", "choose binning deliberately"], "strong")
    elif goal == "geography":
        add("map plus companion ranking", "Spatial position matters for geographic questions.", "Normalize by exposure when raw counts mostly reflect population or opportunity.", ["check denominator", "state projection/boundaries if relevant"], "strong")
    elif goal == "uncertainty":
        add("interval, band, fan, or distribution display", "Estimates and forecasts need uncertainty visible.", "Label what the interval means.", ["show interval definition", "avoid false precision"], "strong")
    return recs


def print_markdown(profile: Dict[str, Any], recs: List[Dict[str, Any]]) -> None:
    print(f"Rows sampled: {profile['sample_rows']}")
    print("Columns:")
    for col in profile["columns"]:
        extra = f", role={col['role']}" if col.get("role") else ""
        print(f"- {col['name']}: {col['type']}{extra} ({col['unique_in_sample']} unique, {col['missing_in_sample']} missing in sample)")
    print("\nRecommendations:")
    for rec in recs:
        line = f"- [{rec['priority']}] {rec['display']}: {rec['why']}"
        if rec.get("caution"):
            line += f" Caution: {rec['caution']}"
        print(line)
        if rec.get("integrity_checks"):
            print("  Checks: " + "; ".join(rec["integrity_checks"]))


def main(argv: Optional[list[str]] = None) -> int:
    parser = argparse.ArgumentParser(description="Inspect a CSV and suggest quantitative display families.")
    parser.add_argument("--csv", type=Path, required=True, help="Input CSV with a header row.")
    parser.add_argument("--goal", choices=("auto", "lookup", "trend", "comparison", "relationship", "distribution", "geography", "uncertainty"), default="auto")
    parser.add_argument("--question", default="", help="Optional user question to include in output metadata.")
    parser.add_argument("--max-rows", type=int, default=500, help="Rows to sample for type inference. Default: 500.")
    parser.add_argument("--format", choices=("json", "markdown"), default="json")
    args = parser.parse_args(argv)

    if args.max_rows <= 0:
        print("Error: --max-rows must be positive.", file=sys.stderr)
        return 2
    profile = inspect_csv(args.csv, args.max_rows)
    result = {"profile": profile, "goal": args.goal, "question": args.question, "recommendations": recommendations(profile, args.goal, args.question)}
    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        print_markdown(profile, result["recommendations"])
    return 0


if __name__ == "__main__":
    raise SystemExit(main())