Grid Exploration for svyplan Objects — predict.svyplan • svyplan

Evaluate a svyplan result at new parameter combinations. Returns a data frame with the varied parameters and resulting quantities, suitable for sensitivity analysis or plotting.

Usage

# S3 method for class 'svyplan_n'
predict(object, newdata, ...)

# S3 method for class 'svyplan_cluster'
predict(object, newdata, ...)

# S3 method for class 'svyplan_power'
predict(object, newdata, ...)

# S3 method for class 'svyplan_prec'
predict(object, newdata, ...)

Arguments

object: A svyplan object (svyplan_n, svyplan_cluster, svyplan_power, or svyplan_prec).
newdata: A data frame of parameter combinations to evaluate. Column names must be valid parameters for the object type (see Details). Parameters not in newdata stay at their original values from the object.
...: Ignored.

Value

A data frame with newdata columns followed by result columns. The result columns depend on the object type:

svyplan_n: n, se, moe, cv
svyplan_cluster: n_psu, psu_size, (opt. ssu_size), total_n, cv, cost
svyplan_power: n, power, effect
svyplan_prec: se, moe, cv

Details

Valid parameters for newdata by object type:

n_prop: p, moe, cv, alpha, N, deff, resp_rate
n_mean: var, mu, moe, cv, alpha, N, deff, resp_rate
n_cluster: cv, budget, rel_var, resp_rate, fixed_cost, stage deltas (delta or delta_psu; plus delta_ssu for 3-stage), stage ratios (k or k_psu; plus k_ssu for 3-stage), stage costs (cost_psu, cost_ssu, cost_tsu; for 2-stage, cost_tsu aliases cost_ssu)
power_prop: p1, p2, n, power, alpha, N, deff, alternative, overlap, rho, resp_rate (excluding the solved-for parameter). Not supported for objects with vector n.
power_mean: effect, var, n, power, alpha, N, deff, alternative, overlap, rho, resp_rate (excluding the solved-for parameter). Not supported for objects with vector n.
prec_prop: p, n, alpha, N, deff, resp_rate
prec_mean: var, n, mu, alpha, N, deff, resp_rate

For svyplan_n objects, moe and cv are mutually exclusive in newdata. If one appears, that mode is used; if neither, the original mode is preserved.

Similarly, for svyplan_cluster objects, cv and budget are mutually exclusive.

Multi-indicator (n_multi) and multi-indicator cluster results are not supported; use the underlying single-indicator functions instead.

If evaluation fails for a particular row (e.g. invalid parameter combinations), that row's result columns are NA and a warning is issued.

Examples

# Sensitivity of sample size to deff and response rate
x <- n_prop(p = 0.3, moe = 0.05, deff = 1.5)
predict(x, expand.grid(
  deff = seq(1, 3, 0.5),
  resp_rate = c(0.7, 0.8, 0.9)
))
#>    deff resp_rate         n         se  moe         cv
#> 1   1.0       0.7  460.9751 0.02551067 0.05 0.08503558
#> 2   1.5       0.7  691.4626 0.02551067 0.05 0.08503558
#> 3   2.0       0.7  921.9501 0.02551067 0.05 0.08503558
#> 4   2.5       0.7 1152.4376 0.02551067 0.05 0.08503558
#> 5   3.0       0.7 1382.9252 0.02551067 0.05 0.08503558
#> 6   1.0       0.8  403.3532 0.02551067 0.05 0.08503558
#> 7   1.5       0.8  605.0298 0.02551067 0.05 0.08503558
#> 8   2.0       0.8  806.7064 0.02551067 0.05 0.08503558
#> 9   2.5       0.8 1008.3829 0.02551067 0.05 0.08503558
#> 10  3.0       0.8 1210.0595 0.02551067 0.05 0.08503558
#> 11  1.0       0.9  358.5362 0.02551067 0.05 0.08503558
#> 12  1.5       0.9  537.8042 0.02551067 0.05 0.08503558
#> 13  2.0       0.9  717.0723 0.02551067 0.05 0.08503558
#> 14  2.5       0.9  896.3404 0.02551067 0.05 0.08503558
#> 15  3.0       0.9 1075.6085 0.02551067 0.05 0.08503558

# Power curve: how does power vary with sample size?
pw <- power_prop(p1 = 0.30, p2 = 0.35, n = 500, power = NULL)
predict(pw, data.frame(n = seq(100, 1000, 100)))
#>       n     power effect
#> 1   100 0.1175929   0.05
#> 2   200 0.1877131   0.05
#> 3   300 0.2581732   0.05
#> 4   400 0.3272968   0.05
#> 5   500 0.3938436   0.05
#> 6   600 0.4569385   0.05
#> 7   700 0.5160053   0.05
#> 8   800 0.5707088   0.05
#> 9   900 0.6209032   0.05
#> 10 1000 0.6665884   0.05