Dual-frame allocation with the area-frame cost taken from the routing

dual_frame_allocation() needs the cost per unit of the area frame, which is not a constant: the routed cost G(n_a) of visiting n_a area units grows like c0 + a n_a + b sqrt(n_a). As two_stage_design(), this function measures that curve by routing samples at a few sizes, fits it, and re-allocates with the marginal cost G'(n_a) as cost_a, which sets the split between the frames and theta; under a budget the sample sizes then come from the fitted curve, keeping that split, so the design spends the budget at its real routed cost. The cost model prices the area units (visits, interviews and travel); cost_b is the list cost per unit.

Usage

dual_frame_design(
  frame,
  depot,
  cost_model,
  domains,
  cost_b,
  deff_a = 1,
  deff_b = 1,
  theta = NULL,
  target_variance = NULL,
  target_cv = NULL,
  budget = NULL,
  interviews_per_unit = NULL,
  cost_a_start = NULL,
  max_iter = 8,
  size = NULL,
  strata = NULL,
  selection = c("lpm", "systematic", "srs"),
  matrix = NULL,
  method = c("haversine", "euclidean", "osrm"),
  max_length = Inf,
  max_stops = Inf,
  n_rep = 5,
  iterations = 100,
  seed = 1
)

Arguments

frame: Data frame of units as in select_units(), including the depot row named in depot.
depot: Name of the depot unit in frame$unit.
cost_model: A field_cost_model().
domains: Data frame with one row per domain a, ab, b (column domain) and columns size (units), mean and sd (standard deviation with divisor size - 1) of the study variable.
cost_b: Cost per sampled unit of the list frame.
deff_a, deff_b: Design effects of the two samples relative to simple random sampling (an area sample of segments or points usually has deff_a > 1).
theta: NULL to optimise, a number in [0, 1], or "screening" (zero).
target_variance, target_cv, budget: Exactly one: target variance of the estimated total, target coefficient of variation (relative to the population total implied by domains), or budget.
interviews_per_unit: Expected interviews per visited area unit (for the cost model; the model's own value is used when NULL).
cost_a_start: Starting value of the cost per area unit.
max_iter: Maximum number of rounds.
size: Optional size column for probability-proportional-to-size selection.
strata: Optional stratum column, passed to select_units().
selection: Selection method of select_units(): "lpm", "systematic" or "srs".
matrix: Optional travel_matrix() of the frame (computed from the coordinates otherwise).
method: Distance method of travel_matrix() when matrix is NULL ("osrm" queries the road network once for the whole frame).
max_length, max_stops: Route limits passed to route_fieldwork().
n_rep: Routed samples per sample size of the cost curve.
iterations: GRASP iterations per routing.
seed: Seed.

Value

The final fieldopt_dual_frame allocation, with cost the routed cost G(n_a) + cost_b n_b, cost_a the marginal cost used, cost_a_average (G(n_a)/n_a), cost_curve, cost_coef, history (one row per round: round, cost_a, cost_a_average, n_a, n_b, theta, cost, variance) and converged.

Examples

set.seed(3)
cells <- expand.grid(x = 1:12, y = 1:12)
cells$unit <- paste0("c", seq_len(nrow(cells)))
frame <- rbind(data.frame(unit = "depot", x = 6, y = 6), cells)
model <- field_cost_model(
  per_travel = 3, per_unit = 40, per_interview = 20,
  interviews_per_unit = 3
)
domains <- data.frame(
  domain = c("a", "ab", "b"), size = c(400, 60, 20),
  mean = c(6, 30, 45), sd = c(5, 20, 35)
)
dual_frame_design(frame, "depot", model, domains,
  cost_b = 45, deff_a = 1.5,
  target_cv = 0.05, method = "euclidean", n_rep = 1, iterations = 10
)
#> 
#> ── Dual-frame allocation ───────────────────────────────────────────────────────
#> Minimum cost for target variance 65020: n_A = 91 (frame A, cost 102.1/unit),
#> n_B = 80 (frame B, cost 45/unit), theta = 0.103 (optimised).
#> Cost 13020; variance 65020 (frame A 65000, frame B 0); CV 5% of the total 5100.
#> Expected overlap units: 11.9 in the A sample, 60 in the B sample; a bound on a
#> sample size was active.