Print and coerce planning design effects

Display and coercion methods for the composed design effect that design_effect() returns. print() gives the overall value, while summary() gives an ANOVA-style decomposition and the assumptions behind each component. The coercion and arithmetic methods let the object stand in for the overall value wherever a plain number is expected.

Usage

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

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

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

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

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

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

# S3 method for class 'svyplan_deff'
x$name

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

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

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

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

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

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

Arguments

x

A svyplan_deff object from design_effect(), 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_deff 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, a design effect being the product of the components it carries.

Value

print() returns x invisibly. summary() returns a summary.svyplan_deff object containing the overall value, named components, component notes, and the basis of the decomposition. format() returns a character scalar, and as.double() returns the overall design effect. as.data.frame() returns a one-row table with the overall value and one column per component; as.list() returns the same fields as a named list, and $ and [[ return one of them. Arithmetic and mathematical transformations return ordinary numeric results.

Details

A svyplan_deff behaves as the numeric overall design effect wherever one is expected: it can be passed to any deff argument, compared, and arithmetically combined, with the components dropped by any such operation.

The decomposition is reached by name, under one set of names shared by every access route: deff for the overall value and deff_<component> for each part, so d$deff_cluster, d[["deff_cluster"]], as.list(d)$deff_cluster, and as.data.frame(d)$deff_cluster are the same number. Naming a field that this design effect does not have is an error listing the ones it does. The overall value is always present, so a one-component design effect reports it twice, once as deff and once as the component it is made of.

See also

design_effect(), which builds these objects, and print.svyplan for the sample size and precision results.

Examples

d <- design_effect(icc = 0.03, n_per_psu = 20,
                   weights = rep(c(1, 3), c(400, 100)))
d
#> Planning design effect: 2.0827
summary(d)
#> Analysis of design effects
#> 
#>            Design effect
#> Clustering        1.5700
#> Weighting         1.3265
#> Overall           2.0827
#> 
#> Components combine multiplicatively.
#> Basis: approximate multiplicative decomposition
#> 
#> Component assumptions:
#>   Clustering  icc = 0.03, n_per_psu = 20, var_ratio = 1
#>   Weighting   500 planned weights, cv(w) = 0.5714

# one component, by name
d$deff
#> [1] 2.082653
d$deff_cluster
#> [1] 1.57

# or the whole decomposition, as a list or a one-row table
as.list(d)
#> $deff
#> [1] 2.082653
#> 
#> $deff_cluster
#> [1] 1.57
#> 
#> $deff_weight
#> [1] 1.326531
#> 
as.data.frame(d)
#>       deff deff_cluster deff_weight
#> 1 2.082653         1.57    1.326531

# it is the overall value wherever a number is expected
as.double(d)
#> [1] 2.082653
n_prop(p = 0.3, moe = 0.05, deff = d)
#> Sample size for proportion (wald)
#> n = 673 (p = 0.30, moe = 0.050, deff = 2.08)
#> expected cases = 201.6