Map-ready, enriched country tibble — world

The package's headline function, generalised but backward-compatible. Returns a tibble that already stitches together map geometry, World Bank indicators and the countrycode crosswalk, keyed on the ISO spine – ready to pipe into world_map() or ggplot2.

Usage

world_data(
  year,
  indicator = c(gdp_per_capita = "NY.GDP.PCAP.KD"),
  geometry = c("polygon", "sf", "none"),
  scale = c("small", "medium", "large"),
  region = NULL,
  classify = c("income", "continent", "region"),
  projection = "equal_earth",
  recenter = NULL,
  latest = FALSE,
  cache = TRUE,
  language = "en",
  parallel = TRUE,
  overrides = country_overrides(),
  vintage = NULL
)

Arguments

year: A single year or a range (e.g. 2000:2020, yielding a panel keyed on iso3c + year). Minimum 1960.
indicator: A named character vector of WDI codes. Names drive column names, e.g. c(gdp = "NY.GDP.PCAP.KD", pop = "SP.POP.TOTL"). Defaults to c(gdp_per_capita = "NY.GDP.PCAP.KD").
geometry: "polygon" (default; reproduces the classic output), "sf" (Natural Earth, for geom_sf() and real projections) or "none".
scale: Natural Earth resolution for the sf backend. "large" needs the non-CRAN rnaturalearthhires package; see world_geometry(). The other backends warn if asked for a resolution they cannot serve.
region: Optional subset: a continent, group name, iso3c vector or bounding box. Applied whichever geometry is used, including "none". A bounding box clips the shapes rather than selecting whole countries, and only the sf backend can do that properly – see world_geometry(); with geometry = "none" there is nothing to clip, so a box is refused.
classify: Which classifications to add (any of "income", "continent", "region").
projection, recenter: Projection, and optional central meridian, for the sf backend (see world_map() for the projections available). The other backends warn if asked, rather than ignoring the request.
latest: For a single-year request: TRUE takes each indicator's most recent non-NA value per country, and "common" the most recent year in which every requested indicator is present, so arithmetic across them is consistent. Either way each indicator gains an <indicator>_year column saying which year its value comes from. FALSE (default) pins the requested year.
cache: Whether to use the memoised / on-disk WDI cache.
language: WDI language code (default "en").
parallel: Whether to fetch multiple indicators in parallel. Ignored when the cache is memory-only (an unwritable countryatlas.cache_dir), because a forked worker's memo dies with it and nothing would be cached.
overrides: Name -> iso3c overrides for geometry matching (default country_overrides()).
vintage: Which release of the World Development Indicators to read: NULL (default) for the current one, or an archived release such as "2024-07" from the World Bank's WDI Database Archives (see wdi_vintages()). An archived release never changes, so its cache entries never expire. A series the release does not hold warns and names the nearest releases that do.

Value

A tibble (polygon backend), sf object (sf backend) or country-level tibble (geometry = "none").

iso3c is the stable key; country is a label and its spelling depends on where the row came from. A successful fetch carries the World Bank's names ("Korea, Rep.", "Congo, Dem. Rep."), while the country spine used when the fetch returns nothing carries the countrycode names ("South Korea", "Congo - Kinshasa") – as do convert_country(), standardize_country() and the rest of the package. Match on iso3c, and relabel with convert_country(iso3c, to = "country") if you need one consistent set.

Details

world_data(2020) keeps its original behaviour (polygon backend, GDP per capita). Everything else is opt-in: any indicator(s), a span of years (a panel), an sf backend with real projections, and region subsetting.

Examples

# \donttest{
# geometry = "polygon", the default, is bundled: nothing to install.
world_data(2020)
#> # A tibble: 97,812 × 12
#>     long   lat group order subregion iso3c iso2c country continent region income
#>    <dbl> <dbl> <int> <int> <chr>     <chr> <chr> <chr>   <chr>     <chr>  <fct> 
#>  1  131.  42.3     1     1 NA        RUS   RU    Russia… Europe    Europ… High …
#>  2  131.  42.3     1     2 NA        RUS   RU    Russia… Europe    Europ… High …
#>  3  131.  42.4     1     3 NA        RUS   RU    Russia… Europe    Europ… High …
#>  4  131.  42.4     1     4 NA        RUS   RU    Russia… Europe    Europ… High …
#>  5  131.  42.5     1     5 NA        RUS   RU    Russia… Europe    Europ… High …
#>  6  131.  42.5     1     6 NA        RUS   RU    Russia… Europe    Europ… High …
#>  7  131.  42.6     1     7 NA        RUS   RU    Russia… Europe    Europ… High …
#>  8  131.  42.6     1     8 NA        RUS   RU    Russia… Europe    Europ… High …
#>  9  131.  42.7     1     9 NA        RUS   RU    Russia… Europe    Europ… High …
#> 10  130.  42.7     1    10 NA        RUS   RU    Russia… Europe    Europ… High …
#> # ℹ 97,802 more rows
#> # ℹ 1 more variable: gdp_per_capita <dbl>

# geometry = "none" returns the country table alone.
world_data(2020, indicator = c(life_exp = "SP.DYN.LE00.IN"),
           geometry = "none")
#> # A tibble: 216 × 7
#>    iso3c iso2c country             continent region              income life_exp
#>    <chr> <chr> <chr>               <chr>     <chr>               <fct>     <dbl>
#>  1 AFG   AF    Afghanistan         Asia      Middle East, North… Low i…     61.5
#>  2 ALB   AL    Albania             Europe    Europe & Central A… Upper…     77.8
#>  3 DZA   DZ    Algeria             Africa    Middle East, North… Upper…     73.3
#>  4 ASM   AS    American Samoa      Oceania   East Asia & Pacific High …     72.7
#>  5 AND   AD    Andorra             Europe    Europe & Central A… High …     79.4
#>  6 AGO   AO    Angola              Africa    Sub-Saharan Africa  Lower…     63.1
#>  7 ATG   AG    Antigua and Barbuda Americas  Latin America & Ca… High …     77.2
#>  8 ARG   AR    Argentina           Americas  Latin America & Ca… Upper…     75.9
#>  9 ARM   AM    Armenia             Asia      Europe & Central A… Upper…     73.4
#> 10 ABW   AW    Aruba               Americas  Latin America & Ca… High …     75.4
#> # ℹ 206 more rows
# }