Precision for a constrained allocation

Compute aggregate precision for a stratum allocation. For a joint constrained allocation, return one achieved-precision row per target and separate stratum-bound diagnostics.

Usage

prec_alloc(frame, ...)

# Default S3 method
prec_alloc(
  frame,
  n = NULL,
  ...,
  measures = NULL,
  targets = NULL,
  psu = NULL,
  certainty_cutoff = NULL,
  n_psu_per_zone = NULL,
  objective = NULL,
  budget = NULL,
  domains = NULL,
  alpha = 0.05,
  deff = 1,
  resp_rate = 1,
  df = NULL,
  unit_cost = NULL,
  min_n_stratum = NULL,
  fpc = c("unit", "stage", "none"),
  plan = NULL
)

# S3 method for class 'svyplan_n'
prec_alloc(frame, ...)

Arguments

frame: For the default method: a stratum-level data frame in the same format as the frame argument to n_alloc() (one row per stratum, with at least N and sd or var columns). See n_alloc() for the full column reference). For svyplan_n objects: an allocation result from n_alloc().
...: Additional arguments passed to methods. Unused arguments are rejected. For an allocation result, named arguments override the fitted values, and n_per_psu sets the take per PSU of a cluster allocation, one value or one per stratum. See "Evaluating a cluster field design".
n: Stratum sample sizes, length nrow(frame). In a cluster allocation these count ultimate units, fielded at the take in the frame's n_per_psu column, or at the continuous cost-optimal take when the frame has none. For a fitted joint allocation, omission uses its continuous allocation. Pass $detail$n_int to assess the operational recommendation. A named vector is matched to frame$stratum, an unnamed vector is positional. In fixed-take multistage mode these are ultimate-unit sizes. Explicit adopted sizes must correspond to whole PSU counts. Omission from a fitted result retains its continuous first-stage allocation.
measures: Optional long indicator table for joint assessment. See the measures argument to n_alloc(). It must be supplied with targets in the default method and is recovered automatically from a fitted result.
targets: Optional long precision-requirement table for joint assessment. See the targets argument to n_alloc(). It must be supplied with measures in the default method and is recovered automatically from a fitted result.
psu: Optional PSU register for certainty-aware assessment. See the psu argument to n_alloc(). A budget is refused with it, and an objective is reported as a description of the assessed allocation. No loop is needed here, since the allocation is supplied, so the threshold it implies is supplied with it and the classification is read off the design being assessed. The $psu table carries the same columns as a fitted plan's, with n_take read off the supplied allocation. A fitted result carries its own register and its held classification, so prec_alloc(fit) reproduces the plan's precision exactly.
certainty_cutoff: Inclusion probability at which a PSU is taken with certainty. See the certainty_cutoff argument to n_alloc(). A fitted result carries its own.
n_psu_per_zone: NULL, 1 or 2, PSUs drawn per zone of the remainder. See the n_psu_per_zone argument to n_alloc(). A fitted result carries its own.
objective: Optional objective components to report alongside the targets. See the objective argument to n_alloc(). Recovered automatically from a fitted budget-objective result.
budget: Optional budget, used only to report the residual against the assessed allocation's cost. Requires objective.
domains: Character vector of column names in frame to treat as domain identifiers, or NULL (default) for no domains.
alpha: Significance level, default 0.05.
deff: Design effect multiplier (> 0). A scalar applies to every stratum. A length-nrow(frame) vector gives one per stratum and overrides a deff column in frame.
resp_rate: Expected response rate, in (0, 1]. Default 1. A scalar applies to every stratum. A length-nrow(frame) vector gives one per stratum and overrides a resp_rate column in frame.
df: Degrees of freedom of the variance estimator the allocation will have, typically sampled PSUs minus strata, and available from design_df(). It switches the quantile used to translate a moe target in and to report moe out. A cv target carries no quantile and is unaffected. NULL (default) applies no adjustment.
unit_cost: Optional scalar or length-nrow(frame) vector of per-stratum unit costs, overriding frame$unit_cost. Fixed-take multistage joint assessment instead uses the stage costs stored in frame.
min_n_stratum: Optional minimum sample size per stratum, applied as the lower bound the assessment reports against in $bounds. It is the same argument n_alloc() takes, so a design and its assessment can be held to one floor. Joint assessment only: supplying it without measures and targets is an error.
fpc: Which finite population correction the variance carries in cluster allocation: "unit" (default) for the ultimate-unit 1 - n / N on the whole inflated variance, "stage" for the stage-by-stage correction, exact under the equal-size, equal-take variance-component model this path assumes, or "none" for n_cluster()'s with-replacement model. "stage" requires N_psu, and N_ssu as well at three stages. Refused outside cluster allocation and with a psu register. See the correction section in Details.
plan: Optional svyplan() object providing design defaults.

Value

A svyplan_prec object with type = "alloc". Top-level se, moe, and cv describe the whole population. $detail carries the stratum table documented in n_alloc(), including per-stratum .se, .moe, .rmoe, .cv, and the variance .share. When domains is given, $domains reports .n, .se, .moe, .rmoe, .cv, and .cost per domain, the same table n_alloc() returns, so a design and its assessment can be compared row for row.

For joint assessment, $detail is the constraint dictionary described in n_alloc(): target and achieved precision, ratio/residual/tolerance, pass/binding flags, and (when available) multiplier/sensitivity columns. $bounds reports ultimate-unit n, lower/upper limits, each violation flag, and .pass by stratum. $params$achieved$cost is variable field cost under the supplied allocation. When the fitted object carries an objective, $objective and $objective_value report its components and weighted value under the assessed allocation.

With psu, $psu carries the per-PSU table described in n_alloc(), classified at the supplied allocation.

Passing a joint precision result back to n_alloc() round trips the design. Minimum-cost results invert through precision, pinning the achieved values as the requirement. Budget-objective results invert through cost instead. The targets stay as specified and the assessed allocation's cost becomes the budget, because pinning achieved precision as hard targets would over-constrain a design that already spends its whole budget.

A result assessed with a psu register carries the register, the caller's frame and measures, and any certainty_cutoff, so the round trip plans the register design again. It derives the classification afresh from the register the fit was solved from, so where the fit's loop cycled the new plan can resolve the cycle at another member.

Details

Evaluating a cluster field design

The take is part of a cluster design. Whole-unit counts evaluated at the continuous take imply a fractional number of PSUs, which no field design has. $operational on an n_alloc() result already reports the precision of its whole-unit design. The same design, or a variation of it, is evaluated here by supplying both stage sizes:

prec_alloc(fit, n = fit$detail$n_int, n_per_psu = fit$detail$n_per_psu_int)

which reproduces fit$operational$cv. n_per_psu does not apply to an allocation built on a PSU register, whose takes come from the register.

Examples

frame <- data.frame(
  N    = c(4000, 3000, 3000),
  sd   = c(10, 15, 8),
  mean = c(50, 60, 55)
)
res <- n_alloc(frame, n = 600)
prec_alloc(res)
#> Sampling precision for alloc
#> n = 600 (3 strata)
#> se = 0.4305, moe = 0.8438, cv = 0.0079, rmoe = 0.0155

# Direct joint assessment (the allocation is in ultimate-unit units)
jf <- data.frame(
  stratum = c("A", "B"), region = c("North", "South"),
  N = c(1000, 1500), unit_cost = c(1, 1.2)
)
jm <- data.frame(
  stratum = rep(jf$stratum, 2),
  name = rep(c("coverage", "income"), each = 2),
  p = c(0.4, 0.6, NA, NA),
  mean = c(NA, NA, 50, 55),
  sd = c(NA, NA, 10, 12)
)
jt <- data.frame(
  name = c("coverage", "income"),
  cv = c(0.10, NA), moe = c(NA, 2.5)
)
prec_alloc(jf, n = c(120, 150), measures = jm, targets = jt)
#> Joint allocation precision (2 constraints)
#> targets: all pass