Precision of a stratified allocation

Compute the precision of a stratum allocation, over the whole population and by domain. The allocation is either an n_alloc() result or any stratum sample sizes given as n, such as the previous round's published 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,
  eligibility_rate = 1,
  eligible_per_unit = 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 one of sd, var or p). 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. A frame n_step does not constrain n here, so an allocation made without steps can be assessed on the same 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.
psu: Optional PSU register for certainty-aware assessment. See the psu argument to n_alloc(). An objective is reported as a description of the assessed allocation, and the residual against a budget counts the certainty visits. 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 field design, so prec_alloc(fit) reports the precision the plan was sized for, and an override such as n is assessed with the fit's classification held.
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. alpha = 2 * pnorm(-2) gives the multiplier of 2 that the DHS and MICS manuals use in place of 1.96.
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. A published DEFT is squared first, and the allocation already carries its own weighting loss. See varcomp().
resp_rate: Expected response rate among eligible units, 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. See the nonresponse section of svyplan-package for what the rate counts.
eligibility_rate: Share of issued units in scope, such as dwellings found occupied, in (0, 1]. Default 1. A scalar applies to every stratum. A length-nrow(frame) vector gives one per stratum and overrides an eligibility_rate column in frame. In joint allocation it is a scalar, a frame column or a measures column. Strata are weighted by their population in scope, N * eligibility_rate, while the bounds on the sample stay in frame units. With a PSU register it is a scalar or a frame column, one rate per stratum. See the nonresponse section of svyplan-package.
eligible_per_unit: Eligible units per sampled unit in joint assessment. See the eligible_per_unit argument to n_alloc(). A fitted result carries its own.
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, one value or one per stratum, 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: "unit" (default) for the ultimate-unit 1 - n / N, on the whole inflated variance in cluster allocation, "stage" for the stage-by-stage correction, exact under the equal-size, equal-take variance-component model cluster allocation assumes, or "none" for no correction, n_cluster()'s default with-replacement model. "stage" and "none" match n_cluster() with the same fpc. "stage" requires N_psu, and N_ssu as well at three stages, and is refused in element allocation. Only "unit" is available 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.

The print shows the allocation as evaluated, unrounded, and for a fit read back without n it says the allocation is the continuous optimum. For a fit res, prec_alloc(res, n = res$detail$n_int) gives the precision of the whole allocation.

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, or the fit's own table when a register fit is evaluated as it stands.

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 plans from the register the fit was solved from, so it reaches a design of the same cost, though it may pick another where several tie.

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. A register fit's field design is evaluated by prec_alloc(fit) with nothing overridden, which reports what fit$operational$constraints reports, with the fit's $psu table. Supplying n evaluates the design built from those totals, holding the fit's certainty PSUs.

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 stratum allocation (continuous optimum)
#> n = 600 (3 strata)
#> se = 0.4305, moe = 0.8438, cv = 0.0079, rmoe = 0.0155
prec_alloc(res, n = res$detail$n_int)
#> Sampling precision for stratum allocation
#> n = 600 (3 strata)
#> se = 0.4305, moe = 0.8438, cv = 0.0079, rmoe = 0.0155

# The previous round's allocation, assessed nationally and per region
last_round <- data.frame(
  stratum = c("North", "Centre", "South"),
  N = c(380000, 250000, 25000),
  p = c(0.48, 0.60, 0.16),
  deff = 4.4
)
last_round$region <- last_round$stratum
assessed <- prec_alloc(last_round, n = c(768, 576, 192), domains = "region")
assessed$moe
#> [1] 0.05372056
assessed$domains[c("region", ".moe")]
#>   region       .moe
#> 1  North 0.07404187
#> 2 Centre 0.08382408
#> 3  South 0.10835726

# An island district of 16 enumeration areas of about 180 households,
# 16 interviewed in each. Taking 12 of the 16 removes most of the variance
# between areas, which only the stage-by-stage correction sees.
island <- data.frame(
  stratum = "Island", N = 2892, p = 0.314,
  icc_psu = 0.23, n_per_psu = 16, N_psu = 16
)
prec_alloc(island, n = 16 * 12, fpc = "stage")$moe
#> [1] 0.08360424
prec_alloc(island, n = 16 * 12, fpc = "none")$moe
#> [1] 0.1384855
n_alloc(island, cv = 0.10 / (qnorm(0.975) * 0.314), fpc = "stage")
#> Stratum allocation (neyman, two-stage, 1 strata)
#> field design: n = 176, n_psu = 11, cv = 0.1516
#> continuous design: n = 165.6018, cv = 0.1625, se = 0.0510
#> (deff = 1)
#> design df = 10

# 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

# A fixed allocation of households assessed nationally and per region,
# with each region's published design effect (a DEFT, squared) and its
# married women per household. The national row weights each region by
# its eligible women, N * eligible_per_unit.
regions <- data.frame(
  stratum = c("Coast", "Centre", "East"),
  region = c("Coast", "Centre", "East"),
  N = c(60000, 150000, 40000)
)
mcpr <- data.frame(
  stratum = regions$stratum, name = "mcpr",
  p = c(0.22, 0.19, 0.08),
  deff = c(1.02, 1.09, 1.65)^2,
  resp_rate = c(0.84, 0.91, 0.88),
  eligible_per_unit = c(0.59, 1.23, 2.30)
)
every_level <- data.frame(
  name = "mcpr", domain = c(".overall", "region"), cv = 0.10
)
assessed <- prec_alloc(regions, n = c(850, 1525, 975), measures = mcpr,
                       targets = every_level)
assessed
#> Joint allocation precision (4 constraints)
#> targets: 1 violated
#> showing 1 violated of 4
#> 
#>  constraint          .metric .target .achieved .pass
#>  mcpr@region=East:cv cv      0.1     0.1246003 FALSE
#> 
#> ... see $detail for all rows
assessed$detail[, c("domain", "level", ".achieved", ".pass")]
#>     domain  level  .achieved .pass
#> 1 .overall   <NA> 0.04444467  TRUE
#> 2   region  Coast 0.09301813  TRUE
#> 3   region Centre 0.05422092  TRUE
#> 4   region   East 0.12460032 FALSE