Skip to contents

Precision for a constrained allocation

Source: R/n_alloc.R
prec_alloc.Rd

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,
  objective = NULL,
  budget = NULL,
  domains = NULL,
  alpha = 0.05,
  deff = 1,
  resp_rate = 1,
  df = NULL,
  unit_cost = NULL,
  min_n_stratum = NULL,
  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.

n

Stratum sample sizes, length nrow(frame). 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.

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.

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.

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.

See also

n_alloc().

Other precision functions: prec_change(), prec_cluster(), prec_mean(), prec_multi(), prec_multi_cluster(), prec_panel(), prec_pooled(), prec_prop(), prec_twophase()

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