Skip to contents

Summarize stratified allocation results

Source: R/print.R
summary.svyplan_alloc.Rd

summary() separates a classic n_alloc() or prec_alloc() result into the overall answer, the per-stratum allocation, achieved precision, allocation bounds, domains, and assumptions. The design summary evaluates the whole-unit field allocation; the precision summary evaluates the supplied allocation exactly. Generalized Bethel allocations return a separate diagnostic summary containing their constraint, objective, optimization, and bound tables.

Usage

# S3 method for class 'svyplan_n'
summary(object, ...)

# S3 method for class 'svyplan_prec'
summary(object, ...)

# S3 method for class 'summary.svyplan_bethel'
print(x, ...)

# S3 method for class 'summary.svyplan_alloc'
print(x, ...)

Arguments

object

An allocation result from n_alloc() or prec_alloc().

...

Additional arguments are not supported for allocation summaries. For other svyplan_n and svyplan_prec results they are passed to the default summary method.

x

A summary.svyplan_alloc or summary.svyplan_bethel object.

Value

For a classic allocation, summary() returns a summary.svyplan_alloc object with fields kind, question, method, mode, overall, continuous, allocation, precision, bounds, domains, and assumptions. For a generalized allocation it returns the summary.svyplan_bethel fields described in Details. Numeric quantities remain unformatted; formatting is applied only by the summary print methods. print() returns the summary invisibly.

Details

For n_alloc(), overall, allocation, precision, and domains describe $detail$n_int and the operational cluster takes when present. The mathematical optimum remains in continuous. For prec_alloc(), the same fields describe $detail$n, the allocation actually supplied to the precision calculation; continuous and bounds are NULL.

Stratum standard errors, margins of error, and CVs do not add to their overall counterparts. variance_share is the stratum's contribution to the overall variance and sums to one when that variance is positive. Domain rows are separate subpopulation assessments, not contributions to add to the overall row.

A generalized Bethel summary has fields kind, question, mode, stages, status, overall, continuous, allocation, constraints, operational_constraints, objective, operational_objective, bounds, optimization, and assumptions. For a fitted design the headline and allocation describe the integer field recommendation, while continuous and constraints retain the mathematical optimum. For a precision assessment they describe the supplied allocation exactly.

Constraint rows are simultaneous requirements, not an additive decomposition. .ratio is achieved divided by target, .residual is that ratio minus one, and .sensitivity is the local change in minimum cost per unit relaxation of the stated target. Objective .contribution and .share columns are genuinely additive across components.

Examples

frame <- data.frame(
  stratum = c("Urban", "Rural", "Remote"),
  N = c(12000, 30000, 8000),
  sd = c(5, 8, 12),
  mean = c(20, 18, 15),
  unit_cost = c(1, 1.4, 3)
)
allocation <- n_alloc(frame, n = 1200)
summary(allocation)
#> Stratified allocation summary
#> 
#> Question: distribute a fixed sample of 1200 using Neyman allocation
#> 
#> Overall field design
#>   Sample        1200
#>   Cost          2072.8
#>   SE            0.2257
#>   MOE           0.4423
#>   Relative MOE  0.0246
#>   CV            0.0125
#>   Design df     1197
#> 
#> Continuous optimum
#>   Sample        1200
#>   Cost          2072.7
#>   SE            0.2257
#>   MOE           0.4423
#>   Relative MOE  0.0246
#>   CV            0.0125
#> 
#> Allocation by stratum
#> 
#>  Stratum  Pop. Resp.  Cont. Field Exp. resp.
#>    Urban 12000     1 181.82   182     182.00
#>    Rural 30000     1 727.27   727     727.00
#>   Remote  8000     1 290.91   291     291.00
#> 
#> Cost and weights by stratum
#> 
#>  Stratum Cost/unit Weight    Cost
#>    Urban      1.00  65.93  182.00
#>    Rural      1.40  41.27 1017.80
#>   Remote      3.00  27.49  873.00
#> 
#> Achieved precision by stratum
#> 
#>  Stratum   Eff. n     SE    MOE Rel. MOE     CV Var. share
#>    Urban 182.0000 0.3678 0.7209   0.0360 0.0184      0.153
#>    Rural 727.0000 0.2931 0.5744   0.0319 0.0163      0.607
#>   Remote 291.0000 0.6905 1.3534   0.0902 0.0460      0.240
#> 
#> Allocation bounds
#> 
#>  Stratum Lower Field Upper Binding Source
#>    Urban     1   182 12000               
#>    Rural     1   727 30000               
#>   Remote     1   291  8000               
#> 
#> No allocation bounds are active.
#> 
#> Assumptions
#>   alpha: 0.05
#>   design effect: 1.00
#>   response rate: 1.00
summary(prec_alloc(allocation, n = allocation$detail$n_int))
#> Allocation precision summary
#> 
#> Question: assess a supplied stratified allocation
#> 
#> Overall precision
#>   Sample        1200
#>   Cost          2072.8
#>   SE            0.2257
#>   MOE           0.4423
#>   Relative MOE  0.0246
#>   CV            0.0125
#> 
#> Allocation by stratum
#> 
#>  Stratum  Pop. Resp. Supplied Exp. resp.
#>    Urban 12000     1   182.00     182.00
#>    Rural 30000     1   727.00     727.00
#>   Remote  8000     1   291.00     291.00
#> 
#> Cost and weights by stratum
#> 
#>  Stratum Cost/unit Weight    Cost
#>    Urban      1.00  65.93  182.00
#>    Rural      1.40  41.27 1017.80
#>   Remote      3.00  27.49  873.00
#> 
#> Achieved precision by stratum
#> 
#>  Stratum   Eff. n     SE    MOE Rel. MOE     CV Var. share
#>    Urban 182.0000 0.3678 0.7209   0.0360 0.0184      0.153
#>    Rural 727.0000 0.2931 0.5744   0.0319 0.0163      0.607
#>   Remote 291.0000 0.6905 1.3534   0.0902 0.0460      0.240
#> 
#> Assumptions
#>   alpha: 0.05
#>   design effect: 1.00
#>   response rate: 1.00