Create a reusable profile that captures shared design defaults
for survey sample size and power calculations. A plan can be passed
to functions like n_prop(), n_mean(), power_prop(), or
n_cluster() either via the plan named argument or by piping:
Usage
svyplan(...)
# S3 method for class 'svyplan'
update(object, ...)Details
plan <- svyplan(deff = 1.8, resp_rate = 0.85, N = 50000)
# Named argument
n_prop(p = 0.3, moe = 0.05, plan = plan)
# Pipe
plan |> n_prop(0.3, moe = 0.05)
plan |> n_prop(p = 0.3, moe = 0.05)
plan |> n_cluster(cv = 0.05)The profile stores design parameters that are shared across multiple functions. Each default fills in only arguments not explicitly provided by the caller. Explicit arguments always take precedence:
plan <- svyplan(deff = 1.8, resp_rate = 0.85)
n_prop(p = 0.3, moe = 0.05, plan = plan) # uses plan defaults
n_prop(p = 0.3, moe = 0.05, plan = plan, deff = 2) # deff = 2 winsDefaults are applied only when their names match the called function's
formals. Irrelevant defaults are silently ignored. prop_method must
be "wald", "wilson", or "logodds" (validated at construction)
and also fills the method argument of n_prop(), prec_prop(), and
power_prop() when its value is valid for that function (so
svyplan(prop_method = "wilson") applies to n_prop() but is ignored
by power_prop(), which has no Wilson method).
All stored defaults are validated when the profile is created or updated.
When both stage_cost and delta are supplied, their lengths must describe
the same number of stages. Length checks that depend on call-specific data,
such as matching unit_cost to an allocation frame, occur when the plan is
used.
Estimand-specific values (p, var, mu, moe, cv, n, power,
effect) should be passed directly to each function, not stored in
the plan.
When piping, the plan is detected automatically. The function's
original first argument (e.g., p in n_prop()) can be passed
either positionally or by name.
Examples
# Create a plan with common design parameters
plan <- svyplan(deff = 1.8, resp_rate = 0.85, N = 50000)
# Use via named argument
n_prop(p = 0.3, moe = 0.05, plan = plan)
#> Sample size for proportion (wald)
#> n = 676 (net: 575) (p = 0.30, moe = 0.050, deff = 1.80, resp_rate = 0.85)
n_mean(var = 100, mu = 50, cv = 0.05, plan = plan)
#> Sample size for mean
#> n = 34 (net: 29) (var = 100.00, cv = 0.050, deff = 1.80, resp_rate = 0.85)
power_prop(p1 = 0.30, p2 = 0.35, plan = plan)
#> Power analysis for proportions (solved for sample size)
#> n = 2772 (net: 2356, per group), power = 0.800, effect = 0.0500
#> (p1 = 0.300, p2 = 0.350, alpha = 0.05, deff = 1.80, resp_rate = 0.85)
n_multi(data.frame(p = 0.05, moe = 0.02), plan = svyplan(prop_method = "wilson"))
#> Multi-indicator sample size
#> n = 469 (binding: 1)
#> ---
#> name .n .cv_target .cv_achieved .binding
#> 1 469 0.2040854 0.2040854 *
# Use via pipe
plan |> n_prop(0.3, moe = 0.05)
#> Sample size for proportion (wald)
#> n = 676 (net: 575) (p = 0.30, moe = 0.050, deff = 1.80, resp_rate = 0.85)
plan |> n_prop(p = 0.3, moe = 0.05)
#> Sample size for proportion (wald)
#> n = 676 (net: 575) (p = 0.30, moe = 0.050, deff = 1.80, resp_rate = 0.85)
plan |> n_mean(100, mu = 50, cv = 0.05)
#> Sample size for mean
#> n = 34 (net: 29) (var = 100.00, cv = 0.050, deff = 1.80, resp_rate = 0.85)
plan |> power_prop(0.30, p2 = 0.35)
#> Power analysis for proportions (solved for sample size)
#> n = 2772 (net: 2356, per group), power = 0.800, effect = 0.0500
#> (p1 = 0.300, p2 = 0.350, alpha = 0.05, deff = 1.80, resp_rate = 0.85)
# Cluster context
cl_plan <- svyplan(stage_cost = c(500, 50), delta = 0.05, resp_rate = 0.85)
cl_plan |> n_cluster(cv = 0.05)
#> Optimal 2-stage allocation
#> field design: n_psu = 58 | psu_size = 13 -> total n = 754 (net: 641)
#> cv = 0.0500, cost = 66700
#> continuous optimum: n_psu = 55.96247 | psu_size = 13.78405 (cv = 0.0500, cost = 66551)
# Override a plan default
n_prop(p = 0.3, moe = 0.05, plan = plan, deff = 2.0)
#> Sample size for proportion (wald)
#> n = 750 (net: 638) (p = 0.30, moe = 0.050, deff = 2.00, resp_rate = 0.85)