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()
)

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().
region: Optional subset: a continent, group name, iso3c vector or bounding box. A bounding box clips the shapes rather than selecting whole countries, and only the sf backend can do that properly – see world_geometry().
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).
latest: If TRUE, use the most recent non-NA value per country for a single-year request.
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()).

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, comes from the suggested `maps`
# package, so guard the call: an example may not assume a Suggests is
# installed (R CMD check runs \donttest{} blocks, and CRAN has a
# check flavour with no suggested packages at all).
if (requireNamespace("maps", quietly = TRUE)) {
  world_data(2020)
}
#> # A tibble: 99,338 × 12
#>     long   lat group order subregion iso3c iso2c country continent region income
#>    <dbl> <dbl> <dbl> <int> <chr>     <chr> <chr> <chr>   <chr>     <chr>  <fct> 
#>  1 -69.9  12.5     1     1 NA        ABW   AW    Aruba   Americas  Latin… High …
#>  2 -69.9  12.4     1     2 NA        ABW   AW    Aruba   Americas  Latin… High …
#>  3 -69.9  12.4     1     3 NA        ABW   AW    Aruba   Americas  Latin… High …
#>  4 -70.0  12.5     1     4 NA        ABW   AW    Aruba   Americas  Latin… High …
#>  5 -70.1  12.5     1     5 NA        ABW   AW    Aruba   Americas  Latin… High …
#>  6 -70.1  12.6     1     6 NA        ABW   AW    Aruba   Americas  Latin… High …
#>  7 -70.0  12.6     1     7 NA        ABW   AW    Aruba   Americas  Latin… High …
#>  8 -70.0  12.6     1     8 NA        ABW   AW    Aruba   Americas  Latin… High …
#>  9 -69.9  12.5     1     9 NA        ABW   AW    Aruba   Americas  Latin… High …
#> 10 -69.9  12.5     1    10 NA        ABW   AW    Aruba   Americas  Latin… High …
#> # ℹ 99,328 more rows
#> # ℹ 1 more variable: gdp_per_capita <dbl>

# geometry = "none" needs nothing beyond the hard dependencies.
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
# }