Skip to contents

spicy: descriptive statistics, summary tables, and data management

Source: R/spicy-package.R
spicy-package.Rd

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, regression coefficient tables for one or several fits side by side (thirty-plus supported model classes), 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):

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

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

broom output shape

The broom::tidy() and broom::glance() methods on spicy_categorical_table, spicy_continuous_table, spicy_continuous_lm_table, and spicy_regression_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 keep the types downstream broom-consumers expect: test degrees of freedom that are integer by construction (chi-squared, factor-comparison F tests) stay integer, while every degrees-of-freedom column that can be fractional – df.residual, the regression method's per-coefficient df, and Welch-corrected test df – is numeric double, 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 or content (not a data.frame, length mismatch, bit64::integer64 columns, degenerate grouping).

  • 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_ame_satt_unsupported_formula – signaled together with spicy_unsupported when AME Satterthwaite degrees of freedom are unavailable for the model's formula structure; normally caught internally and surfaced as a spicy_fallback warning.

  • spicy_unsupported_class – the model class has no regression-frame method, so table_regression() cannot render it.

  • spicy_unsupported_vcov – the requested vcov mode is not available for this model class.

  • spicy_unsupported_standardized – the requested standardized mode is not available for this model class.

  • spicy_invalid_frame – an object failed the structural validation of the internal regression-frame contract behind table_regression().

  • spicy_resampling_failed – bootstrap / jackknife resampling produced too few valid replicates to estimate the requested statistic.

  • spicy_defunct – an argument removed in a pre-1.0 hard break; the message names the replacement. Signaled together with spicy_invalid_input so generic input handlers still catch it.

  • spicy_internal – an internal precondition failed; this is a bug in spicy, please report it.

  • spicy_internal_invariant – an internal consistency check on a spicy-built object failed and the result cannot be trusted (see the warning leaf of the same name for the renderable case).

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_caveat – the computation succeeded but its interpretation carries a non-trivial methodological caveat (e.g., standardized coefficients on non-additive terms).

  • spicy_bayes_diagnostics – signaled together with spicy_caveat when a Bayesian fit's sampler or predictive-accuracy diagnostics miss their targets (R-hat, ESS, divergences, E-BFMI, Pareto k, p_waic).

  • spicy_model_choice – a defaulted modeling choice was made on the user's behalf and is disclosed (e.g., the linear probability model table_regression_uv() fits to a binary outcome under the default method).

  • spicy_passthrough – a third-party warning captured during an operation (e.g., the clipboard copy) and re-emitted under the spicy taxonomy.

  • 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()).

  • spicy_internal_invariant – an internal consistency check on a spicy-built object failed but the output still renders, so the user sees both the table and the diagnostic.

spicy_info

Parent for informational messages (emitted via rlang::inform(); muffle with withCallingHandlers(spicy_info = ...)). Leaf: spicy_silent_reference – reference levels are displayed nowhere under reference_style = "none" with factor_layout = "flat". The once-per-session hint on ordered-factor polynomial contrasts carries its own class, spicy_polynomial_contrasts_info.

See also

Useful links:

Author

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

Authors: