spicy: descriptive statistics, summary tables, and data management

spicy provides tools for descriptive data analysis, variable inspection, and tabulation workflows: frequency tables, cross-tabulations with chi-squared tests and effect sizes, association measures for contingency tables, categorical and continuous summary tables, model-based linear-regression tables with optional additive covariate adjustment, row-wise descriptive summaries, interactive codebooks, variable-label extraction, and clipboard export.

API stability

spicy is in active pre-1.0 development. Breaking changes are made deliberately at minor-version bumps and are always announced in NEWS.md. The API surface is partitioned as follows; users planning to embed spicy in production pipelines or downstream packages should rely on the stable surface.

Stable (signature and behaviour preserved across 0.y.z and into 1.0.0; documented changes only):

• Frequency / cross-tabs: freq(), cross_tab()

• Variable inspection: varlist() / vl(), code_book(), label_from_names()

• Row-wise summaries: mean_n(), sum_n(), count_n()

• Clipboard export: copy_clipboard()

• Association measures (point estimates and documented CIs): cramer_v(), phi(), contingency_coef(), yule_q(), gamma_gk(), kendall_tau_b(), kendall_tau_c(), somers_d(), lambda_gk(), goodman_kruskal_tau(), uncertainty_coef()

Stabilising (still maturing; argument names may be tightened before 1.0 with a NEWS.md entry, but no silent behavioural changes):

• Summary table builders: table_categorical(), table_continuous(), table_continuous_lm()

• Omnibus association overview: assoc_measures()

Internal API (not part of the public surface; can change without notice – avoid calling directly from downstream code):

• ASCII rendering primitives: build_ascii_table(), spicy_print_table()

broom output shape

The broom::tidy() and broom::glance() methods on spicy_freq_table, spicy_categorical_table, spicy_continuous_table, and spicy_continuous_lm_table follow the standard broom column conventions (outcome, term, estimate, std.error, conf.low, conf.high, statistic, p.value, df, df.residual, r.squared, adj.r.squared, nobs, ...). The set of columns produced by each method is considered stabilising: existing columns will not be silently renamed or have their semantics changed within 0.y.z, and any breaking change is announced in NEWS.md. Adding optional new columns (e.g. covariate-adjustment metadata) is not a breaking change. Numeric columns are always returned with the type downstream broom-consumers expect: df integer, df.residual numeric (so Satterthwaite-corrected degrees of freedom from cluster-robust variance modes are preserved verbatim, matching lmerTest::glance() and the afex output convention).

Classed conditions

All errors and warnings emitted by the stable / stabilising surfaces carry classed conditions so downstream code can dispatch on class via tryCatch() / withCallingHandlers() instead of matching message strings. Each condition has a package-wide parent class plus a leaf class describing the specific cause:

spicy_error

Catch-all parent for every error raised by spicy. Leaves:

• spicy_invalid_input – bad argument value or type.

• spicy_invalid_data – bad data shape (not a data.frame, NA cells where forbidden, length mismatch).

• spicy_missing_pkg – a Suggests dependency is required by the requested operation but not installed.

• spicy_missing_column – a referenced column is not in data.

• spicy_unsupported – the operation is not applicable to this input (e.g., Phi requested on a non-2x2 table).

spicy_warning

Catch-all parent for every warning. Leaves:

• spicy_undefined_stat – the requested statistic is undefined for this input; result is NA (e.g., Tau-b on a table with all-zero marginals).

• spicy_dropped_na – NA observations were silently excluded from the computation (e.g., NA weights).

• spicy_ignored_arg – an argument was ignored due to context (e.g., correct = TRUE on a non-2x2 table).

• spicy_no_selection – a column selector produced an empty set; an empty result is returned rather than erroring.

• spicy_fallback – the requested computation failed; a simpler estimator was used instead.

• spicy_summary_failed – varlist() could not summarise one column; the rest of the table is fine.

• spicy_renamed_column – a user data column or factor level collided with a spicy-internal name and was auto-renamed to preserve the data (emitted by cross_tab()).

See also

Useful links:

• https://github.com/amaltawfik/spicy/

• https://amaltawfik.github.io/spicy/

• Report bugs at https://github.com/amaltawfik/spicy/issues

Author

Maintainer: Amal Tawfik amal.tawfik@hesav.ch (ORCID) (ROR) [copyright holder]

Authors:

• Amal Tawfik amal.tawfik@hesav.ch (ORCID) (ROR) [copyright holder]