Design degrees of freedom

Count nominal degrees of freedom from a planned design's issued units. This is a planning counterpart to survey::degf(). Realized degrees of freedom depend on the responding sample and the analysis variance estimator.

Usage

design_df(x = NULL, ...)

# Default S3 method
design_df(x = NULL, ..., n_psu = NULL, n_strata = 1, n = NULL)

# S3 method for class 'svyplan_cluster'
design_df(x, ...)

# S3 method for class 'svyplan_n'
design_df(x, ...)

# S3 method for class 'svyplan_strata'
design_df(x, ...)

# S3 method for class 'svyplan_twophase'
design_df(x, ...)

Arguments

x: A svyplan result to count from: a n_cluster() or prec_cluster() allocation, a n_alloc() allocation, a strata_bound() stratification, a n_twophase() allocation, or a single-indicator n_prop() or n_mean() size. NULL (default) counts from the components below.
...: Additional arguments passed to methods. Unused arguments are rejected.
n_psu: Number of PSUs the design will select, across all strata.
n_strata: Number of strata, default 1 (unstratified).
n: Number of ultimate units, for an element design. Supply this or n_psu, not both.

Value

A svyplan_df object: a numeric scalar carrying the counts it was formed from. Use it directly wherever a df argument is expected, as.double() to strip it to a plain number, and $strata and $domains for the per-stratum and per-domain tables.

Details

The degrees of freedom of a design-based variance estimator are the number of independent units contributing to it, less the number of constraints the design imposes: for a stratified design, sampled units minus strata. In a clustered design the units are the PSUs, not the ultimate units, which is why a survey of 12,000 households in 300 clusters across 20 strata has 280 degrees of freedom rather than 11,999.

Pass the count as df to use a t quantile in place of the normal one, and to the Korn-Graubard interval, which widens as the count falls. It is the nominal first-stage count. The degrees of freedom of a particular estimator, such as a Satterthwaite approximation combining several variance components, differ from it.

What is counted, per design shape

Design	Counted	df
Unstratified element	units	$n - 1$
Unstratified cluster	PSUs	$m - 1$
Stratified element	units per stratum	$\sum_h n_h - H$
Stratified cluster	PSUs per stratum	$\sum_h m_h - H$
Two-phase	phase-2 units per stratum	$\sum_h n_{2h} - H$

The counts are read from the whole-unit columns a plan reports (n_int, n_psu_int, n_psu_draw, operational$n), never from the continuous optimum, since a degree of freedom is a unit that will be fielded. They are issued counts and are not adjusted for nonresponse. For an element design, fewer respondents generally mean fewer degrees of freedom. For a cluster design, element nonresponse need not change the PSU count, but lost PSUs or PSUs with no responding domain members can reduce it. The two-phase count is a phase-2 planning convention, not a derivation of the degrees of freedom of the combined two-phase variance estimator.

A stratum that carries no sampling variance drops out of both terms. In element mode a take_all stratum is a census and contributes nothing. In cluster mode take_all marks an element-level census inside the stratum, which leaves the PSU stage sampling as before, so such a stratum still contributes $m_h - 1$. A phase-2 take_all stratum likewise still contributes, since following up every phase-1 unit in a stratum does not remove the phase-1 sampling variance.

Per-domain degrees of freedom

$domains applies the same nominal counting rule by domain. The allocation API expresses a domain as a set of whole strata, so a domain's df is that union's own contribution, $\sum_{h \in d} m_h - H_d$, and the per-domain values sum to the overall df whenever the domains partition the frame.

The case that is not derivable is an analytic domain cutting across strata, such as an age group or sex. Its df is bounded above by the design df, and the Korn-Graubard counting rule for it (PSUs containing domain members, minus strata containing them) needs frame information that a plan does not carry. It is a limit of what is knowable before fielding, not an omission.

What the count cannot see

Certainty, or self-representing, PSUs contribute no between-PSU variance and should not count toward first-stage df. For a PSU register supplied through n_alloc() with no certainty PSUs, this helper counts the operational PSUs (n_psu_draw) minus strata. Allocations containing certainty PSUs remain unsupported: combining their within-PSU variance contributions with other strata requires an explicit degrees-of-freedom convention that this helper does not yet implement. In other inputs, unrecorded certainty PSUs can make the nominal first-stage count too large.

A stratum holding a single PSU supports no within-stratum variance estimate at all, and warns, naming the stratum. Its own contribution is zero and $strata marks it "singleton". Whether a small but positive df is a problem is a judgment call, so it is reported and never warned about.

Methods (by class)

design_df(default): Count from the design's own numbers. Supply n_psu for a clustered design or n for an element design, with n_strata where the design is stratified.
design_df(svyplan_cluster): Count the PSUs a n_cluster() or prec_cluster() allocation selects. Unstratified, so the count is one design.
design_df(svyplan_n): Count a n_alloc() allocation, at the PSU stage when the frame carried cluster columns and at the element stage otherwise, or the units of a single n_prop() or n_mean() size.
design_df(svyplan_strata): Count a strata_bound() stratification, whose strata are element-stage and whose take-all strata are censuses.
design_df(svyplan_twophase): Count the phase-2 units a n_twophase() allocation measures. A take-all phase-2 stratum still carries the phase-1 sampling variance, so it contributes as any other does.

References

Valliant, R., Dever, J. A., and Kreuter, F. (2018). Practical Tools for Designing and Weighting Survey Samples (2nd ed.). Springer. Ch. 3.

Korn, E. L. and Graubard, B. I. (1998). Confidence intervals for proportions with small expected number of positive counts estimated from survey data. Survey Methodology, 24(2), 193–201.

Examples

# A stratified cluster allocation: PSUs minus strata
frame <- data.frame(
  stratum = c("a", "b", "c"),
  N       = c(12000, 30000, 8000),
  sd      = c(5, 8, 3),
  mean    = c(10, 20, 5),
  icc_psu = 0.05,
  n_per_psu = 12
)
alloc <- n_alloc(frame, n = 3000)
design_df(alloc)
#> Design degrees of freedom (planning)
#> 
#>   df = 247   (250 PSUs - 3 strata)
design_df(alloc)$strata
#>   stratum n_units  df .status
#> 1       a      46  45      ok
#> 2       b     185 184      ok
#> 3       c      19  18      ok

# Drop-in wherever a df is expected
n_prop(p = 0.02, moe = 0.01, method = "beta", df = design_df(alloc))
#> Sample size for proportion (beta)
#> n = 867 (p = 0.02, moe = 0.010, deff = 1)
#> expected cases = 17.3

# From counts, with no plan in hand
design_df(n_psu = 300, n_strata = 20)
#> Design degrees of freedom (planning)
#> 
#>   df = 280   (300 PSUs - 20 strata)