Print and coerce design degrees of freedom

Display and coercion methods for the count that design_df() returns. print() shows the headline count and the numbers it was formed from, while summary() gives the additive per-stratum decomposition and the separate per-domain counts. The coercion and arithmetic methods let the object stand in for the headline count wherever a plain number is expected.

Usage

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

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

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

# S3 method for class 'svyplan_df'
format(x, ...)

# S3 method for class 'svyplan_df'
as.double(x, ...)

# S3 method for class 'svyplan_df'
as.list(x, ...)

# S3 method for class 'svyplan_df'
x$name

# S3 method for class 'svyplan_df'
x[[i, ...]]

# S3 method for class 'svyplan_df'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  stringsAsFactors = FALSE,
  validRN = TRUE,
  ...
)

# S3 method for class 'svyplan_df'
Ops(e1, e2)

# S3 method for class 'svyplan_df'
Math(x, ...)

# S3 method for class 'svyplan_df'
x[i] <- value

# S3 method for class 'svyplan_df'
x[[i]] <- value

Arguments

x

A svyplan_df object from design_df(), or its summary for the summary print method.

...

For mathematical transformations, additional arguments passed to the underlying operation. The other methods do not support additional arguments.

object

A svyplan_df object to summarize.

name, i

A field name, one of those listed under Details. [[ also accepts a numeric index, which reads the underlying numeric vector.

row.names, optional

Standard as.data.frame() arguments.

stringsAsFactors

Logical. Retained for compatibility when a result is converted through data.frame().

validRN

Logical. Accepted for compatibility with data.frame() in R 4.7.0 and later. Svyplan results already have valid row names.

e1, e2

Objects supplied to an arithmetic or comparison operator.

value

Replacement value. Replacement is refused, the count being derived from the strata and domains it carries.

Value

print() returns x invisibly. summary() returns a summary.svyplan_df object containing the overall count, its inputs, the per-stratum decomposition when available, the per-domain counts, and the counting basis. format() returns a character scalar, and as.double() returns the degrees of freedom. as.data.frame() returns a one-row table of the scalar fields; as.list() returns every field, including the per-stratum and per-domain tables, and $ and [[ return one of them. Arithmetic and mathematical transformations return ordinary numeric results.

Details

A svyplan_df behaves as the numeric degrees of freedom wherever one is expected: it can be passed to any df argument, compared, and arithmetically combined, with the detail dropped by any such operation.

The fields are df for the count itself, n_units for the units it counts and stage for what those units are ("psu" or "element"), n_strata for the constraints subtracted, and the strata and domains tables, which are NULL for an unstratified or domain-free plan. Naming a field the object does not have is an error listing the ones it does.

The summary's stratum table is an additive decomposition: a contributing stratum uses one constraint and contributes its sampled units minus one. A census stratum has no units counted and no constraint, while a singleton uses its one constraint and contributes zero. The domain table is printed separately because domain degrees of freedom are alternative subpopulation counts, not additional contributions to the overall design.

See also

design_df(), which builds these objects, and print.svyplan_deff for the design effect's counterpart.

Examples

d <- design_df(n_psu = 300, n_strata = 20)
d
#> Design degrees of freedom (planning)
#> 
#>   df = 280   (300 PSUs - 20 strata)
d$df
#> [1] 280
as.double(d) + 1
#> [1] 281
as.data.frame(d)
#>    df n_units n_strata stage
#> 1 280     300       20   psu
summary(d)
#> Analysis of design degrees of freedom
#> 
#>         Units Constraints Design df
#> Overall   300          20       280
#> 
#> Per-stratum counts were not supplied.
#> 
#> Counted stage: PSU
#> Basis: counted PSUs minus contributing strata