# Metadata for data/population.csv
# Regenerate the data (and the stamps below) with: python3 data/population.py

name: population
title: Sovereign states, their capitals, and both populations
description: >
  One row per (country, capital) pair for present-day sovereign states, with the
  most recent population figure available for the country and for its capital
  city. Built to back the small daily geography game on the lcsrg.me home page,
  so it favours recognisable English names over formal legal ones.

date_retrieved: 2026-09-05
n_rows: 201

source:
  name: Wikidata Query Service
  url: https://query.wikidata.org/
  license: CC0 1.0 Universal (public domain dedication)
  license_url: https://creativecommons.org/publicdomain/zero/1.0/
  citation: >
    Wikidata contributors. Wikidata, the free knowledge base. Retrieved via the
    Wikidata Query Service (SPARQL).
  description: >
    Wikidata is a collaboratively edited knowledge base. Its population figures
    are sourced by contributors from national statistical offices, national
    censuses, and UN estimates, and each statement may carry a "point in time"
    qualifier recording the reference date of the figure.

# Wikidata entities and properties this dataset is built from.
wikidata_terms:
  Q3624078: sovereign state (the class used to select countries)
  P31: instance of
  P36: capital
  P1082: population
  P585: point in time (qualifier giving a figure's reference date)
  P576: dissolved, abolished or demolished date (used to exclude former states)

fields:
  country:
    type: string
    description: >
      English label of the sovereign state, as recorded in Wikidata. These are
      Wikidata's preferred labels, so a few are formal rather than colloquial
      (for example "People's Republic of China" and "Kingdom of the
      Netherlands").
  capital:
    type: string
    description: >
      English label of a capital city of that country. Countries with more than
      one capital appear once per capital, so `country` is not unique. Six
      countries currently have multiple rows: Bolivia, Eswatini, Palestine,
      South Africa, Sri Lanka and Yemen.
  population_country:
    type: integer
    unit: people
    description: >
      Most recent population of the country. Where Wikidata holds several
      population statements, the one with the latest "point in time" qualifier
      is kept; if no statement is dated, the largest value is used.
  population_capital:
    type: integer
    unit: people
    description: >
      Most recent population of the capital city, selected the same way as
      `population_country`. This is the population of the city entity itself,
      which is usually the municipality or city proper rather than the wider
      metropolitan area — so it can be far smaller than the figure people
      associate with the city (New Delhi and Washington, D.C. are good
      examples).
  year_country:
    type: string
    description: >
      Four-digit reference year of `population_country`, taken from the "point
      in time" qualifier. Empty when the underlying statement carries no date.
  year_capital:
    type: string
    description: >
      Four-digit reference year of `population_capital`. Empty when the
      underlying statement carries no date.

processing:
  - Selects entities that are an instance of "sovereign state" (Q3624078) and have a capital (P36).
  - Excludes any country or capital carrying a dissolved/abolished date (P576).
  - Excludes entities whose English label could not be resolved (bare Q-ids).
  - Keeps the latest dated population statement per entity; falls back to the largest undated value.
  - Drops pairs where either population is missing.
  - Drops pairs where the capital's population exceeds the country's, which indicates a bad figure on one side.

caveats:
  - >
    City populations are not measured on a consistent basis across countries.
    Some refer to the city proper, others to a wider administrative district, so
    capitals are not strictly comparable with one another.
  - >
    Reference years differ between rows and between the two population columns
    of the same row; always read `year_country` / `year_capital` alongside the
    figures.
  - >
    "Sovereign state" on Wikidata includes states with limited or disputed
    recognition (for example Kosovo, Palestine and Taiwan). This is a deliberate
    inclusion for the game, not a political statement.
  - >
    Wikidata is openly editable, so figures can change between runs and are not
    a substitute for an official statistical source. For research use, prefer
    the UN World Population Prospects (countries) and the UN World Urbanization
    Prospects (cities).