Scatter charts

scatter owns independent x and y roles. Use it to inspect correlation, clusters, outliers, and tradeoffs between two measures.

Two measures

 1{
 2  "version": "2026-09-26",
 3  "config": {
 4    "version": "2026-09-26",
 5    "title": "Model size and training compute",
 6    "type": "scatter",
 7    "x": {
 8      "field": "parameters",
 9      "scale": {
10        "type": "log"
11      }
12    },
13    "y": {
14      "field": "compute",
15      "scale": {
16        "type": "log"
17      }
18    },
19    "xAxis": {
20      "title": "Parameters (billions)"
21    },
22    "yAxis": {
23      "title": "Compute (PF-days)"
24    },
25    "theme": "editorial"
26  },
27  "data": [
28    {
29      "parameters": 1,
30      "compute": 0.5
31    },
32    {
33      "parameters": 3,
34      "compute": 1.8
35    },
36    {
37      "parameters": 10,
38      "compute": 6
39    },
40    {
41      "parameters": 30,
42      "compute": 25
43    },
44    {
45      "parameters": 100,
46      "compute": 90
47    },
48    {
49      "parameters": 300,
50      "compute": 380
51    },
52    {
53      "parameters": 1000,
54      "compute": 1600
55    }
56  ],
57  "presentation": {
58    "background": "opaque",
59    "colorScheme": "system",
60    "systemFallback": "light"
61  }
62}

An id field gives points stable identity across updates and animation. It does not affect visual encoding.

Size encoding

Add size.field to encode a third numeric measure. range sets the minimum and maximum rendered radius; format and legend control its display semantics.

{
  "size": {
    "field": "population",
    "range": [4, 22],
    "format": ".3~s",
    "legend": { "title": "Population" }
  }
}

Use size for ordered magnitude, not category. Large circles can occlude smaller ones, so keep the range restrained.

Estimate intervals

Add interval when each point is an estimate with lower and upper bounds. The interval shares the selected point axis and expands its scale domain when needed.

{
  "interval": {
    "axis": "x",
    "lower": { "field": "lower" },
    "upper": { "field": "upper" },
    "stroke": { "width": 2 }
  }
}

Intervals paint behind their points. Use them for confidence intervals, credible intervals, and comparable estimate ranges rather than for unrelated line overlays.

Either axis may carry the interval and keeps its own band, linear, log, or UTC scale semantics. Lower, estimate, and upper follow that selected scale's order.

Intervals inherit point color by default. Set one optional uniform stroke color when every interval needs the same treatment:

{
  "interval": {
    "axis": "x",
    "lower": { "field": "start" },
    "upper": { "field": "end" },
    "stroke": { "color": "#2563eb", "width": 2 }
  }
}

The interval stroke does not create another color encoding or legend; point grouping, legends, and interaction continue to use the chart-level color encoding.

Categorical, sequential, and diverging color

Scatter color always names the encoded field explicitly.

{
  "color": {
    "type": "categorical",
    "field": "region",
    "domain": ["Americas", "EMEA", "APAC"],
    "legend": { "title": "Region" }
  }
}

Use type: "sequential" for ordered numeric magnitude. Use type: "diverging" when a required midpoint separates two meaningful directions inside an explicit numeric domain. Sequential color accepts two or three colors; diverging color accepts three or five. Both support formatting and a continuous legend. See Color for complete behavior and examples.

Labels, references, and annotations

labels.field prints one field beside each point. Labels prefer the side by default; use position: "above" when the text should sit over its point. Use labels for a small set of important identities rather than labeling a dense cloud.

Reference lines use axis: "x" | "y" and divide the plot at a fixed value or an average, median, minimum, or maximum calculated from the data. Annotations use either a stable datum anchor such as { type: "datum", id } or an exact { type: "coordinate", x, y } anchor. Together they support quadrants and highlighted outliers without introducing free-form drawing layers.

Scales

Both axes may independently use band, linear, log, or utc when compatible with their values. Log input and explicit log domains must be positive and finite. Use explicit domains only when the domain is part of the analysis; otherwise let Szum derive readable bounds.

Properties