dual_frame_design: Dual-frame allocation with the area-frame cost taken from the...

In fieldopt: Area-Frame and Dual-Frame Survey Design under Real Field Cost

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

Description

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
)

fieldopt documentation built on Oct. 22, 2026, 1:07 a.m.