{
  "state": "design_patterns_only",
  "preview_state": "schematic_not_calculated",
  "references": [
    "https://github.com/Financial-Times/chart-doctor/tree/main/visual-vocabulary",
    "https://observablehq.com/@observablehq/plot-gallery",
    "https://vega.github.io/vega/examples/"
  ],
  "patterns": [
    {
      "id": "bar",
      "title": "Ranked Bars",
      "purpose": "Compare one measure across a short list of entities",
      "required_shape": "entity x value",
      "pitfall": "Truncated axis or ranking unequal populations"
    },
    {
      "id": "dot",
      "title": "Dot Plot",
      "purpose": "Compare one measure across many entities with less ink",
      "required_shape": "entity x value",
      "pitfall": "Hiding suppressed entities"
    },
    {
      "id": "slope",
      "title": "Slope Chart",
      "purpose": "Show change between two periods per entity",
      "required_shape": "entity x two periods",
      "pitfall": "Definition change between the two periods"
    },
    {
      "id": "dumbbell",
      "title": "Dumbbell",
      "purpose": "Show gap between two values per entity",
      "required_shape": "entity x value A x value B",
      "pitfall": "Comparing values from different populations"
    },
    {
      "id": "line",
      "title": "Line Trend",
      "purpose": "Show a measure over many periods",
      "required_shape": "entity x period x value",
      "pitfall": "Bridging series breaks without a marker"
    },
    {
      "id": "area",
      "title": "Share Area",
      "purpose": "Show composition over time",
      "required_shape": "period x category x share",
      "pitfall": "Stacking categories that are not exhaustive"
    },
    {
      "id": "stacked-bar",
      "title": "Stacked Composition",
      "purpose": "Show parts of a whole per entity",
      "required_shape": "entity x category x value",
      "pitfall": "Parts that overlap or double count"
    },
    {
      "id": "waterfall",
      "title": "Waterfall",
      "purpose": "Show how components build to a total or change",
      "required_shape": "ordered component x signed value",
      "pitfall": "Mixing stocks and flows"
    },
    {
      "id": "scatter",
      "title": "Scatter",
      "purpose": "Show co-variation of two measures",
      "required_shape": "entity x value X x value Y",
      "pitfall": "Implying causation or trend lines on different populations"
    },
    {
      "id": "bubble",
      "title": "Bubble",
      "purpose": "Scatter with a third size measure",
      "required_shape": "entity x X x Y x size",
      "pitfall": "Area misread as radius"
    },
    {
      "id": "histogram",
      "title": "Histogram",
      "purpose": "Show distribution of one measure",
      "required_shape": "value list with bins",
      "pitfall": "Bin choice hiding suppressed ranges"
    },
    {
      "id": "box",
      "title": "Box Plot",
      "purpose": "Compare distributions across groups",
      "required_shape": "group x value list",
      "pitfall": "Small groups shown without counts"
    },
    {
      "id": "violin",
      "title": "Violin",
      "purpose": "Compare distribution shape across groups",
      "required_shape": "group x value list",
      "pitfall": "Smoothing inventing density where data are sparse"
    },
    {
      "id": "heatmap",
      "title": "Matrix Heatmap",
      "purpose": "Show availability or intensity across two categories",
      "required_shape": "row x column x value or flag",
      "pitfall": "Blank cells read as zero instead of unknown"
    },
    {
      "id": "calendar",
      "title": "Calendar",
      "purpose": "Place events or daily values in time",
      "required_shape": "date x value or event",
      "pitfall": "Time zone and schedule version drift"
    },
    {
      "id": "choropleth",
      "title": "Choropleth",
      "purpose": "Show rates by geographic area",
      "required_shape": "GEOID x rate x vintage",
      "pitfall": "Counts instead of rates; mixed vintages"
    },
    {
      "id": "symbol-map",
      "title": "Symbol Map",
      "purpose": "Show point locations with a size or category",
      "required_shape": "point x coordinates x attribute",
      "pitfall": "Overlapping symbols in dense areas"
    },
    {
      "id": "flow",
      "title": "Stage Flow",
      "purpose": "Show connected counts across stages in one source",
      "required_shape": "stage x stage x connected count",
      "pitfall": "Multiplying unrelated rates to fake a flow"
    },
    {
      "id": "sankey",
      "title": "Sankey",
      "purpose": "Show allocation flows between categories",
      "required_shape": "source node x target node x actual amount",
      "pitfall": "Flows not from one linked dataset"
    },
    {
      "id": "network",
      "title": "Network",
      "purpose": "Show documented links between entities",
      "required_shape": "node x node x link type",
      "pitfall": "Implying strength from layout"
    },
    {
      "id": "treemap",
      "title": "Treemap",
      "purpose": "Show hierarchical composition",
      "required_shape": "hierarchy x value",
      "pitfall": "Comparing areas across separate treemaps"
    },
    {
      "id": "waffle",
      "title": "Waffle",
      "purpose": "Show share of a whole as counted units",
      "required_shape": "category x share",
      "pitfall": "Rounding hiding small categories"
    },
    {
      "id": "interval",
      "title": "Range Interval",
      "purpose": "Show a low-high range per entity",
      "required_shape": "entity x low x high",
      "pitfall": "Ranges from different definitions"
    },
    {
      "id": "small-multiples",
      "title": "Small Multiples",
      "purpose": "Repeat one chart across entities for comparison",
      "required_shape": "entity x period x value",
      "pitfall": "Independent axes misread as shared"
    }
  ]
}