Schemas for secondary sampling — ssu

Creates schemas for secondary sampling in wt_strata. Schemas provide ways to "translate" between weights rasters and auxiliary survey data. Example: When a survey respondent states they live in a small town, what population values does this correspond to?

Usage

ssu_schema(
  ...,
  type = "fixed",
  closure = "left",
  adj_threshold = FALSE,
  void_threshold = FALSE,
  warn_reorder = TRUE,
  default_sd = NULL,
  cv = 0.2,
  kernel = kernel_bisquare,
  dist_scale = "log",
  decay = 1,
  normalize_decay = TRUE
)

# S3 method for class 'ssu_schema'
plot(x, ...)

Arguments

...

For future extension, not currently used.

type

Type of schema. Must be one of fixed, fuzzy, ideal, or relative. See Details. Defaults to fixed. The following parameters must be provided with each group in ...:

fixed: A lower and upper threshold, or a single value for categorical matching (equivalent to setting lower and upper to the same value)
fuzzy: A mean (optionally, a standard deviation)
ideal An ideal value (optionally, a decay value that overwrites decay)
relative: A lower and upper threshold specified as a proportion (0 to 1)

closure

If type is "fixed", a character string specifying whether threshold intervals are closed on the left or the right. Can be "left" (default) or "right". Interval closures are relevant when a cell is tied between two thresholds in wt_strata. This argument can become important when working with integers where ties can occur.

adj_threshold

If type is "fixed" or "fuzzy", whether to allow second-stage sampling to automatically adjust the selected schema group if no SSUs can be selected. If TRUE and no values in weights fit the threshold, the threshold is dynamically adjusted upwards and downwards until sampling is possible.

Adjustment successively checks whether the neighboring schema groups produce a valid threshold until all indices are consumed. If no valid threshold can be found, either aborts or sets the threshold range to c(-Inf, Inf) if void_threshold = TRUE.

For example, the selected threshold could be a high population density in a sparsely populated PSU. In this case, no cell or polygon could be selected. By default, this would result in an error. If schema adjustment is allowed, the schema index would be adjusted downwards until sampling is possible.

void_threshold

If type is "fixed" or "fuzzy", whether to allow second-stage sampling to sample locations anywhere and effectively void the threshold if threshold adjustment is not successful. If FALSE, signals an error in this case. Setting this to TRUE maximizes the error tolerance of the algorithm but eliminates weighting for affected locations. If the schema covers the entire range of values in weights, this argument should do nothing. Ignored if adj_threshold is FALSE. Consider this argument a nuclear option, if threshold adjustment is not sufficient.

warn_reorder

If type is "fuzzy", thresholds can sometimes be invalid when standard deviations are too wide and distributions overlap each other. In such cases, benchmarks of a higher group can be smaller than those of lower groups. The algorithm sorts all benchmarks such that thresholds are strictly ascending. This behavior should not be a problem if the overlap of distributions is small. However, if the overlap is large, sorting can lead to unexpected results. If warn_reorder is TRUE (default), the geoimpuation algorithm a warning if sorting is necessary.

default_sd

If type is "fuzzy", specifies a default standard deviation. Defaults to NULL, in which case the standard deviation is derived from cv or specified directly in ....

cv

If type is "fuzzy", specifies a coefficient of variation to compute a fallback standard deviation. Defaults to 0.2. This value is multiplied with the mean to estimate a reasonable standard deviation.

kernel

If type is "ideal", a kernel function that describes the decay around an ideal value. The function needs to accept exactly one argument (a distance vector). Distances are scaled according to the dist_scale argument.

dist_scale

If type is "ideal", a character string describing the kind of scaling to apply to distances before entering the kernel function. Must be one of "absolute" (unscaled), "log" (log difference), or "relative" (proportional difference). Defaults to "log".

decay

If type is "ideal", specifies the default rate of decay from the ideal benchmark. Higher values indicate a higher decay. Note that values around 1 are only sensible for log or relative scales. The optional decay specified in ... overwrites this argument. If dist_scale is "absolute", consider normalizing the decay rate by setting normalize_decay to TRUE. Defaults to 1.

normalize_decay

If type is "ideal" and dist_scale is "absolute", the decay parameter must correspond to the scale of the data. If normalize_decay is TRUE, normalizes the decay parameter based on the mean of the differences of the schema benchmarks. Ignored if dist_scale is "log" or "relative". Defaults to TRUE.

x

An object of class ssu_schema.

Value

An SSU schema, i.e. a named list containing thresholds or benchmarks for each name.

Details

Schemas distinguish thresholds and benchmarks. Thresholds are intervals in which points are allowed to be sampled. Benchmarks are "optimal" points around which points are allowed to be sampled, e.g. through a kernel function or statistical distribution.

There are five kinds of schema types:

fixed: Fixed schemas define "hard" thresholds that are known in advance and do not change during sampling. For each group, a lower and an upper boundary need to be provided. If the weights dataset is categorical, a single value can be provided alternatively.
fuzzy: Fuzzy schemas define benchmarks that are used to sample fixed thresholds from a normal distribution for each PSU. In other words, thresholds are not fixed for all PSUs but change to a certain degree and can account for threshold uncertainty. For each group, a mean and standard deviation need to be provided.
ideal: Ideal schemas define prototypical benchmarks that are used to weight raster cells according to their proximity to these ideals using a kernel function. You may want to use ideal schemas, if you believe each group has an ideal value and cells should be weighted by how similar they are to this prototype. For each group, an ideal value needs to be provided.
relative: Relative schemas define variable thresholds that are specified as percentiles of the population in each PSU. The exact thresholds are recomputed for each PSU. You may want to use relative schemas if PSUs are structurally different and you need to account for local contexts. For each group, a lower and upper probability need to be provided.

Examples

# two types of schemas
# 1. threshold-based schemas require ranges of values
ssu_schema(
  village = c(0, 200),
  town = c(200, 500),
  city = c(500, Inf),
  type = "fixed"
)
#> SSU schema using fixed thresholds
#> Points are only sampled within these thresholds.
#> 
#> village = [0, 200)
#> town    = [200, 500)
#> city    = [500, Inf] 

# 2. benchmark-based schemas require "prototypical" midpoints
ssu_schema(
  village = 100,
  town = 350,
  city = 750,
  type = "ideal"
)
#> SSU schema using ideal benchmarks
#> Points are sampled based on distance to these benchmarks.
#> 
#> village = 100 (λ = 1)
#> town    = 350 (λ = 1)
#> city    = 750 (λ = 1) 

ssu_schema(
  village = c(mean = 100, sd = 100),
  town = c(mean = 400, sd = 400),
  city = c(mean = 1000, sd = 1000),
  type = "fuzzy"
)
#> SSU schema using fuzzy thresholds
#> Points are sampled within thresholds around these distributions.
#> 
#> village ~ N(mean = 100, sd = 100)
#> town    ~ N(mean = 400, sd = 400)
#> city    ~ N(mean = 1000, sd = 1000) 

# relative schemas specify probabilities and cannot exceed [0, 1]
ssu_schema(
  village = c(0, 0.33),
  town = c(0.33, 0.66),
  city = c(0.66, 1),
  type = "relative"
)
#> SSU schema using relative thresholds
#> Points are sampled within these quantiles of the respective sampling unit.
#> 
#> village = Q[0, 0.33]
#> town    = Q[0.33, 0.66]
#> city    = Q[0.66, 1] 

# thresholds or benchmarks can be provided as arguments or as a list
schema_list <- list(
  village = c(0, 200),
  town = c(200, 500),
  city = c(500, Inf)
)
ssu_schema(schema_list)
#> SSU schema using fixed thresholds
#> Points are only sampled within these thresholds.
#> 
#> village = [0, 200)
#> town    = [200, 500)
#> city    = [500, Inf]