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,
  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().
...: 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).
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 var_ratio_ssu = var_ratio_psu * (1 - icc_psu) follows from the decomposition. See design_effect().
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, 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.
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 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(...)).

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.

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
res <- n_cluster(stage_cost = c(500, 50), icc = 0.05, cv = 0.05)
prec_cluster(res)
#> Sampling precision for 2-stage cluster
#> n_psu = 48 | n_per_psu = 14 -> total n = 672
#> cv = 0.0500

# 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