API Specification

Core API Specification

The 0.2.0.9000 development redesign was implemented locally on 2026-09-11. This is not a published release. The package repository's dev/api-specification.md contains the existing-work review and full contract; dev/validation.md records the actual verification results.

Functions and Scope

• freq_tbl(): one outcome, counts and proportions.
• wald_ci() / logit_ci(): composable interval helpers.
• freq_table(): counts plus intervals and optional detail.
• freq_test(), freq_format(), and get_group_n(): updated integrations.
• Multi-outcome tables, contingency tables, epidemiologic measures, and new presentation backends remain separate proposals. The existing multi-outcome draft is preserved under dev/freq_tables.R, outside the package build.

Input, Options, and Output

Use one outcome and groups supplied through group_by():

mtcars |> dplyr::group_by(cyl) |> freqtables::freq_tbl(am)
mtcars |> dplyr::group_by(cyl, vs) |> freqtables::freq_table(am)

The constructors accept .data, .freq_var, and named options drop = FALSE, percent = FALSE, overall = FALSE, generic_col_names = FALSE. freq_table() additionally accepts percent_ci = 95, ci_type = "logit" (or "wald"), se = FALSE, and critical_value = FALSE. Their ... must be empty. Earlier .drop, .percent, and col_headers proposals are not aliases.

Default columns are outcome, n, prop; grouped defaults add the grouping columns and use n_group, prop_group. Intervals add lcl/ucl or lcl_group/ucl_group. Results are ungrouped tibbles.

n_group is the total observations in the group across all outcome values. overall = TRUE adds n_total and, for grouped data, the joint cell proportion prop_total = n / n_total. Ungrouped prop is already overall. percent = TRUE changes proportion prefixes to percent and scales proportions, standard errors, and interval limits by 100, but not critical values. Generic headers use group_01_col/group_01_cat pairs and col/cat, with character categories suitable for stacking completed analyses.

Missing outcomes and group values count as categories. Filter explicitly:

df |>
  dplyr::filter(!is.na(sex), !is.na(diabetes)) |>
  dplyr::group_by(sex) |>
  freqtables::freq_tbl(diabetes)

drop = FALSE retains unused factor levels and empty factor combinations. drop = TRUE retains observed combinations without removing missing values. A zero denominator yields a missing proportion.

Intervals

Brad selected continuity with the existing convention:

p = n / N
SE = sqrt(p * (1 - p) / (N - 1))
critical = qt((1 + percent_ci / 100) / 2, df = N - 1)

For within-group estimates, N is the group size in both calculations. For overall estimates, N is the total sample size. Old subgroup limits used total-sample degrees of freedom and therefore differ from the corrected limits.

Wald bounds use p +/- critical * SE without clipping. Logit bounds use the logit transformation with SE/(p*(1-p)) and the stable inverse plogis(). At p=0 or p=1, logit limits are missing without a continuity correction; Wald limits equal p for N>1. N<=1 gives missing standard errors, critical values, and interval bounds. Confidence levels must lie strictly between 0 and 100.

Both helpers accept compact results with metadata or plain data frames with explicit counts, proportions, and denominators. Missing denominators are never reconstructed by summing a possibly filtered count table.

Transition and Documentation

freq_table(mtcars, cyl, am) now errors with the grouped replacement. Use percent = TRUE, overall = TRUE, se = TRUE, critical_value = TRUE, and generic_col_names = TRUE for rich output. The migration vignette includes explicit old/new column mappings.

The example fixture is A/no=3, A/yes=7, B/no=4, B/yes=2 (total 16). Five executable vignettes cover descriptive tables, intervals, tests, formatting/sample-size labels, and migration. A coverage inventory maps all seven exports, three S3 methods, and their 40 formal arguments to examples.