(Two-stage) Stratified and weighted sampling

Samples a single spatial point for each polygon based on an underlying spatial weights dataset. An auxiliary vector can be provided to define a secondary sampling unit and limit where points may be sampled.

Usage

wt_strata(x, weights, ...)

# S3 method for class 'SpatVector'
wt_strata(x, weights, ...)

# S3 method for class 'sf'
wt_strata(x, weights, ...)

# S3 method for class 'sfc'
wt_strata(
  x,
  weights,
  ...,
  psu = NULL,
  ssu = NULL,
  schema = NULL,
  ids = NULL,
  reuse_weights = TRUE,
  composition = "reductive",
  smooth = FALSE,
  smooth_opts = list(fun = "mean")
)

Arguments

x

A spatial object containing vector data (sfc, sf, or SpatVector) and either POLYGON/MULTIPOLYGON geometries or POINT/MULTIPOINT geometries. If polygons are provided, they are interpreted as primary sampling units. If points are provided, polygons must be provided to psu to be linked to the points in x through a spatial join. For each row in x, a spatial point representation is estimated based on the reference data in weights.

weights

An object of class sf, sfc, SpatVector, or SpatRaster that is used to define spatial weights. For example, this could be a population raster to define weights based on where people live. If raster data is provided, it is masked and vectorized internally. In any case, the polygons are intersected with the outer boundaries of x such that no points can be sampled outside of its boundaries.

...

Further arguments passed to wt_sample.

psu

Optional spatial vector dataset of class sf, sfc, or SpatVector representing the primary sampling unit (PSU). If not provided (the default), x is required to consist of polygons (which then act as the PSU). PSUs limit where each location in x can be sampled.

ssu

Optional character vector or factor with the same length as x representing the secondary sampling unit (SSU). If provided, a schema (using the schema argument) must be provided as well specifying the combinations of values in ssu and cell values in weights. Within each PSU, a location can only be sampled in those grid cells of weights whose cell values fall within the range of its corresponding category in ssu as defined in schema. For example, ssu could be a vector of place types (village, town, city) and schema could be a list combining each place type to a corresponding number of people. In this case, a record in x identified as being located in a village can only be sampled in raster cells with a low population density. If not provided, performs single-stage stratified sampling.

schema

An SSU schema object created by ssu_schema. Only necessary if ssu is provided. A schema "translates" SSUs defined in ssu to raster cells in weights. For example, if a SSU "town" is defined, what population values does this unit refer to?

ids

Optional vector used to identify sampling units in x. Passed down to the f argument in split. If a single ID identifies multiple geometries, they are merged using st_combine. Useful if the boundaries of an administrative unit are dispersed over multiple geometries. If not provided (the default), each row identifies one sampling unit.

reuse_weights

If TRUE and ssu is provided, uses the weights dataset defined in the weights argument both for generating SSUs and as a weights raster for wt_sample. This would result in a double weighting where locations can only be sampled in certain regions of weights and within these regions have a certain probability to be sampled in a specific part of the region. If FALSE, performs random sampling after SSU assignment. Defaults to TRUE to reduce randomness. Ignored if ssu is not provided.

Set to FALSE if performance is at a premium or if this behavior is not desired. For example, in high-value regions of a population raster, the probability of people living in regions with lower population densities is still very high and might not be properly represented by weighted sampling. Generally, if the assignment of sampling zones using schema is already detailed and leaves little space within each zone, reusing weights can be superfluous.

Only relevant if the schema is threshold-based, i.e., the argument is silently ignored if the schema is of type ideal.

composition

If computing composite weights (see section "Composite weights"), this argument controls the order of composition. If "reductive" (the default), the provided weights are reduced to a single surface by taking the product of all weights layers. If "sequential", the weights are applied in their index order, that is, the second weight is only applied in the cells eligible after applying the first weight, and so on. When combined with relative schemas "sequential" is the safer option, as it prevents non-overlapping weights. However, "reductive" is the default because it is usually the expected behavior and does not impose an order on the weights.

smooth

If TRUE and if weights is an object of class SpatRaster, computes focal statistics of the raster before entering grid weighting. Arguments to focal can be provided using the smooth_opts argument. This can be useful if the values in aux represent spatially contiguous spatial entities like settlements or population centers.

smooth_opts

Arguments passed to focal. Only relevant if smooth is TRUE and weights is a SpatRaster.

Value

The geoimputed point geometries as an sfc, sf, or SpatVector object. If x is an sf dataframe or SpatVector with additional columns, the columns are kept and only the geometry is updated.

Composite weights

You can provide composite weights instead of single weights by providing named lists to weights, ssu, and schema. Whereas single weights determine where geoimputation is allowed to sample based on a single raster, composite weights are defined through multiple combinations of rasters and SSUs. In particular, the geoimputation algorithm is only allowed to sample inside the intersection of the provided rasters. For example, if a population and an income raster are provided, then high-income and rural individuals can only be sampled within neighborhoods that exhibit high population and high income.

When providing composite weights, the names of the composite lists act as identifiers for the weights. The arguments weights, ssu and schema must have matching names. If the combination of raster surfaces does not overlap, wt_strata silently unions the surfaces and enables sampling in ALL weights rasters. See warn_union.

Examples

dummy <- dummy_data()
set.seed(123)

# Single-stage geoimputation
# Population-weighted sampling within PSUs
ssg <- wt_strata(dummy$survey, dummy$pop, psu = dummy$areas)

plot(
  ssg["place_type"],
  pch = 16,
  main = "Single-state geoimputation",
  extent = st_geometry(dummy$areas), # Forces the plot to fit the polygon size
  reset = FALSE
)
plot(dummy$areas, add = TRUE)


# Two-stage geoimputation
# Population- and survey-weighted sampling within PSUs
schema <- proto_schema(dummy$pop, dummy$survey$place_type)
tsg <- wt_strata(
  dummy$survey,
  dummy$pop,
  psu = dummy$areas,
  ssu = dummy$survey$place_type,
  schema = schema
)

plot(
  tsg["place_type"],
  pch = 16,
  main = "Two-state geoimputation",
  extent = st_geometry(dummy$areas), # Forces the plot to fit the polygon size
  reset = FALSE
)
plot(dummy$areas, add = TRUE)