Generates a "Table 1" of descriptive statistics for complex survey data, stratified by an outcome variable. It supports different reporting modes, optional comma formatting, and optional reliability checks based on NCHS Data Presentation Standards.
Usage
svytable1(
design,
strata_var,
table_vars,
mode = "mixed",
commas = TRUE,
reliability_checks = FALSE,
return_metrics = FALSE
)Arguments
- design
A survey design object created by the survey package.
- strata_var
A string with the name of the stratification variable. If this variable contains NA values, they will be automatically grouped into a separate 'Missing' stratum in the output table.
- table_vars
A character vector of variable names to summarize.
- mode
A string specifying the output type: "mixed" (default), "weighted", or "unweighted".
- commas
Logical; if TRUE (default), large numbers in counts are formatted with commas.
- reliability_checks
Logical; if TRUE, performs reliability checks. Unreliable estimates are replaced with an asterisk (*). The rules are based on NCHS guidelines.
For proportions (categorical variables), an estimate is suppressed if it meets ANY of the following criteria:
Unweighted Sample Size < 30: The actual number of survey participants in the cell is too small to produce a stable estimate.
Effective Sample Size < 30: After accounting for the complex survey design, the estimate's precision is equivalent to that from a simple random sample of fewer than 30 people.
Degrees of Freedom < 8: The variance estimate is itself unstable, making the entire estimate unreliable.
Confidence Interval Width >= 30%: The 95% confidence interval is 30 percentage points wide or wider, indicating extreme imprecision.
Conditional Relative CI Width > 130%: If the confidence interval width is between 5% and 30%, it is also checked to see if it is excessively large relative to the estimate itself.
For means (numeric variables), an estimate is suppressed if:
Relative Standard Error (RSE) >= 30%: The standard error is 30% or more of the mean's value, indicating high imprecision.
Defaults to FALSE.
- return_metrics
Logical; if TRUE and `reliability_checks` is also TRUE, the function returns a list containing the formatted table and a detailed data frame of the reliability metrics. This includes the RSE and specific TRUE/FALSE columns (e.g., `fail_n_30`, `fail_eff_n_30`) for each suppression rule. Defaults to FALSE.
Value
If `return_metrics` is FALSE (default), returns a data.frame. If TRUE, returns a list with two elements: `formatted_table` and `reliability_metrics`.
Examples
# Ensure required packages are loaded
if (requireNamespace("survey", quietly = TRUE) &&
requireNamespace("NHANES", quietly = TRUE) &&
requireNamespace("dplyr", quietly = TRUE)) {
# 1. Prepare Data using NHANES
data(NHANESraw, package = "NHANES")
nhanes_adults_with_na <- NHANESraw %>%
dplyr::filter(Age >= 20) %>%
dplyr::mutate(
ObeseStatus = factor(ifelse(BMI >= 30, "Obese", "Not Obese"),
levels = c("Not Obese", "Obese"))
)
adult_design_with_na <- survey::svydesign(
id = ~SDMVPSU,
strata = ~SDMVSTRA,
weights = ~WTMEC2YR,
nest = TRUE,
data = nhanes_adults_with_na
)
# 2. Basic Example: Create a simple Table 1
vars_to_summarize <- c("Age", "Gender", "Race1", "Education")
table1 <- svytable1(
design = adult_design_with_na,
strata_var = "ObeseStatus",
table_vars = vars_to_summarize
)
print(table1)
# 3. Advanced Example: Use reliability checks and get detailed metrics
results <- svytable1(
design = adult_design_with_na,
strata_var = "ObeseStatus",
table_vars = vars_to_summarize,
reliability_checks = TRUE,
return_metrics = TRUE
)
# View the table with unreliable estimates suppressed (*)
print(results$formatted_table)
# View the detailed report card of reliability checks
print(results$reliability_metrics)
}
#> Variable Level Overall Missing Not Obese
#> 1 n 11,778 547 7,073
#> 2 Age
#> 3 Mean (SD) 47.18 (16.89) 56.29 (19.15) 46.45 (17.32)
#> 4 Gender
#> 5 female 6,032 (51.9%) 275 (52.3%) 3,443 (51.2%)
#> 6 male 5,746 (48.1%) 272 (47.7%) 3,630 (48.8%)
#> 7 Race1
#> 8 Black 2,577 (11.4%) 108 (12.1%) 1,296 (9.1%)
#> 9 Hispanic 1,210 (5.8%) 62 (2.9%) 714 (5.7%)
#> 10 Mexican 1,680 (8.2%) 75 (9.4%) 920 (7.3%)
#> 11 White 5,017 (67.2%) 235 (69.6%) 3,114 (68.6%)
#> 12 Other 1,294 (7.4%) 67 (6.0%) 1,029 (9.3%)
#> 13 Education
#> 14 8th Grade 1,321 (6.1%) 79 (9.8%) 770 (5.9%)
#> 15 9 - 11th Grade 1,787 (11.8%) 84 (16.8%) 1,021 (11.3%)
#> 16 High School 2,595 (21.5%) 121 (21.1%) 1,496 (20.2%)
#> 17 Some College 3,399 (31.3%) 144 (33.4%) 1,968 (29.4%)
#> 18 College Grad 2,656 (29.3%) 116 (18.7%) 1,805 (33.0%)
#> 19 Missing 20 (0.1%) 3 (0.2%) 13 (0.1%)
#> Obese
#> 1 4,158
#> 2
#> 3 48.25 (15.87)
#> 4
#> 5 2,314 (53.2%)
#> 6 1,844 (46.8%)
#> 7
#> 8 1,173 (15.8%)
#> 9 434 (6.0%)
#> 10 685 (9.8%)
#> 11 1,668 (64.4%)
#> 12 198 (4.0%)
#> 13
#> 14 472 (6.3%)
#> 15 682 (12.5%)
#> 16 978 (23.8%)
#> 17 1,287 (34.5%)
#> 18 735 (22.8%)
#> 19 4 (0.0%)
#> Variable Level Overall Missing Not Obese
#> 1 n 11,778 547 7,073
#> 2 Age
#> 3 Mean (SD) 47.18 (16.89) 56.29 (19.15) 46.45 (17.32)
#> 4 Gender
#> 5 female 6,032 (51.9%) 275 (52.3%) 3,443 (51.2%)
#> 6 male 5,746 (48.1%) 272 (47.7%) 3,630 (48.8%)
#> 7 Race1
#> 8 Black 2,577 (11.4%) 108 (12.1%) 1,296 (9.1%)
#> 9 Hispanic 1,210 (5.8%) * 714 (5.7%)
#> 10 Mexican 1,680 (8.2%) * 920 (7.3%)
#> 11 White 5,017 (67.2%) 235 (69.6%) 3,114 (68.6%)
#> 12 Other 1,294 (7.4%) 67 (6.0%) 1,029 (9.3%)
#> 13 Education
#> 14 8th Grade 1,321 (6.1%) * 770 (5.9%)
#> 15 9 - 11th Grade 1,787 (11.8%) 84 (16.8%) 1,021 (11.3%)
#> 16 High School 2,595 (21.5%) 121 (21.1%) 1,496 (20.2%)
#> 17 Some College 3,399 (31.3%) 144 (33.4%) 1,968 (29.4%)
#> 18 College Grad 2,656 (29.3%) * 1,805 (33.0%)
#> 19 Missing 20 (0.1%) * *
#> Obese
#> 1 4,158
#> 2
#> 3 48.25 (15.87)
#> 4
#> 5 2,314 (53.2%)
#> 6 1,844 (46.8%)
#> 7
#> 8 1,173 (15.8%)
#> 9 434 (6.0%)
#> 10 685 (9.8%)
#> 11 1,668 (64.4%)
#> 12 198 (4.0%)
#> 13
#> 14 472 (6.3%)
#> 15 682 (12.5%)
#> 16 978 (23.8%)
#> 17 1,287 (34.5%)
#> 18 735 (22.8%)
#> 19 *
#> stratum variable level n df deff
#> Age Overall Age Mean (SD) NA NA NA
#> 1 Missing Age Mean (SD) NA NA NA
#> 11 Not Obese Age Mean (SD) NA NA NA
#> 12 Obese Age Mean (SD) NA NA NA
#> Genderfemale Missing Gender female 275 26 1.38
#> Genderfemale1 Not Obese Gender female 3443 33 0.95
#> Genderfemale2 Obese Gender female 2314 33 2.05
#> Gendermale Missing Gender male 272 26 1.38
#> Gendermale1 Not Obese Gender male 3630 33 0.95
#> Gendermale2 Obese Gender male 1844 33 2.05
#> Race1Black Missing Race1 Black 108 26 1.51
#> Race1Black1 Not Obese Race1 Black 1296 33 8.56
#> Race1Black2 Obese Race1 Black 1173 33 9.74
#> Race1Hispanic Missing Race1 Hispanic 62 26 1.77
#> Race1Hispanic1 Not Obese Race1 Hispanic 714 33 11.46
#> Race1Hispanic2 Obese Race1 Hispanic 434 33 9.76
#> Race1Mexican Missing Race1 Mexican 75 26 2.18
#> Race1Mexican1 Not Obese Race1 Mexican 920 33 15.06
#> Race1Mexican2 Obese Race1 Mexican 685 33 14.59
#> Race1White Missing Race1 White 235 26 3.04
#> Race1White1 Not Obese Race1 White 3114 33 18.60
#> Race1White2 Obese Race1 White 1668 33 16.87
#> Race1Other Missing Race1 Other 67 26 0.63
#> Race1Other1 Not Obese Race1 Other 1029 33 8.65
#> Race1Other2 Obese Race1 Other 198 33 2.43
#> Education8th Grade Missing Education 8th Grade 79 26 1.81
#> Education8th Grade1 Not Obese Education 8th Grade 770 33 2.20
#> Education8th Grade2 Obese Education 8th Grade 472 33 2.49
#> Education9 - 11th Grade Missing Education 9 - 11th Grade 84 26 1.83
#> Education9 - 11th Grade1 Not Obese Education 9 - 11th Grade 1021 33 5.37
#> Education9 - 11th Grade2 Obese Education 9 - 11th Grade 682 33 2.60
#> EducationHigh School Missing Education High School 121 26 3.06
#> EducationHigh School1 Not Obese Education High School 1496 33 4.32
#> EducationHigh School2 Obese Education High School 978 33 2.69
#> EducationSome College Missing Education Some College 144 26 1.67
#> EducationSome College1 Not Obese Education Some College 1968 33 4.96
#> EducationSome College2 Obese Education Some College 1287 33 1.66
#> EducationCollege Grad Missing Education College Grad 116 26 3.61
#> EducationCollege Grad1 Not Obese Education College Grad 1805 33 9.31
#> EducationCollege Grad2 Obese Education College Grad 735 33 4.47
#> EducationMissing Missing Education Missing 3 26 0.29
#> EducationMissing1 Not Obese Education Missing 13 33 1.20
#> EducationMissing2 Obese Education Missing 4 33 0.54
#> effective_n ci_low ci_high rse suppressed fail_n_30
#> Age NA NA NA 1.03 FALSE NA
#> 1 NA NA NA 3.51 FALSE NA
#> 11 NA NA NA 1.25 FALSE NA
#> 12 NA NA NA 0.87 FALSE NA
#> Genderfemale 199.82 0.42 0.63 9.27 FALSE FALSE
#> Genderfemale1 3443.00 0.50 0.52 1.13 FALSE FALSE
#> Genderfemale2 1128.18 0.51 0.55 2.08 FALSE FALSE
#> Gendermale 197.64 0.37 0.58 10.17 FALSE FALSE
#> Gendermale1 3630.00 0.48 0.50 1.19 FALSE FALSE
#> Gendermale2 899.03 0.45 0.49 2.37 FALSE FALSE
#> Race1Black 71.51 0.06 0.21 27.40 FALSE FALSE
#> Race1Black1 151.45 0.07 0.11 11.02 FALSE FALSE
#> Race1Black2 120.38 0.12 0.20 11.19 FALSE FALSE
#> Race1Hispanic 35.04 0.00 0.10 63.22 TRUE FALSE
#> Race1Hispanic1 62.29 0.04 0.08 16.34 FALSE FALSE
#> Race1Hispanic2 44.49 0.04 0.09 19.13 FALSE FALSE
#> Race1Mexican 34.47 0.03 0.20 38.01 TRUE FALSE
#> Race1Mexican1 61.10 0.05 0.10 16.50 FALSE FALSE
#> Race1Mexican2 46.94 0.06 0.14 18.02 FALSE FALSE
#> Race1White 77.36 0.54 0.83 9.53 FALSE FALSE
#> Race1White1 167.38 0.64 0.73 3.47 FALSE FALSE
#> Race1White2 98.85 0.58 0.71 4.74 FALSE FALSE
#> Race1Other 67.00 0.03 0.10 26.03 FALSE FALSE
#> Race1Other1 118.92 0.07 0.12 10.91 FALSE FALSE
#> Race1Other2 81.41 0.03 0.05 11.79 FALSE FALSE
#> Education8th Grade 43.74 0.04 0.19 33.69 TRUE FALSE
#> Education8th Grade1 349.97 0.05 0.07 7.07 FALSE FALSE
#> Education8th Grade2 189.42 0.05 0.08 9.41 FALSE FALSE
#> Education9 - 11th Grade 45.82 0.09 0.27 24.94 FALSE FALSE
#> Education9 - 11th Grade1 190.25 0.10 0.13 7.71 FALSE FALSE
#> Education9 - 11th Grade2 262.75 0.11 0.14 6.60 FALSE FALSE
#> EducationHigh School 39.55 0.10 0.36 28.01 FALSE FALSE
#> EducationHigh School1 346.05 0.18 0.22 4.91 FALSE FALSE
#> EducationHigh School2 363.21 0.22 0.26 4.55 FALSE FALSE
#> EducationSome College 86.04 0.23 0.45 15.12 FALSE FALSE
#> EducationSome College1 396.45 0.27 0.32 4.10 FALSE FALSE
#> EducationSome College2 776.40 0.33 0.36 2.75 FALSE FALSE
#> EducationCollege Grad 32.16 0.08 0.35 32.76 TRUE FALSE
#> EducationCollege Grad1 193.84 0.30 0.37 5.17 FALSE FALSE
#> EducationCollege Grad2 164.49 0.20 0.26 6.03 FALSE FALSE
#> EducationMissing 3.00 0.00 0.01 102.95 TRUE TRUE
#> EducationMissing1 10.86 0.00 0.00 34.32 TRUE TRUE
#> EducationMissing2 4.00 0.00 0.00 52.87 TRUE TRUE
#> fail_eff_n_30 fail_df_8 fail_ciw_30 fail_rciw_130
#> Age NA NA NA NA
#> 1 NA NA NA NA
#> 11 NA NA NA NA
#> 12 NA NA NA NA
#> Genderfemale FALSE FALSE FALSE FALSE
#> Genderfemale1 FALSE FALSE FALSE FALSE
#> Genderfemale2 FALSE FALSE FALSE FALSE
#> Gendermale FALSE FALSE FALSE FALSE
#> Gendermale1 FALSE FALSE FALSE FALSE
#> Gendermale2 FALSE FALSE FALSE FALSE
#> Race1Black FALSE FALSE FALSE FALSE
#> Race1Black1 FALSE FALSE FALSE FALSE
#> Race1Black2 FALSE FALSE FALSE FALSE
#> Race1Hispanic FALSE FALSE FALSE TRUE
#> Race1Hispanic1 FALSE FALSE FALSE FALSE
#> Race1Hispanic2 FALSE FALSE FALSE FALSE
#> Race1Mexican FALSE FALSE FALSE TRUE
#> Race1Mexican1 FALSE FALSE FALSE FALSE
#> Race1Mexican2 FALSE FALSE FALSE FALSE
#> Race1White FALSE FALSE FALSE FALSE
#> Race1White1 FALSE FALSE FALSE FALSE
#> Race1White2 FALSE FALSE FALSE FALSE
#> Race1Other FALSE FALSE FALSE FALSE
#> Race1Other1 FALSE FALSE FALSE FALSE
#> Race1Other2 FALSE FALSE FALSE FALSE
#> Education8th Grade FALSE FALSE FALSE TRUE
#> Education8th Grade1 FALSE FALSE FALSE FALSE
#> Education8th Grade2 FALSE FALSE FALSE FALSE
#> Education9 - 11th Grade FALSE FALSE FALSE FALSE
#> Education9 - 11th Grade1 FALSE FALSE FALSE FALSE
#> Education9 - 11th Grade2 FALSE FALSE FALSE FALSE
#> EducationHigh School FALSE FALSE FALSE FALSE
#> EducationHigh School1 FALSE FALSE FALSE FALSE
#> EducationHigh School2 FALSE FALSE FALSE FALSE
#> EducationSome College FALSE FALSE FALSE FALSE
#> EducationSome College1 FALSE FALSE FALSE FALSE
#> EducationSome College2 FALSE FALSE FALSE FALSE
#> EducationCollege Grad FALSE FALSE FALSE TRUE
#> EducationCollege Grad1 FALSE FALSE FALSE FALSE
#> EducationCollege Grad2 FALSE FALSE FALSE FALSE
#> EducationMissing TRUE FALSE FALSE FALSE
#> EducationMissing1 TRUE FALSE FALSE FALSE
#> EducationMissing2 TRUE FALSE FALSE FALSE
#> fail_rse_30
#> Age FALSE
#> 1 FALSE
#> 11 FALSE
#> 12 FALSE
#> Genderfemale FALSE
#> Genderfemale1 FALSE
#> Genderfemale2 FALSE
#> Gendermale FALSE
#> Gendermale1 FALSE
#> Gendermale2 FALSE
#> Race1Black FALSE
#> Race1Black1 FALSE
#> Race1Black2 FALSE
#> Race1Hispanic TRUE
#> Race1Hispanic1 FALSE
#> Race1Hispanic2 FALSE
#> Race1Mexican TRUE
#> Race1Mexican1 FALSE
#> Race1Mexican2 FALSE
#> Race1White FALSE
#> Race1White1 FALSE
#> Race1White2 FALSE
#> Race1Other FALSE
#> Race1Other1 FALSE
#> Race1Other2 FALSE
#> Education8th Grade TRUE
#> Education8th Grade1 FALSE
#> Education8th Grade2 FALSE
#> Education9 - 11th Grade FALSE
#> Education9 - 11th Grade1 FALSE
#> Education9 - 11th Grade2 FALSE
#> EducationHigh School FALSE
#> EducationHigh School1 FALSE
#> EducationHigh School2 FALSE
#> EducationSome College FALSE
#> EducationSome College1 FALSE
#> EducationSome College2 FALSE
#> EducationCollege Grad TRUE
#> EducationCollege Grad1 FALSE
#> EducationCollege Grad2 FALSE
#> EducationMissing TRUE
#> EducationMissing1 TRUE
#> EducationMissing2 TRUE