Multi-indicator sample size for cluster designs

Compute a two- or three-stage cluster allocation that satisfies precision requirements for several survey indicators. Domain-level planning and a shared budget across domains are supported.

Usage

n_multi_cluster(indicators, ...)

# Default S3 method
n_multi_cluster(
  indicators,
  ...,
  stage_cost = NULL,
  domains = NULL,
  budget = NULL,
  n_psu = NULL,
  n_per_psu = NULL,
  n_per_ssu = NULL,
  allocation = c("separate", "joint"),
  domain_sampling = c("separate", "natural"),
  min_n_domain = NULL,
  fixed_cost = 0,
  resp_rate_psu = 1,
  resp_rate_ssu = 1,
  resp_rate = 1,
  plan = NULL
)

# S3 method for class 'svyplan_prec'
n_multi_cluster(indicators, ...)

Arguments

indicators: For the default method, a non-empty data frame with one row per indicator. Each row requires p or var, a cv, moe, or rmoe target, and icc_psu. Three-stage designs also require icc_ssu. Optional var_ratio_psu defaults to 1; three-stage var_ratio_ssu is derived as var_ratio_psu * (1 - icc_psu) when absent, the value the variance decomposition implies (see design_effect()). For the svyplan_prec method, a result from prec_multi_cluster().
...: Additional arguments passed to methods. Unused arguments are rejected.
stage_cost: Numeric vector of per-stage costs with length 2 or 3.
domains: Optional character vector naming domain columns in indicators. The function solves each domain independently unless allocation = "joint" in budget mode. Domains are sized as separate quotas, so $total_n is their sum and $n carries no aggregate stage vector; the fieldable per-domain stage sizes are in $domains. domain_sampling = "natural" is refused here, because a domain's expected yield in a multistage design depends on how its members sit inside PSUs and SSUs rather than on its population share alone.
budget: Optional total budget. Supply precision indicators or a budget, according to the target schema described in Details.
n_psu: Optional fixed stage-1 sample size.
n_per_psu: Optional fixed stage-2 sample size per PSU.
n_per_ssu: Optional fixed stage-3 sample size per SSU. This is valid only for three-stage designs.
allocation: How a budget is split across domains, either "separate" (default, each domain sized on its own) or "joint" (one budget split across domains to minimize the worst precision ratio). "joint" applies only when domains and budget are supplied.
domain_sampling: How the per-domain requirements combine into one overall size. Only "separate" (the default) is available here, and $total_n is then the sum of the per-domain totals. "natural" is refused: a domain's expected yield in a multistage design depends on how its members sit inside PSUs and SSUs rather than on its share of the population alone, and that model is not in the package.
min_n_domain: Optional positive minimum total sample size per domain. In joint budget mode it is a constraint. In independent domain mode, domains below the floor produce a warning.
fixed_cost: Non-negative fixed overhead cost. The default is 0.
resp_rate_psu: Default expected PSU response rate, in (0, 1]. Used where the indicator column is absent or NA.
resp_rate_ssu: Default expected SSU response rate for a three-stage design, in (0, 1]. It is not applicable to a two-stage design.
resp_rate: Default expected ultimate-unit response rate, in (0, 1]. Non-missing indicator columns override these three defaults row by row.
plan: Optional svyplan() profile providing stage_cost and other applicable defaults.

Value

A svyplan_cluster object. The output class does not depend on which optional arguments are supplied.

Details

The indicator columns follow n_multi(), with one difference that matters. Nonresponse is named for the stage it acts on: resp_rate_psu for clusters that cannot be worked at all, resp_rate_ssu for second-stage units in a three-stage design, and resp_rate for the ultimate units. They are not interchangeable, and n_cluster() sets out why. A column naming a stage the design does not have is an error rather than a column carried along and ignored, since a silently dropped response rate plans a design with none.

Margin-of-error indicators are converted to CV before optimization. For each candidate allocation, the required stage-1 size is the maximum across all indicators. The solver minimizes total cost for precision indicators or the worst precision ratio under a fixed budget.

That conversion respects the row's prop_method. The multistage model is driven by a relative standard error, and only the Wald interval has half-width z * se, so a proportion row's moe is restated as the sampling CV at the effective sample size its own method needs to close the interval to that margin. A stricter interval therefore asks for a larger design, in the same order it does in n_prop(). Under "wald" the restatement is moe / (z * p) exactly. A mean row converts as moe / (z * |mu|), on the magnitude so that a negative mean yields a positive target. prec_multi_cluster() inverts the same way, so a design sized from a moe target reports that moe back.

Homogeneity values numerically close to 0 or 1 are rejected because they make the analytical cluster optimum degenerate. The result includes an integer $operational allocation that preserves the applicable precision or budget constraint. See n_multi() for shared indicator columns and n_cluster() for the cluster cost model.

How strong the optimum is

With a stage size fixed, the remaining problem is solved from the closed-form cluster optimum. With all stage sizes free, the objective is a maximum over indicator requirements, which is not smooth, and it is minimized by a bounded quasi-Newton search. That search warns when it fails to converge or lands on a bound, but it carries no global-optimality or KKT certificate: a successful return means the best design this search found, not a proven minimum-cost one. The $operational allocation can always be checked against its own precision or budget constraint, which is a separate and exact statement. n_alloc() gives the stronger guarantee where it applies, returning feasibility and KKT diagnostics for its convex continuous problem.

Examples

indicators <- data.frame(
  name = c("stunting", "anemia"),
  p = c(0.30, 0.10),
  cv = c(0.10, 0.15),
  icc_psu = c(0.02, 0.05)
)
n_multi_cluster(indicators, stage_cost = c(500, 50))
#> Multi-indicator optimal allocation (2-stage)
#> field design: n_psu = 52 | n_per_psu = 12 -> total n = 624
#> worst cv = 0.1495, cost = 57200 (binding: anemia)
#> continuous optimum: n_psu = 47.5681 | n_per_psu = 13.78405 (cv = 0.1500, cost = 56568)
#> 
#>  name     .n       .cv_target .cv_achieved .binding
#>  stunting 292.9922 0.10       0.0668               
#>  anemia   655.6810 0.15       0.1500       *