Attach geometry to a country-level table — attach

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

data: A data frame with an iso3c (or by) column.
by: The join key (default "iso3c").
geometry: "polygon" (default: the bundled Natural Earth 1:50m countries) or "sf". "maps", the maps package's polygons as drawn before 4.0.0, is deprecated.
scale: Natural Earth resolution for the sf backend. The polygon backend draws its one bundled resolution, 1:50m, and warns if asked for "large", which needs the non-CRAN rnaturalearthhires package; see world_geometry(). It also affects which countries are covered at all – see below.
region: Optional region subset (see world_geometry()).
projection, recenter: Projection, and optional central meridian. The sf backend projects the geometry here (see world_map() for the projections available). The polygon backend returns longitude/latitude, which the map verbs project when they draw, so it warns about projection; recenter cuts its rings at the new antimeridian.
overrides: Name -> iso3c overrides applied when matching the geometry backend's country names (default country_overrides()). Pass a custom set built with country_overrides() to add your own.
year: Attach historical geometry for this year instead of present-day borders, via historical_geometry(). Entities that never had an ISO code cannot match on iso3c, so a low match rate warns.
worldview: A Natural Earth point of view, as in world_geometry(): the viewing country's ISO code or "ISO". Needs geometry = "sf".

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

# \donttest{
df <- data.frame(iso3c = c("USA", "CAN"), value = c(1, 2))
attach_geometry(df, geometry = "polygon")
#> # A tibble: 97,812 × 9
#>     long   lat group order region subregion iso3c iso2c value
#>    <dbl> <dbl> <int> <int> <chr>  <chr>     <chr> <chr> <dbl>
#>  1  131.  42.3     1     1 Russia NA        RUS   RU       NA
#>  2  131.  42.3     1     2 Russia NA        RUS   RU       NA
#>  3  131.  42.4     1     3 Russia NA        RUS   RU       NA
#>  4  131.  42.4     1     4 Russia NA        RUS   RU       NA
#>  5  131.  42.5     1     5 Russia NA        RUS   RU       NA
#>  6  131.  42.5     1     6 Russia NA        RUS   RU       NA
#>  7  131.  42.6     1     7 Russia NA        RUS   RU       NA
#>  8  131.  42.6     1     8 Russia NA        RUS   RU       NA
#>  9  131.  42.7     1     9 Russia NA        RUS   RU       NA
#> 10  130.  42.7     1    10 Russia NA        RUS   RU       NA
#> # ℹ 97,802 more rows
# }