Creating Spatial Resources for World Bank Survey Solutions Fieldwork

library(vantorr)
library(sf)

# Define a small Enumeration Area bounding box in WGS84 (EPSG:4326)
ea_aoi <- st_bbox(
  c(xmin = -105.004, ymin = 39.736, xmax = -105.000, ymax = 39.740),
  crs = st_crs(4326)
)

# 1. Generate 250m Enumeration Area sub-cells (A1, A2, B1, B2)
ea_grid <- vantor_survey_grid(
  aoi = ea_aoi,
  cell_size = 250,
  shape = "square",
  verbose = FALSE
)

# 2. Define sampled household locations inside the EA
hh_samples <- st_as_sf(
  data.frame(
    hh_id = c("EA01-HH01", "EA01-HH02", "EA01-HH03"),
    lon = c(-105.0030, -105.0015, -105.0010),
    lat = c(39.7388, 39.7382, 39.7370)
  ),
  coords = c("lon", "lat"),
  crs = 4326
)

suso_tab_file <- tempfile(pattern = "suso_assignments_", fileext = ".tab")

capi_pts <- vantor_export_capi(
  samples         = hh_samples,
  id_col          = "hh_id",
  grid            = ea_grid,
  output_suso_tab = suso_tab_file,
  suso_gps_var    = "hh_gps",
  verbose         = FALSE
)

# Inspect the returned sf object (coordinate columns use <suso_gps_var>__Latitude / __Longitude)
st_drop_geometry(capi_pts)[, c(
  "sample_id", "cell_id", "plus_code",
  "hh_gps__Latitude", "hh_gps__Longitude"
)]
#>   sample_id cell_id   plus_code hh_gps__Latitude hh_gps__Longitude
#> 1 EA01-HH01      B1 85FPPXQW+GR          39.7388         -105.0030
#> 2 EA01-HH02      B2 85FPPXQX+7C          39.7382         -105.0015
#> 3 EA01-HH03      C2 85FPPXPX+RJ          39.7370         -105.0010

# Inspect the generated Survey Solutions .tab preload table
read.delim(suso_tab_file, check.names = FALSE)[, c(
  "sample_id", "cell_id", "plus_code",
  "hh_gps__Latitude", "hh_gps__Longitude",
  "_target_area"
)]
#>   sample_id cell_id   plus_code hh_gps__Latitude hh_gps__Longitude _target_area
#> 1 EA01-HH01      B1 85FPPXQW+GR          39.7388         -105.0030           B1
#> 2 EA01-HH02      B2 85FPPXQX+7C          39.7382         -105.0015           B2
#> 3 EA01-HH03      C2 85FPPXPX+RJ          39.7370         -105.0010           C2

if (requireNamespace("terra", quietly = TRUE)) {
  suso_bundle <- vantor_offline_package(
    grid              = ea_grid,
    samples           = capi_pts,
    raster            = r_ea,
    create_tpk        = "tpk",
    tpk_zoom          = 15:16,
    create_shapefiles = TRUE,
    suso_gps_var      = "hh_gps",
    package_name      = "suso_ea01",
    verbose           = FALSE
  )

  # Files ready for Survey Solutions Headquarters upload:
  basename(c(
    suso_bundle$tpk_zip_path,
    suso_bundle$shapefile_zip_path,
    suso_bundle$suso_tab_path,
    suso_bundle$raster_path,
    suso_bundle$csv_path
  ))

  # Inspect the root-level files inside suso_ea01_shapes.zip:
  utils::unzip(suso_bundle$shapefile_zip_path, list = TRUE)$Name
}
#> [1] "suso_ea01_grid.dbf"    "suso_ea01_grid.prj"    "suso_ea01_grid.shp"   
#> [4] "suso_ea01_grid.shx"    "suso_ea01_samples.dbf" "suso_ea01_samples.prj"
#> [7] "suso_ea01_samples.shp" "suso_ea01_samples.shx"

usermaps_df <- data.frame(
  map   = c("suso_ea01.tpk", "suso_ea01_grid.shp"),
  users = c("interviewer_01, interviewer_02", "interviewer_01, interviewer_02"),
  stringsAsFactors = FALSE
)

usermaps_tab <- file.path(tempdir(), "usermaps.tab")
utils::write.table(
  usermaps_df,
  file      = usermaps_tab,
  sep       = "\t",
  row.names = FALSE,
  quote     = FALSE
)

cat(readLines(usermaps_tab), sep = "\n")
#> map  users
#> suso_ea01.tpk    interviewer_01, interviewer_02
#> suso_ea01_grid.shp   interviewer_01, interviewer_02

# Install SurveySolutionsAPIv2 from GitHub if not already installed:
# remotes::install_github("michael-cw/SurveySolutionsAPIv2")
library(SurveySolutionsAPIv2)
library(data.table)

# 1. Authenticate with Survey Solutions Headquarters
suso_set_key(
  suso_server = "https://your-suso-server.mysurvey.solutions",
  suso_user    = Sys.getenv("SUSO_API_USER"),
  suso_password   = Sys.getenv("SUSO_API_PASS")
)

ws <- "primary"

# 2. Upload the Vantor .tpk basemap and Enumeration Area Shapefiles to HQ
suso_mapupload(
  workspace   = ws,
  path_to_zip = suso_bundle$tpk_zip_path
)

suso_mapupload(
  workspace   = ws,
  path_to_zip = suso_bundle$shapefile_zip_path
)

# Verify the uploaded maps and scales on the server
suso_mapinfo(workspace = ws)

# 3. Assign the .tpk basemap and EA grid boundary overlay to field interviewers
# (Assuming these interviewers are created on the server already)

for (int_user in c("interviewer01", "interviewer02")) {
  suso_mapassign(
    workspace  = ws,
    fileName   = "suso_ea01.tpk",
    userName   = int_user,
    assignUser = TRUE
  )
  suso_mapassign(
    workspace  = ws,
    fileName   = "suso_ea01_grid.shp",
    userName   = int_user,
    assignUser = TRUE
  )
}

# 4. Create preloaded assignments via REST API v1 (suso_createASS)
# (Assuming this questionnaire has the required ID fields and is loaded)
preload_dt <- data.frame(
  sample_id         = capi_pts$sample_id,
  cell_id           = capi_pts$cell_id,
  plus_code         = capi_pts$plus_code,
  ResponsibleName   = rep("interviewer01", nrow(capi_pts)),
  Quantity          = rep(1L, nrow(capi_pts))
)

suso_createASS(
  df        = preload_dt,
  workspace = ws,
  questID   = "00000000-0000-0000-0000-000000000000",
  version   = 1L
)