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, icc, unit_relvar, var_ratio, fixed_cost, unit_cost, alternative, ratio, overlap, overlap_cor, alloc, min_n_stratum, min_n_domain, alloc_q, phase1_cost.

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. prop_method must be "wald", "wilson", "logodds", or "beta" (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 icc 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. unit_cost is ordered by allocation-frame row, whereas strata_bound() orders costs from the lowest to the highest stratum, so only a scalar unit_cost reaches that function from a profile; a vector one is rejected there rather than applied to the wrong strata.

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 = 676 gross (net: 575) (p = 0.30, moe = 0.050, deff = 1.80, resp_rate = 0.85)
#> expected cases = 172.3
n_mean(var = 100, mu = 50, cv = 0.05, plan = plan)
#> Sample size for mean
#> n = 34 gross (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.2014559  0.2014559    *       

# Use via pipe
plan |> n_prop(0.3, moe = 0.05)
#> Sample size for proportion (wald)
#> n = 676 gross (net: 575) (p = 0.30, moe = 0.050, deff = 1.80, resp_rate = 0.85)
#> expected cases = 172.3
plan |> n_prop(p = 0.3, moe = 0.05)
#> Sample size for proportion (wald)
#> n = 676 gross (net: 575) (p = 0.30, moe = 0.050, deff = 1.80, resp_rate = 0.85)
#> expected cases = 172.3
plan |> n_mean(100, mu = 50, cv = 0.05)
#> Sample size for mean
#> n = 34 gross (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), icc = 0.05, resp_rate = 0.85)
cl_plan |> n_cluster(cv = 0.05)
#> Optimal 2-stage allocation
#> field design: n_psu = 52 | n_per_psu = 14 -> total n = 728 (net: 619)
#> (resp_rate = 0.85)
#> cv = 0.0500, cost = 62400
#> continuous optimum: n_psu = 49.9018 | n_per_psu = 14.9509 (cv = 0.0500, cost = 62255)
#> design df = 51

# Override a plan default
n_prop(p = 0.3, moe = 0.05, plan = plan, deff = 2.0)
#> Sample size for proportion (wald)
#> n = 750 gross (net: 638) (p = 0.30, moe = 0.050, deff = 2.00, resp_rate = 0.85)
#> expected cases = 191.1