countryatlas: join World Bank data, country codes and maps on the ISO spine

countryatlas exists to kill one recurring source of pain: country names never line up across data sources. The package makes ISO codes the universal join key and hands you a ready-to-map tibble that stitches together map geometry (ggplot2::map_data() or Natural Earth sf), World Bank indicators (WDI::WDI()) and the countrycode::countrycode() crosswalk.

Details

The happy path stays one call: world_data(). Everything else is opt-in.

Core data assembly

world_data(), country_data(), world_geometry(), locate_country(), country_borders(), neighbors(), distance_between().

The join engine

standardize_country(), join_world(), attach_geometry(), country_join(), country_join_all(), dissolve_country().

Diagnostics

check_country_match(), repair_country_names(), country_overrides(), audit_coverage().

Reference data

convert_country(), country_codes(), country_groups(), in_group(), wdi_search(), and the datasets country_meta, common_indicators, country_groups_tbl, world_snapshot, world_tiles, historical_codes.

Analysis helpers

per_capita(), aggregate_regions(), rank_countries(), complete_years(), growth_rate(), index_to(), share_of_world(), lag_by_country(), diff_by_country(), correlate_indicators(), beta_convergence(), sigma_convergence(), gini(), theil(), morans_i().

Visualization

world_map(), globe_map(), spin_globe(), facet_map(), bubble_map(), spike_map(), bivariate_map(), cartogram_map(), dorling_map(), tile_map(), flow_map(), animate_world(), interactive_map(), geom_country_labels(), theme_world_map(), simplify_geometry().

Database rendering (ggsql)

as_ggsql_source(), world_query().

Performance & caching

clear_wdi_cache().

Options

Four options change the package's behaviour. All are unset by default.

countryatlas.cache_dir: Where the persistent World Bank cache lives. Defaults to tools::R_user_dir("countryatlas", "cache"); set it to "" for session-only caching. See clear_wdi_cache().
countryatlas.cache_max_age: How long a persistent cache entry stays usable, in seconds. Defaults to 30 days. World Bank figures are revised, so an old entry is not merely stale on disk – it is a different answer from the one the API would give now.
countryatlas.cache_max_size: The size cap on the persistent cache, in bytes. Defaults to 50 MB, past which the least-recently-used entries are dropped. CRAN policy allows a package cache under tools::R_user_dir() only if its contents are actively managed.
countryatlas.workers: How many processes fetch indicators in parallel (only when the cache is on disk – a memory-only memo cannot survive a fork). Defaults to one fewer than the available cores, and to 2 under R CMD check, per CRAN policy. Must be a single finite number; values below one are clamped to one.
countryatlas.gdp_compat: Set to TRUE to restore the gdp_per_capita_2015 column that world_data() emitted in 1.0.0. A deprecation shim, off by default, and now warning when used.
countryatlas.dispute_policy: Which map convention disputed territories are drawn under: "none" (default), "de_facto", "de_jure" or "neutral". Set it with dispute_policy() rather than directly, which also reports what the setting does and does not change.

Author

Maintainer: Youzhi Yu yuyouzhi666@icloud.com