Skip to contents

Standardise subnational region names to ISO 3166-2

Source: R/subnational.R
standardize_subnational.Rd

The subnational counterpart to standardize_country(): resolve messy region names within a country to ISO 3166-2 codes, so subnational data can be joined on a real key instead of on spelling.

Usage

standardize_subnational(
  data,
  region,
  country,
  origin = "country.name",
  warn = TRUE
)

Arguments

data

A data frame with a region column.

region

The region-name column (unquoted).

country

The country column (unquoted), or a single country name/code applying to every row. ISO 3166-2 codes are only unique within a country, so this is required.

origin

How to read country (default "country.name").

warn

Warn about regions that do not resolve (default TRUE).

Value

data with iso3c and iso_3166_2 columns added. Unresolved regions get NA, never a guess.

Coverage, stated plainly

Two things resolve, and it is worth being blunt about how little that is.

A region value that is already an ISO 3166-2 code ("DE-BY", "US-CA") passes through, provided its country prefix matches the country the row gives – these codes are unique only within a country, which is why country is required. A mismatch is reported and left as NA.

A region name resolves only through the optional regions package's crosswalk, and only when the installed version exposes a name-to-code pair this function recognises. As of regions 0.1.8 none of them do: nuts_lau_2019 offers lau_name_national / lau_name_latin and all_valid_nuts_codes has no name column, so no region name resolves at all, anywhere – the function says so once per session. The package carries no ISO 3166-2 name table of its own, deliberately: the datasets that do pair names with codes key on NUTS codes (DE2) rather than ISO 3166-2 (DE-BY), and filling iso_3166_2 from those would put a different code system in the column.

So: pass codes if you have them. If you have names, expect NA until regions ships a usable crosswalk. This function returns NA rather than a plausible-looking wrong code, and audit_coverage() on the result is the right next step.

See also

subnational_map(), nuts_geometry(), standardize_country()

Examples

# \donttest{
d <- data.frame(region = c("Bavaria", "Hesse", "Nowhere"), value = 1:3)
if (requireNamespace("regions", quietly = TRUE)) {
  standardize_subnational(d, region, country = "Germany")
}
#> ! The installed regions (0.1.8) exposes no name-to-code crosswalk this function
#>   can use.
#> ℹ Only exact and case-insensitive ISO 3166-2 name and code matches will
#>   resolve; region names will not.
#> This message is displayed once per session.
#> Warning: 3 regions did not resolve to an ISO 3166-2 code:
#> • "Bavaria", "Hesse", and "Nowhere"
#> ℹ Only values that are already ISO 3166-2 codes resolve; region names need a
#>   crosswalk the installed regions does not provide. See the section in
#>   `?countryatlas::standardize_subnational()`.
#> # A tibble: 3 × 4
#>   region  value iso3c iso_3166_2
#>   <chr>   <int> <chr> <chr>     
#> 1 Bavaria     1 DEU   NA        
#> 2 Hesse       2 DEU   NA        
#> 3 Nowhere     3 DEU   NA        
# }