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 (bundled Natural Earth polygons, 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().

Data sources beyond the World Bank

fetch_indicator(), add_indicator(), compare_sources(), country_sources(), register_country_source(), remove_country_source(), and the adapters fetch_owid(), fetch_eurostat(), fetch_oecd() and fetch_comtrade().

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, country_groups_history, world_snapshot, world_tiles, historical_codes, disputed_territories.

Time

country_timeline(), audit_time_coverage(), historical_geometry().

Analysis helpers

per_capita(), aggregate_regions(), rank_countries(), complete_years(), interpolate_missing(), growth_rate(), index_to(), share_of_world(), lag_by_country(), diff_by_country(), deflate(), to_ppp(), rate_check(), smooth_rates(), correlate_indicators(), beta_convergence(), sigma_convergence(), convergence_club(), gini(), theil().

Spatial statistics and networks

country_weights(), morans_i(), local_morans(), lisa_map(), gearys_c(), getis_ord(), spatial_lag(); flow_matrix(), country_network(), od_map().

Visualization

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

Honest maps

classify_compare(), coverage_map(), value_by_alpha_map(), projection_info(), projection_compare(), projection_distortion(), tissot_map(), cartogram_diagnostics(), map_provenance(), dispute_policy(), check_dispute_coverage().

Subnational

standardize_subnational(), nuts_geometry(), subnational_map().

Reporting

country_factsheet(), world_table().

Database rendering (ggsql)

as_ggsql_source(), world_query().

Performance & caching

clear_country_cache().

Options

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

countryatlas.cache_dir: Where the persistent cache lives, one directory per source. Defaults to tools::R_user_dir("countryatlas", "cache"); set it to "" for session-only caching. See clear_country_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. A single non-negative number; Inf for no expiry.
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. A single non-negative number; Inf for no cap.
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.timeout: How long one request to a provider may take, in seconds. Defaults to 60. Every built-in source goes through the same client, so a failing fetch is bounded: at most countryatlas.retries + 1 requests of this length each, plus the waits between them.
countryatlas.retries: How many times a request is retried after a failure worth retrying (HTTP 429, a 5xx, a dropped connection), with exponential backoff and jitter, honouring Retry-After. Defaults to 3; a whole number from 0 to 10.
countryatlas.strict: Set to TRUE to make a failed download an error (class countryatlas_fetch_failed) instead of a warning and an empty result, for a pipeline that must not continue with data missing. The default, FALSE, is what CRAN asks of a package that uses the network: fail gracefully.
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.
countryatlas.worldview: A Natural Earth point of view the sf backend draws, as the viewing country's ISO code ("IND") or "ISO"; unset by default. Set it with dispute_policy(worldview = ), which validates it; see world_geometry().

Author

Maintainer: Youzhi Yu yuyouzhi666@icloud.com