Grid exploration for svyplan objects

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). For svyplan_prec, only types "proportion" and "mean" are supported (not "cluster" or "multi").
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.
...: Additional arguments are not supported and produce an error.

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, rmoe, except for a type = "change" result, which reports one size per occasion as n1 and n2 in place of n
svyplan_cluster: n_psu, n_per_psu, (opt. n_per_ssu), total_n, cv, cost
svyplan_power: n, power, effect
svyplan_prec: se, moe, cv, rmoe

Details

Valid parameters for newdata by object type:

n_prop: p, moe, rmoe, cv, alpha, N, deff, resp_rate, df (method = "beta" only)
n_mean: var, mu, moe, rmoe, cv, alpha, N, deff, resp_rate
n_change: moe, rmoe, cv, alpha, N, deff, resp_rate, ratio, overlap, overlap_cor, and change on the mean scale only, since two proportions determine it. The occasion variances are held at the values the result was built from, so vary the design rather than the estimand: sweeping overlap and overlap_cor is what prices a rotation against a fresh sample each round.
n_pooled: moe, rmoe, cv, alpha, N, deff, resp_rate, mu on the mean scale, and occasions only where the overlap and correlation are flat across lags, a shaped profile being a statement about a horizon that changing the horizon would contradict. The lag profiles themselves cannot be varied, a grid row having nowhere to hold a vector.
n_cluster: cv, budget, unit_relvar, resp_rate, fixed_cost, stage deltas (icc or icc_psu, plus icc_ssu for 3-stage), stage ratios (var_ratio or var_ratio_psu, plus var_ratio_ssu for 3-stage), and stage costs (cost_psu, cost_ssu, cost_tsu). For 2-stage designs, cost_tsu aliases cost_ssu.
power_prop: p1, p2, n, power, alpha, N, deff, alternative, overlap, overlap_cor, 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, overlap_cor, resp_rate (excluding the solved-for parameter). Not supported for objects with vector n.
prec_prop: p, n, alpha, N, deff, resp_rate, df (method = "beta" only). A result that solved for p varies the target it solved from, cv or rmoe, in place of p.
prec_mean: var, n, mu, alpha, N, deff, resp_rate

For svyplan_n objects, moe, rmoe, and cv are mutually exclusive in newdata. If one appears, that mode is used. If none appears, 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.

A joint constrained allocation (n_alloc() with measures and targets) is supported only in fixed-budget objective mode, where newdata varies budget alone and the result is the cost-versus-objective frontier: n, continuous cost, objective_value and its equivalent cv, the operational n_int and cost_int, whether the budget binds, and .feasible. Budgets that cannot fund the hard targets give an all-NA row with .feasible = FALSE and a warning, so one infeasible point does not discard the rest of the frontier. In minimum-cost mode there is no scalar to vary; modify targets and call n_alloc() again.

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      rmoe
#> 1   1.0       0.7  460.9751 0.02551067 0.05 0.08503558 0.1666667
#> 2   1.5       0.7  691.4626 0.02551067 0.05 0.08503558 0.1666667
#> 3   2.0       0.7  921.9501 0.02551067 0.05 0.08503558 0.1666667
#> 4   2.5       0.7 1152.4376 0.02551067 0.05 0.08503558 0.1666667
#> 5   3.0       0.7 1382.9252 0.02551067 0.05 0.08503558 0.1666667
#> 6   1.0       0.8  403.3532 0.02551067 0.05 0.08503558 0.1666667
#> 7   1.5       0.8  605.0298 0.02551067 0.05 0.08503558 0.1666667
#> 8   2.0       0.8  806.7064 0.02551067 0.05 0.08503558 0.1666667
#> 9   2.5       0.8 1008.3829 0.02551067 0.05 0.08503558 0.1666667
#> 10  3.0       0.8 1210.0595 0.02551067 0.05 0.08503558 0.1666667
#> 11  1.0       0.9  358.5362 0.02551067 0.05 0.08503558 0.1666667
#> 12  1.5       0.9  537.8042 0.02551067 0.05 0.08503558 0.1666667
#> 13  2.0       0.9  717.0723 0.02551067 0.05 0.08503558 0.1666667
#> 14  2.5       0.9  896.3404 0.02551067 0.05 0.08503558 0.1666667
#> 15  3.0       0.9 1075.6085 0.02551067 0.05 0.08503558 0.1666667

# 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

# Cluster design: sensitivity to icc (homogeneity)
cl <- n_cluster(stage_cost = c(500, 50), icc = 0.05, budget = 100000)
predict(cl, data.frame(icc = c(0.01, 0.03, 0.05, 0.10, 0.15)))
#>    icc     n_psu n_per_psu   total_n         cv  cost
#> 1 0.01  48.23430 31.464265 1517.6570 0.02931966 1e+05
#> 2 0.03  71.47587 17.981472 1285.2413 0.03427016 1e+05
#> 3 0.05  84.08997 13.784049 1159.1003 0.03760588 1e+05
#> 4 0.10 102.63340  9.486833  973.6660 0.04357388 1e+05
#> 5 0.15 114.10493  7.527727  858.9507 0.04800166 1e+05

# Allocation: how does the CV change with sample size?
frame <- data.frame(
  N    = c(4000, 3000, 3000),
  sd   = c(10, 15, 8),
  mean = c(50, 60, 55)
)
alloc <- n_alloc(frame, n = 600)
predict(alloc, data.frame(n = seq(200, 1000, 200)))
#>      n        se       moe          cv cost
#> 1  200 0.7624828 1.4944388 0.013990510  200
#> 2  400 0.5332495 1.0451498 0.009784394  400
#> 3  600 0.4305191 0.8438019 0.007899432  600
#> 4  800 0.3685682 0.7223803 0.006762719  800
#> 5 1000 0.3257913 0.6385393 0.005977823 1000

Usage

Arguments

Value

Details

See also

Examples