addUpper: Attach upper-level admin names to lower-level polygons

In surveyPrev: Mapping the Prevalence of Binary Indicators using Survey Data in Small Areas

Attach upper-level admin names to lower-level polygons

Description

Maps each polygon in a lower administrative layer (e.g., ADM2) to its containing polygon in an upper layer (e.g., ADM1), populating an upper-level name column. If containment fails for some polygons (e.g., due to slivers or minor topology issues), a nearest-centroid fallback is used.

Usage

addUpper(
  poly.adm.upper,
  poly.adm,
  by.adm,
  by.adm.upper,
  out_lower = "NAME_2",
  out_upper = "NAME_1",
  sort = TRUE
)

Arguments

poly.adm.upper	Spatial polygons for the *upper* admin level (e.g., Admin 1 when the desired output is Admin 2). Can be an sf object or an sp::SpatialPolygonsDataFrame.
poly.adm	Spatial polygons for the *target* admin level you want returned (e.g., Admin 2). Can be an sf object or an sp::SpatialPolygonsDataFrame.
by.adm	Character scalar. Column name in poly.adm that contains the admin names for the target level (e.g., "NAME_2").
by.adm.upper	Character scalar. Column name in poly.adm.upper that contains the admin names for the upper level (e.g., "NAME_1").
out_lower	Character scalar. Name of the output column to hold the lower-level names in the returned object. Defaults to "NAME_2".
out_upper	Character scalar. Name of the output column to hold the upper-level names in the returned object. Defaults to "NAME_1".
sort	Logical. If TRUE (default), alphabetically sorts the output by out_upper then out_lower.

Details

Inputs may be either sf or sp polygon data. If sp inputs are provided, they are converted to sf internally. Containment is determined via sf::st_within(). For polygons not matched by containment, the function uses sf::st_nearest_feature() on centroids (sf::st_centroid()) to assign an upper-level name.

Value

An sf object at the target (lower) admin level containing:

• out_lower: lower-level admin name (copied from by.adm)

• out_upper: upper-level admin name (derived via spatial matching)

• geometry: polygon geometry

• admin2.name.full: convenience concatenation paste0(out_upper, "_", out_lower)

Examples

## Not run: 
library(sf)
adm1 <- st_read("geoBoundaries/geoBoundaries-NGA-ADM1-all/geoBoundaries-NGA-ADM1.shp")
adm2 <- st_read("geoBoundaries/geoBoundaries-NGA-ADM2-all/geoBoundaries-NGA-ADM2.shp")

# If both layers use "shapeName" but you want outputs named NAME_1/NAME_2:
res <- addUpper(
  poly.adm.upper = adm1,
  poly.adm       = adm2,
  by.adm         = "shapeName",   # lower-level names
  by.adm.upper   = "shapeName",   # upper-level names
  out_lower      = "NAME_2",
  out_upper      = "NAME_1",
  sort           = TRUE
)

# If the columns are already NAME_1 / NAME_2:
res2 <- addUpper(
  poly.adm.upper = adm1,
  poly.adm       = adm2,
  by.adm         = "NAME_2",
  by.adm.upper   = "NAME_1"
)

## End(Not run)

surveyPrev documentation built on June 19, 2026, 5:06 p.m.