Sampling precision for a multistage cluster allocation

Compute the sampling error (SE, MOE, CV) for a given multistage sample allocation. This is the inverse of n_cluster().

Usage

prec_cluster(n = NULL, ...)

# Default S3 method
prec_cluster(
  n = NULL,
  ...,
  icc = NULL,
  unit_relvar = NULL,
  var_ratio = NULL,
  resp_rate_psu = 1,
  resp_rate_ssu = 1,
  resp_rate = 1,
  eligibility_rate = 1,
  eligible_per_unit = 1,
  fpc = c("none", "stage"),
  N = NULL,
  N_psu = NULL,
  N_ssu = NULL,
  indicators = NULL,
  domains = NULL,
  stage_cost = NULL,
  plan = NULL
)

# S3 method for class 'svyplan_cluster'
prec_cluster(n, ...)

Arguments

n: For the default method: numeric vector of per-stage sample sizes (c(n_psu, n_per_psu) for 2-stage or c(n_psu, n_per_psu, n_per_ssu) for 3-stage). Named vectors are accepted with stage names n_psu, n_per_psu, n_per_ssu. For svyplan_cluster objects: a cluster allocation from n_cluster(), evaluated at its continuous optimum $n.
...: Additional arguments passed to methods. Unused arguments are rejected.
icc: Numeric vector of homogeneity measures (length = stages - 1), or a svyplan_varcomp object.
unit_relvar: Unit relvariance, default 1. A proportion p has (1 - p) / p, so the default reports a proportion's cv as if p = 0.5. Required beside a svyplan_varcomp backed out of a design effect, which identifies none, and refused beside one estimated from data, which sets it. See n_cluster().
var_ratio: Ratio of the stage components' unit variance to the analysis variable's, default 1. A scalar names var_ratio_psu, and for three stages derives var_ratio_ssu = var_ratio_psu * (1 - icc_psu), the value for SSUs of equal size or drawn proportional to size. See design_effect(). Refused when icc is a svyplan_varcomp, which sets it.
resp_rate_psu: Expected PSU-level response rate, in (0, 1]. Default 1 (no adjustment). The effective stage-1 size is n * resp_rate_psu. It describes clusters that cannot be worked, not nonresponse among the ultimate units inside a cluster.
resp_rate_ssu: Expected SSU-level response rate, in (0, 1]. Three-stage designs only, default 1. The effective stage-2 size is n[2] * resp_rate_ssu.
resp_rate: Expected ultimate-unit response rate among eligible units, in (0, 1]. Default 1. It scales the final stage, so it also shrinks the realized cluster and therefore the clustering penalty. See n_cluster() for the decomposition. See the nonresponse section of svyplan-package for what the rate counts.
eligibility_rate: Share of issued final-stage units in scope, in (0, 1]. Default 1. It acts at the final stage, as resp_rate does, and with indicators it applies to every row. See the nonresponse section of svyplan-package.
eligible_per_unit: Eligible units per final-stage unit, a positive number, default 1. It multiplies resp_rate in the realized take, and n stays in final-stage units. Not available with indicators. See n_cluster().
fpc: Which finite population correction the variance carries. "none" (default) drops every sampling fraction. "stage" corrects each component by its own stage's sampling fraction and needs N and N_psu, and N_ssu at three stages. See "Finite populations" in n_cluster().
N: Number of final-stage units in the population, the units the sizes count. With eligibility_rate or eligible_per_unit the correction reads N * eligibility_rate * eligible_per_unit eligible units. Read only with fpc = "stage" and refused otherwise.
N_psu: Number of PSUs in the population. Read only with fpc = "stage" and refused otherwise.
N_ssu: Number of SSUs in the population, across all PSUs. Read only with fpc = "stage" at three stages and refused otherwise.
indicators: Optional data frame with one row per indicator, which switches the function to the several-indicators mode of Details. It carries the stage sizes per row in n and n_per_psu, plus n_per_ssu for a three-stage design, so n is left NULL.
domains: Optional character vector naming domain columns in indicators. Precision is computed row by row either way, so naming domains leaves every $detail value unchanged. What it does is put the domain columns first in $detail and record the domain structure on the result, so that a round trip back to n_cluster() rebuilds the same design. There is no domain_sampling argument here, because that choice governs how per-domain requirements combine into one size, and this direction reads the sizes you already have.
stage_cost: Optional per-stage costs, recorded on the result so that a later round trip to n_cluster() can re-solve the design. Costs do not enter the precision calculation.
plan: Optional svyplan() object providing design defaults. In the several-indicators mode a profile supplies only the defaults that mode accepts, so icc, unit_relvar and var_ratio are left to the indicator columns.

Value

A svyplan_prec object with components $se, $moe, and $cv. Because the cluster model is parameterized with unit relvariance (unit_relvar = S^2 / Y_bar^2), only $cv is computable. The $se and $moe components are NA.

With indicators, per-indicator precision is in $detail: .se, .moe, .rmoe and .cv. All four are reported whatever target the design was sized against, since the achieved precision does not depend on how the requirement was written. .rmoe is measured against the row's own estimand, p for a proportion, abs(mu) for a mean and abs(r) for a ratio.

Details

prec_cluster() is the inverse of n_cluster(): given per-stage sample sizes, it computes the achieved precision. You can pass the result of n_cluster() directly: prec_cluster(n_cluster(...)). A fit is evaluated at its continuous optimum, so the round trip returns the fit's cv exactly, and the print labels the sizes as that optimum. The whole design the fit fields is $operational$n, and passing it as n with the fit's other inputs gives its precision. Fractional sizes are printed as given.

Stage count is determined by length(n).

2-stage (Valliant et al., 2018, Eq. 9.2.23): $$CV = \sqrt{\frac{V \cdot k}{n_1 \cdot n_2} (1 + \delta (n_2 - 1))}$$

3-stage: $$CV = \sqrt{\frac{V}{n_1 \cdot n_2 \cdot n_3} (k_1 \delta_1 n_2 n_3 + k_2 (1 + \delta_2 (n_3 - 1)))}$$

Several indicators at once

indicators reads the precision of several indicators under one allocation. It is a data frame with one row per indicator, carrying n and n_per_psu, plus n_per_ssu for a three-stage design. The homogeneity and indicator columns follow the schema n_cluster() documents, including the derived three-stage var_ratio_ssu. The scalar arguments n, icc, unit_relvar and var_ratio are refused in this mode, because the frame carries each of them per row.

resp_rate_psu, resp_rate_ssu and resp_rate are the defaults used where a row's own column is absent or NA, as they are in n_cluster(). Precision is computed row by row, so an allocation returned by n_cluster(indicators = ) can be passed straight in.

Finite populations

These formulas drop every sampling fraction, so a sample that takes most of a small domain's PSUs is assessed as if they were a few among many. With fpc = "stage", N and N_psu, and N_ssu at three stages, a design is assessed with each component corrected by its own stage, which is exact for PSUs and SSUs of equal size drawn with equal probability. With indicators the arguments give the one population every row is measured on, and with domains each domain's counts are indicators columns of the same names. See "Finite populations" in n_cluster().

References

Valliant, R., Dever, J. A., and Kreuter, F. (2018). Practical Tools for Designing and Weighting Survey Samples (2nd ed.). Springer. Ch. 9.

Examples

# Direct usage
prec_cluster(n = c(50, 12), icc = 0.05)
#> Sampling precision for 2-stage cluster
#> n_psu = 50 | n_per_psu = 12 -> total n = 600
#> cv = 0.0508
prec_cluster(n = c(50, 12, 8), icc = c(0.01, 0.05))
#> Sampling precision for 3-stage cluster
#> n_psu = 50 | n_per_psu = 12 | n_per_ssu = 8 -> total n = 4800
#> cv = 0.0219

# Round-trip from n_cluster, at the continuous optimum and at the whole
# design it fields
res <- n_cluster(stage_cost = c(500, 50), icc = 0.05, cv = 0.05)
prec_cluster(res)
#> Sampling precision for 2-stage cluster (continuous optimum)
#> n_psu = 47.5681 | n_per_psu = 13.78405 -> total n = 655.681
#> cv = 0.0500
prec_cluster(n = res$operational$n, icc = 0.05)
#> Sampling precision for 2-stage cluster
#> n_psu = 52 | n_per_psu = 12 -> total n = 624
#> cv = 0.0498

# 12 of an island's 16 enumeration areas, 20 of about 150 households each
prec_cluster(n = c(12, 20), icc = 0.05)
#> Sampling precision for 2-stage cluster
#> n_psu = 12 | n_per_psu = 20 -> total n = 240
#> cv = 0.0901
prec_cluster(n = c(12, 20), icc = 0.05, fpc = "stage",
             N = 2400, N_psu = 16)
#> Sampling precision for 2-stage cluster
#> n_psu = 12 | n_per_psu = 20 -> total n = 240
#> corrected by stage for N_psu = 16 PSUs of N = 2400 units
#> cv = 0.0669

# 30 of 40 villages, 4 of 10 hamlets each, 8 of 30 households each
prec_cluster(n = c(30, 4, 8), icc = c(0.04, 0.10), fpc = "stage",
             N = 12000, N_psu = 40, N_ssu = 400)
#> Sampling precision for 3-stage cluster
#> n_psu = 30 | n_per_psu = 4 | n_per_ssu = 8 -> total n = 960
#> corrected by stage for N_psu = 40 PSUs, N_ssu = 400 SSUs of N = 12000 units
#> cv = 0.0384

# 600 clusters of 20 households, 0.41 married women per household, for a
# proportion near 0.28
prec_cluster(n = c(600, 20), icc = 0.07, unit_relvar = 0.72 / 0.28,
             resp_rate = 0.9, eligible_per_unit = 0.41)
#> Sampling precision for 2-stage cluster
#> n_psu = 600 | n_per_psu = 20 -> total n = 12000 (eligible respondents: 4428, eligible_per_unit = 0.41)
#> cv = 0.0290

# Several indicators under one allocation
indicators <- data.frame(
  name      = c("stunting", "anemia"),
  p         = c(0.30, 0.10),
  n         = c(60, 60),
  n_per_psu = c(12, 12),
  icc_psu   = c(0.02, 0.05)
)
prec_cluster(indicators = indicators)
#> Multi-indicator sampling precision
#> 
#>  name     .se        .moe       .rmoe     .cv       
#>  stunting 0.01886355 0.03697187 0.1232396 0.06287848
#>  anemia   0.01391941 0.02728154 0.2728154 0.13919411