Package 'countryatlas'

Description

fetch_indicator() plus country_join() in one step: pull an indicator from any registered source and attach it to a frame you already have, matched on the ISO spine (and on year too, when both sides are panels).

Usage

add_indicator(data, source, indicator, countries = NULL, years = NULL, ...)

Arguments

Value

data with the indicator column(s) added.

How much countries actually saves

countries bounds the result, not necessarily the download. Only some providers accept a country filter in the request:

So add_indicator(one_row, "owid", "life-expectancy") still transfers every country and year that dataset holds in order to keep a single value. When that matters, narrow with years (which the wdi and comtrade adapters do push down), or fetch once into a variable and reuse it rather than calling this per subset. The on-disk cache means a repeated wdi fetch is free; the other sources are memoised for the session only.

See Also

fetch_indicator(), country_join()

Examples

## Not run: 
world_snapshot$countries |>
  add_indicator("wdi", c(unemployment = "SL.UEM.TOTL.ZS"), years = 2020)

## End(Not run)

Description

Roll countries up to a group such as the EU or the OECD using the members of each row's own year, not today's list. An "EU" series built from the current 27 members misstates every year before 2020 and every year before an accession; this builds it from whoever was a member at the time, under the same coverage rule as aggregate_regions().

Usage

aggregate_groups(
  data,
  value,
  groups,
  as_of = NULL,
  fun = "sum",
  weight = NULL,
  min_coverage = 2/3
)

Arguments

Value

A tibble of group (and year for a panel), the aggregated value, n_countries (members on that date), n_reporting, coverage, and for a weighted mean coverage_weighted.

Who counts as a member

Coverage is measured against the group's full membership on that date, taken from country_groups_history, not against the members that happen to be in data: a member with no row is counted as missing. That is the difference from aggregate_regions(), which can only count what it is given. For fun = "weighted_mean" the weighted share is computed over the members present, since an absent member's weight is unknown. A group with no dated history (Commonwealth, G20, OPEC) warns and uses the current membership for every year.

See Also

aggregate_regions(), in_group(), country_groups_history

Examples

pan <- data.frame(iso3c = rep(c("GBR", "FRA", "DEU", "HRV"), each = 2),
                  year = rep(c(2012, 2021), 4), gdp = 1:8)
# The United Kingdom counts in 2012 and not in 2021; Croatia the reverse.
aggregate_groups(pan, gdp, "EU", min_coverage = 0)

Description

Aggregate a country-level value to a coarser grouping, optionally with population-weighted means.

Usage

aggregate_regions(
  data,
  value,
  by = "region",
  fun = "sum",
  weight = NULL,
  min_coverage = 2/3,
  coverage_weight = NULL
)

Arguments

Value

A tibble of by, the aggregated value, n_countries, n_reporting and coverage, plus coverage_weighted when a coverage weight applies.

Coverage

A sum over a region that is missing its largest member is not that region's total, and nothing about the number says so. So every row reports how much of the group stands behind it: n_countries (members present in data), n_reporting (members with a value), coverage (their share) and, with a coverage weight, coverage_weighted (the share of that weight the reporting members hold). A group whose coverage is below min_coverage is NA.

The default threshold is the World Bank's rule for the aggregates in the World Development Indicators: a sum is not computed when more than a third of the observations are missing, and a weighted mean is not computed when missing data account for more than a third of the weights. Coverage is tested on coverage_weighted when there is one, so fun = "weighted_mean" follows the second rule by default. Note that only members present in data are counted: a country with no row at all is invisible to this check, so complete the frame against the full membership first (for example with country_codes() or country_groups()) when that matters. Rows whose grouping value is missing are reported but never withheld: they are not a group with a membership to fall short of.

Groups with no data

Missing values are dropped before aggregating, so a group is summarised from whatever it does have. A group with no non-missing value returns NA rather than a figure: sum() would otherwise report 0, mean() NaN and min()/max() -Inf/Inf, each of which reads as a real total for a region we simply have no data for. Use audit_coverage() to see where those gaps are.

See Also

aggregate_groups() to aggregate by dated group membership.

Examples

df <- data.frame(iso3c = c("USA", "CAN", "BRA"),
                 region = c("North America", "North America", "Latin America"),
                 gdp = c(21, 1.7, 1.4))
aggregate_regions(df, gdp, fun = "sum")

# A region missing a third of its members is not aggregated by default.
ssa <- data.frame(iso3c = c("NGA", "ZAF", "KEN"), region = "Sub-Saharan Africa",
                  gdp = c(NA, 400, 100), pop = c(223, 60, 55))
aggregate_regions(ssa, gdp, coverage_weight = pop, min_coverage = 0)

Description

Given a panel from world_data(2000:2020, ...), animate the choropleth over year via the optional gganimate package, or fall back to a faceted small-multiple when it is not installed.

Usage

animate_world(
  data,
  fill,
  time = year,
  projection = "equal_earth",
  breaks_by = c("pooled", "panel"),
  ...
)

Arguments

Value

A gganim object (if gganimate is available) or a faceted ggplot.

Backend

Either backend, as world_map(): the frame decides, and both draw in projection (Equal Earth by default).

Examples

## Not run: 
world_data(2000:2005, c(gdp = "NY.GDP.PCAP.KD")) |>
  animate_world(gdp)

## End(Not run)

Description

Hand countryatlas's curated, ISO-reconciled, WDI-joined spatial table to ggsql so it can be charted with ⁠DRAW spatial⁠ – the bridge that lets ggsql draw maps of your override-corrected data instead of its static bundled world. sf geometry is WKB-encoded so ggsql can decode it.

Usage

as_ggsql_source(
  data,
  name = "countryatlas_world",
  format = c("duckdb", "parquet", "arrow"),
  con = NULL,
  path = NULL,
  geometry_col = "geometry"
)

Arguments

Value

Depending on format: a DuckDB connection (with the table written), a Parquet file path, or a nanoarrow array stream.

You own the connection that format = "duckdb" returns, and duckdb keeps its in-memory database alive until the handle is released, so close it when you are done:

src <- as_ggsql_source(d, format = "duckdb")
on.exit(DBI::dbDisconnect(src, shutdown = TRUE))

format = "parquet" needs no such care: it closes the connection it opened before returning the path. Passing your own con leaves it open in every case, since it was never ours to close.

Examples

## Not run: 
# Curate in R, render in the database:
src <- world_data(2020, geometry = "sf") |> as_ggsql_source(format = "duckdb")
ggsql::ggsql_execute(src, world_query(gdp_per_capita))

## End(Not run)

Description

The bridge between a one-row-per-country table (e.g. from country_data()) and plotting: bolts polygon or sf geometry onto your data, keyed on iso3c.

Usage

attach_geometry(
  data,
  by = "iso3c",
  geometry = c("polygon", "sf"),
  scale = "small",
  region = NULL,
  projection = "equal_earth",
  recenter = NULL,
  overrides = country_overrides(),
  year = NULL,
  worldview = NULL
)

Arguments

Value

For "polygon", a tibble with long/lat/group plus your columns, one row per polygon vertex. For "sf", an sf object, one row per feature. Both carry every country the backend has – see How many rows come back.

One row in, one row out

Geometry is attached once per row, not once per country. That is what a panel wants – one row per country-year, each carrying the shape – but it means a frame that repeats a country by accident draws that country more than once, and only the last one painted is visible. The package cannot tell the two apart (a panel's time column may be called anything), so reduce to one row per country yourself when that is what you meant.

Which countries have geometry

The join keeps only countries the chosen backend actually carries, so rows of data with no matching geometry are dropped silently – worth checking first when a country you expected is missing from the map. Coverage differs by backend and, for "sf", by scale, which changes which countries are present and not merely how detailed they look. Of the 216 countries in world_snapshot, "polygon" and "sf" with scale = "medium" carry the same 215, because both are Natural Earth 1:50m, while "sf" with scale = "small" (the default, 110m) carries 170: the 110m coastlines omit most small states, so use the polygon backend or scale = "medium" when microstates matter. Gibraltar alone is in none of them.

How many rows come back

The result is the backend's whole map, not just your rows: every country the backend carries is present, and the ones absent from data carry NA in your columns. That is what makes them draw in na.value rather than vanish, which is the point – a choropleth that quietly omits the countries you have no data for reads as though they did not exist. It does mean the result is much larger than data and is not something to summarise directly: attach_geometry() on three countries returns 237 of them on the polygon backend and 175 on "sf", whatever data held. The row count is larger still: "polygon" gives one row per polygon vertex (about 98,000), and "sf" one row per feature – usually one per country, but a divided country appears more than once (Cyprus at scale = "small"; Cyprus and India at "medium"), so an iso3c join against it can fan out. Summarise data before attaching geometry, or use the verbs in this package, which de-duplicate to one row per country first.

Examples

df <- data.frame(iso3c = c("USA", "CAN"), value = c(1, 2))
attach_geometry(df, geometry = "polygon")

Description

What is missing, before you trust the map: which countries are unmatched, the NA rate per indicator, and which World Bank regions / income groups are under-covered – so a half-empty map is caught before it is published.

Usage

audit_coverage(data, indicator = NULL, by = c("region", "income", "continent"))

Arguments

Value

A list of class countryatlas_coverage, with elements unmatched, na_rates and by_group. It has a print() method, so at the console you see a formatted report rather than the raw list; reach into the elements by name to use the numbers programmatically.

• unmatched – one row per input value that did not resolve to an ISO code. Empty is the good case.

• na_rates – one row per indicator: n is the number of countries considered, n_missing how many of them lack a value, and na_rate is n_missing / n. An infinite value counts as lacking one: no map can draw it, and coverage_map() shows it as missing too.

• by_group – one row per group: n_countries is how many countries are in that group, and na_rate is the share of those lacking a value. The counts sum to n.

Both n and by_group's n_countries are denominators – everything counted, not everything present. That is the opposite orientation from map_provenance(), whose n_countries is the numerator (countries drawn with a value) and whose n_total is the denominator. The two verbs report the same coverage from opposite ends, so on 216 countries with 17 missing this gives n = 216 where map_provenance() gives n_countries = 199.

Examples

audit_coverage(countryatlas::world_snapshot$countries)

Description

The time-aware counterpart to audit_coverage(). A join can succeed and still be wrong about history: South Sudan with 1995 data, Czechoslovakia with 2001 data, the USSR with 2010 data. Those rows survive every check the package had, because the country resolves and the year is a number.

Usage

audit_time_coverage(data, quiet = FALSE)

Arguments

Value

A tibble of the offending rows: iso3c, country, year, issue, existed (a human-readable span) and basis (where the dates come from). issue is "before_existence" or "after_dissolution" – the country did not exist – or the milder "before_independence": it existed, but was not yet (or not then) an independent state. Zero rows means the panel is clean.

What it can and cannot see

Dissolution dates come from historical_codes, which covers the entities the package curates (USSR, Yugoslavia, Czechoslovakia and the rest), and a successor state is treated as not existing before its predecessor dissolved (basis = "historical_codes").

Independence comes from Gleditsch & Ward's list of independent states since 1816 (Gleditsch & Ward 1999, through the states package), with every spell of independence: Namibia from 1990, Eritrea from 1993, Timor-Leste from 2002, and Estonia from 1918 to 1940 and again from 1991. A year inside an earlier spell also corrects the crosswalk for a state it dates from a later succession (Estonia's interwar years). A year outside every spell is "before_independence" (basis = "gleditsch_ward"). That is statehood, not data availability – a colony often reports statistics before independence, and a World Bank series may legitimately start there – so it is a separate, lower-severity issue, for the caller to judge. Territories that are not on the list are assumed to have existed throughout, so a clean result still means "nothing these lists know about is wrong", not "every date is right".

References

Gleditsch, K. S. & Ward, M. D. (1999). A revised list of independent states since the congress of Vienna. International Interactions 25(4), 393-413. doi:10.1080/03050629908434958

See Also

audit_coverage(), dissolve_country(), country_timeline()

Examples

panel <- data.frame(
  iso3c = c("SSD", "CZE", "FRA"),
  year  = c(1995L, 2001L, 2001L),
  gdp   = c(1, 2, 3)
)
audit_time_coverage(panel)

Description

Do poor countries grow faster than rich ones? The classic unconditional beta-convergence test: each country's average log growth rate is regressed on its log initial level. A significantly negative beta is convergence; the implied convergence speed and half_life (years to close half the gap) are derived from it.

Usage

beta_convergence(data, value)

Arguments

Value

A one-row tibble: beta, se, t_value, p_value, r_squared, n (countries), speed (annual convergence rate) and half_life (years).

speed and half_life are NA in two cases: when beta >= 0, because there is no convergence to put a rate on; and when the panel's per-country spans are too heterogeneous for any single span to reconcile with the fitted slope, which is warned about. beta and its inference are unaffected in both – only the annualised figures need one common span, so restrict the panel to a shared window if you need them. The fitted stats::lm() object is attached as the "model" attribute.

See Also

sigma_convergence() for the dispersion-over-time counterpart.

Examples

set.seed(1)
start <- runif(20, 6, 11)                              # log initial level
growth <- 0.05 - 0.004 * start + rnorm(20, 0, 0.002)   # poorer grow faster
panel <- data.frame(
  iso3c = rep(sprintf("C%02d", 1:20), each = 2),
  year  = rep(c(2000L, 2020L), 20),
  gdp   = as.vector(rbind(exp(start), exp(start + growth * 20)))
)
beta_convergence(panel, gdp)

Description

The local Moran statistic for two variables (Anselin, Syabri & Smirnov 2002): each country's standardised x against the average standardised y of its neighbours, so "rich countries surrounded by long-lived neighbours" is a cluster, and a rich country among short-lived neighbours an outlier.

Usage

bivariate_lisa(
  data,
  x,
  y,
  weights = NULL,
  n_perm = 9999,
  alpha = 0.05,
  p_adjust = c("fdr", "bonferroni", "holm", "none")
)

Arguments

Value

A tibble with one row per country used: iso3c, x, lag_y (the neighbours' average y), ii, p_value, p_adjusted and cluster ("High-High", "Low-Low", "High-Low", "Low-High" or "Not significant"), where the first word is the country's x and the second its neighbours' y. A country needs both values to take part.

References

Anselin, L., Syabri, I. & Smirnov, O. (2002). Visualizing multivariate spatial correlation with dynamically linked windows. Proceedings, CSISS Workshop on New Tools for Spatial Data Analysis.

See Also

local_morans(), lisa_map()

Examples

snap <- countryatlas::world_snapshot$countries
bivariate_lisa(snap, gdp_per_capita, life_expectancy, n_perm = 499)

Description

A 2-D bivariate choropleth with a built-in 2-D legend (via the optional biscale package), e.g. GDP per capita x life expectancy in one map.

Usage

bivariate_map(
  data,
  fill_x,
  fill_y,
  palette = "GrPink",
  dim = 3,
  projection = "equal_earth",
  footnote = "auto"
)

Arguments

Value

A ggplot object (the map; combine with biscale::bi_legend() for a standalone legend).

Backend

The sf backend only, since biscale classes an sf frame; drawn in projection (Equal Earth by default).

Examples

if (requireNamespace("sf", quietly = TRUE) &&
    requireNamespace("rnaturalearth", quietly = TRUE) &&
    requireNamespace("biscale", quietly = TRUE)) {
  attach_geometry(countryatlas::world_snapshot$countries, geometry = "sf") |>
    bivariate_map(gdp_per_capita, life_expectancy)
}

Description

Plots sized circles at country centroids – the right idiom for totals (population, total emissions, total GDP), which a choropleth misrepresents because big values hide in small countries and vice versa.

Usage

bubble_map(
  data,
  size,
  color = NULL,
  projection = "equal_earth",
  backend = c("polygon", "sf"),
  max_size = 18,
  alpha = 0.7,
  footnote = "auto"
)

Arguments

Value

A ggplot object.

Examples

snap <- countryatlas::world_snapshot$countries
bubble_map(snap, population)

Description

Cartograms fail quietly. An under-converged one looks entirely plausible while still misrepresenting the areas it exists to make honest. This reports the residual error per country, so the failure is visible.

Usage

cartogram_diagnostics(x, weight = NULL)

Arguments

Value

A tibble of iso3c, target_share (the country's share of the weight), actual_share (its share of the cartogram's area) and area_error (the relative difference). The summary – mean absolute error, worst country – is attached as the "countryatlas_cartogram" attribute.

What counts as converged

A perfect cartogram has area_error of 0 everywhere. In practice a mean absolute error under a few percent is good and under 10% is usually acceptable; a systematically large error, or one concentrated in the small countries, means the algorithm stopped early. Raise itermax and try again.

See Also

cartogram_map(), dorling_map(), gridded_cartogram()

Examples

if (requireNamespace("sf", quietly = TRUE) &&
    requireNamespace("cartogram", quietly = TRUE) &&
    requireNamespace("rnaturalearth", quietly = TRUE)) {
  sfd <- attach_geometry(countryatlas::world_snapshot$countries,
                         geometry = "sf")
  cg <- cartogram_map(sfd, population)
  cartogram_diagnostics(cg)
}

Description

Resizes countries by weight (population, GDP, ...) via the optional cartogram package, defeating the "big empty countries dominate the eye" bias of world choropleths.

Usage

cartogram_map(
  data,
  weight,
  type = c("contiguous", "dorling", "noncontiguous", "flow"),
  fill = NULL,
  projection = "equal_earth",
  footnote = "auto",
  ...
)

Arguments

Value

A ggplot object.

Which algorithm

"contiguous" (Dougenik) and "dorling"/"noncontiguous" come from cartogram. "flow" comes from cartogramR and implements the Gastner-Seguy-More flow-based method, which is both the current state of the art and far faster than diffusion-based approaches – prefer it for contiguous cartograms when cartogramR is available.

Cartograms fail quietly: an under-converged one looks plausible while still misrepresenting the areas it exists to make honest. Pass a larger itermax if the result still looks close to the true map.

Backend

The sf backend only: the cartogram package distorts sf geometry, in projection (Equal Earth by default).

References

Gastner, M. T., Seguy, V. & More, P. (2018). Fast flow-based algorithm for creating density-equalizing map projections. Proceedings of the National Academy of Sciences 115(10), E2156-E2164. doi:10.1073/pnas.1712674115

Examples

if (requireNamespace("sf", quietly = TRUE) &&
    requireNamespace("rnaturalearth", quietly = TRUE) &&
    requireNamespace("cartogram", quietly = TRUE)) {
  attach_geometry(countryatlas::world_snapshot$countries, geometry = "sf") |>
    cartogram_map(population, type = "dorling")
}

Description

A report on what will and will not match before you trust the map: the input, its iso3c, whether it matched, whether it is a historical (dissolved) entity, and a suggestion (the closest known country name by string distance) for misses. Surfaced automatically by join_world().

Usage

check_country_match(
  x,
  origin = "country.name",
  custom_match = country_overrides(),
  suggest = TRUE
)

Arguments

Details

The historical flag matters even for rows that matched: countrycode silently resolves "USSR" to Russia's RUS, so Soviet-era data becomes Russian data without a warning. Rows flagged historical should usually be routed through dissolve_country() instead.

Value

A tibble with columns input, iso3c, matched, historical, method and suggestion. method says how a name was matched, tier by tier, each tried only for what is still unmatched: "override" (the country_overrides() table), "regex_en" (countrycode's English patterns), "name_de", "name_es", "name_fr" and "name_it" (an exact match, ignoring case, accents and punctuation, against countrycode's German, Spanish, French and Italian names), "cldr" (the same against every name, short name and variant in the Unicode CLDR tables countrycode carries, in every language), "ambiguous" (a CLDR name for more than one country, which is left unmatched) or "none". Exact rather than countrycode's language patterns, which are unanchored and matched Somaliland to Somalia. For an origin other than a name it is "code".

See Also

dissolve_country() for resolving the entities this flags as historical to their successor states, and repair_country_names() for applying the suggestion column automatically.

Examples

check_country_match(c("USA", "Cote d'Ivoire", "Yugoslavia", "Wakanda"))
# "USSR" matches (to RUS!) but is flagged historical:
check_country_match("USSR")

Description

Cross-references your data against disputed_territories so a contested area does not pass unremarked. Reports both directions: the disputed territories your data covers, and those it is silent about.

Usage

check_dispute_coverage(data, quiet = FALSE)

Arguments

Value

A tibble of every disputed territory the package knows about, with in_data saying whether your data covers it. The scope caveat in disputed_territories applies: this is a documented subset, not every dispute in the world.

See Also

disputed_territories, dispute_policy(), audit_coverage()

Examples

check_dispute_coverage(countryatlas::world_snapshot$countries)

Description

Simulate how the map's fill colours look with deuteranopia, protanopia and tritanopia – the Machado, Oliveira & Fernandes (2009) model, through the optional colorspace – and report the smallest colour difference between adjacent classes under each. Two classes a reader cannot tell apart are two classes the map does not have. Roughly one man in twelve has a red-green deficiency.

Usage

check_palette(p, threshold = 10)

Arguments

Details

The difference is CIE 1976 $\Delta E^*_{ab}$, the distance between the two colours in CIELAB. A difference under about 10 is hard to tell apart at the size of a small country on a map; the package's own defaults (the viridis family) clear it under all three simulations.

Value

A tibble with one row per vision type (normal, deuteranopia, protanopia, tritanopia): min_delta_e, and between, the two classes that come closest.

References

Machado, G. M., Oliveira, M. M. & Fernandes, L. A. F. (2009). A physiologically-based model for simulation of color vision deficiency. IEEE Transactions on Visualization and Computer Graphics 15(6), 1291-1298. doi:10.1109/TVCG.2009.113

Crameri, F., Shephard, G. E. & Heron, P. J. (2020). The misuse of colour in science communication. Nature Communications 11, 5444. doi:10.1038/s41467-020-19160-7

Examples

if (requireNamespace("colorspace", quietly = TRUE)) {
  snap <- countryatlas::world_snapshot$countries
  check_palette(world_map(attach_geometry(snap), gdp_per_capita))
  # A rainbow fails all three simulations:
  check_palette(grDevices::rainbow(7))
}

Description

Small multiples of one choropleth, drawn once per classification method, plus the break table and the count of countries in each class. The point is that the choice is consequential and usually unexamined: Brewer & Pickle (2002) found quantiles among the best methods for general choropleth reading and natural breaks (Jenks) below 70% as accurate, which is the reverse of the common GIS default.

Usage

classify_compare(
  data,
  value,
  methods = c("quantile", "jenks", "fisher", "headtails", "equal", "pretty"),
  n_bins = 5,
  ncol = NULL,
  ...,
  n = deprecated()
)

Arguments

Value

A faceted ggplot object, with the per-method break and class-count table attached as the "countryatlas_classification" attribute (and readable with map_provenance()). Each method's rows also carry three measures of fit: gvf, the goodness of variance fit, and tai, the tabular accuracy index (both Jenks & Caspall 1971; 1 is a perfect fit), and max_class_share, the share of countries in the fullest class.

No number picks a classification

GVF and TAI measure how homogeneous the classes are, which is what natural breaks optimise; they rate a map that puts most countries in one class highly, and they say nothing about how well readers read the map. They are reported to inform the choice, never to rank the methods: Brewer & Pickle's finding that quantiles read best stands beside them, and max_class_share flags the map whose fullest class swallows the rest.

References

Brewer, C. A. & Pickle, L. (2002). Evaluation of methods for classifying epidemiological data on choropleth maps in series. Annals of the Association of American Geographers 92(4), 662-681. doi:10.1111/1467-8306.00310

Jenks, G. F. & Caspall, F. C. (1971). Error on choroplethic maps: definition, measurement, reduction. Annals of the Association of American Geographers 61(2), 217-244. doi:10.1111/j.1467-8306.1971.tb00779.x

Jiang, B. (2013). Head/tail breaks: a new classification scheme for data with a heavy-tailed distribution. The Professional Geographer 65(3), 482-494. doi:10.1080/00330124.2012.700499

See Also

world_map(), map_provenance()

Examples

snap <- countryatlas::world_snapshot$countries
cmp <- attach_geometry(snap, geometry = "polygon") |>
  classify_compare(gdp_per_capita)
attr(cmp, "countryatlas_classification")

Description

Add the World Bank's income group, region or lending category to a frame, as in force on a date – each row's own year, by default – from the bundled country_classifications. A panel spanning 2000 to 2026 gets the income group each country had in each year, not today's list painted across every year, and the July 2025 move of Afghanistan and Pakistan from South Asia into the Middle East and North Africa region falls where it happened.

Usage

classify_countries(
  data,
  schemes = c("income", "region"),
  as_of = NULL,
  basis = c("in_effect", "data_year")
)

Arguments

Value

data with the requested columns – income a factor in income order, region and lending character – NA where the table has no classification for that country on that date (a country not yet a member, or a date before the table begins). Each added column carries a source_info() record naming the World Bank source and the fiscal years used.

The fiscal-year rule

The World Bank classifies each economy once a year, on 1 July, and the class holds for its fiscal year: fiscal year t runs from 1 July t-1 to 30 June t, and its classification is set from GNI per capita (Atlas method) for calendar year t-2.

So for a row dated 2020, basis = "in_effect" reads 1 January 2020, which falls in fiscal year 2020 (1 July 2019 to 30 June 2020), whose classes were computed from 2018 incomes. basis = "data_year" reads the class computed from 2020 incomes instead, which is fiscal year 2022's (in force from 1 July 2021). The first answers "how was this country treated at the time"; the second "where did this year's income put it". Regions and lending categories have no data year and are always read as in force on the date.

See Also

country_classifications, in_group(), world_data()

Examples

pan <- data.frame(iso3c = c("VNM", "VNM", "PAK", "PAK"),
                  year = c(2026, 2027, 2025, 2026))
classify_countries(pan, c("income", "region"))

# The class computed from a year's income, two fiscal years on:
classify_countries(data.frame(iso3c = "VNM", year = 2024), "income",
                   basis = "data_year")

Description

Empties the memoised in-session cache and, optionally, the on-disk one.

Usage

clear_country_cache(source = NULL, disk = FALSE)

Arguments

Value

Invisibly TRUE.

What a global clear releases

Called with no source, this also drops the two cached geometry backends: the Natural Earth sf layer held per scale (tens of megabytes at scale = "medium") and the polygon backend's memoised vertex table (about 98,000 rows per override set). Those are the largest things the package keeps in memory, and in a long-lived process – a Shiny app or a plumber API – this is the only way to release them. They rebuild on the next map.

Naming a source leaves geometry alone, since it is not a data source.

Where the cache lives

The persistent cache goes in the standard per-user cache location, tools::R_user_dir("countryatlas", "cache"). Point it elsewhere with options(countryatlas.cache_dir = ), or skip it by passing cache = FALSE to world_data() or country_data(). Under ⁠R CMD check⁠ the whole cache moves to the session temp directory, so a check never writes to the user's file space.

Entries expire: a fetch from a current release is dropped once it is 30 days old, because providers revise their figures, and past 50 MB per source the least-recently-used entries go first. Adjust either with options(countryatlas.cache_max_age = ) (seconds) and options(countryatlas.cache_max_size = ) (bytes). A pinned World Bank release (wdi_vintages()) never changes, so its entries never expire.

See Also

country_sources(), fetch_indicator()

Examples

clear_country_cache()

Description

A friendly-name to WDI-code lookup so indicator = common_indicators$population beats memorising "SP.POP.TOTL".

Usage

common_indicators

Format

A tibble with columns name (friendly name), code (WDI indicator code) and description.

Source

World Bank indicator catalogue.

Description

Fetch the same indicator from several providers and put the answers side by side. Sources disagree more often than people expect – different vintages, PPP bases, territorial definitions, revision schedules – and on the ISO spine the comparison is one join. This is the verb that turns "I used OWID" into "I used OWID, and here is where it differs from the World Bank".

Usage

compare_sources(
  indicator,
  sources = c("wdi", "owid"),
  year,
  countries = NULL,
  tolerance = 0.05,
  allow_unit_mismatch = FALSE
)

Arguments

Value

A tibble with one row per country: the value from each source, n_sources (how many reported it), rel_diff (max relative spread) and disagrees. The correlation, coverage and disagreement summary is attached as the "countryatlas_source_summary" attribute, with each source's stated unit.

Different units are not a disagreement

GDP per capita in constant 2015 US dollars and in current international dollars differ for every country, and calling that a disagreement between the sources would be wrong. Each fetch records the unit its provider states (see source_info()); when two of them state different units the comparison is refused with class countryatlas_unit_mismatch, naming them. Pass allow_unit_mismatch = TRUE to compare anyway – a ratio that is constant across countries can still be worth seeing – and read rel_diff accordingly. A source that states no unit is not checked.

See Also

fetch_indicator(), country_sources()

Examples

## Not run: 
cmp <- compare_sources(c(wdi = "NY.GDP.PCAP.KD", owid = "gdp_per_capita"),
                       sources = c("wdi", "owid"), year = 2020)
attr(cmp, "countryatlas_source_summary")

## End(Not run)

Description

The same indicator, the same year, from several releases of the World Development Indicators side by side. Revisions between releases of one database are large enough to change cross-country results (Johnson, Larson, Papageorgiou & Subramanian 2013 show this for growth rates), and they are easy to miss because a figure looks the same whichever release it came from. This makes the check one call.

Usage

compare_vintages(indicator, vintages, year = NULL, countries = NULL)

Arguments

Value

A tibble, one row per country and release: iso3c, country, vintage, value, and the revision and rel_revision from the first release listed. A summary per release – the number of countries in both, the median absolute and absolute relative revision, and the shares of countries revised by more than 1% and 10% – is attached as the "countryatlas_revisions" attribute.

Units change between releases too

A series can be rebased between releases – GDP in constant 2010 US$ in one, constant 2015 US$ in the next – and then every country is "revised" by the change of base. The series label of each release is compared, and a change of unit warns (class countryatlas_unit_mismatch).

References

Johnson, S., Larson, W., Papageorgiou, C. & Subramanian, A. (2013). Is newer better? Penn World Table revisions and their impact on growth estimates. Journal of Monetary Economics 60(2), 255-274. doi:10.1016/j.jmoneco.2012.10.022

See Also

wdi_vintages(), compare_sources()

Examples

compare_vintages("SP.POP.TOTL", c("2019-07", "current"), year = 2015)

Description

Completes a panel so every country has every year, optionally filling missing values by carry-forward ("locf") or linear interpolation ("linear") so animations do not flicker on missing years.

Usage

complete_years(
  data,
  years = NULL,
  value = NULL,
  method = c("none", "locf", "linear")
)

Arguments

Value

A completed (and optionally filled) panel tibble – or an sf frame, if data was one; each invented row carries its country's geometry.

Examples

df <- data.frame(iso3c = "USA", year = c(2000L, 2002L), gdp = c(1, 3))
complete_years(df, 2000:2002, method = "linear")

Description

Countries do not all converge to one steady state; they converge in groups. This implements the Phillips-Sul (2007) log-t procedure: a regression test for whether a set of countries is converging, applied iteratively to peel off clubs that converge internally even when the whole sample does not.

Usage

convergence_club(data, value, min_size = 2, alpha = 0.05)

Arguments

Value

A tibble: iso3c, club (an integer, 1 = highest-level club, NA = not classified), and the club's log_t statistic. The per-club test results are attached as the "countryatlas_clubs" attribute. Every country in data appears: one without a complete series (a missing or non-finite value in any year) cannot be tested, so it comes back with club = NA and a warning naming it.

The test

For each country form the relative transition path $h_{it} = y_{it} / \bar{y}_t$, then regress $\log(H_1/H_t) - 2\log(\log t)$ on $\log t$ over the last part of the sample, where $H_t$ is the cross-sectional mean of $(h_{it}-1)^2$. The one-sided t statistic on $\log t$ is the log-t statistic: above $-1.65$ the group is converging. Clubs are then formed by sorting countries on their final-period value and growing a core group while the test still passes.

A panel needs a reasonable number of periods for this to mean anything – below roughly fifteen the test has very little power, and the function warns.

References

Phillips, P. C. B. & Sul, D. (2007). Transition modeling and econometric convergence tests. Econometrica 75(6), 1771-1855. doi:10.1111/j.1468-0262.2007.00811.x

See Also

beta_convergence(), sigma_convergence()

Examples

set.seed(1)
# two groups converging to different levels
panel <- expand.grid(iso3c = c(paste0("A", 1:5), paste0("B", 1:5)),
                     year = 2000:2024)
panel$y <- ifelse(startsWith(as.character(panel$iso3c), "A"), 100, 30) +
  rnorm(nrow(panel), 0, 2)
convergence_club(panel, y)

Description

A discoverable wrapper around countrycode::countrycode() exposing the full set of schemes with first-class shortcuts for the high-value ones: flag emoji, currency, top-level domain, continent/region and research codes (Correlates of War, Polity, Gleditsch-Ward, V-Dem, IMF, FAO, FIPS, GAUL).

Usage

convert_country(
  x,
  to = "iso3c",
  origin = "country.name",
  custom_match = country_overrides(),
  warn = TRUE,
  from = deprecated()
)

Arguments

Value

A vector of converted codes.

Examples

convert_country(c("Japan", "Brazil"), to = "flag")
convert_country("Germany", to = "currency")
convert_country(c("USA", "France"), to = "continent")
convert_country(c("Germany", "United States"), to = "name_fr")

Description

Which indicators move together across countries? Computes pairwise correlations between indicator columns (pairwise-complete, so patchy coverage doesn't shrink every pair to the common subset), with the per-pair n reported so a headline r computed on 12 countries can't masquerade as a world fact.

Usage

correlate_indicators(
  data,
  ...,
  method = c("pearson", "spearman"),
  min_n = 3,
  by_year = FALSE,
  weight = NULL
)

Arguments

Value

A tibble with one row per indicator pair: var_x, var_y, r, n (complete pairs), sorted by ⁠|r|⁠ descending; with by_year = TRUE, the same per year, led by year.

Examples

correlate_indicators(countryatlas::world_snapshot$countries)
# weighted by population: the correlation for the average person
correlate_indicators(countryatlas::world_snapshot$countries,
                     gdp_per_capita, life_expectancy, weight = population)

Description

Which countries share a land border with which, as a tidy edge list – built from polygon topology (sf::st_touches()), so it reflects the same curated geometry as the rest of the package. Powers neighbors().

Usage

country_borders(scale = "small", region = NULL)

Arguments

Value

A tibble, one row per bordering pair: iso3c_a, country_a, iso3c_b, country_b. Each unordered pair appears once, with iso3c_a <= iso3c_b alphabetically.

Turning it into a graph

igraph::graph_from_data_frame() takes the first two columns as the edge endpoints, so pass only the two code columns – handing it the whole tibble would build edges from each country's code to its own name:

igraph::graph_from_data_frame(
  country_borders()[, c("iso3c_a", "iso3c_b")], directed = FALSE)

Attaching igraph also masks neighbors(), which it exports too, so call that one as countryatlas::neighbors() from then on.

Which countries the default leaves out

Adjacency is computed from Natural Earth polygons, and the default scale = "small" (110m) has no polygon at all for the European microstates. Andorra, Liechtenstein, Monaco, San Marino and the Vatican are therefore absent from the table entirely – not merely missing a short border, but contributing no rows, despite a land border being the whole of their geography. The default reports 310 pairs over 153 countries; France comes back with 8 neighbours rather than 10.

scale = "medium" (50m) has all five, giving 322 pairs over 162 countries and France its full list. Use it whenever the microstates matter:

country_borders(scale = "medium")

The same 110m gap is why morans_i()'s contiguity weights exclude them – see its n_excluded – and it is the land-border twin of the island problem described in vignette("honest-maps"). Note the two Guiana borders are real, not artefacts: French Guiana makes Brazil and Suriname neighbours of France.

Examples

if (requireNamespace("sf", quietly = TRUE) &&
    requireNamespace("rnaturalearth", quietly = TRUE)) {
  head(country_borders(region = "Europe"))
  # The whole world is only a little dearer: a fraction of a second.
  nrow(country_borders())
}

Description

The World Bank's income groups, regions and lending categories, each row dated, so a country can be classified as it was on any day the table covers. classify_countries() reads it; world_data() and country_data() take their income and region from it, as of the current fiscal year.

Usage

country_classifications

Format

A tibble with one row per classification spell: iso3c, scheme ("wb_income", "wb_region" or "wb_lending"), value, from and to (the spell runs from from up to but not including to; NA means open-ended, or, for from, in force since before the table's records begin), source and note.

wb_income

One row per economy per World Bank fiscal year from FY1989 to FY2027, from the historical classification by income (OGHIST). Fiscal year t runs from 1 July t-1 to 30 June t and is set from GNI per capita for calendar year t-2; see classify_countries(). An economy the World Bank did not classify in a year has no row for it.

wb_region

The current regions, with the July 2025 change dated: Afghanistan and Pakistan are in South Asia until 1 July 2025 and in "Middle East, North Africa, Afghanistan & Pakistan" from then on, and the other members of that region carry its former name, "Middle East & North Africa", until the same date. No earlier region change is recorded.

wb_lending

The FY2027 lending categories (IDA, IBRD, Blend). Earlier years are not recorded.

The World Bank's codes for two former entities are recoded to ISO 3166-3's (its YUG, Serbia and Montenegro, is SCG; its YUGf, Yugoslavia, is YUG), and the Channel Islands, which have no ISO code, are left out. The fiscal year the table reaches is its "vintage" attribute.

Source

World Bank, "World Bank Country and Lending Groups" (CLASS) and the historical classification by income (OGHIST), both licensed CC BY 4.0; the July 2025 region change from the World Bank DataBank Metadata Glossary. Built by data-raw/country_classifications.R, which checks one class per economy per fiscal year, agreement with OGHIST's thresholds sheet, and the current classes against the World Bank API.

Description

The whole countrycode::codelist reshaped into a tidy, pipeable lookup you can filter() / join() directly – one row per country.

Usage

country_codes(codes = NULL)

Arguments

Value

A tibble, one row per country.

Examples

country_codes()
country_codes(c("iso2c", "continent", "currency"))

Description

The analysis counterpart to world_data(): no polygons, one tidy row per country (iso3c, iso2c, country, classifications and the requested indicators). This is what you actually join() / mutate() / summarise() / rank() on; attach geometry only at draw time with attach_geometry().

Usage

country_data(
  year,
  indicator = NULL,
  latest = FALSE,
  panel = FALSE,
  classify = c("income", "continent", "region"),
  cache = TRUE,
  language = "en",
  parallel = TRUE,
  vintage = NULL
)

Arguments

Value

A tibble, one row per country (or per country-year for a panel).

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.

The most recent value, and which year it is from

With latest = TRUE each indicator takes its own most recent value, so one row can hold GDP from 2023 beside population from 2021. That is often what is wanted – the freshest number for each – but dividing one by the other mixes years, so every indicator carries an ⁠<indicator>_year⁠ column, and per_capita(), deflate() and to_ppp() warn (class countryatlas_mixed_years) when the two columns they combine come from different years. latest = "common" instead takes, per country, the most recent year in which every requested indicator is present, so the row is internally consistent; a country with no such year gets NA throughout.

Examples

country_data(2020, c(co2 = "EN.GHG.CO2.MT.CE.AR5"))

Description

A single-country summary drawn from the bundled reference data and, if you ask, live indicators: codes, geography, groups, neighbours and any dissolution history.

Usage

country_factsheet(x, indicators = NULL, origin = "country.name")

Arguments

Value

A countryatlas_factsheet object – a list of tibbles (identity, geography, groups, neighbours, indicators) that prints as a formatted block.

See Also

country_meta, country_groups(), neighbors(), world_table()

Examples

country_factsheet("Brazil")

Description

Answers the constant question "is this country in the EU / OECD / G7 / G20 / BRICS / ...?" from a curated membership table. By default that is the current snapshot (country_groups_tbl); pass as_of to ask the question of a particular date, which is what a panel needs.

Usage

country_groups(group = NULL, as_of = NULL)

Arguments

Value

A tibble of group, iso3c, country; with as_of, also from and to.

Membership changes, and which groups are dated

A snapshot silently misstates any panel that spans an accession. An EU panel over 2015-2020 either includes the United Kingdom throughout or excludes it throughout, and both are wrong:

"GBR" %in% country_groups("EU", as_of = 2016)$iso3c   # TRUE
"GBR" %in% country_groups("EU", as_of = 2021)$iso3c   # FALSE

country_groups_history carries dated membership for nineteen groups: EU, EuroZone, NATO, OECD, ASEAN, EFTA, GCC, Mercosur, Nordic, Visegrad, BRICS, G7, SCO, CPTPP, RCEP, EAC, SADC, APEC and the Arab League, with suspensions as spells of their own: Syria is not counted in the Arab League from 2011 to 2023. Commonwealth, G20 and OPEC are not dated – their histories involve suspensions, readmissions and contested dates the sources give unevenly, and a fabricated date is worse than an absent one. Asking for as_of on those warns and falls back to the snapshot.

See Also

in_group(), country_groups_history, country_timeline()

Examples

country_groups("EU")
country_groups(c("G7", "BRICS"))
# the UK was a member in 2016 and not in 2021
nrow(country_groups("EU", as_of = 2016))
nrow(country_groups("EU", as_of = 2021))

Description

When each country joined – and where applicable left, or was suspended from – each of nineteen international groups. The dated counterpart to country_groups_tbl, which is a single current snapshot.

Usage

country_groups_history

Format

A tibble with 288 rows:

group

Group name.

iso3c

ISO 3166-1 alpha-3 code.

country

Country name.

from

Date the spell took effect.

to

The first date on which it no longer held (it runs up to the day before), or NA for one still in force. The United Kingdom's EU to is therefore 2020-02-01: it left at the end of 31 January 2020.

status

"member" or "suspended". A country can have several spells in a group: Seychelles left SADC in 2004 and rejoined in 2008, and Syria was suspended from the Arab League from 2011 to 2023. country_groups() and in_group() count the member spells only.

Details

A snapshot silently misstates any panel that spans an accession: an EU panel over 2015-2020 either includes the United Kingdom throughout or excludes it throughout, and both are wrong. country_groups() and in_group() read this table when given as_of.

Scope, and what is deliberately absent

Nineteen groups are dated: EU, EuroZone, NATO, OECD, ASEAN, EFTA, GCC, Mercosur, Nordic, Visegrad, BRICS, G7, and since 4.0.0 SCO, CPTPP, RCEP, EAC, SADC, APEC (member economies, so Hong Kong and Taiwan too) and the Arab League ("ArabLeague"). Every date carries its source in data-raw/country_groups_history.R. Commonwealth, G20 and OPEC are not, and that is a decision rather than an omission: the Commonwealth's and OPEC's suspensions, lapses and readmissions are dated unevenly by the sources, and G20's members include the EU and the African Union, which are not countries. A fabricated date is worse than an absent one, so country_groups(as_of =) warns and falls back to the snapshot for those. RCEP leaves out Myanmar, whose ratification the ASEAN Secretariat questioned and whose date of entry into force is disputed.

Dates are the treaty, accession or decision date where one exists; where the sources give only the month, the 1st of that month (APEC's accessions). The table is validated at build time against country_groups_tbl: the members current today must reproduce the snapshot exactly, for every group covered.

See Also

country_groups(), in_group(), country_timeline()

Examples

# EFTA is the instructive one: most of its founders left, for the EU
subset(country_groups_history, group == "EFTA")

Description

A curated, dated membership table for the common country groups.

Usage

country_groups_tbl

Format

A tibble with columns group, iso3c, country.

As of when

Membership is a snapshot taken on 2026-06-01, carried on the table itself:

attr(country_groups_tbl, "as_of")
#> [1] "2026-06-01"

Read the attribute rather than this paragraph if you need the date in code; it is set from a single constant in data-raw/build_datasets.R, so it cannot drift from the data the way a hand-written date can. For membership at any other date use country_groups_history and country_groups(as_of = ), which is the table this snapshot is a slice of.

Source

Curated from official membership lists, as of the date above. (This used to point at the package NEWS for the reference date, where two different dates were on record – an Rd should not delegate a fact to a changelog.)

Description

The generic two-table version of the package's whole reason for being: join any two data frames that each key on country names or codes, by reconciling both sides to iso3c first. Tables keyed on "Czech Republic" vs "Czechia", or "South Korea" vs "Korea, Rep.", just work.

Usage

country_join(
  x,
  y,
  by_x,
  by_y,
  origin_x = "country.name",
  origin_y = "country.name",
  type = c("left", "inner", "full"),
  suffix = c(".x", ".y"),
  key = c("iso3c", "cowc", "cown", "gwn"),
  warn = TRUE,
  also_by = NULL
)

Arguments

Value

A tibble joined on a reconciled iso3c key.

Panels

one row per country-year: Two country-year panels are joined country-year to country-year: when both tables have a year column it becomes part of the key, with a message, so France 2019 meets France 2019 rather than every year of France meeting every other. A panel joined to a cross-section (one side has no year) repeats the cross-section's values across the panel's years, and says that too. Pass also_by to key on other columns, or also_by = character() to join on the country alone.

Whatever the keys, a key that appears more than once on both sides pairs every copy with every copy. dplyr warns about that many-to-many join only when it is called from the console, never from inside a package, so this verb checks for itself and warns with class countryatlas_many_to_many, naming the keys.

Joining historical data

the second spine: ISO 3166 was first published in 1974 and never covered colonies, so iso3c cannot key anything before about 1970. Correlates of War and Gleditsch-Ward codes can, they run back to the nineteenth century, and historical_geometry() is keyed on gwn. Setting key switches the join onto one of those:

country_join(a, b, country, nation, key = "gwn")

The trade-off is real and worth stating: COW/GW codes cover states ISO never did, but they omit the dependencies and non-sovereign territories ISO does cover, so a modern dataset joined on gwn loses Hong Kong, Puerto Rico and the rest – which the join warns about. Use iso3c unless you are working before 1970.

Examples

a <- data.frame(country = c("Czechia", "South Korea"), gdp = c(1, 2))
b <- data.frame(nation = c("Czech Republic", "Korea, Rep."), pop = c(10, 51))
country_join(a, b, country, nation)

Description

The many-table generalisation of country_join(): reduce-join a list of data frames that each key on country names or codes, reconciling every one to iso3c first.

Usage

country_join_all(
  tables,
  by,
  origin = "country.name",
  type = c("full", "left", "inner"),
  key = c("iso3c", "cowc", "cown", "gwn"),
  warn = TRUE,
  also_by = NULL
)

Arguments

Value

A single tibble joined on key (clashing non-key columns get dplyr's default .x/.y suffixes).

Examples

a <- data.frame(country = c("Czechia", "South Korea"), gdp = c(1, 2))
b <- data.frame(country = c("Czech Republic", "Korea, Rep."), pop = c(10, 51))
d <- data.frame(country = c("Czechia", "Korea"), area = c(79, 100))
country_join_all(list(a, b, d), by = "country")

Description

One row per country with the facts people constantly need and currently scrape together by hand.

Usage

country_meta

Format

A tibble with one row per country and columns iso3c, iso2c, country, continent, region, un_region, income, capital, capital_lat, capital_lon, centroid_lat, centroid_lon, area_km2, currency, tld, landlocked, flag.

Assembled from countrycode::codelist, plus a curated row for Kosovo (XKX), which countrycode does not carry, so distance_between() and the k-nearest-neighbour weights can use it. Centroids and areas come from the bundled Natural Earth 1:50m polygons, the ones the polygon backend draws, with each country's holes taken out; territories drawn as part of their country (French Guiana, Svalbard) take theirs from Natural Earth's map units. Three territories have a row but no centroid or area, because Natural Earth does not draw them at 1:50m: Bouvet Island, Gibraltar and the U.S. Minor Outlying Islands.

income and region are the World Bank's for the current fiscal year (the "classification" attribute names it, "FY2027"), from country_classifications, so they agree with what world_data() returns; region falls back to countrycode's where the World Bank lists no region.

country therefore carries the English names from countrycode ("South Korea", "Congo - Kinshasa"), which differ from the World Bank's for 39 of the 216 countries in world_snapshot ("Korea, Rep.", "Congo, Dem. Rep."). Each table is faithful to its own source, so join on iso3c and keep whichever label you want to display – reconciling the two is what country_join() is for.

Source

Assembled from countrycode, WDI metadata (capitals), the World Bank's classifications and Natural Earth geometry.

Description

Node- and edge-level summaries of a bilateral flow table: who sends, who receives, who is central. No igraph required – at country scale the dense arithmetic is trivial.

Usage

country_network(
  data,
  from,
  to,
  weight = NULL,
  origin = "country.name",
  top_n = 20
)

Arguments

Value

A list of two tibbles:

• nodes – iso3c, country, out_flow, in_flow, net_flow, out_degree, in_degree and strength_share (the country's share of all flow, in or out).

• edges – from, to, weight, share and reciprocity (the opposite flow as a proportion of this one; NA where there is none).

See Also

flow_matrix(), od_map(), flow_map()

Examples

od <- data.frame(
  from = c("China", "China", "Germany", "USA", "Mexico"),
  to   = c("USA", "Germany", "France", "Mexico", "USA"),
  value = c(500, 100, 80, 300, 320)
)
country_network(od, from, to, value)

Description

A documented custom_match table for entities that geometry sources (Natural Earth, and the maps package's 2013 copy of it) and data providers spell in ways name matching gets wrong or leaves without an ISO code. Earlier versions of the package deleted these regions; now they are matched instead, so they stop silently disappearing from maps.

Usage

country_overrides(extra = NULL)

Arguments

Details

The table maps a country/region name (as spelled by the geometry backends) to an ISO 3166-1 alpha-3 code. Pass the result as the custom_match argument to standardize_country(), world_data() and friends. Every downstream code (iso2c, continent, region, flag, ...) is derived from this iso3c, so a single override is enough.

Value

A named character vector suitable for countrycode(custom_match=).

Accented names and locales

Every name in this table is plain ASCII, and that is deliberate: ASCII spellings match in any locale. Accented spellings ("Curacao" with a cedilla, "Saint Barthelemy" with an acute) are matched natively by countrycode::countrycode() in a UTF-8 locale, which is why they are not listed here – but in a non-UTF-8 locale (LC_CTYPE=C) they cannot be compared reliably and resolve to NA.

Accented spellings also come in two Unicode forms that look identical: the accent can be one precomposed code point (NFC) or a base letter followed by a combining mark (NFD, which macOS returns for filenames). Only NFC matches countrycode::countrycode()'s tables, so a name that resolves to nothing is retried with its combining marks stripped, which turns an NFD spelling into the ASCII spelling that resolves anywhere. Only unresolved names are retried, so this never changes a name that already matched.

If your input may contain accented country names, run in a UTF-8 locale. De-accenting with iconv(x, to = "ASCII//TRANSLIT") gives ASCII spellings that resolve everywhere, but it is not an escape from the locale problem: ⁠//TRANSLIT⁠ is itself locale-dependent, so under LC_CTYPE=C it returns NA (or, given an explicit from = "UTF-8", replaces each accent with ⁠?⁠) and nothing resolves. De-accent while still in a UTF-8 locale, or supply the ASCII spellings directly.

Examples

country_overrides()
country_overrides(c(Somaliland = "SOM"))

Description

What fetch_indicator() can reach, whether each one's backing package is actually installed, and how to cite it.

Usage

country_sources()

Value

A tibble: source, meta, key_col, key_type, cache, available (is the backing package installed?) and citation.

See Also

register_country_source(), fetch_indicator()

Examples

country_sources()

Description

When did this country exist, and what came before and after it? Reads the bundled historical_codes crosswalk in both directions – so it answers both "what did the USSR become" and "what was Estonia part of".

Usage

country_timeline(x, origin = "country.name", warn = TRUE)

Arguments

Value

A tibble, one row per input: input, iso3c, country, dissolved (the year it ceased to exist, or NA if it still does), predecessors and successors (list-columns of iso3c codes). An input that resolves to neither spine keeps its input and gets NA elsewhere; with warn = TRUE it is reported rather than left to be spotted.

Why the two directions are not mirror images

Both columns hold codes, so an entity ISO never coded cannot appear in either. ISO 3166-3 only records changes from 1974 on, and three entities in historical_codes predate it: the United Arab Republic (1961), Tanganyika and Zanzibar (both 1964). Asking about one of those by name works – country_timeline("Tanganyika") gives TZA as a successor, because the table stores that side as a name – but the reverse does not: country_timeline("TZA") reports no predecessors, since there is no code to report. The other eleven entities carry codes and round-trip in both directions. Naming them instead of coding them would break the column's type; inventing codes for them would be a guess, which this package does not make.

See Also

dissolve_country(), historical_codes, audit_time_coverage()

Examples

country_timeline(c("USSR", "Estonia", "France"))

Description

Build a reusable neighbour-weights object for morans_i(), local_morans(), gearys_c(), getis_ord() and spatial_lag(). Four schemes, three of which give every country at least one neighbour – which land-border contiguity, the default before 4.0.0, cannot do for an island.

Usage

country_weights(
  type = c("knn", "contiguity", "distance", "custom"),
  countries = NULL,
  k = 5,
  cutoff_km = NULL,
  w = NULL,
  style = c("W", "B"),
  scale = "small"
)

Arguments

Value

A countryatlas_weights object: the weights matrix plus the scheme that built it. Inspect it by printing; as.matrix() gives the matrix.

Choosing a scheme

Contiguity encodes "shares a border", which is the right relation for spillovers that cross borders by land. It is the wrong relation for a global question, because it silently deletes the islands. "knn" is the safe default for world-scale work: every country participates, and k controls how local the neighbourhood is. "distance" is right when the process has a real length scale. "custom" is right when geography is not the relevant space at all.

See Also

morans_i(), local_morans(), lisa_map(), spatial_lag()

Examples

# k-nearest neighbours: no sf needed, and islands are included
w <- country_weights("knn", k = 4)
w


snap <- countryatlas::world_snapshot$countries
morans_i(snap, gdp_per_capita, weights = country_weights("knn", k = 5),
         n_perm = 99)

Description

A choropleth of whether a value is present, rather than what it is. The companion to audit_coverage(), which reports the same thing as a table: a world map with a large well-covered region and a systematically empty one is telling you something about the indicator that the headline map hides behind a uniform grey.

Usage

coverage_map(data, value, by = NULL, title = NULL, ...)

Arguments

Value

A ggplot object.

Backend

Either backend, as world_map(): the frame decides, and both draw in Equal Earth unless projection is passed on through ....

See Also

audit_coverage(), world_map()

Examples

snap <- countryatlas::world_snapshot$countries
attach_geometry(snap, geometry = "polygon") |>
  coverage_map(gdp_per_capita)

Description

A nominal series is not comparable across years. deflate() divides by a price index rebased to base_year, turning current-price values into constant base_year prices.

Usage

deflate(data, value, base_year, deflator = NULL, suffix = "_real")

Arguments

Value

data with the constant-price column added.

Which deflator

The GDP deflator is the right default for aggregate output. For household spending the CPI (FP.CPI.TOTL) is usually preferred, and for cross-country level comparisons a deflator is not enough at all – you want to_ppp() as well, because exchange rates do not equalise purchasing power. Deflating and converting to PPP are different corrections for different problems, and a cross-country panel over time generally needs both.

See Also

to_ppp(), per_capita(), index_to()

Examples

d <- data.frame(iso3c = "USA", year = 2000:2002,
                gdp = c(100, 110, 120), defl = c(90, 100, 105))
deflate(d, gdp, base_year = 2001, deflator = defl)

Description

Disputed territories are drawn differently by different conventions, and a map that does not say which one it used is making a choice silently. This sets the session's convention so world_map() can record it and map_provenance() can report it.

Usage

dispute_policy(policy = NULL, worldview = NULL)

Arguments

Value

When called with no argument, the policy currently in effect. When setting, the policy that was in effect before the call, invisibly – R's convention for a setter, so on.exit(dispute_policy(dispute_policy("neutral"))) restores it.

What this does and does not do

On its own it records a choice and makes it visible. It does not redraw any boundary, and selecting "de_jure" gives no claimed-boundary geometry, so it warns. With a worldview it does change the shapes: the sf backend draws that country's published view. The package ships no worldview of its own beyond Natural Earth's default, and anyone publishing under an institutional convention should still verify the shapes against that institution's own basemap rather than trusting a setting.

See Also

disputed_territories, check_dispute_coverage(), world_map()

Examples

old <- dispute_policy("neutral")   # sets, and returns what it replaced
dispute_policy()                   # "neutral"
dispute_policy(old)                # put it back

Description

Territories whose status is contested, recorded so that a map can say so.

Usage

disputed_territories

Format

A tibble with 22 rows:

territory

Common name of the territory.

iso3c

ISO 3166-1 alpha-3 code where one exists, else NA. Most disputed territories have none, which is why they cannot appear in an iso3c-keyed dataset at all.

administered_by

The party in de facto control, or NA where none is. An ISO 3166-1 alpha-3 code where that party has one – see the note on codes below.

claimed_by

Semicolon-separated claimants, coded as for administered_by.

status

One of "un_member", "un_observer", "partially_recognised", "administered" or "claimed".

note

One sentence of context, including why the row is here.

Details

This table records that a dispute exists and who the parties are. It does not adjudicate, rank claims, or imply that any claim is better founded than another. Where it says "administered by" it means de facto control as reported by the mapping sources the package already uses (Natural Earth), not recognition, legitimacy or endorsement.

What reads these columns

Nothing in the package does. The internal layer and note builders behind world_map(disputes = ) and dispute_policy() key on iso3c alone, and no verb filters on the parties. administered_by and claimed_by are here for your own filtering – "show me everything Morocco administers", "drop the territories with more than one claimant" – and are documented precisely so that such a filter is writable. Their contents are validated at build time against the placeholder list below.

The codes in administered_by and claimed_by

Mostly ISO 3166-1 alpha-3, so they join the iso3c spine directly – but not entirely, and the exceptions are the point of the table. Six parties here are entities ISO assigns no code to, and they are written with a mnemonic placeholder instead: ABK (Abkhazia), CYP-N (Northern Cyprus), OST (South Ossetia), PMR (Transnistria), SAH (the Sahrawi Arab Democratic Republic) and SOL (Somaliland).

Five of them – ABK, CYP-N, OST, PMR and SOL – appear in administered_by for the like-named territory, which has no ISO code of its own: the entity administers itself and ISO codes neither. SAH is the exception and worth knowing about: it appears only as a claimant, of Western Sahara, which ISO does code (ESH) and which MAR administers.

None of the six are ISO codes, so none will resolve through convert_country() or any other iso3c lookup. Filter them out with ⁠%in% country_codes()$iso3c⁠ if you need a strictly ISO-keyed column.

Scope

A documented subset, not the roughly 188 disputed areas the EU's data-visualisation guidance counts. The selection criterion is mechanical and checkable: territories that appear as a distinct unit or a contested boundary in Natural Earth at 1:110m or 1:50m, and have an ISO 3166-1 code, a widely-used user-assigned code, or a standard "disputed" label in ISO, UN M49 or World Bank practice. That criterion requires nobody to judge the merits.

See Also

dispute_policy(), check_dispute_coverage(), world_map()

Examples

disputed_territories[, c("territory", "iso3c", "status")]

Description

Historical data is full of countries that no longer exist – the USSR, Yugoslavia, Czechoslovakia – and they poison naive joins twice over: most are silently unmatched, and some are silently mismatched (countrycode resolves "USSR" to Russia alone, so Soviet-era totals quietly become Russian totals). dissolve_country() resolves a mixed vector of historical and modern names against the curated historical_codes crosswalk: dissolved entities expand to one row per successor state (one-to-many, dated), while modern names pass through as single rows – so a whole messy column can be piped in unchanged.

Usage

dissolve_country(x, warn = TRUE)

Arguments

Value

A tibble with one row per (input, successor) pair: input (as given), historical (canonical dissolved-entity name, NA for modern countries), dissolved (year the entity ceased to exist, NA for modern), iso3c and country (the successor state). Unmatched inputs yield one row with iso3c = NA.

See Also

historical_codes for the crosswalk itself and the successor policy (e.g. Kosovo's inclusion in the Yugoslavia list); check_country_match(), whose historical column flags these entities; repair_country_names(), which deliberately leaves them alone.

Examples

dissolve_country(c("USSR", "Czechoslovakia", "France"))
# One-to-many: Yugoslavia expands to its successor territories
dissolve_country("Yugoslavia")

Description

Haversine distance (km) between two countries' centroids – the lightweight companion to country_borders() for "how far apart" rather than "do they touch". Works from the bundled country_meta centroids, so unlike most of the spatial toolkit it needs neither sf nor the network.

Usage

distance_between(a, b, origin = "country.name")

Arguments

Value

A numeric vector of great-circle distances in kilometres (NA for any country that doesn't resolve to a known centroid).

Countries without a bundled centroid

country_meta carries no centroid for three territories Natural Earth does not draw at 1:50m (Bouvet Island, Gibraltar and the U.S. Minor Outlying Islands); those inputs return NA here. Kosovo, which countrycode::codelist does not carry, has a curated row with a centroid.

Examples

distance_between("France", "Germany")
distance_between("USA", c("Canada", "Mexico"))

Description

Non-overlapping proportional circles sized by weight, positioned to stay as close as possible to each country's true location – arguably the most legible cartogram variant, since a microstate's circle is exactly as visible as a giant country's. A first-class verb for cartogram_map()(type = "dorling") that surfaces the Dorling-specific tuning knobs.

Usage

dorling_map(
  data,
  weight,
  fill = NULL,
  k = 5,
  itermax = 1000,
  projection = "equal_earth",
  footnote = "auto"
)

Arguments

Value

A ggplot object.

Backend

The sf backend only: the cartogram package places its circles from sf geometry, in projection (Equal Earth by default).

Examples

if (requireNamespace("sf", quietly = TRUE) &&
    requireNamespace("rnaturalearth", quietly = TRUE) &&
    requireNamespace("cartogram", quietly = TRUE)) {
  attach_geometry(countryatlas::world_snapshot$countries, geometry = "sf") |>
    dorling_map(population)
}

Description

Moran's I on raw rates mistakes the noise of small denominators for clustering: a few small states with extreme rates beside one another look like a hot spot. The empirical-Bayes index (Assuncao & Reis 1999) standardises each rate by how much variation its denominator alone would produce before testing for autocorrelation.

Usage

eb_morans_i(data, numerator, denominator, weights = NULL, n_perm = 999)

Arguments

Value

A one-row tibble like morans_i()'s: i, expected, n, n_excluded, n_links, p_value (one-sided, for positive autocorrelation) and the list-column excluded.

The statistic

With rates $p_i = y_i / x_i$, the global rate $b = \sum y / \sum x$ and the method-of-moments between-country variance $a$ (as in smooth_rates()), each rate is standardised as $z_i = (p_i - b) / \sqrt{a + b / x_i}$ and Moran's I is computed on $z$. It agrees with spdep::EBImoran.mc() on the same weights.

References

Assuncao, R. M. & Reis, E. A. (1999). A new proposal to adjust Moran's I for population density. Statistics in Medicine 18(16), 2147-2162. doi:10.1002/(SICI)1097-0258(19990830)18:16<2147::AID-SIM179>3.0.CO;2-I

See Also

morans_i(), smooth_rates(), rate_funnel()

Examples

snap <- countryatlas::world_snapshot$countries
snap$births <- snap$population * 0.02
eb_morans_i(snap, births, population, n_perm = 0)

Description

Facet a choropleth into small multiples (one panel per group or per year) – the static counterpart to animate_world(), for print and side-by-side comparison. Builds a world_map() and facets it on facet.

Usage

facet_map(
  data,
  fill,
  facet,
  ncol = NULL,
  breaks_by = c("pooled", "panel"),
  ...
)

Arguments

Value

A faceted ggplot object.

Backend

Either backend, as world_map(): the frame decides, and both draw in projection (Equal Earth by default).

Examples

snap <- countryatlas::world_snapshot$countries
mapdf <- attach_geometry(snap, geometry = "polygon")
facet_map(mapdf, gdp_per_capita, continent, style = "quantile")

Description

One verb, many providers. Whatever the source, the result comes back on the ISO spine: iso3c, year where the data is a panel, and one column per indicator.

Usage

fetch_indicator(
  source,
  indicator,
  countries = NULL,
  years = NULL,
  vintage = NULL,
  ...
)

Arguments

Value

A tibble keyed on iso3c (and year, for a panel), with a record of where each indicator column came from; see source_info().

See Also

add_indicator(), compare_sources(), country_sources()

Examples

## Not run: 
fetch_indicator("wdi", c(gdp = "NY.GDP.PCAP.KD"), years = 2020)
fetch_indicator("owid", "life_expectancy", years = 2020)

## End(Not run)

Description

One reader for the statistical agencies that publish through SDMX, the standard for statistical data exchange: the OECD, the IMF, the ILO, Eurostat, the European Central Bank, the BIS and UNICEF, or any other SDMX REST service by URL. It asks for SDMX-CSV, which needs no client package, and returns the result on the ISO spine. fetch_oecd() is this with provider = "oecd", and the "imf" and "ilo" sources of fetch_indicator() go through it too.

Usage

fetch_sdmx(provider, flow, key = NULL, countries = NULL, years = NULL, ...)

Arguments

Value

A tibble of iso3c, year and the value column, with a source_info() record (the unit and its power of ten, from UNIT_MEASURE and UNIT_MULT where the provider sends them). The provider's aggregates ("OECD", "EA20") are not countries and are dropped.

One row per country-year

The package keys on country and year, so every other dimension has to be pinned. When a dimension still varies – several measures, both sexes, or quarterly periods – a country-year has several rows, and keeping the first would be a silent choice; the reader aborts instead and names the dimensions that vary, so the key can be narrowed. A failed request is a warning and no rows, unless options(countryatlas.strict = TRUE).

See Also

fetch_oecd(), fetch_indicator(), register_country_source()

Examples

# Real GDP growth for three countries, filtered by the OECD's server:
fetch_sdmx("oecd", c(gdp_growth = "OECD.SDD.NAD,DSD_NAAG@DF_NAAG_I,1.0"),
           key = "A..B1GQ_R_GR..", countries = c("FRA", "DEU", "JPN"),
           years = 2020:2023)

Description

Draws great-circle arcs between country pairs from an origin-destination table (trade, migration, flights, remittances), resolving both endpoints to centroids automatically.

Usage

flow_map(
  data,
  from,
  to,
  weight = NULL,
  origin = "country.name",
  arc_points = 50,
  projection = "equal_earth",
  footnote = "auto",
  n = deprecated()
)

Arguments

Value

A ggplot object.

Backend

The polygon backend draws it, in projection (Equal Earth by default), so it needs no sf.

Examples

od <- data.frame(from = c("China", "Germany"),
                 to = c("United States", "France"),
                 value = c(500, 200))
flow_map(od, from, to, value)

Description

Reshape a long bilateral table (trade, migration, flights, remittances) into a square origin x destination matrix on the ISO spine, with both country columns standardised. The natural input to a network analysis, and to country_weights()(type = "custom") – which is how "countries near each other in trade space" becomes a spatial weights object.

Usage

flow_matrix(
  data,
  from,
  to,
  weight = NULL,
  origin = "country.name",
  symmetric = FALSE,
  fill = 0
)

Arguments

Value

A square numeric matrix with iso3c row and column names. Rows are origins, columns destinations.

See Also

country_network(), flow_map(), country_weights()

Examples

od <- data.frame(
  from = c("China", "China", "Germany", "USA"),
  to   = c("USA", "Germany", "France", "Mexico"),
  value = c(500, 100, 80, 300)
)
flow_matrix(od, from, to, value)

Description

The other classical global autocorrelation statistic. Where Moran's I is a correlation-like measure centred on $-1/(n-1)$, Geary's C is a distance-like one centred on 1: below 1 means positive autocorrelation (neighbours are similar), above 1 means negative. It is more sensitive than Moran's I to local differences.

Usage

gearys_c(data, value, weights = NULL, n_perm = 999)

Arguments

Value

A one-row tibble: c (observed), expected (always 1), n (countries used), n_excluded (countries with data that the weights could not reach), n_links (non-zero weights), p_value and an excluded list-column of the excluded iso3c codes. n and n_excluded sum to the countries supplied with a value, and mean the same here as in morans_i().

p_value is one-sided on the lower tail: $(1 + \#\{C^{*} \le C_{obs}\}) / (n_{perm} + 1)$. The lower tail is the clustered one, which is the opposite way round from Moran's I: Geary's C runs from 0 (neighbours identical) through 1 (no autocorrelation) upwards, so a small c is the evidence of positive spatial association. Never exactly zero; the floor is $1/(n_{perm}+1)$. Set a seed beforehand for a reproducible p_value.

References

Geary, R. C. (1954). The contiguity ratio and statistical mapping. The Incorporated Statistician 5(3), 115-146. doi:10.2307/2986645

See Also

morans_i(), country_weights()

Examples

snap <- countryatlas::world_snapshot$countries
gearys_c(snap, gdp_per_capita, weights = country_weights("knn", k = 5),
         n_perm = 99)

Description

A ggplot2 layer that places labels (names, ISO codes or flag emoji) at country centroids, with optional ggrepel collision avoidance. Designed for the polygon backend produced by world_data() / join_world(): it reads the long, lat and group columns, so it errors on an sf frame and points at ggplot2::geom_sf_text() instead. Placement is exact only while group is present – that is what identifies each country's separate pieces, and the label goes on the largest one.

Usage

geom_country_labels(
  mapping = NULL,
  data = NULL,
  repel = TRUE,
  flag = FALSE,
  size = 3,
  ...
)

Arguments

Value

A ggplot2 layer.

Examples

library(ggplot2)
snap <- countryatlas::world_snapshot$countries
mapdf <- attach_geometry(snap, geometry = "polygon")

# Labelling all 188 countries at once is unreadable, and ggrepel responds
# by dropping nearly every label. Pass `data` to choose a subset ...
world_map(mapdf, gdp_per_capita) +
  geom_country_labels(
    data = ~ dplyr::filter(.x, iso3c %in% c("USA", "BRA", "CHN", "IND", "ZAF"))
  )

# ... or zoom in, where there is room for every label.
europe <- attach_geometry(
  dplyr::filter(snap, continent == "Europe"), geometry = "polygon")
world_map(europe, gdp_per_capita) +
  geom_country_labels(size = 2.5) +
  coord_quickmap(xlim = c(-25, 45), ylim = c(34, 72))

Description

Global $G$ and local $G_i^*$: unlike Moran's I, these distinguish clusters of high values from clusters of low ones, which is what "hot spot" analysis usually wants.

Usage

getis_ord(
  data,
  value,
  weights = NULL,
  local = TRUE,
  p_adjust = c("fdr", "bonferroni", "holm", "none")
)

Arguments

Value

With local = TRUE, a tibble of iso3c, gi_star, z_score, p_value (two-sided, from the normal approximation) and p_adjusted, one row per country used. With local = FALSE, a one-row tibble of g, expected, n (countries used – the same count, so the local form returns n rows) and n_links (non-zero weights).

References

Getis, A. & Ord, J. K. (1992). The analysis of spatial association by use of distance statistics. Geographical Analysis 24(3), 189-206. doi:10.1111/j.1538-4632.1992.tb00261.x

See Also

local_morans(), country_weights()

Examples

snap <- countryatlas::world_snapshot$countries
getis_ord(snap, gdp_per_capita, weights = country_weights("knn", k = 5))

Description

The Gini index of inequality across countries, optionally weighted (weight by population and the statistic describes inequality between people assigned their country's mean, not between country units).

Usage

gini(x, weights = NULL, na.rm = TRUE)

Arguments

Value

A single number in ⁠[0, 1]⁠: 0 is perfect equality.

See Also

theil(), which adds a between/within-group decomposition.

Examples

snap <- countryatlas::world_snapshot$countries
gini(snap$gdp_per_capita)                          # between countries
gini(snap$gdp_per_capita, weights = snap$population)  # between people

Description

The world as a globe (orthographic projection) centred on lon/lat – the honest answer to "the whole world on a rectangle exaggerates the poles". Takes the same fill / style options as world_map(). The default "sf" backend gives the cleanest limb; the "polygon" backend draws the globe with ggplot2::coord_map() and needs only mapproj (no sf).

Usage

globe_map(
  data,
  fill,
  lon = 0,
  lat = 20,
  backend = c("sf", "polygon"),
  style = c("quantile", "continuous", "binned", "equal", "jenks", "fisher", "headtails",
    "sd", "fixed", "categorical"),
  palette = NULL,
  n_bins = 5,
  breaks = NULL,
  midpoint = NULL,
  borders = TRUE,
  title = NULL,
  legend = NULL,
  na_label = "No data",
  footnote = "auto",
  small_states = c("auto", "none", "dots"),
  small_area_km2 = 1000,
  interactive = FALSE
)

Arguments

Value

A ggplot object.

Examples

# No sf required -- the polygon backend needs only mapproj:
if (requireNamespace("mapproj", quietly = TRUE)) {
  globe_map(countryatlas::world_snapshot$countries, continent,
            backend = "polygon", style = "categorical")
}

## Not run: 
# The sf backend gives the cleanest limb (needs a World Bank fetch):
world_data(2020, geometry = "sf") |>
  globe_map(gdp_per_capita, lon = 10, lat = 30)

## End(Not run)

Description

A gridded (or "waffle") cartogram: the world redrawn as equal cells, each worth a fixed quantity, allocated to countries in proportion to their value and placed near where they belong. Where a Dorling cartogram preserves position and a contiguous one preserves adjacency, this preserves countability – the reader can literally count the cells.

Usage

gridded_cartogram(
  data,
  value,
  cells = 1000,
  fill = NULL,
  cell_size = 2.5,
  projection = "equal_earth",
  footnote = "auto"
)

Arguments

Value

A ggplot object. The per-country cell allocation is attached as the "countryatlas_cells" attribute – every placeable country, including the ones that rounded to zero cells, so share sums to 1 and the rounding is fully visible.

Backend

The cells are laid out from the bundled centroids in projection (Equal Earth by default), so it needs no geometry backend and no sf.

Rounding is the whole difficulty

Allocating a whole number of cells to each country cannot be exact, so the remainder has to go somewhere. This uses the largest-remainder method, which guarantees the cell total is exactly cells and that no country with a positive value gets zero cells while a smaller one gets one. The attached table reports each country's exact share alongside its integer allocation so the rounding is inspectable rather than hidden.

Crowded neighbours overlap

Each country's block is centred on its own centroid, with no collision avoidance between countries. That is deliberate – a global packing solve would push countries away from where they belong – but it means blocks in crowded regions are drawn on top of one another, and a partly hidden block cannot be counted or compared. The effect is not marginal: at the defaults (cells = 1000, cell_size = 2.5) about two fifths of the cells overlap a cell of a different country, across some eighty countries, and it grows with cells – at cells = 2500 it is roughly 70%.

cell_size is the lever, because it scales the tiles without moving the centroids: dropping it to 1.5 cuts the overlap at cells = 1000 to about a sixth of the cells. Fewer cells also helps. Where exact areas matter more than geographic position, dorling_map() resolves collisions by displacing circles instead.

See Also

cartogram_map(), dorling_map(), tile_map()

Examples

snap <- countryatlas::world_snapshot$countries
gridded_cartogram(snap, population, cells = 400)

Description

Adds a growth-rate column to a panel: either the period-over-period change ("yoy") or the compound annual growth rate from the first observed year ("cagr"), computed per country.

Usage

growth_rate(
  data,
  value,
  type = c("yoy", "cagr"),
  suffix = "_growth",
  by = c("year", "row")
)

Arguments

Value

data with a growth-rate column added (a proportion, so 0.03 = 3%). Rows come back sorted by iso3c then year: the calculation reads each country's series in time order, so a row-aligned vector held alongside data will no longer line up.

Examples

df <- data.frame(iso3c = "USA", year = 2000:2002, gdp = c(100, 110, 121))
growth_rate(df, gdp)

Description

A curated crosswalk from dissolved entities (Soviet Union, Yugoslavia, Czechoslovakia, ...) to the modern states that succeeded them – one row per (entity, successor) pair, dated, so historical panels can be brought onto the modern ISO spine honestly instead of being silently dropped (or worse: countrycode resolves "USSR" to Russia alone). Consumed by dissolve_country() and flagged by check_country_match().

Usage

historical_codes

Format

A tibble with one row per (entity, successor):

historical

Canonical name of the dissolved entity.

iso3c_hist

The alpha-3 code the entity held at dissolution, where one existed (SUN, YUG, CSK, DDR, ANT, SCG, YMD, ...); it may since have been inherited by a successor (e.g. YEM).

dissolved

Year the entity ceased to exist.

iso3c, country

The successor state.

relation

How the successor relates to the entity, per successor: "succession" if it is a genuinely new state created at dissolved, or "continuation" if the same state carried on (possibly with less territory) or a state that already existed absorbed the entity. Sudan is both at once – SDN continued and SSD is new – which is why the relation is per successor rather than per entity. The distinction matters: a "continuation" was not created at dissolved, so testing its data against that year says nothing, and the code did not cease to exist either. audit_time_coverage() keys on this column for both reasons.

Details

Kosovo (XKX) is included among the Yugoslavia and Serbia-and-Montenegro successors on a territory basis (its territory was part of both); filter it out if your analysis follows strict UN-membership succession.

Source

Curated from ISO 3166-3 and the historical record.

Description

Country polygons as they were, from CShapes 2.0 (Schvitz et al. 2022), which maps states and colonies and dependencies for 1886-2019 with per-polygon validity periods. A 1970 map with 2024 borders is a common and quiet error; this is the fix.

Usage

historical_geometry(year, dependencies = FALSE, projection = "equal_earth")

Arguments

Value

An sf frame with gwcode, country, iso3c (where one can be assigned – see below), status, from, to and geometry. Two further CShapes columns are passed through when the installed version supplies them, since they answer the questions this verb is usually asked:

• owner – the gwcode of the sovereign a dependency belonged to; a sovereign state carries its own gwcode here. This is the column that makes dependencies = TRUE legible: without it a colony and its metropole are two unrelated rows. owner != gwcode picks out the dependencies.

• capname – the capital's name at that date.

Both were returned but undocumented. Neither is guaranteed: cshapes decides what its own table holds, so check with names() rather than assuming.

The ISO spine does not reach back

ISO 3166 was first published in 1974 and never covered colonies, so a historical map cannot be keyed on iso3c. CShapes uses Gleditsch-Ward codes, which is why gwcode is the key here and iso3c is a best-effort extra, read off the GW code: the modern code of the state that holds it. So it is NA for an entity with no modern counterpart (the German Democratic Republic, Czechoslovakia, Yugoslavia, the two Yemens), and also where historical_codes says the modern state did not exist yet – GW give the USSR and Russia one code, but the 1980 polygon is the Soviet Union, so it carries NA rather than "RUS". A colony carries the code of the state it became: CShapes names the 1950 Gold Coast "Ghana" and it comes back as "GHA", with status saying it was a colony. Join historical data on gwcode, not on iso3c, and use convert_country()(to = "gwn") to get there from a modern code.

References

Schvitz, G., Girardin, L., Ruegger, S., Weidmann, N. B., Cederman, L.-E. & Gleditsch, K. S. (2022). Mapping the international system, 1886-2019: The CShapes 2.0 dataset. Journal of Conflict Resolution 66(1), 144-161. doi:10.1177/00220027211013563

See Also

world_geometry(), country_timeline(), world_map()

Examples

## Not run: 
# Africa before decolonisation needs the dependencies
historical_geometry(1950, dependencies = TRUE)

## End(Not run)

Description

A vectorised membership predicate built on country_groups().

Usage

in_group(x, group, origin = "country.name", as_of = NULL)

Arguments

Value

A logical vector the same length as x. A value origin cannot resolve to an ISO code answers FALSE – the same as a country that is genuinely outside the group – so run check_country_match() first if you need to tell "not a member" from "not recognised". A missing as_of answers NA: membership at an unknown date is unknown.

See Also

country_groups(), country_groups_history

Examples

in_group(c("France", "United States", "Japan"), "EU")
# membership is a function of time
in_group("United Kingdom", "EU", as_of = 2016)
in_group("United Kingdom", "EU", as_of = 2021)
# one date per row, as a panel needs
in_group(c("GBR", "GBR"), "EU", origin = "iso3c", as_of = c(2016, 2021))

Description

Rescales a value column so the chosen base year equals to (100 by default), per country – the standard way to compare trajectories that start at very different levels.

Usage

index_to(data, value, base_year, to = 100, suffix = "_index")

Arguments

Value

data with an index column added. The column is NA for any country whose series does not cover base_year (see the note there). A negative base-year value is indexed as it is, so that country's index runs opposite to its series.

Examples

df <- data.frame(iso3c = "USA", year = 2000:2002, gdp = c(50, 55, 60))
index_to(df, gdp, base_year = 2000)

# A base year the data does not have gives NA, not an error:
index_to(df, gdp, base_year = 1999)

Description

The usual inequality measures for one variable, in one tibble, so a report does not rest on whichever index came to hand. Weight by population for inequality between people rather than between countries.

Usage

inequality(
  x,
  weights = NULL,
  measures = c("gini", "theil_t", "theil_l", "atkinson", "cv", "palma", "p90_p10"),
  epsilon = 1
)