Survey Plan Profile

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, ...)

Arguments

...

Named defaults to reuse across calls. Allowed names: alpha, N, deff, resp_rate, prop_method, stage_cost, delta, rel_var, k, fixed_cost, unit_cost, alternative, method, ratio, overlap, rho, alloc, min_n, power_q.

object

A svyplan object to update.

Value

A svyplan 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 wins

Defaults are applied only when their names match the called function's formals. Irrelevant defaults are silently ignored.

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.

See also

n_prop(), n_mean(), n_cluster(), power_prop(), power_mean(), power_did().

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 = 679 (net: 578) (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  .binding
#>  1    469 *       

# Use via pipe
plan |> n_prop(0.3, moe = 0.05)
#> Sample size for proportion (wald)
#> n = 679 (net: 578) (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 = 679 (net: 578) (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
#> n_psu = 56 | psu_size = 14 -> total n = 784 (unrounded: 771.3894, net: 667)
#> 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 = 755 (net: 642) (p = 0.30, moe = 0.050, deff = 2.00, resp_rate = 0.85)