Check Empty Entities

Check Empty Entities

After an indicator upgrade, a view can end up pinned to entities that have no data in the new indicators. Nothing fails: the pipeline is green, chart-diff renders, and the chart silently opens empty. This skill audits every surface that stores an entity selection against the entities that actually have data, and grades each finding against production so regressions and pre-existing gaps aren't conflated.

Called from: /update-dataset step 7 (author side — fix regressions before merge) and /review-data-pr §8d (reviewer side — verify the outcome). Keep those pointers in sync with this file.

Inputs

• Staging branch name (e.g. Marigold/wdi-update) — determines the DB (OWIDEnv.from_staging(branch)) and the indicators API prefix.
• The new grapher dataset: catalogPath <ns>/<version>/<short_name> or its datasets.id on staging.

Availability lookup (used by every check)

A variable's entities-with-data come from the indicators API metadata.json — not MySQL (indicator data lives outside the DB):

• Staging: OWIDEnv.from_staging(branch).indicators_url + /<id>.metadata.json → dimensions.entities.values[].name. Don't hand-build the staging-site-<branch> prefix — branch names with /, ., _ or over 28 characters get normalized/truncated (etl.config.get_container_name()), and a wrong prefix silently serves another environment instead of 404ing.
• Production: https://api.ourworldindata.org/v1/indicators/<id>.metadata.json

Cache per variable id and fetch in parallel (a large dataset means hundreds of variables). A failed fetch is unknown availability, not an empty set — track those variable ids separately and report them as coverage caveats; never grade a view on them.

Checks

Where dead selections come from (read before scanning)

Overwhelmingly from entity-rename cycles of a dataset's own aggregate entities — a past update changed the suffix convention (Multilaterals (OECD) → Multilateral organizations, Low-income countries (WB) → hyphenated unsuffixed forms) and every surface that pinned the old names kept them. Real-country selections almost never die; dataset-defined aggregates (donor groups, income groups, provider regions) are the population to watch. Two consequences for the audit: the moment one finding surfaces a renamed-suffix pattern, grep every surface for that pattern directly (chart selectedEntityNames and focusedSeriesNames, narrative-chart patches, article country= URLs) instead of relying only on per-view availability checks — the same rename hits them all; and note that dead names sit in both directions (an old suffixed form can die while its unsuffixed twin lives, or vice versa — check availability, don't pattern-guess the fix). (ODA 2026-07: one rename cycle left dead names on 5 charts, 6 narrative charts, and 4 published articles simultaneously.)

Fixing a dead selection: rename, drop, or neither

String similarity picks the fix, never validates it — it proposed Nigeria → Niger (different countries) in a real sweep. Before applying any rename, read the chart's whole selection, and gate every edit on three checks: the replacement must have data in that chart's own y-variables, must not already be selected, and the result must contain no duplicates. Drops need the mirror guard — refuse to remove any entity that does have data.

Reading the whole selection is what catches the two failure modes similarity can't:

• Scheme mismatch. A chart pinning a coherent non-provider scheme (Oceania, Central Asia, Eastern Europe, South America, Western & Central Europe…) against an indicator that only carries provider regions will offer tempting one-to-one matches for the handful whose names overlap (South Asia, North America). Applying them silently mixes two incompatible region definitions in one chart. The fix is a decision about which scheme the chart should use, not a rename — put it to the dataset owner.
• The target is already pinned. Then the dead name is a leftover, and the fix is a drop, not a rename — renaming duplicates the entity. Common after a partial past migration: the same chart carries both Sub-Saharan Africa and Sub-Saharan Africa (WB), or both the old and new MENA names. (Watch for genuinely renamed aggregates too: the World Bank's Middle East and North Africa became Middle East, North Africa, Afghanistan and Pakistan (WB) — a definitional change, not cosmetic.) Same for aggregates we never carry: Middle-income countries isn't one of the four WB income groups, and charts pinning it usually already have Upper-middle-income countries and Lower-middle-income countries.

Keep selectedEntityColors in step with every edit: on a rename, move the entry from the old name to the replacement (deleting it discards a deliberately assigned color — a visual regression); on a drop, delete the entry. Either way, don't leave a dangling color key. And check the excluded-countries file before proposing anything: an entity in <short_name>.excluded_countries.json (IDA only, Arab World, Heavily-indebted poor countries) can never have data, so a drop is the only option.

Getting the surface list. find-chart-references sweeps every surface in §1–§4 from a dataset or indicator subject and returns each reference with its query_string (where country= pins live) and an embed/render/link classification — use it (--dataset-id, plus --transitive for the article hop) rather than re-deriving the joins. It also expands chart subjects through chart_slug_redirects, which §4 requires. What stays here is the part it can't do: reading each surface's entity selection, checking it against entities-with-data, and grading the result against production.

1. Charts

For every chart on the new dataset (chart_dimensions → variables.datasetId), parse chart_configs.config:

• selectedEntityNames must intersect the union of the chart's y-variables' entities-with-data. Zero overlap on a non-empty selection = the chart renders empty.
• Skip ScatterPlot and Marimekko — they legitimately have no selectedEntityNames (they plot all entities). Detect them by shape, not by the type field: a chart with an x dimension renders as a scatter even when type is absent (reporting as the LineChart default). An empty selection means every entity renders, not none — so a bad value in such a chart is maximally visible, not hidden. (share-of-rural-population-with-electricity-access-vs-…, 0 selected + minTime: latest, is where a reader spotted Chad plotted at 100% rural electricity access.) Phrasing a report line as "corrected entity not in selection" for these charts is actively misleading.
• Skip map-only charts — chartTypes: [] with hasMapTab: true has no chart tab, so selectedEntityNames never renders and a dead or partly dead selection is harmless. Note that [] is not the absent-field case: an absent chartTypes defaults to LineChart and must still be checked. The map itself is still covered by §2.
• A missing/empty selection on other chart types is only a finding if production's config differs — the upgrader never touches entity selections, so an empty selection is almost always pre-existing. Verify via public Datasette before flagging.
• Also flag any y-variable whose entity list is entirely empty (a broken indicator, not just a broken view).

2. Map tabs

For every chart with hasMapTab, validate map.columnSlug only when it is set — an absent columnSlug is valid (grapher defaults the map to the first y variable), so flagging None produces false blockers. When present it must be one of the chart's dimension variable ids; it's stored as a string — str-cast before comparing (the int-vs-string mismatch is exactly how the upgrader left map tabs pinned to old variables for years; see #6457). A set columnSlug that resolves to a variable outside the chart's dimensions, or to a dangling id, is a finding.

3. MDim views, explorer views, and narrative charts

Same selection-vs-availability check on their configs:

• MDim views: the sweep returns them with a config_id, covering all MDims (not just the dataset's own — another MDim can carry these variables in its y-dimensions) and finding multi-indicator views that mx.variableId alone misses, since that column records only the first y indicator.
• Explorer views: explorer panels render grapher configs and can pin selectedEntityNames too, so an upgraded explorer view can be empty while everything else passes. The sweep returns them one row per view (surface = "explorer view"), each with its own config_id, so they go through the same config loop as charts and MDim views. A surface = "explorer" row with no config_id means the indicator is registered on that explorer but no view config names it — report it as unchecked rather than passing it. Legacy CSV-backed explorers (data://explorers/... wide tables — e.g. the poverty explorer) appear in no DB table at all: their data and selections live in the explorer TSV, outside grapher configs, so report them as a coverage caveat instead of silently passing.
• Narrative charts: audit the full config, never the bare patch. The authored layer in narrative_charts.patchConfigId → chart_configs.config lacks every inherited field, so a narrative chart inheriting selectedEntityNames or dimensions from its parent can falsely pass — use AdminAPI(OWIDEnv.from_staging("<branch>")).get_narrative_chart(id)["configFull"] (this is the stored materialized chart_configs.config; it lags a parent edit until the child is re-saved — see /update-dataset step 7's narrative-chart notes). Pass the staging env explicitly — the global OWID_ENV points at your local/default environment unless the process was launched with STAGING=<branch>, and reading narrative configs from the wrong DB silently hides staging-only regressions.