Package {spicy}

Title:	Publication-Ready Tables for Descriptive Statistics and Regression Models
Version:	0.14.0
Description:	Provides publication-ready tables for descriptive statistics and regression models: frequency tables and cross-tabulations with association measures (Cramér's V, Kendall's Tau-b, and others), categorical and continuous summary tables, by group or from a complex survey design, and regression tables for one or more models side by side, across more than thirty model classes from mixed-effects to survival and Bayesian, with robust standard errors, average marginal effects, and univariable screening. Tables follow APA conventions by default, can switch to named journal styles such as JAMA, NEJM, or The Lancet, and render identically in the console and in 'gt', 'tinytable', 'flextable', 'Word', 'Excel', or the clipboard. Declared missing values in labelled data are honored and disclosed throughout the descriptive tables. Helpers cover codebooks, variable inspection, and row-wise summaries.
License:	MIT + file LICENSE
URL:	https://amaltawfik.github.io/spicy/, https://github.com/amaltawfik/spicy
BugReports:	https://github.com/amaltawfik/spicy/issues
Encoding:	UTF-8
Language:	en-US
Imports:	crayon, dplyr, labelled, rlang (≥ 1.1.0), sandwich (≥ 3.1-2), stats, stringr, tibble, tidyselect, utils
Suggests:	bit64, boot, broom, car, clipr, clubSandwich, effectsize, emmeans, estimatr (≥ 1.0.0), fixest (≥ 0.11), flexsurv (≥ 2.2), flextable, geepack (≥ 1.3.9), gt, haven, hms, htmltools, insight, glmmTMB (≥ 1.1.7), knitr, lme4 (≥ 1.1-35), lmerTest (≥ 3.1-3), lmtest, merDeriv (≥ 0.2.6), marginaleffects, modelsummary, collapse, MASS, mgcv (≥ 1.9), nlme (≥ 3.1-160), nnet, numDeriv, ordinal (≥ 2022.11), AER (≥ 1.2), betareg (≥ 3.1), mlogit (≥ 1.1), pscl (≥ 1.5), quantreg (≥ 5.86), quarto, RLRsim, reformulas, rms (≥ 6.7), sampleSelection (≥ 1.2), posterior (≥ 1.5.0), rstanarm (≥ 2.21), brms (≥ 2.20), loo (≥ 2.6), rstan, survey (≥ 4.5), survival (≥ 3.5), officer, openxlsx2, parameters, pdftools, performance, rmarkdown, spelling, testthat (≥ 3.0.0), tinytable, withr
VignetteBuilder:	knitr
Depends:	R (≥ 4.1.0)
Config/testthat/edition:	3
LazyData:	true
Config/roxygen2/version:	8.1.1
NeedsCompilation:	no
Packaged:	2026-10-31 00:59:50 UTC; at
Author:	Amal Tawfik [aut, cre, cph]
Maintainer:	Amal Tawfik <amal.tawfik@hesav.ch>
Repository:	CRAN
Date/Publication:	2026-10-31 08:10:10 UTC

spicy: publication-ready tables for descriptive statistics and regression models

Description

spicy provides publication-ready tables for descriptive statistics and regression models: frequency tables and cross-tabulations with association measures, categorical and continuous summary tables (by group or from a complex survey design), and regression tables for one or more models side by side, across more than thirty model classes, with robust standard errors, average marginal effects, and univariable screening. Tables follow APA conventions by default, can switch to named journal styles, and render identically in the console and the rich outputs. Declared missing values in labelled data are honored and disclosed throughout the descriptive tables; helpers cover codebooks, variable inspection, and row-wise summaries.

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 behavior preserved across 0.y.z and into 1.0.0; documented changes only):

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

• Variable inspection: varlist() / vl(), 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()

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

• Summary table builders: table_categorical(), table_continuous(), table_continuous_lm(), table_outcome(), and var_labels() for their labels

• Survey-design summary tables: table_continuous_svy(), table_categorical_svy()

• Regression tables: table_regression(), table_regression_uv(), table_regression_models(), as_structured()

• Inline citation: inline()

• Table styles: spicy_style(), spicy_style_names()

• Omnibus association overview: assoc_measures()

Experimental (new since 0.13.0; the shape of the output and the argument names may still move, with a NEWS.md entry, on their OWN clock rather than the parent family's):

• Display language and label overrides: spicy_labels() (with options(spicy.language) / options(spicy.labels)), since 0.13.0

• Codebooks: code_book() (the spicy_codebook object, its Excel workbook, and its PDF), since 0.14.0

• Multiple-response questions: table_multiresponse(), since 0.14.0

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

• ASCII rendering primitive: spicy_print_table() (build_ascii_table() is no longer exported)

broom output shape

The broom::tidy() and broom::glance() methods of every table class, spicy_categorical_table, spicy_categorical_svy_table, spicy_continuous_table, spicy_continuous_svy_table, spicy_continuous_lm_table, spicy_outcome_table, spicy_multiresponse_table, and spicy_regression_table, and the output = "long" frame of every table function, speak one vocabulary: broom's name wherever broom defines one, and one snake_case name per concept otherwise, the same in every function. One exception, the estimates: tidy() gives them broom's names, and the long output of a descriptive table names each statistic it holds (see the table below).

variable holds the name of the column a row describes and label its displayed label. outcome names the response of a regression model and the single outcome of table_outcome(). group is a key of the tables that take a by (table_categorical(), table_categorical_svy(), table_continuous(), table_continuous_svy() and table_multiresponse()): their tidy() carries it with or without by, NA without. table_outcome() has no group: its groupings are the level of each block. Nor has table_continuous_lm(), whose by sets the columns of the table: its levels are the level of the long output and the term of the "emmean" rows of tidy(). A fit statistic is a column of glance() and of the long output, under broom's name, and a row of output = "data.frame" (.row_role "fit_stat"), keyed in variable by its show_fit_stats token, the token inline() takes: r2 is the row of the column r.squared. The proportions of tidy() are between 0 and 1, and the Total rows stay, flagged by total. Each role column describes the key column it follows, whatever the orientation of the printed table: .row_role the row's level, .group_role its group. A level or a group added for missing values is told apart by its role, "missing", never by its label, which follows the display language. With by, the long output of table_categorical() and table_continuous() carries the effect-size and SMD columns whether or not they were requested (NA then), and that of table_continuous_lm() and table_outcome() the effect-size columns; the survey tables and table_multiresponse() compute neither. glance() has a fixed set of columns. p_value = FALSE removes from the long output the test columns that neither the statistic nor an effect size needs; glance() keeps them, NA, as does the tidy() of table_continuous_lm(). Model-level statistics (nobs, r.squared, ...) are in glance(). The long output carries them as well where its rows are models of their own: in table_continuous_lm(), one model per outcome (the fit on the first row of the outcome, its size on every row), and in table_regression_uv(), one univariable model per predictor. The long output of table_regression() has the same columns, NA: one shape for the class. The printed objects carry the by column and its label in the attributes group_var and group_label, the label the title gives it (its label in note_labels, when there is one).

output = "data.frame" and as.data.frame() return the table as it is displayed, one row per printed row, with numbers: the key columns variable, label (and the level or group of the row, and .row_role, the role of the printed row, where the table adds rows), then the printed columns under their names. The two are identical for every class. output = "excel" and "word" return the path of the file, invisibly. The columns of the object output = "default" returns are internal and can change without notice: the contracts are output = "data.frame", output = "long", tidy(), glance() and as_structured().

The set of columns produced by each method is considered stabilizing (experimental for table_multiresponse(), as the function itself): 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 / stabilizing 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, data or a design with no rows, length mismatch, bit64::integer64 columns, degenerate grouping).

• spicy_wrong_regime – signaled together with spicy_invalid_data when a table receives the wrong kind of data for its regime: a survey design handed to a plain table, or a data frame handed to a survey twin. The message names the function to use instead.

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

• spicy_missing_quarto – code_book() was asked for a PDF, and Quarto 1.7 or later, which compiles it, was not found.

• spicy_typst_failed – Typst could not compile the PDF of code_book(); the condition carries its messages in stderr.

• spicy_missing_column – a referenced column is not in data; the message names it. Signaled together with spicy_invalid_input.

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

• spicy_not_implemented – signaled together with spicy_unsupported when the request is well formed but spicy does not compute it (e.g., weighted group tests in table_continuous()); the message names an alternative.

• spicy_empty_table – table_regression() has no row left to show for a model once the requested row blocks are switched off.

• 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_structured_version – as_structured() received a table built under an older version of the typed contract; rebuild the table with the current spicy.

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

• spicy_defunct – an argument, or a value of an argument, removed or renamed in a pre-1.0 hard break (e.g., v_digits, effect_size = "eta_sq"); the message names the replacement. Signaled together with spicy_invalid_input so generic input handlers still catch it.

• spicy_bad_authors – the authors argument of code_book() has none of its accepted shapes. Signaled together with spicy_invalid_input.

• spicy_label_collision – a label a summary table adds (the row or column of missing values, the margin, a base row, the Overall row) would be displayed beside a level, a value or a label of yours that reads the same. Signaled together with spicy_invalid_input; the message gives the two ways out.

• 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_negative_weights_no_test – signaled together with spicy_undefined_stat when table_continuous_svy() or table_categorical_svy() withholds a group comparison because the analytic sample carries negatively weighted rows; the estimates are still reported and the table note says so.

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

• spicy_ignored_arg – an argument the call typed has no effect in its context (e.g., correct = TRUE on a non-2x2 table, excel_path without output = "excel"); the warning names that argument and no other.

• spicy_unknown_name – an argument named by variable (labels, note_labels, a named digits, the named list of show_columns) holds a name that matches nothing in the table; the warning names the argument and the name, and the table is built without it.

• spicy_no_selection – a selection or a filter matched nothing, and an empty result is returned rather than an error (the row-wise summaries, varlist(), a levels_keep of table_categorical() that matches no level of a variable, which is left out). In the table functions an empty column selection is an error (spicy_invalid_input).

• spicy_no_match – a keep or drop pattern of table_regression() matched no coefficient term.

• 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_nonconvergence – signaled together with spicy_caveat when the fitting engine reports that its optimizer did not converge. The table still shows the numbers the model object holds, and a footer note says what they are worth.

• 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_typst_warning – Typst warned while compiling the PDF of code_book(), which it still wrote; the condition carries its messages in stderr. Signaled together with spicy_passthrough.

• spicy_summary_failed – varlist() could not summarize 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.

Author(s)

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

Authors:

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

See Also

Useful links:

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

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

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

Coerce a spicy_categorical_svy_table to a data frame or tibble

Description

as.data.frame() returns the table table_categorical_svy() displays, with its numbers: exactly what output = "data.frame" returns. One row per printed row – the header row of each variable, which carries its p-value, then one row per level – and the printed columns under their names ("Female n", "Female %", the interval bounds "Female 95% CI LL" and "Female 95% CI UL", "Female DEff", ..., "p"), plus the key columns variable, label, level and .row_role ("factor_header", "level", or "missing"). The note, as printed, is kept in attr(, "note"). as_tibble() returns the same table as a tibble.

Usage

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

## S3 method for class 'spicy_categorical_svy_table'
as_tibble(x, ...)

Arguments

Value

A plain data.frame (or a tbl_df for as_tibble()), identical to the output = "data.frame" of the same call.

See Also

table_categorical_svy().

Coerce a spicy_categorical_table to a plain data frame or tibble

Description

as.data.frame() returns the table table_categorical() displays, with its numbers: exactly what output = "data.frame" returns. One row per printed row – the header row of each variable, which carries its p-value and its association measure, then one row per level – and the printed columns under their names ("Female n", "Female %", ..., "p", the measure), plus the key columns variable (the column name), label (the label displayed for it), level, and .row_role ("factor_header", "level", "missing" for the row of missing values the table adds, or "total" for the Total row of total_row = TRUE). The note, as printed, is kept in attr(, "note"). as_tibble() returns the same table as a tibble.

Usage

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

## S3 method for class 'spicy_categorical_table'
as_tibble(x, ...)

Arguments

Details

For one row per variable, level and group, use output = "long" or tidy.spicy_categorical_table(). The original x is unaffected, and print(x) continues to render the formatted ASCII table.

Value

A plain data.frame (or tbl_df), identical to the output = "data.frame" of the same call.

See Also

tidy.spicy_categorical_table(), glance.spicy_categorical_table().

Coerce a spicy_continuous_lm_table to a plain data frame or tibble

Description

as.data.frame() returns the table table_continuous_lm() displays, with its numbers: exactly what output = "data.frame" returns. One row per outcome, the key columns variable (the column name of the outcome) and label (the label displayed for it), then the printed columns under their names ("M (<level>)", the contrast, the interval bounds, the test statistic, "p", the fit statistic, the effect size, "n", "Weighted n"); an effect size printed with its interval keeps the bounds beside it as es_ci_lower and es_ci_upper. The note, as printed, is kept in attr(, "note"). as_tibble() returns the same table as a tibble. The original x is unaffected, and print(x) continues to render the formatted ASCII table.

Usage

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

## S3 method for class 'spicy_continuous_lm_table'
as_tibble(x, ...)

Arguments

Details

For one row per level of by with every estimate, use output = "long", tidy.spicy_continuous_lm_table() or glance.spicy_continuous_lm_table().

Value

A plain data.frame (or tbl_df), identical to the output = "data.frame" of the same call.

See Also

tidy.spicy_continuous_lm_table(), glance.spicy_continuous_lm_table() for cleaner broom-style pivots tailored to downstream pipelines.

Coerce a spicy_continuous_svy_table to a plain data frame or tibble

Description

as.data.frame() returns the table table_continuous_svy() displays, with its numbers: exactly what output = "data.frame" returns, the shape of as.data.frame.spicy_continuous_table() (the key columns variable, label and, with by, group and .row_role, then the printed columns under their names). The note, as printed, is kept in attr(, "note"). as_tibble() returns the same table as a tibble.

Usage

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

## S3 method for class 'spicy_continuous_svy_table'
as_tibble(x, ...)

Arguments

Value

A plain data.frame (or a tbl_df for as_tibble()), identical to the output = "data.frame" of the same call.

See Also

table_continuous_svy().

Coerce a spicy_continuous_table to a plain data frame or tibble

Description

as.data.frame() returns the table table_continuous() displays, with its numbers: exactly what output = "data.frame" returns. One row per printed row, the key columns variable (the column name), label (the label displayed for it) and, with by, group and .row_role ("group", or "missing" for the group of missing by values), then the printed columns under their names ("M", "SD", "95% CI LL", ..., "n", "p"). A cell that prints several numbers keeps the first in its column and the others beside it under their names in the long output: df and df.residual after the test statistic "Test", es_ci_lower and es_ci_upper after the effect size "ES" when its interval is printed, q1 and q3 after "Mdn [Q1, Q3]". The note, as printed, is kept in attr(, "note"). as_tibble() returns the same table as a tibble.

Usage

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

## S3 method for class 'spicy_continuous_table'
as_tibble(x, ...)

Arguments

Details

For every statistic the table computes, whatever it displays, use output = "long" or tidy.spicy_continuous_table(). The original x is unaffected, and print(x) continues to render the formatted ASCII table.

Value

A plain data.frame (or tbl_df), identical to the output = "data.frame" of the same call.

See Also

tidy.spicy_continuous_table(), glance.spicy_continuous_table() for cleaner broom-style pivots tailored to downstream pipelines.

Coerce a spicy_multiresponse_table to a plain data frame or tibble

Description

as.data.frame() returns the table table_multiresponse() displays, with its numbers: exactly what output = "data.frame" returns. One row per printed row – the items, the rows of none_row, then the base – with the key columns variable (the item's column, or the token of a row the table adds: "none", "no_data", "nobs" for the base), label (the label displayed) and .row_role ("summary" for an item, "none", "missing", or "fit_stat" for the base), then the printed columns under their names ("<group> n", "<group> %", ..., "Test" with df beside it under statistic = TRUE, "p"). The "note" and "global_test" attributes are kept. as_tibble() returns the same table as a tibble. The original x is unaffected, and print(x) continues to render the formatted table.

Usage

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

## S3 method for class 'spicy_multiresponse_table'
as_tibble(x, ...)

Arguments

Value

A plain data.frame (or tbl_df), identical to the output = "data.frame" of the same call.

See Also

tidy.spicy_multiresponse_table(), glance.spicy_multiresponse_table().

Coerce a spicy_outcome_table to a plain data frame or tibble

Description

as.data.frame() returns the table table_outcome() displays, with its numbers: exactly what output = "data.frame" returns. One row per printed row – the Overall row, then for each grouping its header row, which carries the block's comparison, and its levels – with the key columns variable (the outcome on the Overall row, the grouping elsewhere), label, level and .row_role ("summary", "factor_header", "level", or "missing"), then the printed columns under their names ("M", "SD", ..., "n", "p"). A cell that prints several numbers keeps the others beside it, as in as.data.frame.spicy_continuous_table(). The note, as printed, is kept in attr(, "note"). as_tibble() returns the same table as a tibble. The original x is unaffected, and print(x) continues to render the formatted table.

Usage

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

## S3 method for class 'spicy_outcome_table'
as_tibble(x, ...)

Arguments

Details

For every statistic the table computes, use output = "long" or tidy.spicy_outcome_table().

Value

A plain data.frame (or tbl_df), identical to the output = "data.frame" of the same call.

See Also

tidy.spicy_outcome_table(), glance.spicy_outcome_table().

Convert a spicy_regression_table to a plain data.frame / tibble

Description

as.data.frame() returns the table table_regression() displays, with its numbers: exactly what output = "data.frame" returns. One row per printed row – the coefficients, the header and the levels of each factor, the reference levels, the fit statistics – with the key columns variable (the variable of the row: the term of a coefficient, the factor of a level, the token of a fit statistic such as "nobs" or "r2"), label (the label displayed for that variable, or the text of a fit-statistic row), level (the level of a factor row) and .row_role ("coef", "factor_header", "level", "reference", "fit_stat", ..., the roles of as_structured()), then the printed columns under their names, numeric: the interval of a coefficient is split into its two bounds ("95% CI LL", "95% CI UL"), a fit statistic sits in the first column of its model, and a cell of events over a total (n_events) keeps the events in its column and the total beside it ("<column>: N"). With several models each column name starts with the model's label. The note, as printed, is kept in attr(, "note"). as_tibble() returns the same table as a tibble.

Usage

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

## S3 method for class 'spicy_regression_table'
as_tibble(x, ...)

Arguments

Details

For one row per coefficient with the broom names, use output = "long" or tidy.spicy_regression_table().

Value

A plain data.frame (for as.data.frame()) or a tbl_df (for as_tibble()), identical to the output = "data.frame" of the same call.

See Also

tidy.spicy_regression_table(), glance.spicy_regression_table() for broom-canonical long views.

Convert a spicy flextable output to a plain flextable

Description

table_regression() and table_continuous_lm() return their output = "flextable" tables with a lightweight spicy_flextable class tag whose only job is HTML note styling. Every flextable verb already works on the tagged object; this method returns the clean underlying flextable::flextable() – the note is already part of its footer – for workflows that want the untagged object (e.g. custom knit hooks, flextable::save_as_docx() pipelines, or composition with other flextable tooling), mirroring gtsummary::as_flex_table().

Usage

as_flextable.spicy_flextable(x, ...)

Arguments

Details

Rendering in Quarto / R Markdown does NOT require this conversion: the knit_print method auto-detects the output format and delegates to flextable's native rendering for non-HTML targets (Word, PowerPoint, PDF).

Value

A flextable object.

Extract the typed (structured) view of a spicy table

Description

spicy's tables return a display representation by default – a character data.frame with stars suffixes, en-dash for reference rows, bracketed "[L, U]" confidence intervals, and APA padding on p-values. This accessor returns the typed view that the output engines (Excel, gt, tinytable, flextable, clipboard) consume internally: a fully numeric body with CI pre-split into LL / UL columns, NAs for non-applicable / reference cells, plus per-cell markers and a format specification.

Usage

as_structured(x)

Arguments

Details

This is the right entry point for users who want to:

• Filter coefficients programmatically, e.g. as_structured(tbl)$body[which(as_structured(tbl)$body$p < 0.05), ] (which() drops the structurally empty rows – factor headers, reference levels – whose p is NA; a bare logical index would keep them as all-NA rows).

• Aggregate raw values across rows, e.g. mean(as_structured(tbl)$body[["B"]], na.rm = TRUE).

• Build a custom downstream renderer that consumes the same structured contract as spicy's built-in engines.

Value

A list with the structured view (see Details for the schema).

Schema

• version – integer contract version (see Versioning below).

• body – data.frame with a Variable character column, one or more numeric value columns, and four dot-prefixed identity columns at the end. Confidence intervals are split into a lower and an upper column, named as each family names them: "95% CI: LL" / "95% CI: UL" in a regression table (prefixed with the model label in multi-model output), "95% CI LL" / "95% CI UL" in table_continuous(), table_continuous_lm(), table_outcome() and table_continuous_svy(), "CI lower" / "CI upper" for the association measure of table_categorical(), and "<group> % CI lower" / "<group> % CI upper" in table_categorical_svy(). A cell with no value (reference level, term absent from a model, factor header) is NA.

• body$.variable – source variable of the row: the factor name on a factor header / level / reference row, the term otherwise, and the fit-statistic token ("nobs", "r2", "fixed_effects", ...) on a fit-statistic row.

• body$.level – the factor level (or the absorbed factor of a fixed-effects block, or the grouping factor of an "N (...)" row); NA outside a factor.

• body$.row_role – what the row is: "coef", "factor_header", "level", "reference", "fit_stat", "outcome", "vc" (variance component) in a regression table, plus "summary" (a row summarizing one variable), "group" (a row keyed by one level of by), "missing" (a row keyed by the missing value), "none" (the respondents who chose no item of a multiple-response question) and "total" (the Total row of table_categorical() under total_row = TRUE) in the descriptive ones. The role is the key a consumer matches on: "(Missing)" is a display label – translatable, and relabeled through options(spicy.labels) – and the role survives both.

• body$.indent – display indent depth of the label (0 or 1). Renderers indent .indent > 0 rows; the label text itself is already indented in the character body only.

• cell_status – per-cell semantics, keyed by column name, one character vector as long as body per column that needs one: "reference" (reference level, in this estimate block and this model), "undefined" (the statistic applies to the row but no number expresses it – an unavailable variance-component standard error, a fit statistic undefined for one model's class), "" otherwise. Both marked statuses display as an en-dash. A cell whose value is NA with no status is absent and displays blank. Columns with no marked cell are omitted.

• outcome_labels_by_col – for the outcome row (explicit outcome_labels with two or more models), the display label keyed by each model's first structured column name.

• col_meta – per-column metadata keyed by structured column name (token, model_id, precision, p-style, below-threshold, CI pair / role / label). A column whose cells cannot be reconstructed from one number – the "events/N" counts of show_columns = "n_events" – also carries display_cells, a character vector as long as body holding the display string of each cell (NA where the number formats normally). A renderer must prefer it over the numeric value.

• stars – NULL unless stars was requested, otherwise a list with thresholds (symbol to p cutoff) and markers (per-cell marker strings, keyed by column name, "" where a cell takes none).

• spanners – named list mapping a grouping label to its column indices in body: the model labels of a multi-model regression table, the by levels of a categorical one (each spanning its n / ⁠%⁠ pair).

• ci_pairs – list of ⁠(label, cols)⁠ entries describing each CI pair in body.

• format_spec – global format defaults (decimal mark, digits, p-style, CI level, etc.).

Descriptive tables

The descriptive tables return the same schema; only the col_meta tokens and the row roles they emit differ. table_outcome() has the columns of table_continuous() and the rows of table_categorical(): a "summary" row for the whole sample, then a "factor_header" row per grouping and its "level" (or "missing") rows. The survey twins follow the table they twin, table_categorical_svy() with the interval of each percentage (token "prop_ci") and no association measure.

• table_categorical() – one "factor_header" row per variable then one "level" (or "missing") row per category, and under total_row = TRUE the "total" row that closes each block, exactly as the console lays them out. Tokens: "n", "pct", "p", "assoc" (the association measure), "assoc_ci" (its bounds) and "smd" (the standardized mean difference, when smd = TRUE). In a by table each group owns an n / ⁠%⁠ pair with its own spanner, and the margin column is flagged ⁠col_meta$<col>$total⁠, never matched on the label "Total".

• table_continuous() – one "summary" row per variable, or one "group" row per level of by ("missing" for the missing-by group), with the level in .level. Tokens are the show_columns vocabulary itself ("m", "sd", "med", "iqr", "med_iqr", "q1", "q3", "min", "max", "ci", "med_ci", "n", "weighted_n") plus "statistic", "p", "es" and "smd" for the group comparison – the last four are col_meta tokens without being show_columns values, because they belong to a comparison BETWEEN groups rather than to any one group. A statistic another variable displays is absent (NA, no status); one that applies but has no value is "undefined".

• table_continuous_lm() – one "summary" row per outcome. Tokens: "emmean" (a marginal mean; the column says which level in ⁠col_meta$<col>$level⁠, also its display_label: the table heads each mean by its level under the mean symbol), "delta" (the contrast), "b" (a numeric predictor's slope), "ci", "statistic", "p", "r2", "es", "n", "weighted_n".

• table_multiresponse() – one "summary" row per item, then the rows of none_row: a "none" row (.variable == "none") for the respondents of the base with no item chosen and a "missing" row (.variable == "no_data") for those with no data for the question, then one "fit_stat" row (.variable == "nobs") holding the respondents of each group. Tokens: "n", "pct" (percentage of cases), "pct_responses" (percentage of responses), "statistic" and "p". Each group owns its columns under its own spanner, and the margin is flagged ⁠col_meta$<col>$total⁠.

Cells the console builds from more than one number – a "Mdn [Q1, Q3]", a test gloss, an effect size with its interval – keep their numeric anchor in body and their exact printed string in ⁠col_meta$<col>$display_cells⁠. So does a cell of a variable that a named digits gives decimals other than the column's precision, which stays the table's digits. stars is always NULL: descriptive tables carry no significance markers.

Under p_adjust, the p-value column holds the adjusted values and its col_meta adds p_adjust (the method), p_adjust_m (the number of tests adjusted together) and p_unadjusted (the raw p-value of each cell, as long as body). In table_categorical() and table_multiresponse(), the p-value column's col_meta also carries test_type, the test of each cell, as long as body ("chi_squared", "n1_chi_squared", "fisher_exact", "fisher_midp", "fisher_exact_mc", NA where the cell holds no p-value).

Versioning

version says which contract an object carries. Version 3 moved row identity out of index vectors and into the body itself:

• reference_rows and reference_models_by_row become cell_status, which marks the reference cell instead of the whole row – the row-scoped flag was blanking estimate blocks that have no per-level reference at all.

• factor_header_rows becomes .row_role == "factor_header".

• fit_stat_rows becomes .row_role == "fit_stat".

• level_rows becomes .indent > 0.

• outcome_row becomes .row_role == "outcome".

Index vectors are the structure that corrupts as soon as two bodies are stacked or merged, so they were removed rather than kept alongside. An object carrying an older contract (or none) is refused with the correspondence above; rebuild it with the function that produced it. An object carrying a newer contract than the spicy reading it is refused as well.

Version 3 also opened the accessor to the descriptive families, which had no typed view before: .row_role gained "summary", "group" and "missing", then "none" with table_multiresponse() and "total" with the total_row of table_categorical(). The vocabulary is extended by addition – an existing role never changes meaning.

Version 4 renames one component: in the format_spec of table_categorical(), the number of decimals of the association measure and the SMD is effect_size_digits, the key of the other tables, where it was v_digits (the argument was renamed alike). An object carrying version 3 is refused as an older contract.

See Also

table_regression(), table_categorical(), table_continuous(), table_continuous_lm() for the user-facing entry points.

Examples

fit <- lm(mpg ~ wt + factor(cyl), data = mtcars)
tbl <- table_regression(fit)
s <- as_structured(tbl)
s$body                               # raw numeric body
s$body[which(s$body$p < 0.05), ]     # filter significant rows
# which() drops the structural NA rows (headers, reference levels)
s$body$.row_role                     # what each row is
s$body[s$body$.variable == "wt", ]   # address a row by its variable
s$col_meta$B                         # column metadata for B

# The same schema on a descriptive table.
ct <- table_categorical(mtcars, c(cyl, gear), by = am)
sc <- as_structured(ct)
sc$body[, c("Variable", ".variable", ".level", ".row_role")]
sc$spanners                          # one per `by` group

Association measures summary table

Description

assoc_measures() computes a range of association measures for a two-way contingency table and returns them in a tidy data frame.

Usage

assoc_measures(
  x,
  type = c("all", "nominal", "ordinal"),
  conf_level = 0.95,
  digits = 3L
)

Arguments

Details

type = "all" (the default) returns all nominal and ordinal measures. Use type = "nominal" or type = "ordinal" to restrict the output to a single family.

The nominal family includes cramer_v(), contingency_coef(), lambda_gk(), goodman_kruskal_tau(), uncertainty_coef(), and (for 2x2 tables) phi() and yule_q().

The ordinal family includes gamma_gk(), kendall_tau_b(), kendall_tau_c(), and somers_d().

Measures that are undefined on the given table appear as NA rows (printed as an en dash). The classed warnings the individual functions raise (e.g. spicy_undefined_stat) are re-emitted once per distinct message after the table is assembled, so condition handlers and suppressWarnings() behave as they do for the individual functions.

Standard error formulas follow the DescTools implementations (Signorell et al., 2024), except for Kendall's Tau-b, whose ASE follows Brown and Benedetti (1977) as printed by SPSS / PSPP CROSSTABS; see kendall_tau_b().

Value

A data frame with columns measure, estimate, se, ci_lower, ci_upper, and p_value. The p_value comes from two test families:

• Pearson chi-squared test of independence for Cramér's V, Phi, and the Contingency Coefficient (the three chi-squared-derived nominal measures). All three carry the same chi-squared p-value on a given table.

• Wald z-test of H0: measure = 0 for every other measure: Yule's Q, Lambda, Goodman-Kruskal's Tau, the Uncertainty Coefficient, and all ordinal measures (Gamma, Tau-b, Tau-c, Somers' D).

Direction-dependent measures (lambda_gk(), goodman_kruskal_tau(), uncertainty_coef(), somers_d()) contribute one row per direction (symmetric / R|C / C|R where applicable), so the output has more rows than the number of helper functions.

References

Agresti, A. (2002). Categorical Data Analysis (2nd ed.). Wiley.

Brown, M. B., & Benedetti, J. K. (1977). Sampling behavior of tests for correlation in two-way contingency tables. Journal of the American Statistical Association, 72(358), 309-315. doi:10.1080/01621459.1977.10480995

Liebetrau, A. M. (1983). Measures of Association. Sage.

Signorell, A. et al. (2024). DescTools: Tools for Descriptive Statistics. R package.

See Also

cramer_v(), gamma_gk(), kendall_tau_b()

Other association measures: contingency_coef(), cramer_v(), gamma_gk(), goodman_kruskal_tau(), kendall_tau_b(), kendall_tau_c(), lambda_gk(), phi(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$smoking, sochealth$education)
assoc_measures(tab)
assoc_measures(tab, type = "nominal")
assoc_measures(tab, type = "ordinal")

Build a formatted ASCII table

Description

Low-level rendering engine that constructs a visually aligned ASCII table from a data.frame. Supports Unicode line-drawing characters, ANSI colors via crayon, automatic colored-text-aware width detection, configurable padding, and per-column alignment.

Usage

build_ascii_table(
  x,
  padding = 2L,
  first_column_line = TRUE,
  row_total_line = TRUE,
  bottom_line = FALSE,
  lines_color = "darkgrey",
  align_left_cols = c(1L, 2L),
  align_center_cols = integer(0),
  center_headers = FALSE,
  spanners = NULL,
  group_sep_rows = integer(0),
  total_row_idx = NULL,
  display_labels = NULL,
  ...
)

Arguments

Details

Most users should not call this directly: it is wrapped by spicy_print_table() and the internal ⁠print.spicy_*⁠ methods, which add titles, notes, and table-type-aware alignment defaults. Reach for build_ascii_table() only when you need to render an arbitrary data.frame to a string with the same look as spicy's tables.

Value

A single character string containing the full ASCII-formatted table, suitable for direct printing with cat().

See Also

spicy_print_table() for a user-facing wrapper that adds titles and notes.

Build a codebook of a data frame

Description

code_book() documents the variables of a data frame: one row per variable (position, name, label, type, valid and missing counts, summary statistics), and one row per category of its categorical and logical variables (code, label, count, percentages). The codebook prints as the list of variables, and output writes it to an Excel workbook or to a PDF.

Counts and percentages are unweighted: they describe the data file and are not estimates for a population.

Usage

code_book(
  x,
  ...,
  title = "Codebook",
  subtitle = NULL,
  authors = NULL,
  notes = NULL,
  source = NULL,
  values = 100,
  range = TRUE,
  factor_levels = c("all", "observed"),
  user_na = TRUE,
  decimal_mark = NULL,
  font = NULL,
  font_code = NULL,
  font_size = 10,
  colors = NULL,
  paper = c("a4", "letter"),
  index_columns = NULL,
  output = NULL
)

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

Arguments

Details

The type of a variable is read off its R class, never guessed: a factor is categorical (nominal), an ordered factor categorical (ordinal), a haven_labelled vector categorical (labelled codes), an integer or double vector numeric, a logical, character, or Date vector logical, text, or date, a POSIXct or POSIXlt vector date-time, and an hms vector time. The level of measurement comes from the declaration alone: a factor whose order was not declared with ordered() is nominal. A vector of any other class is shown by its first class (difftime, ...), without statistics. The R class stays in its own column. A haven_labelled vector without value labels is numeric, or text when it stores characters, and so is one whose value labels all sit on declared missing codes, with user_na = TRUE.

values lists the categories of factors and labelled vectors and the two values of a logical, then the declared missing values of the variable and, when it has any, a row for its system missing values (code = "NA"). Numeric, text, and date variables have no category rows: they appear in values only through their declared missing values. The codes of a labelled vector come in code order, the levels of a factor in level order. An explicit NA level of a factor (from addNA()) counts as missing, in the row of the system missing values.

Dates are written as YYYY-MM-DD, date-times as ⁠YYYY-MM-DD HH:MM:SS⁠ followed by the name of the time zone the variable carries, or UTC when it carries none, and times as HH:MM:SS.

The words the codebook adds (column headers, types, field and sheet names) follow options(spicy.language) when the codebook is built (see spicy_labels()); the variable and value labels of the data are never translated.

print() shows a line break or a tab in a label as a space, and shortens long variable labels, counting display columns, when that makes the list fit the console; the object keeps the labels whole.

Value

A spicy_codebook object, returned invisibly when output is given: a list with

header

A list: title, subtitle, authors (a tibble with name, affiliation, and orcid), date, n_obs, n_vars, notes (blank notes dropped), and declared_missing, a tibble of the declared missing values found in the data and, under factor_levels = "all", of the declared codes no observation carries, sorted by code then label (code, label, variables, n_variables).

variables

A tibble, one row per variable: position (the column's position in x), name, label, type, class, source, n_valid, n_missing, n_declared_missing, declared_codes (the na_values and na_range of a haven_labelled_spss vector, as text, the two parts separated by a semicolon; NA without them or under user_na = FALSE), n_distinct (the distinct values observed, of any variable), n_categories (the categories a categorical or logical variable declares, its levels, codes, or TRUE and FALSE, whether values lists them all or not; NA for a numeric, text, or date variable; it exceeds n_distinct when a category has no observation, and the Excel workbook shows it as "Categories" next to "Distinct values"), then min, max, mean, sd, and median for numeric variables and earliest and latest for dates and times. range = FALSE drops min, max, earliest, and latest.

values

A tibble, one row per value: position and variable (of the variable), code, label, declared_missing, n, pct_total, and pct_valid. The row of the system missing values (code = "NA") exists only for a variable that has missing values.

The attributes language and decimal_mark record the language and the decimal mark the codebook was built with, and appearance the look of its PDF: a list of font, font_code, font_size, colors (all eight), paper, and index_columns.

Excel output

The workbook has three worksheets, named in the language of the codebook. The first, codebook, holds the header as field-value pairs: title, subtitle, one row per author, date, numbers of observations and variables, declared missing values, notes, and the versions of spicy and R that wrote it, with the date and time of writing. The other two, variables and values, hold the two tables of the object from the first row, under the column headers the console and the PDF show (code is "Value", n_valid "Valid"), with a frozen header and filters; in variables, the position, name, and label stay in view while the statistics scroll. The workbook always has the same columns, in the same order: a column that does not apply to a variable, or to any variable of the file, is empty, never left out. Numbers stay numeric cells at their full precision, shown as the PDF shows them: the percentages to one decimal, the mean, SD, and median of a variable to three significant digits of its SD; a statistic that is not finite (of a column holding Inf) is an empty cell, and dates stay text, written as above. Each worksheet prints in landscape, fitted to the width of the page, its header row on every page.

PDF output

The PDF opens on a cover: the word "Codebook" above the title (unless the title already contains it), the subtitle, the authors with their affiliations and ORCID addresses, the date, and at the foot the versions of spicy and R that made it. A page about the data follows (numbers of observations and variables, then the notes and the declared missing values), then the list of variables with the page of each.

One sheet per variable comes next, under the heading "Variable sheets": a dark band with the position, name, and type (a name over 45 characters takes a row of its own), rows for the label, the declared missing codes, and the source code, then the counts (valid, missing, and distinct values), the statistics, and the table of the values. The number of categories is not among the counts: the table of values shows them, one row each, and a row "Other categories (n)" the rest when values caps the list; n_categories is a column of the object and of the Excel workbook only. On a sheet that lists declared missing codes, a Missing column marks them with M; the row of the system missing values reads "System missing". Minimum and maximum are written at the precision of the data; mean, SD, and median at three significant digits of the SD. A negative statistic takes the minus sign of a printed table, and a code keeps the hyphen the data has, since a reader types it back into a filter; spicy_style(minus_sign = "ascii"), set through options(spicy.style), keeps the hyphen on the statistics too. A sheet breaks across pages only when it does not fit on one; its table of values then repeats its header under "name (continued)". An index of the variables closes the document, sorted by name in byte order, where uppercase letters come before lowercase ones.

code_book() writes the Typst source and compiles it with the Typst that Quarto bundles; Typst warnings, such as a character missing from the fonts, arrive as one R warning of class spicy_typst_warning. Without Quarto, output = "<path>.typ" writes the same source, self-contained: ⁠typst compile⁠ makes the PDF on any machine with Typst 0.12 or later.

Declared missing values

Survey files imported with haven often carry declared missing values: codes such as ⁠8 = Don't know⁠ or 9 = Refused that the source file marks as missing while keeping them distinct from a plain NA. Two kinds of declaration exist: na_values / na_range metadata on haven::labelled_spss() vectors, and tagged missing values created by haven::tagged_na() (the Stata .a, .b, ... convention). haven::read_sav() keeps the na_values / na_range declaration only with user_na = TRUE: its default turns the declared codes into NA on import.

spicy honors the declaration by default (user_na = TRUE): declared missing values are excluded from every statistic exactly like NA – valid percentages, means, chi-squared tests, association measures, row-wise summaries, and group definitions – but they are not erased from display. freq() lists each observed declared value as its own row of the Missing block, with its value label; cross_tab(), table_categorical(), and table_continuous() disclose the exclusion in the table note (⁠Declared missing values removed: x (2).⁠); varlist() counts them as missing in N_valid / NAs / N_distinct while still listing the declared codes in Values; code_book() counts them in n_declared_missing and flags them in its values table.

Every function involved offers the same escape hatch: set user_na = FALSE to ignore the declaration and treat the declared codes as valid values (the behavior of spicy before 0.13.0). Tagged missing values are genuine NAs either way; for them, user_na = FALSE only collapses the per-tag breakdown back into the regular NA count.

See Also

varlist() to explore the variables in the Viewer; freq() for the frequency table of one variable; the article Explore variables and build codebooks.

Other variable inspection: label_from_names(), varlist()

Examples

code_book(sochealth)

cb <- code_book(
  sochealth,
  starts_with("bmi"),
  title = "Social health survey",
  subtitle = "Body mass index",
  authors = c("Jane Doe" = "University of Somewhere"),
  notes = "Simulated data (see ?sochealth)."
)
cb
cb$variables
cb$values

# Labelled survey data: declared missing codes count as missing and are
# flagged in `values`.
if (requireNamespace("haven", quietly = TRUE)) {
  trust <- haven::labelled_spss(
    c(1, 2, 2, 3, 4, 8, 9, 1, NA, 2),
    labels = c(
      "Not at all" = 1, "A little" = 2, "Somewhat" = 3, "A lot" = 4,
      "Don't know" = 8, "Refused" = 9
    ),
    na_values = c(8, 9),
    label = "Trust in the health system"
  )
  code_book(tibble::tibble(trust))$values
}

if (requireNamespace("openxlsx2", quietly = TRUE)) {
  path <- tempfile(fileext = ".xlsx")
  code_book(sochealth, output = path)
}

# The Typst source of the PDF, which `output = "<path>.pdf"` compiles
# when Quarto is installed.
code_book(sochealth, output = tempfile(fileext = ".typ"))

Pearson's contingency coefficient

Description

contingency_coef() computes Pearson's contingency coefficient C for a two-way contingency table.

Usage

contingency_coef(x, detail = FALSE, conf_level = 0.95, digits = 3L)

Arguments

Details

The contingency coefficient is C = \sqrt{\chi^2 / (\chi^2 + n)}. It ranges from 0 (independence) to a maximum that depends on the table dimensions. No standard asymptotic standard error exists, so the confidence interval is not computed.

Value

Same structure as cramer_v(): a scalar when detail = FALSE, a named vector when detail = TRUE. The p-value tests the null hypothesis of no association (Pearson chi-squared test). CI values are NA because no standard asymptotic SE exists for C.

References

Liebetrau, A. M. (1983). Measures of Association. Sage.

See Also

cramer_v(), assoc_measures()

Other association measures: assoc_measures(), cramer_v(), gamma_gk(), goodman_kruskal_tau(), kendall_tau_b(), kendall_tau_c(), lambda_gk(), phi(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$smoking, sochealth$education)
contingency_coef(tab)

Copy data to the clipboard

Description

Copies a data.frame, matrix, 2D or higher array, table, or atomic vector to the system clipboard, ready to paste into a text editor, spreadsheet, or word processor. Wraps clipr::write_clip() (a Suggests dependency); requires clipr to be installed and a clipboard backend to be available on the platform.

Usage

copy_clipboard(
  x,
  row_names_as_col = FALSE,
  row_names = TRUE,
  col_names = TRUE,
  show_message = TRUE,
  quiet = FALSE,
  ...
)

Arguments

Details

Objects that are not data.frames or 2D matrices (atomic vectors, arrays, tables) are automatically coerced to character on the way to the clipboard, as required by clipr::write_clip(). The caller's object is never modified in place; transformations happen on a local copy (see the return value).

Multidimensional arrays (3D and higher) are flattened to a 1D character vector with one element per line. To preserve a tabular layout, extract a 2D slice first, e.g. copy_clipboard(my_array[, , 1]).

Messages and warnings raised by the clipboard backend are re-emitted as regular R conditions, so suppressMessages() / suppressWarnings() work as usual; quiet = TRUE silences them all at once.

Value

Invisibly returns the object as it was sent to the clipboard: identical to x by default, but reflecting the row_names_as_col transformation when one was requested (e.g. a matrix comes back as a data.frame with the promoted row-name column). The function is called for its clipboard side effect.

Examples

# Writes to the system clipboard, so never run by checks:
## Not run: 
if (clipr::clipr_available()) {
  # Data frame
  copy_clipboard(sochealth)

  # Data frame with row names as column
  copy_clipboard(head(sochealth), row_names_as_col = "id")

  # Matrix
  mat <- matrix(1:6, nrow = 2)
  copy_clipboard(mat)

  # Table
  tbl <- table(sochealth$education)
  copy_clipboard(tbl)

  # Array (3D) -- flattened to character
  arr <- array(1:8, dim = c(2, 2, 2))
  copy_clipboard(arr)

  # Recommended: copy 2D slice for tabular layout
  copy_clipboard(arr[, , 1])

  # Numeric vector
  copy_clipboard(c(3.14, 2.71, 1.618))

  # Character vector
  copy_clipboard(c("apple", "banana", "cherry"))

  # Quiet mode (no messages shown)
  copy_clipboard(sochealth, quiet = TRUE)
}

## End(Not run)

Row-wise count of specific or special values

Description

Counts, for each row of a data.frame or matrix, how many times one or more values appear across selected columns. Supports type-safe comparison (allow_coercion = FALSE), case-insensitive string matching (ignore_case = TRUE), and detection of special values (NA, NaN, Inf, -Inf) via special. Designed to flow inside dplyr::mutate() pipelines.

Usage

count_n(
  data = NULL,
  select = tidyselect::everything(),
  exclude = NULL,
  count = NULL,
  special = NULL,
  allow_coercion = TRUE,
  ignore_case = FALSE,
  regex = FALSE,
  verbose = FALSE,
  user_na = TRUE
)

Arguments

Value

A numeric vector of row-wise counts (unnamed), of length nrow(data). Missing values never match a regular count value, so an all-NA row counts 0 unless special targets missing values. If the selection resolves to zero usable columns, a classed warning (spicy_no_selection) is emitted and NA is returned for all rows, as in mean_n() and sum_n().

Strict matching (allow_coercion = FALSE)

Comparison falls back to identical() when types differ, which also inspects factor levels. Two consequences:

• count = "b" does not match a factor "b" value: pass a factor, e.g. count = factor("b", levels = levels(df$x)).

• Even with a factor count, comparisons against columns whose level set differs will return 0. To guarantee a perfect match (label and levels), reuse a value taken from the data itself (e.g. df$x[2]).

Case-insensitive matching (ignore_case = TRUE)

All values are converted to lowercase via tolower() before matching; factor columns are first coerced to character. This mode takes precedence over allow_coercion: equality becomes lowercase string equality, so "b" and "B" match even when allow_coercion = FALSE.

Coercion of count itself

R coerces mixed-type vectors at construction time: count = c(2, "2") becomes c("2", "2") before the function ever sees it. To get type-sensitive matching, keep count homogeneous.

Declared missing values

Survey files imported with haven often carry declared missing values: codes such as ⁠8 = Don't know⁠ or 9 = Refused that the source file marks as missing while keeping them distinct from a plain NA. Two kinds of declaration exist: na_values / na_range metadata on haven::labelled_spss() vectors, and tagged missing values created by haven::tagged_na() (the Stata .a, .b, ... convention). haven::read_sav() keeps the na_values / na_range declaration only with user_na = TRUE: its default turns the declared codes into NA on import.

spicy honors the declaration by default (user_na = TRUE): declared missing values are excluded from every statistic exactly like NA – valid percentages, means, chi-squared tests, association measures, row-wise summaries, and group definitions – but they are not erased from display. freq() lists each observed declared value as its own row of the Missing block, with its value label; cross_tab(), table_categorical(), and table_continuous() disclose the exclusion in the table note (⁠Declared missing values removed: x (2).⁠); varlist() counts them as missing in N_valid / NAs / N_distinct while still listing the declared codes in Values; code_book() counts them in n_declared_missing and flags them in its values table.

Every function involved offers the same escape hatch: set user_na = FALSE to ignore the declaration and treat the declared codes as valid values (the behavior of spicy before 0.13.0). Tagged missing values are genuine NAs either way; for them, user_na = FALSE only collapses the per-tag breakdown back into the regular NA count.

See Also

datawizard::row_count() for a closely related row-wise counter; count_n() adds element-wise type-safe matching, multi-value count, and special-value detection.

Other row-wise summaries: mean_n(), sum_n()

Examples

library(dplyr)
library(tibble)
library(labelled)

# Basic usage
df <- tibble(
  x = c(1, 2, 2, 3, NA),
  y = c(2, 2, NA, 3, 2),
  z = c("2", "2", "2", "3", "2")
)
count_n(df, count = 2)
count_n(df, count = 2, allow_coercion = FALSE)
df |> mutate(num_twos = count_n(count = 2))

# Mixed types and special values
df <- tibble(
  num   = c(1, 2, NA, -Inf, NaN),
  char  = c("a", "B", "b", "a", NA),
  fact  = factor(c("a", "b", "b", "a", "c")),
  date  = as.Date(c("2023-01-01", "2023-01-01", NA, "2023-01-02", "2023-01-01")),
  lab   = labelled(c(1, 2, 1, 2, NA), labels = c(No = 1, Yes = 2)),
  logic = c(TRUE, FALSE, NA, TRUE, FALSE)
)
count_n(df, count = 2)
count_n(df, count = "b", ignore_case = TRUE)
count_n(df, count = "a", select = fact)
count_n(df, count = as.Date("2023-01-01"), select = date)

# Count special values
count_n(df, special = "NA")

# Column selection strategies
df <- tibble(
  score_math    = c(1, 2, 2, 3, NA),
  score_science = c(2, 2, NA, 3, 2),
  score_lang    = c("2", "2", "2", "3", "2"),
  name          = c("Jean", "Marie", "Ali", "Zoe", "Nina")
)
count_n(df, select = c(score_math, score_science), count = 2)
count_n(df, select = starts_with("score_"), exclude = "score_lang", count = 2)
count_n(df, select = "^score_", regex = TRUE, count = 2)
df |> mutate(nb_two = count_n(count = 2))

# Strict type-safe matching with factor columns
df <- tibble(
  x = factor(c("a", "b", "c")),
  y = factor(c("b", "B", "a"))
)

# Coercion: character "b" matches both x and y
count_n(df, count = "b")

# Strict match: fails because "b" is character, not factor (returns only 0s)
count_n(df, count = "b", allow_coercion = FALSE)

# Strict match with factor value: works only where levels match
count_n(df, count = factor("b", levels = levels(df$x)), allow_coercion = FALSE)

Cramér's V

Description

cramer_v() computes Cramér's V for a two-way contingency table, measuring the strength of association between two categorical variables.

Usage

cramer_v(x, detail = FALSE, conf_level = 0.95, digits = 3L)

Arguments

Details

Cramér's V is computed as V = \sqrt{\chi^2 / (n \cdot (k - 1))}, where \chi^2 is the Pearson chi-squared statistic, n is the total count, and k = \min(r, c). The point estimate matches the DescTools (Signorell et al., 2024) and SPSS implementations. The confidence interval uses the Fisher z-transformation on V (\tanh(\mathrm{atanh}(V) \pm z_{\alpha/2} / \sqrt{n - 3})), which differs from the noncentral chi-squared or bootstrap CIs reported by DescTools::CramerV().

Value

When detail = FALSE: a single numeric value (the estimate). When detail = TRUE and conf_level is non-NULL: c(estimate, se, ci_lower, ci_upper, p_value). When detail = TRUE and conf_level = NULL: c(estimate, se, p_value). The p-value tests the null hypothesis of no association (Pearson chi-squared test).

References

Agresti, A. (2002). Categorical Data Analysis (2nd ed.). Wiley.

Brown, M. B., & Benedetti, J. K. (1977). Sampling behavior of tests for correlation in two-way contingency tables. Journal of the American Statistical Association, 72(358), 309-315. doi:10.1080/01621459.1977.10480995

Liebetrau, A. M. (1983). Measures of Association. Sage.

Signorell, A. et al. (2024). DescTools: Tools for Descriptive Statistics. R package.

See Also

phi(), contingency_coef(), assoc_measures()

Other association measures: assoc_measures(), contingency_coef(), gamma_gk(), goodman_kruskal_tau(), kendall_tau_b(), kendall_tau_c(), lambda_gk(), phi(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$smoking, sochealth$education)
cramer_v(tab)
cramer_v(tab, detail = TRUE)
cramer_v(tab, detail = TRUE, conf_level = NULL)

Cross-tabulation

Description

Computes a two-way cross-tabulation with optional weights, grouping (including combinations of multiple variables via interaction()), row / column percentages, and inferential statistics (Chi-squared test with an APA-style association measure).

Both x and y are required; for one-way frequency tables, use freq().

Usage

cross_tab(
  data,
  x,
  y = NULL,
  by = NULL,
  weights = NULL,
  rescale = FALSE,
  percent = c("none", "column", "row"),
  include_stats = TRUE,
  assoc_measure = c("auto", "cramer_v", "phi", "gamma", "tau_b", "tau_c", "somers_d",
    "lambda", "none"),
  assoc_ci = FALSE,
  correct = FALSE,
  simulate_p = FALSE,
  simulate_B = 2000,
  digits = NULL,
  output = c("default", "data.frame"),
  show_n = TRUE,
  decimal_mark = ".",
  p_digits = 3L,
  user_na = TRUE,
  styled
)

Arguments

Value

Depends on output and by:

• output = "default", no by: a spicy_cross_table object (a data.frame carrying rendering metadata as attributes: title, digits, decimal_mark, n_row_idx, n_col_name, and the inferential block when include_stats = TRUE). Printing dispatches to print.spicy_cross_table().

• output = "default", by supplied: a spicy_cross_table_list, i.e. a named list of spicy_cross_table objects (one element per group level, named by that level). Printing dispatches to print.spicy_cross_table_list() which renders each table in turn separated by a blank line.

• output = "data.frame": the same payload returned as a plain data.frame (or named list of data.frames with by), stripped of the ⁠spicy_*⁠ classes and of every metadata attribute (title, note, n_total, chi2, p_value, ⁠assoc_*⁠, ...). For programmatic access to the statistics, read the attributes of the default object, e.g. attr(cross_tab(...), "p_value").

Cell columns are the levels of y; rows are the levels of x. When percent != "none", the N column (or N row) is added according to show_n. When include_stats = TRUE, the result carries a Chi-squared row (statistic, df, p) and an association-measure row (estimate, optional CI via assoc_ci).

Global Options

The function recognizes the following global options that modify its default behavior:

• options(spicy.percent = "column") Sets the default percentage mode for all calls to cross_tab(). Valid values are "none", "row", and "column". Equivalent to setting percent = "column" (or another choice) in each call.

• options(spicy.simulate_p = TRUE) Enables Monte Carlo simulation for all Chi-squared tests by default. Equivalent to setting simulate_p = TRUE in every call.

• options(spicy.rescale = TRUE) Automatically rescales weights so that total weighted N equals the raw N. Equivalent to setting rescale = TRUE in each call. Also read by freq(), so one option governs both tabulators.

These options are convenient for users who wish to enforce consistent behavior across multiple calls: spicy.percent and spicy.simulate_p apply to cross_tab(), and spicy.rescale applies to both cross_tab() and freq(). They can be disabled or reset by setting them to NULL: options(spicy.percent = NULL, spicy.simulate_p = NULL, spicy.rescale = NULL).

Example:

options(spicy.simulate_p = TRUE, spicy.rescale = TRUE)
cross_tab(sochealth, smoking, education, weights = weight)

Declared missing values

Survey files imported with haven often carry declared missing values: codes such as ⁠8 = Don't know⁠ or 9 = Refused that the source file marks as missing while keeping them distinct from a plain NA. Two kinds of declaration exist: na_values / na_range metadata on haven::labelled_spss() vectors, and tagged missing values created by haven::tagged_na() (the Stata .a, .b, ... convention). haven::read_sav() keeps the na_values / na_range declaration only with user_na = TRUE: its default turns the declared codes into NA on import.

spicy honors the declaration by default (user_na = TRUE): declared missing values are excluded from every statistic exactly like NA – valid percentages, means, chi-squared tests, association measures, row-wise summaries, and group definitions – but they are not erased from display. freq() lists each observed declared value as its own row of the Missing block, with its value label; cross_tab(), table_categorical(), and table_continuous() disclose the exclusion in the table note (⁠Declared missing values removed: x (2).⁠); varlist() counts them as missing in N_valid / NAs / N_distinct while still listing the declared codes in Values; code_book() counts them in n_declared_missing and flags them in its values table.

Every function involved offers the same escape hatch: set user_na = FALSE to ignore the declaration and treat the declared codes as valid values (the behavior of spicy before 0.13.0). Tagged missing values are genuine NAs either way; for them, user_na = FALSE only collapses the per-tag breakdown back into the regular NA count.

Examples

# Basic crosstab
cross_tab(sochealth, smoking, education)

# Column percentages
cross_tab(sochealth, smoking, education, percent = "column")

# Weighted (rescaled)
cross_tab(sochealth, smoking, education, weights = weight, rescale = TRUE)

# Grouped by sex
cross_tab(sochealth, smoking, education, by = sex)

# Grouped by combination of variables
cross_tab(sochealth, smoking, education, by = interaction(sex, age_group))

# Ordinal variables: auto-selects Kendall's Tau-b
cross_tab(sochealth, education, self_rated_health)

# 2x2 table with Yates correction
cross_tab(sochealth, smoking, physical_activity, correct = TRUE)

# APA-style p-value precision and European decimal mark
cross_tab(sochealth, smoking, education, decimal_mark = ",", p_digits = 4)

Frequency Table

Description

Creates a frequency table for a vector or variable from a data frame, with options for weighting, sorting, handling labelled data, defining custom missing values, and displaying cumulative percentages.

With output = "default", the function returns a spicy_freq_table object that auto-prints as a spicy-formatted ASCII table via print.spicy_freq_table() and spicy_print_table(); with output = "data.frame", it returns a plain data.frame containing frequencies and proportions.

Usage

freq(
  data,
  x = NULL,
  weights = NULL,
  digits = 1L,
  valid = TRUE,
  cum = FALSE,
  sort = "",
  na_val = NULL,
  labelled_levels = c("prefixed", "labels", "values"),
  factor_levels = c("observed", "all"),
  rescale = FALSE,
  decimal_mark = ".",
  output = c("default", "data.frame"),
  user_na = TRUE,
  styled
)

Arguments

x <- labelled(c(1, 2, 3, 1, 2, 3), c("Low" = 1, "Medium" = 2, "High" = 3))
freq(x, na_val = 1) # Treat all "Low" as missing

Details

Designed to mimic common frequency procedures from SPSS or Stata while integrating the flexibility of R's data structures. The input type (vector, factor, labelled) is auto-detected; see ⁠@param labelled_levels⁠ and ⁠@param factor_levels⁠ for the schema-vs-observed level controls, and ⁠@param na_val⁠ for optional sentinel-value recoding.

Weighting (weights): frequencies and percentages are computed proportionally to the weights. Missing values in weights cause those observations to be dropped from the table entirely (with a warning), matching the behavior of cross_tab() in spicy 0.11.0+. With rescale = TRUE, the remaining (non-NA-weighted) weights are normalized so the total weighted N equals the count of non-NA-weighted rows. With rescale = FALSE, the total weighted N is the actual sum of non-NA weights.

For schema-level inspection without computing frequencies, use varlist(); code_book() documents every variable with the counts of its categories.

Value

With output = "data.frame", a plain data.frame with no extra attributes and columns:

• value - unique values or factor levels

• n - frequency count (weighted if applicable)

• prop - proportion of total

• valid_prop - proportion of valid responses (if valid = TRUE)

• cum_prop, cum_valid_prop - cumulative proportions, between 0 and 1 (if cum = TRUE)

With output = "default" (the default), a spicy_freq_table object: the same data.frame carrying rendering metadata as attributes (digits, data_name, var_name, var_label, class_name, n_total, n_valid, weighted, rescaled, weight_var) used by print.spicy_freq_table(). The object is returned visibly, so a bare freq(...) call auto-prints at the console while f <- freq(...) stays silent (print f to display the table).

Declared missing values

Survey files imported with haven often carry declared missing values: codes such as ⁠8 = Don't know⁠ or 9 = Refused that the source file marks as missing while keeping them distinct from a plain NA. Two kinds of declaration exist: na_values / na_range metadata on haven::labelled_spss() vectors, and tagged missing values created by haven::tagged_na() (the Stata .a, .b, ... convention). haven::read_sav() keeps the na_values / na_range declaration only with user_na = TRUE: its default turns the declared codes into NA on import.

spicy honors the declaration by default (user_na = TRUE): declared missing values are excluded from every statistic exactly like NA – valid percentages, means, chi-squared tests, association measures, row-wise summaries, and group definitions – but they are not erased from display. freq() lists each observed declared value as its own row of the Missing block, with its value label; cross_tab(), table_categorical(), and table_continuous() disclose the exclusion in the table note (⁠Declared missing values removed: x (2).⁠); varlist() counts them as missing in N_valid / NAs / N_distinct while still listing the declared codes in Values; code_book() counts them in n_declared_missing and flags them in its values table.

Every function involved offers the same escape hatch: set user_na = FALSE to ignore the declaration and treat the declared codes as valid values (the behavior of spicy before 0.13.0). Tagged missing values are genuine NAs either way; for them, user_na = FALSE only collapses the per-tag breakdown back into the regular NA count.

See Also

cross_tab() for two-way cross-tabulations; table_categorical() for multi-variable categorical summary tables; varlist() / code_book() for variable inspection; print.spicy_freq_table() for formatted printing; spicy_print_table() for the underlying ASCII rendering engine.

Examples

# Frequency table with labelled ordered factor
freq(sochealth, education)
freq(sochealth, self_rated_health, sort = "-")

library(labelled)

# Simple numeric vector
x <- c(1, 2, 2, 3, 3, 3, NA)
freq(x)

# Plain vector with a sentinel value recoded as missing
freq(c(1, 2, 3, 99, 99), na_val = 99)

# Labelled variable (haven-style)
x_lbl <- labelled(
  c(1, 2, 3, 1, 2, 3, 1, 2, NA),
  labels = c("Low" = 1, "Medium" = 2, "High" = 3)
)
var_label(x_lbl) <- "Satisfaction level"

# Treat value 1 ("Low") as missing
freq(x_lbl, na_val = 1)

# Display only labels, add cumulative %
freq(x_lbl, labelled_levels = "labels", cum = TRUE)

# Display values only, sorted descending
freq(x_lbl, labelled_levels = "values", sort = "-")

# Show all declared factor levels, including unused ones (n = 0).
# The default "observed" mirrors Stata's `tab` and SPSS FREQUENCIES,
# which both drop unused levels.
f <- factor(c("Yes", "No", "Yes"), levels = c("Yes", "No", "Maybe"))
freq(f, factor_levels = "all")

# With weighting
df <- data.frame(
  sex = factor(c("Male", "Female", "Female", "Male", NA, "Female")),
  weight = c(12, 8, 10, 15, 7, 9)
)

# Weighted frequencies (raw weighted counts, the default)
freq(df, sex, weights = weight)

# Weighted frequencies rescaled so the total matches the sample size
freq(df, sex, weights = weight, rescale = TRUE)

# Base R style, with weights and cumulative percentages
freq(df$sex, weights = df$weight, cum = TRUE)

# Piped version (tidy syntax) and sort alphabetically descending ("name-")
df |> freq(sex, sort = "name-")

# European decimal mark (matches `cross_tab()` and the `table_*()` family)
freq(sochealth, education, decimal_mark = ",")

# Plain data.frame return (for programmatic use)
f <- freq(df, sex, output = "data.frame")
head(f)

Goodman-Kruskal Gamma

Description

gamma_gk() computes the Goodman-Kruskal Gamma statistic for a two-way contingency table of ordinal variables.

Usage

gamma_gk(x, detail = FALSE, conf_level = 0.95, digits = 3L)

Arguments

Details

Gamma is computed as \gamma = (C - D) / (C + D), where C and D are the numbers of concordant and discordant pairs. It ignores tied pairs, making it appropriate for ordinal variables with many ties. When the asymptotic standard error is zero (e.g. a perfect association), the Wald z-test is undefined and the p-value is NA, matching the other measures in the family. Standard error formulas follow the DescTools implementations (Signorell et al., 2024); see cramer_v() for full references.

Value

Same structure as cramer_v(): a scalar when detail = FALSE, a named vector when detail = TRUE. The p-value tests H0: gamma = 0 (Wald z-test).

References

Goodman, L. A., & Kruskal, W. H. (1954). Measures of association for cross classifications. Journal of the American Statistical Association, 49(268), 732-764. doi:10.2307/2281536

Brown, M. B., & Benedetti, J. K. (1977). Sampling behavior of tests for correlation in two-way contingency tables. Journal of the American Statistical Association, 72(358), 309-315. doi:10.1080/01621459.1977.10480995

See Also

kendall_tau_b(), kendall_tau_c(), somers_d(), assoc_measures()

Other association measures: assoc_measures(), contingency_coef(), cramer_v(), goodman_kruskal_tau(), kendall_tau_b(), kendall_tau_c(), lambda_gk(), phi(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$education, sochealth$self_rated_health)
gamma_gk(tab)
gamma_gk(tab, detail = TRUE)

Goodman-Kruskal's Tau

Description

goodman_kruskal_tau() computes Goodman-Kruskal's Tau, a proportional reduction in error (PRE) measure for nominal variables.

Usage

goodman_kruskal_tau(
  x,
  direction = c("row", "column"),
  detail = FALSE,
  conf_level = 0.95,
  digits = 3L
)

Arguments

Details

Unlike lambda_gk(), Goodman-Kruskal's Tau uses all cell frequencies rather than only the modal categories, making it more sensitive to association patterns where lambda may be zero. Goodman-Kruskal's Tau is intrinsically directional and has no canonical symmetric form (unlike lambda_gk() or uncertainty_coef()); only "row" and "column" are supported.

Standard error formulas follow the DescTools implementations (Signorell et al., 2024); see cramer_v() for full references.

Value

Same structure as cramer_v(): a scalar when detail = FALSE, a named vector when detail = TRUE. The p-value tests H0: tau = 0 (Wald z-test).

References

Goodman, L. A., & Kruskal, W. H. (1954). Measures of association for cross classifications. Journal of the American Statistical Association, 49(268), 732-764. doi:10.2307/2281536

See Also

lambda_gk(), uncertainty_coef(), assoc_measures()

Other association measures: assoc_measures(), contingency_coef(), cramer_v(), gamma_gk(), kendall_tau_b(), kendall_tau_c(), lambda_gk(), phi(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$smoking, sochealth$education)
goodman_kruskal_tau(tab)
goodman_kruskal_tau(tab, direction = "column", detail = TRUE)

Cite a table cell in inline text

Description

Returns one cell of a spicy table as a character scalar, formatted exactly as the table displays it – same decimals, same p style, same interval punctuation, same journal style. Designed for inline R chunks in Quarto / R Markdown:

Smokers had higher odds (`r inline(tbl, smoking, "Yes", "or")`).

Usage

inline(x, variable, level = NULL, column = NULL, model = NULL)

Arguments

Value

A character scalar.

Addressing

The row is found by identity, not by display text: variable names the source column (.variable in the typed body), level the level (.level). Custom labels, a style, or a translated display never change the call. As a convenience, a variable that matches no source column is looked up among the displayed labels before erroring. The missing-value category is addressed by level = "(Missing)" whatever its displayed (possibly translated or relabeled) label, through its row role, and the Total row of table_categorical() under total_row = TRUE by level = "Total", the same way. Fit statistics are addressed by their token as variable (inline(tbl, "nobs"), inline(tbl, "r2")) or by their label (inline(tbl, "n")). The token is the one show_fit_stats takes ("r2", "adj_r2", "aic", ...), the key of the row in the variable column of output = "data.frame". glance() and the long output name the same statistic as broom does (r.squared, adj.r.squared), a name inline() does not read. Identity comes first: a source column wins over a token or a label of the same name, and an exact label over a fit statistic's label read regardless of case. A variable that still matches the rows of two variables or statistics is refused, and the error names an address for each.

A statistic that belongs to a whole variable rather than to one of its levels sits on the variable's own row: the p of a table_categorical() block, its association measure, its SMD. Leave level out to cite it (inline(tbl, smoking, column = "p")). The same call cites the p of a by-group table_continuous() or table_continuous_svy(), which sits on the first group's row: when one row of the variable alone carries the statistic, that row is the address.

Groups and models

model selects a group of by in every table, by its label or its position, wherever the table sets the groups out: the column spanners of table_categorical(), table_categorical_svy() and table_multiresponse(), the margin included (inline(tbl, smoking, "Yes", "pct", model = "Female")), the per-group columns of table_continuous_lm(), headed Female and Male under the mean symbol M (inline(tbl, bmi, column = "emmean", model = "Female")), and the rows of table_continuous() and table_continuous_svy(), one per group (inline(tbl, bmi, model = "Female")). The group of missing by values is model = "(Missing)". In a multi-model table, model selects the model the same way. The cells that belong to no group (a p, the contrast of table_continuous_lm() and its interval, an association measure) are cited without model. In table_continuous() and table_continuous_svy(), the test, its p, the effect size and the SMD are statistics of the variable, printed once on the row of the first group: inline(tbl, bmi, column = "p"). Asked with model, whichever group it names, they are an error (class spicy_invalid_input) that gives that call.

level names a category shown as a row: the level of a variable, its row of missing values. Until spicy 0.14.0 it also selected the groups of table_continuous(), table_continuous_svy() and table_continuous_lm(): that use is an error (class spicy_defunct) whose message gives the call to use instead.

table_multiresponse() has one row per item, addressed by its column name, then the rows of none_row, addressed as "none" and "no_data", and the base row, the number of respondents, addressed as the fit statistic "nobs": inline(tbl, "nobs", model = "Total"). The item p and statistic belong to no group and are cited without model (inline(tbl, info_internet, column = "p")).

Columns

The column is a token of the typed contract ("b", "se", "p", "ci", "or", "ame", "n", "pct", "m", ... – see as_structured()'s col_meta), never a display header. "ci" composes the interval with the style's brackets and separator, and so does every other interval token the table carries ("med_ci", "ame_ci", "assoc_ci"): each addresses its own bounds. "partial_chi2" cites the statistic alone, without the degrees of freedom the table prints beside it.

Patterns

A column containing ⁠{⁠ is a pattern: each {token} is replaced by the corresponding cell, so one call quotes a full sentence fragment:

inline(tbl, smoking, "Yes", "{or} ({ci_label} {ci}; p = {p})")

{ci_label} inserts the interval label of the interval the pattern cites (⁠95% CI⁠, or ⁠Mdn 95% CI⁠ in a pattern quoting {med_ci}) – the first one when it cites several, the table's first when it cites none. Note that {p} carries the floor operator when the table does (⁠<.001⁠), so write ⁠p {p}⁠ rather than p = {p} in patterns that may hit the floor.

Errors

Every misaddressing is a classed error that lists the available choices: unknown variables list the variables, missing levels list the levels, unknown tokens list the table's tokens, ambiguous models and groups list them. A level that names a group of a by table points to model. A cell the table itself displays as undefined (an aliased coefficient's en-dash) refuses with the reason rather than pasting a dash into a sentence.

See Also

as_structured() for the typed contract behind the addressing.

Examples

fit <- lm(wellbeing_score ~ age + sex, data = sochealth)
tbl <- table_regression(fit)
inline(tbl, age, column = "b")
inline(tbl, sex, "Male", "{b} ({ci_label} {ci}; p {p})")
inline(tbl, "n")

# A group of `by` is a `model`, whether the table sets it out as
# columns or as rows.
ct <- table_categorical(sochealth, select = smoking, by = sex)
inline(ct, smoking, "Yes", "pct", model = "Female")
cn <- table_continuous(sochealth, select = bmi, by = sex)
inline(cn, bmi, model = "Female")
inline(cn, bmi, column = "p")

Kendall's Tau-b

Description

kendall_tau_b() computes Kendall's Tau-b for a two-way contingency table of ordinal variables.

Usage

kendall_tau_b(x, detail = FALSE, conf_level = 0.95, digits = 3L)

Arguments

Details

Kendall's Tau-b is computed as \tau_b = (C - D) / \sqrt{(n_0 - n_1)(n_0 - n_2)}, where n_0 = n(n-1)/2, n_1 is the number of pairs tied on the row variable, and n_2 is the number tied on the column variable. Tau-b corrects for ties and is appropriate for square tables. When the asymptotic standard error is zero (e.g. a perfect association), the Wald z-test is undefined and the p-value is NA, matching the other measures in the family.

The asymptotic standard error is the Brown and Benedetti (1977) ASE1, as printed by SPSS / PSPP CROSSTABS. It deliberately diverges from DescTools::KendallTauB(), whose implementation mis-scales one margin term of the gradient; see cramer_v() for full references.

Value

Same structure as cramer_v(): a scalar when detail = FALSE, a named vector when detail = TRUE. The p-value tests H0: tau-b = 0 (Wald z-test).

References

Kendall, M. G. (1938). A new measure of rank correlation. Biometrika, 30(1-2), 81-93. doi:10.2307/2332226

Brown, M. B., & Benedetti, J. K. (1977). Sampling behavior of tests for correlation in two-way contingency tables. Journal of the American Statistical Association, 72(358), 309-315. doi:10.1080/01621459.1977.10480995

See Also

kendall_tau_c(), gamma_gk(), somers_d(), assoc_measures()

Other association measures: assoc_measures(), contingency_coef(), cramer_v(), gamma_gk(), goodman_kruskal_tau(), kendall_tau_c(), lambda_gk(), phi(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$education, sochealth$self_rated_health)
kendall_tau_b(tab)

Kendall's Tau-c (Stuart's Tau-c)

Description

kendall_tau_c() computes Stuart's Tau-c (also known as Kendall's Tau-c) for a two-way contingency table of ordinal variables.

Usage

kendall_tau_c(x, detail = FALSE, conf_level = 0.95, digits = 3L)

Arguments

Details

Stuart's Tau-c is computed as \tau_c = 2m(C - D) / (n^2(m - 1)), where m = \min(r, c). It is designed for rectangular tables; the estimate is bounded by [-1, 1] only when the table is square, and may fall outside that range otherwise. When the asymptotic standard error is zero (e.g. a perfect association), the Wald z-test is undefined and the p-value is NA, matching the other measures in the family. When one variable is constant (all observations in a single row or column), there are no untied pairs and the statistic degenerates to a meaningless 0: the function returns NA with a spicy_undefined_stat warning, like its siblings, matching the SPSS / PSPP behavior of reporting no value. Standard error formulas follow the DescTools implementations (Signorell et al., 2024); see cramer_v() for full references.

Value

Same structure as cramer_v(): a scalar when detail = FALSE, a named vector when detail = TRUE. The p-value tests H0: tau-c = 0 (Wald z-test).

References

Stuart, A. (1953). The estimation and comparison of strengths of association in contingency tables. Biometrika, 40(1-2), 105-110. doi:10.2307/2333101

Brown, M. B., & Benedetti, J. K. (1977). Sampling behavior of tests for correlation in two-way contingency tables. Journal of the American Statistical Association, 72(358), 309-315. doi:10.1080/01621459.1977.10480995

See Also

kendall_tau_b(), gamma_gk(), somers_d(), assoc_measures()

Other association measures: assoc_measures(), contingency_coef(), cramer_v(), gamma_gk(), goodman_kruskal_tau(), kendall_tau_b(), lambda_gk(), phi(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$education, sochealth$self_rated_health)
kendall_tau_c(tab)

Derive variable labels from column names ⁠name<sep>label⁠

Description

Splits each column name at the first occurrence of sep, renames the column to the part before sep (the name, trimmed of surrounding whitespace), and assigns the part after sep as a "label" attribute on the column. The label attribute follows the haven convention also used by labelled::var_label(), so labelled-aware tooling (labelled, haven, varlist(), code_book(), ...) reads it transparently. Splitting at the first sep means the label itself may contain the separator.

Usage

label_from_names(df, sep = ". ")

Arguments

Details

Designed primarily for LimeSurvey CSV exports with Headings: Question code & question text, which produce column names like "code. question text". The default separator ". " matches that export.

LimeSurvey question codes (the part before sep) are restricted to alphanumerics, must start with a letter, and contain no spaces – so the column name has to carry both the code and the question text. If your export uses Headings: Question code (codes only), re-export with Question code & question text before calling this function; there is no way to recover a label from a code alone.

Whitespace handling: the name (left of sep) is trimmed of surrounding whitespace, because R column names are intended to be referenced bare (without backticks) and leading / trailing whitespace would force quoting throughout the user's downstream code. The label (right of sep) is preserved verbatim, following the Stata / SPSS convention that variable labels are faithful user content – spicy does not silently mutate label strings. To trim labels yourself, post-process with labelled::var_label(df) <- lapply(labelled::var_label(df), trimws).

Value

An object of the same class as df – a base data.frame if df was a base data.frame, a tbl_df if df was a tibble. The output has column names equal to the trimmed names (before sep) and, for every column whose original name contained sep, a "label" attribute equal to the label (after sep). Columns whose name does not contain sep are passed through unchanged with no label attached.

Errors

The function raises an actionable error – rather than letting the downstream constructor raise a cryptic one – when the split produces:

• duplicate column names that the renaming itself creates (two original names share the same prefix before sep, or a new name collides with an existing one). Names that were already duplicated in the input (check.names = FALSE data) are passed through untouched, not blamed on the split; or

• an empty column name (the original name starts with sep and has nothing before it).

See Also

labelled::var_label() reads the "label" attribute set by this function; varlist() and code_book() surface it in their inspection outputs.

Other variable inspection: code_book(), varlist()

Examples

# LimeSurvey-style column names (default sep = ". ").
df <- data.frame(
  "age. Age of respondent" = c(25, 30),
  "score. Total score. Manually computed." = c(12, 14),
  check.names = FALSE
)
out <- label_from_names(df)
attr(out$age, "label")
attr(out$score, "label")

# Custom separator.
df2 <- data.frame(
  "id|Identifier" = 1:3,
  "score|Total score" = c(10, 20, 30),
  check.names = FALSE
)
out2 <- label_from_names(df2, sep = "|")

Goodman-Kruskal's Lambda

Description

lambda_gk() computes Goodman-Kruskal's Lambda, a proportional reduction in error (PRE) measure for nominal variables.

Usage

lambda_gk(
  x,
  direction = c("symmetric", "row", "column"),
  detail = FALSE,
  conf_level = 0.95,
  digits = 3L
)

Arguments

Details

Lambda measures how much prediction error is reduced when the independent variable is used to predict the dependent variable. It ranges from 0 (no reduction) to 1 (perfect prediction). Lambda can equal zero even when variables are associated if the modal category dominates in every column (or row).

The default direction = "symmetric" follows the SPSS and DescTools convention: symmetric lambda is a standard, well-defined variant with its own asymptotic standard error. somers_d() deliberately differs (its default is "row") because its symmetric form is a derived quantity without an analytic SE; see its documentation.

Standard error formulas follow the DescTools implementations (Signorell et al., 2024); see cramer_v() for full references.

Value

Same structure as cramer_v(): a scalar when detail = FALSE, a named vector when detail = TRUE. The p-value tests H0: lambda = 0 (Wald z-test).

References

Goodman, L. A., & Kruskal, W. H. (1954). Measures of association for cross classifications. Journal of the American Statistical Association, 49(268), 732-764. doi:10.2307/2281536

See Also

goodman_kruskal_tau(), uncertainty_coef(), assoc_measures()

Other association measures: assoc_measures(), contingency_coef(), cramer_v(), gamma_gk(), goodman_kruskal_tau(), kendall_tau_b(), kendall_tau_c(), phi(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$smoking, sochealth$education)
lambda_gk(tab)
lambda_gk(tab, direction = "row")
lambda_gk(tab, direction = "column", detail = TRUE)

Row means with an optional minimum-valid-values rule

Description

Computes row-wise means across selected numeric columns of a data.frame or matrix. Missing values are handled per row via min_valid (an integer count or proportion of non-NA values required); rows that fail the rule return NA, and rows with no valid values at all return NA even when min_valid = 0. Non-numeric columns are dropped silently (set verbose = TRUE to see which). Designed to flow inside dplyr::mutate(): when called without an explicit data argument, the current data context is used.

Usage

mean_n(
  data = NULL,
  select = tidyselect::everything(),
  exclude = NULL,
  min_valid = NULL,
  digits = NULL,
  regex = FALSE,
  verbose = FALSE,
  user_na = TRUE
)

Arguments

Value

A numeric vector of row-wise means.

Declared missing values

Survey files imported with haven often carry declared missing values: codes such as ⁠8 = Don't know⁠ or 9 = Refused that the source file marks as missing while keeping them distinct from a plain NA. Two kinds of declaration exist: na_values / na_range metadata on haven::labelled_spss() vectors, and tagged missing values created by haven::tagged_na() (the Stata .a, .b, ... convention). haven::read_sav() keeps the na_values / na_range declaration only with user_na = TRUE: its default turns the declared codes into NA on import.

spicy honors the declaration by default (user_na = TRUE): declared missing values are excluded from every statistic exactly like NA – valid percentages, means, chi-squared tests, association measures, row-wise summaries, and group definitions – but they are not erased from display. freq() lists each observed declared value as its own row of the Missing block, with its value label; cross_tab(), table_categorical(), and table_continuous() disclose the exclusion in the table note (⁠Declared missing values removed: x (2).⁠); varlist() counts them as missing in N_valid / NAs / N_distinct while still listing the declared codes in Values; code_book() counts them in n_declared_missing and flags them in its values table.

Every function involved offers the same escape hatch: set user_na = FALSE to ignore the declaration and treat the declared codes as valid values (the behavior of spicy before 0.13.0). Tagged missing values are genuine NAs either way; for them, user_na = FALSE only collapses the per-tag breakdown back into the regular NA count.

See Also

Other row-wise summaries: count_n(), sum_n()

Examples

library(dplyr)

# Create a simple numeric data frame
df <- tibble(
  var1 = c(10, NA, 30, 40, 50),
  var2 = c(5, NA, 15, NA, 25),
  var3 = c(NA, 30, 20, 50, 10)
)

# Compute row-wise mean (all values must be valid by default)
mean_n(df)

# Require at least 2 valid (non-NA) values per row
mean_n(df, min_valid = 2)

# Require at least 50% valid (non-NA) values per row
mean_n(df, min_valid = 0.5)

# Round the result to 1 decimal
mean_n(df, digits = 1)

# Select specific columns
mean_n(df, select = c(var1, var2))

# Select specific columns using a pipe
df |>
  select(var1, var2) |>
  mean_n()

# Exclude a column
mean_n(df, exclude = "var3")

# Select columns ending with "1"
mean_n(df, select = ends_with("1"))

# Use with native pipe
df |> mean_n(select = starts_with("var"))

# Use inside dplyr::mutate()
df |> mutate(mean_score = mean_n(min_valid = 2))

# Select columns directly inside mutate()
df |> mutate(mean_score = mean_n(select = c(var1, var2), min_valid = 1))

# Select columns before mutate
df |>
  select(var1, var2) |>
  mutate(mean_score = mean_n(min_valid = 1))

# Show verbose processing info
df |> mutate(mean_score = mean_n(min_valid = 2, digits = 1, verbose = TRUE))

# Add character and grouping columns
df_mixed <- mutate(df,
  name = letters[1:5],
  group = c("A", "A", "B", "B", "A")
)
df_mixed

# Non-numeric columns are ignored
mean_n(df_mixed)

# Use within mutate() on mixed data
df_mixed |> mutate(mean_score = mean_n(select = starts_with("var")))

# Use everything() but exclude non-numeric columns manually
mean_n(df_mixed, select = everything(), exclude = "group")

# Select columns using regex
mean_n(df_mixed, select = "^var", regex = TRUE)
mean_n(df_mixed, select = "ar", regex = TRUE)

# Apply to a subset of rows (first 3)
df_mixed[1:3, ] |> mean_n(select = starts_with("var"))

# Store the result in a new column
df_mixed$mean_score <- mean_n(df_mixed, select = starts_with("var"))
df_mixed

# With a numeric matrix
mat <- matrix(c(1, 2, NA, 4, 5, NA, 7, 8, 9), nrow = 3, byrow = TRUE)
mat
mat |> mean_n(min_valid = 2)

Phi coefficient

Description

phi() computes the phi coefficient for a 2x2 contingency table.

Usage

phi(x, detail = FALSE, conf_level = 0.95, digits = 3L)

Arguments

Details

The phi coefficient is \phi = \sqrt{\chi^2 / n}. It is equivalent to Cramér's V for 2x2 tables and equals the absolute value of the Pearson correlation between the two binary variables – spicy returns only the magnitude (always non-negative), matching the DescTools (Signorell et al., 2024) and PSPP conventions. SPSS itself SIGNS phi on 2x2 tables (its CROSSTABS algorithm sets the sign to that of the Pearson correlation), so SPSS output can show a negative value of the same magnitude. To recover the signed direction of the 2x2 association, compute the Pearson correlation directly (e.g. cor(x, y) after coding both variables 0/1).

The confidence interval uses the Fisher z-transformation on \phi; see cramer_v() for the formula and full references.

Value

Same structure as cramer_v(): a scalar when detail = FALSE, a named vector when detail = TRUE. The p-value tests the null hypothesis of no association (Pearson chi-squared test).

References

Liebetrau, A. M. (1983). Measures of Association. Sage.

See Also

cramer_v(), yule_q(), assoc_measures()

Other association measures: assoc_measures(), contingency_coef(), cramer_v(), gamma_gk(), goodman_kruskal_tau(), kendall_tau_b(), kendall_tau_c(), lambda_gk(), somers_d(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$smoking, sochealth$sex)
phi(tab)
phi(tab, detail = TRUE)

Print a detailed association measure result

Description

Formats a spicy_assoc_detail vector (returned by association functions with detail = TRUE) with fixed decimal places and ⁠< 0.001⁠ notation for small p-values.

Usage

## S3 method for class 'spicy_assoc_detail'
print(x, digits = attr(x, "digits") %||% 3L, ...)

Arguments

Value

x, invisibly.

See Also

cramer_v(), assoc_measures()

Print an association measures summary table

Description

Formats a spicy_assoc_table data frame (returned by assoc_measures()) with fixed decimal places, aligned columns, and APA-style ⁠<.001⁠ notation for small p-values (same helper as cross_tab() and the ⁠table_*()⁠ family).

Usage

## S3 method for class 'spicy_assoc_table'
print(x, digits = attr(x, "digits") %||% 3L, ...)

Arguments

Value

x, invisibly.

See Also

assoc_measures()

Print method for categorical survey-design tables

Description

Formats and prints a spicy_categorical_svy_table object as a styled ASCII table using spicy_print_table().

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_categorical_svy(), spicy_print_table()

Print method for categorical summary tables

Description

Formats and prints a spicy_categorical_table object as a styled ASCII table using spicy_print_table().

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_categorical(), spicy_print_table()

Print method for bivariate linear-model tables

Description

Formats and prints a spicy_continuous_lm_table object as a styled ASCII table using spicy_print_table().

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_continuous_lm(), spicy_print_table()

Print method for continuous survey-design tables

Description

Formats and prints a spicy_continuous_svy_table object as a styled ASCII table using spicy_print_table().

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_continuous_svy(), spicy_print_table()

Print method for continuous summary tables

Description

Formats and prints a spicy_continuous_table object as a styled ASCII table using spicy_print_table().

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_continuous(), spicy_print_table()

Print method for spicy_cross_table objects

Description

Prints a formatted SPSS-like crosstable created by cross_tab().

Usage

## S3 method for class 'spicy_cross_table'
print(x, digits = NULL, decimal_mark = NULL, ...)

Arguments

Value

Invisibly returns x.

Internal print method for lists of cross-tab tables

Description

Prints each element of a spicy_cross_table_list object on its own, inserting a blank line between tables.

Usage

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

Arguments

Value

Invisibly returns x.

Print method for spicy-tagged flextables

Description

Prints a spicy_flextable object – the flextable::flextable() returned by output = "flextable", tagged so the table note keeps its styling in interactive HTML display. Every flextable verb works on the tagged object directly; printing delegates to flextable's own rendering (as_flextable.spicy_flextable() returns the untagged object).

Usage

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

Arguments

Value

Invisibly returns NULL (HTML display path) or the result of flextable's own print method.

See Also

table_regression(), as_flextable.spicy_flextable()

Print method for freq() tables

Description

Formats and prints a spicy_freq_table object as a styled ASCII table using spicy_print_table().

Usage

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

Arguments

Value

Invisibly returns x.

See Also

freq(), spicy_print_table()

Print method for spicy-tagged gt tables

Description

Prints a spicy_gt object – the gt::gt() table returned by output = "gt", tagged so the table note keeps its styling in interactive HTML display. Every gt verb works on the tagged object directly; printing delegates to gt's own rendering.

Usage

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

Arguments

Value

Invisibly returns NULL (HTML display path) or the result of gt's own print method.

See Also

table_regression()

Print method for multiple-response tables

Description

Formats and prints a spicy_multiresponse_table object as a styled ASCII table using spicy_print_table().

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_multiresponse(), spicy_print_table()

Print method for outcome tables

Description

Formats and prints a spicy_outcome_table object as a styled ASCII table using spicy_print_table().

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_outcome(), spicy_print_table()

Print method for internal regression frames

Description

Prints a compact one-glance summary of a spicy_regression_frame (the internal intermediate representation behind table_regression()): model class, sample size, coefficient dimensions, family / link, CI method, and the capability flags the frame advertises.

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_regression()

Print method for regression tables

Description

Formats and prints a spicy_regression_table object as a styled ASCII table: title banner, spanner row for multi-model tables, decimal-aligned body with factor grouping and reference rows, fit-statistics block, and footer note.

Usage

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

Arguments

Value

Invisibly returns x.

See Also

table_regression(), spicy_print_table()

Print method for table styles

Description

Prints what a spicy_style() encodes: for a named theme, the journal, the rules it applies, and the official document they come from; then the levers themselves.

Usage

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

Arguments

Value

Invisibly returns x.

See Also

spicy_style()

Simulated social-health survey

Description

A simulated dataset of 1200 respondents from a fictional social-health survey, designed to illustrate the main features of the spicy package: variable labels, ordered factors, survey weights, association measures, a multiple-response question, and publication-ready reporting.

Usage

sochealth

Format

A tibble with 1200 rows and 29 variables:

sex

Factor. Sex of the respondent.

age

Numeric. Age in years (25–75).

age_group

Ordered factor. Age group (25–34, 35–49, 50–64, 65–75).

education

Ordered factor. Highest education level (Lower secondary, Upper secondary, Tertiary).

social_class

Ordered factor. Subjective social class (Lower, Working, Lower middle, Middle, Upper middle).

region

Factor. Region of residence (6 regions).

employment_status

Factor. Employment status (Employed, Student, Unemployed, Inactive).

income_group

Ordered factor. Household income group (Low, Lower middle, Upper middle, High). Contains missing values.

income

Numeric. Monthly household income in CHF (1000–7400).

smoking

Factor. Current smoker (No, Yes). Contains missing values.

physical_activity

Factor. Regular physical activity (No, Yes).

dentist_12m

Factor. Dentist visit in the last 12 months (No, Yes).

info_doctor

Logical. Source of health information in the past 12 months: doctor or other health professional (TRUE = chosen). Missing for the 36 respondents who skipped the question; see Details.

info_pharmacist

Logical. Source of health information: pharmacist. Missing as info_doctor.

info_internet

Logical. Source of health information: internet, websites or apps. Missing as info_doctor.

info_family

Logical. Source of health information: family or friends. Missing as info_doctor.

info_media

Logical. Source of health information: television, radio or newspapers. Missing as info_doctor.

self_rated_health

Ordered factor. Self-rated health (Poor, Fair, Good, Very good). Contains missing values.

wellbeing_score

Numeric. WHO-5 wellbeing index (0–100).

bmi

Numeric. Body mass index in kg/m^2 (16–39). Contains missing values.

bmi_category

Ordered factor. BMI category (Normal weight, Overweight, Obesity). Contains missing values.

institutional_trust

Ordered factor. Trust in institutions (Very low, Low, High, Very high).

political_position

Numeric. Political position on a 0 (left) to 10 (right) scale. Contains missing values.

life_sat_health

Integer. Satisfaction with own health (1–5 Likert scale). Contains missing values.

life_sat_work

Integer. Satisfaction with work or main activity (1–5 Likert scale). Contains missing values.

life_sat_relationships

Integer. Satisfaction with personal relationships (1–5 Likert scale). Contains missing values.

life_sat_standard

Integer. Satisfaction with standard of living (1–5 Likert scale). Contains missing values.

response_date

POSIXct. Date and time of survey response (September–November 2024).

weight

Numeric. Survey design weight (range 0.29–3.45); calibrated: mean(weight) is about 1 (0.997) and sum(weight) is 1196.5 for the 1200 rows. See Details.

Details

Every variable carries a "label" attribute (read by labelled::var_label() and surfaced by varlist() / code_book()). The mix of factor types is deliberate: nominal factors (sex, region, ...) and ordered factors (education, self_rated_health, ...) live side by side so that cross_tab() and table_categorical() can demonstrate the automatic ordinal-vs-nominal dispatch (Cramér's V, Phi, Kendall's Tau-b, Goodman-Kruskal Gamma) on the same dataset.

Survey weights (weight) are calibrated: they average about 1 (mean(weight) is 0.997) and sum to 1196.5 for the 1200 rows. Weighted means therefore agree with unweighted means up to sampling noise without further rescaling.

The five ⁠info_*⁠ variables answer one multiple-response question, "Sources of health information used in the past 12 months (check all that apply)", the example data of table_multiresponse(). Each item is logical: TRUE when the source was chosen, FALSE when it was not, and NA on all five items for the 36 respondents who skipped the question. A respondent who answered without choosing any source is FALSE on all five (67 of the 1164 who answered). Like the rest of the data, the block is simulated: doctor and media rise with age, internet falls with age and rises with education, family is more frequent among women, and the pharmacist item depends on no other variable.

Source

Simulated data for illustration purposes; reproducible by sourcing data-raw/sochealth.R. The script seeds the main generation block with set.seed(2025), the two missing-value injection blocks with set.seed(2027) (the four ⁠life_sat_*⁠ items) and set.seed(2026) (smoking, self_rated_health, income_group, political_position, bmi), and the multiple-response block (the five ⁠info_*⁠ items) with set.seed(2030).

Examples

data(sochealth)
varlist(sochealth)
freq(sochealth, education)
cross_tab(sochealth, education, self_rated_health)
table_multiresponse(
  sochealth,
  select = starts_with("info_"),
  by = age_group
)

Somers' D

Description

somers_d() computes Somers' D for a two-way contingency table of ordinal variables.

Usage

somers_d(
  x,
  direction = c("row", "column", "symmetric"),
  detail = FALSE,
  conf_level = 0.95,
  digits = 3L
)

Arguments

Details

Somers' D is an asymmetric ordinal measure defined as d = (C - D) / (C + D + T), where T is the number of pairs tied on the independent variable. The symmetric version (direction = "symmetric") is the harmonic mean of the two asymmetric values, matching the SPSS / PSPP convention; this is not identical to Kendall's Tau-b (which is the geometric mean of the same two quantities), although the two often agree to two decimals. It is computed via the equivalent closed form 2(C - D) divided by the sum of the two asymmetric denominators, so a table with exactly as many concordant as discordant pairs (e.g. an independence pattern) yields the well-defined value 0 – the harmonic-mean form is 0/0 there – as printed by SPSS / PSPP. The symmetric estimate is NA only when one of the asymmetric directions is itself undefined (with the same spicy_undefined_stat warning). No analytic SE / CI is reported for the symmetric form: its se is always NA, matching PSPP, which prints no ASE for it (DescTools offers no symmetric form at all).

The default direction = "row" differs deliberately from lambda_gk() and uncertainty_coef() (which default to "symmetric"): Somers' D is intrinsically asymmetric, its symmetric form is a derived convention without inference, and the reference implementation (DescTools::SomersDelta()) offers only the two asymmetric directions, defaulting to "row".

Standard error formulas for the asymmetric directions follow the DescTools implementations (Signorell et al., 2024); see cramer_v() for full references.

Value

Same structure as cramer_v(): a scalar when detail = FALSE, a named vector when detail = TRUE. The p-value tests H0: D = 0 (Wald z-test).

References

Somers, R. H. (1962). A new asymmetric measure of association for ordinal variables. American Sociological Review, 27(6), 799-811. doi:10.2307/2090408

Brown, M. B., & Benedetti, J. K. (1977). Sampling behavior of tests for correlation in two-way contingency tables. Journal of the American Statistical Association, 72(358), 309-315. doi:10.1080/01621459.1977.10480995

See Also

kendall_tau_b(), gamma_gk(), assoc_measures()

Other association measures: assoc_measures(), contingency_coef(), cramer_v(), gamma_gk(), goodman_kruskal_tau(), kendall_tau_b(), kendall_tau_c(), lambda_gk(), phi(), uncertainty_coef(), yule_q()

Examples

tab <- table(sochealth$education, sochealth$self_rated_health)
somers_d(tab, direction = "row")
somers_d(tab, direction = "column", detail = TRUE)

Table labels and their language

Description

Every string a reader of a spicy table sees – column headers, row labels, titles, table footnotes – is held under a stable key, and spicy_labels() returns those keys with the label each one currently resolves to. It is the companion of the two options that move them.

Usage

spicy_labels(language = NULL)

Arguments

Value

A named character vector, one element per key, in registry order.

Global options

• options(spicy.language = "fr") The language of the table, for the whole document – its labels and the typography its numbers are written in. Two sets ship: "en" (the default) and "fr". The language of a report is a property of the report, so this is set once in a setup chunk rather than passed to each table.

• ⁠options(spicy.labels = list(<key> = "<label>"))⁠ A per-label override, for the case where one word has to change and a language does not: a named list (or named character vector) whose names are keys of spicy_labels(). An unknown key is an error.

• options(spicy.var_labels = TRUE) How the descriptive tables (table_categorical(), table_continuous(), table_continuous_lm(), table_outcome() and the survey twins) and the regression tables (table_regression(), table_regression_uv()) name your variables: TRUE shows each variable's label attribute, FALSE (the default) its name. It is the default of their labels argument, and the variables a named labels vector leaves out follow it. A TRUE, a FALSE or a var_labels() typed in the call wins over it. Any other value is an error.

A label resolves through spicy.labels, then the spicy.language set, then English. A set carries only the keys it translates, so anything it does not name falls back to English rather than erroring or coming out blank. All three options are cleared with NULL.

What a language does not change

Only DISPLAY strings translate. The column names of the exported frames (as.data.frame(), tidy(), as_structured()) are a documented contract that user code indexes into, so out[["Yes %"]] resolves under every language, and so do the block identities, the encoded cell tokens and the mathematical glyphs. Errors, warnings and messages stay English: they are read by developers and quoted in bug reports.

One exception, and it follows from the same rule. A column named after a LEVEL of by takes that level's own spelling – which is why "Yes %" stays "Yes %": your data is never translated. spicy's own missing category is such a level, so it is the one name that does move: table_categorical(by = ) on a variable with missing values gives "(Missing) n" in English and "(Manquant) n" under "fr" (or whatever row_missing_level is overridden to). Address that column through row_missing_level rather than by typing it.

Numbers follow the language too

A language brings its typographic locale with it, so options(spicy.language = "fr") is one gesture for a coherent French report table: French words, comma decimal mark, and the leading zero French typography keeps on a p-value (⁠0,003⁠). The sources are the BIPM's SI brochure and the European Union's Code de redaction interinstitutionnel; spicy_style() quotes them. "en" brings no locale, and nothing changes for anyone who sets no language.

The locale rides the style layer, so it reaches the reporting families – table_regression(), table_categorical(), table_continuous(), table_continuous_lm(), table_outcome() and the survey twins. The language reaches every table, the exploration pair included: freq() and cross_tab() have no style layer, so it sets the DEFAULT of their decimal_mark – the one typographic lever they carry – and an argument you type wins over it. Under a comma their p-value keeps its leading zero (⁠p = 0,659⁠), the form French typography requires.

The locale sits at the BOTTOM of the formatting resolution. A journal style outranks it – style = "jama" under "fr" gives JAMA's p-values and the French comma, style = "lancet" keeps the journal's midline decimal point – and an argument you type outranks both, so decimal_mark = "." gives French words with a decimal point (the p-value keeps its locale zero; spicy_style() documents that lever).

Two timing notes. Figures are frozen when a table is BUILT, like every formatting argument, while words resolve when it is printed – so set the language once, at the top of the document. And a comma mark makes an Excel export write its body as text rather than live numbers, since Excel would otherwise re-punctuate a numeric cell with the viewer's own locale.

See Also

spicy_style() for the journal styles, which outrank the language's own typography.

Examples

head(spicy_labels())

# The same keys in French.
fr <- spicy_labels("fr")
fr[["header_mean"]]
fr[["row_missing_level"]]

# One label, not a language: the missing CATEGORY of the grouping
# variable is a refusal to answer here, not an absent value.
old <- options(spicy.labels = list(row_missing_level = "(No answer)"))
table_categorical(sochealth, select = sex, by = smoking)
options(old)

Print a spicy-formatted ASCII table

Description

User-facing helper that prints a spicy-styled ASCII table to the console with optional title and note, table-type-aware alignment defaults, and automatic horizontal paneling when the table is wider than the console. Wraps the internal renderer build_ascii_table().

Usage

spicy_print_table(
  x,
  title = attr(x, "title"),
  note = attr(x, "note"),
  padding = 2L,
  first_column_line = TRUE,
  row_total_line = TRUE,
  bottom_line = FALSE,
  lines_color = "darkgrey",
  align_left_cols = NULL,
  align_center_cols = integer(0),
  center_headers = FALSE,
  spanners = NULL,
  group_sep_rows = integer(0),
  total_row_idx = attr(x, "total_row_idx"),
  display_labels = NULL,
  fit_stats_start = NULL,
  qualify_companions = FALSE,
  ...
)

Arguments

Details

Table type is auto-detected from x and drives the default alignment when align_left_cols = NULL:

• frequency table (a Category column is present): the first two columns (Category, Values) are left-aligned.

• cross table (otherwise): only the first column (row variable) is left-aligned.

If the table is wider than the console, it is split into stacked horizontal panels with the left-most identifier columns repeated on each panel. Unicode line-drawing characters are used by default; colored separators are drawn when the terminal supports ANSI color (crayon::has_color()) and fall back to monochrome otherwise.

The layout arguments spanners, display_labels, fit_stats_start, total_row_idx and group_sep_rows are plumbing consumed by spicy's own print methods; they are documented for completeness and are rarely useful when calling this function directly.

Value

Invisibly returns x, after printing the formatted ASCII table to the console.

See Also

build_ascii_table() for the underlying text rendering engine. print.spicy_freq_table() for the specialized printing method used by freq().

Examples

# Simple demonstration
df <- data.frame(
  Category = c("Valid", "", "Missing", "Total"),
  Values = c("Yes", "No", "NA", ""),
  Freq. = c(12, 8, 1, 21),
  Percent = c(57.1, 38.1, 4.8, 100.0)
)

spicy_print_table(df,
  title = "Frequency table: Example",
  note = "Class: data.frame\nData: demo"
)

Build or select a table style

Description

A style is a small set of number-formatting rules – how many decimals a p-value gets, where it bottoms out, whether it keeps its leading zero, what the decimal mark is, how a confidence interval is written – with the word that opens the note under the table and the abbreviations that note defines. spicy_style() composes one by hand; the named themes ("jama", "nejm", "lancet", "annals", "apa", "aer" – spicy_style_names() returns the list) are pre-composed ones, each encoding rules taken verbatim from an official document of the institution.

Usage

spicy_style(
  base = NULL,
  ...,
  p_style = NULL,
  p_digits = NULL,
  p_floor = NULL,
  p_bands = NULL,
  p_sigfig = NULL,
  decimal_mark = NULL,
  ci_sep = NULL,
  ci_brackets = NULL,
  stars = NULL,
  digits = NULL,
  effect_size_digits = NULL,
  fit_digits = NULL,
  ic_digits = NULL,
  percent_digits = NULL,
  note_label = NULL,
  abbreviations = NULL,
  minus_sign = NULL,
  v_digits
)

spicy_style_names()

Arguments

Details

A style is accepted by the style argument of the nine table functions (table_categorical(), table_categorical_svy(), table_continuous(), table_continuous_svy(), table_continuous_lm(), table_outcome(), table_multiresponse(), table_regression() and table_regression_uv()), either as a theme name or as the object returned here, and by options(spicy.style = ) for document-wide scope.

Value

spicy_style() returns an object of class spicy_style: a named list holding only the levers that were set. Themes returned by name carry a provenance attribute with the journal, its source document and the exact list of encoded rules; print() shows it. spicy_style_names() returns the character vector of available theme names.

What a theme claims, and what it does not

A theme covers numeric formatting conformity, the word that opens the table note, the abbreviations that note defines and, in English, how the mean and the median are headed, only – not full editorial conformity. It does not check reporting guidelines, table structure, footnote symbols, units, or anything else a journal's instructions ask of a manuscript. Each theme below lists the exact rules it encodes, with the sentence it encodes them from; anything not listed is spicy's own default, not the journal's rule.

Themes only move defaults. An argument you type wins over the theme, always: table_regression(fit, style = "lancet", digits = 3) is a Lancet table with three decimals. One consequence worth stating: typing p_digits is a request for that many decimals on every p-value, so it also switches off the theme's own ways of choosing p-precision – p_bands, p_sigfig, and the p_floor derived from them. The leading-zero rule is orthogonal and stays.

Resolution order

An argument you type, then the style argument, then getOption("spicy.style"), then the typography of getOption("spicy.language"), then spicy's defaults. Within a style, an explicit function argument beats the style's value for the same lever.

The language's locale

A language brings its typography with it, at the bottom of that order. options(spicy.language = "fr") is therefore one gesture for a coherent French report table – French words, and numbers written the French way: comma decimal mark, and the leading zero French typography keeps on a p-value (⁠0,003⁠). "La virgule est utilisee pour separer les unites des decimales" (European Union, Code de redaction interinstitutionnel, French edition 2022, point 6.5, ⁠https://style-guide.europa.eu/fr⁠); "Si le nombre se situe entre +1 et -1, le separateur decimal est toujours precede d'un zero" (BIPM, Le Systeme international d'unites, 9th edition, 2019, section 5.4.4, ⁠https://www.bipm.org/documents/20126/41483022/SI-Brochure-9.pdf⁠). "en" brings no locale, and nothing changes for anyone who sets no language. The locale reaches the exploration pair as well: freq() and cross_tab() have no style layer, so the language sets the DEFAULT of their decimal_mark and nothing else. An argument you type still wins. The leading zero of a p-value works the same way in both worlds: its DEFAULT follows the mark – a comma keeps it (⁠0,003⁠), a point drops it (.003) – and p_style is the explicit lever that overrides that default wherever there is one, which is why a theme's rule survives any mark in the ⁠table_*()⁠ families while the pair, having no such lever, always follows its mark.

A theme composes with a locale rather than fighting it, because a theme encodes only what its own source states: "jama" fixes no decimal mark, so JAMA under a French language gives JAMA's p-value rules and the French comma. Where the two do meet, the theme wins – you asked for it by name. "lancet" keeps its midline decimal point; "apa" keeps its missing leading zero, which under a comma prints ⁠,003⁠, a form the SI brochure forbids. That is the price of an explicit gesture; to keep APA's other rules and restore the zero, compose the way out yourself: style = spicy_style("apa", p_style = "standard"). One lever bends the other way: a theme's ", " interval separator was sourced under a dot mark, and under a comma mark it would BE the mark – so it yields to the derived "; ", exactly as the French adaptations of APA style themselves write (⁠[3,45; 6,78]⁠). Any other separator (" to ", an en dash) is unambiguous and stays.

An argument beats both, which is the escape hatch for a bilingual table: decimal_mark = "." under a French language gives French words and a decimal point. It moves only the mark: the p-value keeps the locale's leading zero (0.003), because p_style is a style lever with no argument of its own – style = spicy_style(p_style = "apa") drops it again.

See spicy_labels() for the language option itself.

Themes

"jama" – JAMA / JAMA Network

Source: Instructions for Table Creation, JAMA Network author document, 23 February 2016 (⁠https://jamanetwork.com/DocumentLibrary/InstructionsForAuthors/InstructionsForTableCreation.pdf⁠), consulted 2026-08-14.

Encoded:

• p-values on two decimals, three below .01, floored at ⁠<.001⁠, with no leading zero – "All P values should be reported to exact numbers to 2 digits past the decimal point, regardless of statistical significance. For values lower than .01, present the P value to 3 digits. Express any values lower than .001 as P<.001."

• no lead-in word before the note under the table (note_label = "") – the AMA Manual of Style, 11th edition (2020), section 4.1.4.10, gives table footnotes none: a footnote on the whole table is called by a letter "placed after the table title".

• the abbreviations of the note on its first line, ⁠Abbreviations: HR, hazard ratio; OR, odds ratio.⁠, in alphabetical order, ⁠Abbreviation:⁠ for one – section 4.1.4.10 again: that footnote comes first, "set off with an introductory word or phrase instead of a letter", and "abbreviations are expanded in alphabetical order". SD, SE and CI are not expanded (section 13.11, "no need to expand"), nor are the symbols of section 19.6 that do not carry "expand at first mention" (n, N, P, d, R^2, \Delta, \sigma, \rho), B and M among them, which that section writes b and \bar{x}: it lists them as usable "without expansion except where noted".

• the mean and the median headed Mean and Median, not M and Mdn – section 4.1.5 writes "mean (SD)" and "median (IQR)" in full.

Not encoded: everything else in that document (percentages carrying their numerator and denominator, one datum per cell, footnote letters, SI conversion factors) is table construction, not number formatting. The document states no rule for the confidence-interval separator or the decimal mark, so spicy's defaults apply.

"nejm" – The New England Journal of Medicine

Source: NEJM Author Center, New Manuscripts, section Statistical Reporting Guidelines (⁠https://www.nejm.org/author-center/new-manuscripts⁠), a living page; its full text was read in a browser by the package maintainer on 2026-08-14 – the site refuses automated retrieval, which is why earlier surveys reported these rules as unavailable.

Encoded:

• tiered p-values, leading zero kept – "In general, P values larger than 0.01 should be reported to two decimal places, and those between 0.01 and 0.001 to three decimal places; P values smaller than 0.001 should be reported as P<0.001." The guideline's own text writes 0.01 / 0.001: unlike JAMA, the leading zero stays.

• measures of association on two decimals – "measures of association, such as odds ratios, should ordinarily be reported to two decimal places" (a pin of spicy's default).

Not encoded: the guideline's stated exceptions to the p rule (stopping-rule tests, genomewide studies) are analysis contexts the style layer cannot see; its inference policy (no p-values without a prespecified multiplicity plan, estimates + 95% CI instead, no p-values in the Table 1 of a randomized trial) is about what to report, not how to format it – request those layouts through show_columns and p_value = FALSE where you need them. No rule on the abbreviations of a table note was found, so the note defines them as spicy's default does.

"lancet" – The Lancet

Sources: Information for Authors, April 2026; Randomised trials in The Lancet: formatting guidelines and Observational studies in The Lancet: formatting guidelines, both last updated July 2025 (⁠https://www.thelancet.com/pb-assets/Lancet/authors/tl-info-for-authors-1690986041530.pdf⁠), consulted 2026-08-14.

Below, the journal's midline decimal point (Unicode U+00B7, MIDDLE DOT) is written ⁠[.]⁠ so it cannot be confused with an ordinary period.

Encoded:

• midline decimal mark, U+00B7, on every number in the table – "Type decimal points midline (ie, 23⁠[.]⁠4, not 23.4)."

• p-values on two significant figures, capped at four decimals, floored at ⁠p<0[.]0001⁠, leading zero kept – "Supply p values to two significant figures (capped at four decimal places), or p<0⁠[.]⁠0001."

• en dash between the bounds of a confidence interval. This one is not a written rule: the journal states none. It matches the intervals printed throughout the journal's own model tables and figures (⁠0[.]78 (0[.]60-1[.]00)⁠) and is encoded as conformity to the journal's published examples, nothing stronger.

• no lead-in word before the note under the table (note_label = ""). Not a written rule either: the model tables of the two formatting guidelines open their note on "Data are n (%)", and none of the 38 table notes of 15 research articles published in 2025-2026, checked on 2026-10-20, opens with "Note".

• the abbreviations spelled out at the end of the note, one ⁠HR=hazard ratio.⁠ sentence each, in alphabetical order, with n, N, p, SD, SE, IQR and CI left undefined. The artwork guidelines ask authors to "list and spell out all abbreviations in the table"; the form and the exemptions are not a written rule: they are those of the model tables of the two formatting guidelines ("Data are n (%), median (IQR), mean (SD) ... BMI=body-mass index.") and of 35 tables of 13 research articles published in 2025-2026, checked on 2026-10-20.

• the mean and the median headed Mean and Median, not M and Mdn, as the "median (IQR), mean (SD)" of the same model tables (not a written rule).

Not encoded: the empty-cell filler, the ban on p-values in a randomized trial's baseline table, and the absolute-rather-than- relative effect rule are content decisions, not number formats.

One caveat on the en dash. The journal's examples are ratio measures, whose bounds are positive. On the identity scale a negative lower bound puts a minus sign next to the dash (⁠[-5.17--2.58]⁠), which reads badly. The journal states no rule for that case and none is invented here; override the separator when it arises: spicy_style("lancet", ci_sep = " to ").

"annals" – Annals of Internal Medicine

Source: Information for Authors, American College of Physicians, document publication date 08/04/2026 (⁠https://www.acpjournals.org/pb-assets/pdf/AnnalsAuthorInfo-1755188286957.pdf⁠), consulted 2026-08-14.

Encoded:

• p-values on three decimals up to 0.20 and two decimals above it, floored at P<0.001, leading zero kept – "For P values between 0.001 and 0.20, please report the value to the nearest thousandth. For P values greater than 0.20, please report the value to the nearest hundredth. For P values less than 0.001, report as 'P<0.001.'"

Not encoded: the percentage rule ("Report percentages to one decimal place ... when sample size is \ge 200", no decimals below 200) is conditional on a per-group sample size that the style layer does not see; set percent_digits yourself. The mean (SD) notation the journal asks for, and its refusal of \pm, are already how spicy renders dispersion. No rule on the abbreviations of a table note was found, so the note defines them as spicy's default does.

"apa" – APA Style, 7th edition

Sources: APA Style numbers and statistics guide, last updated 11 September 2024 (⁠https://apastyle.apa.org/instructional-aids/numbers-statistics-guide.pdf⁠); Sample tables, last updated June 2024 (⁠https://apastyle.apa.org/style-grammar-guidelines/tables-figures/sample-tables⁠), both consulted 2026-08-14.

Encoded – and this theme pins rather than changes: spicy's defaults already follow the guide, so style = "apa" is a promise that a future change of those defaults will not move an APA-formatted table.

• p-values on three decimals, floored at ⁠<.001⁠, no leading zero – "Report exact p values to two or three decimals (e.g., p = .006, p = .03)", "report p values less than .001 as 'p < .001.'", and "Do not use a zero before a decimal when the statistic cannot be greater than 1 (proportion, correlation, level of statistical significance)."

• estimates and dispersion on two decimals – "Report other means and standard deviations and correlations, proportions, and inferential statistics (t, F, chi-square) to two decimals."

• confidence intervals in square brackets, bounds separated by a comma – the Sample tables page gives ⁠95% CI [LL, UL]⁠ as one of the two official layouts.

• the note under the table opens with "Note." in italics (note_label = "Note.") – the Publication Manual, 7th edition (2020), section 7.14: the general note is "designated by the word 'Note' (italicized) followed by a period".

• the abbreviations defined at the end of the general note, ⁠CI = confidence interval; LL = lower limit⁠, in the order they appear in the table – sections 7.14 and 7.15 ("define the abbreviations in the order that they appear in the table"); AIC and BIC are among those section 6.44 names. The symbols that represent statistics are left undefined ("Do not define symbols or abbreviations that represent statistics (e.g., M, SD, F, t, df, p, N, n, OR, r)", section 6.44; section 7.15 adds SE), and spicy counts Mdn (the median of Table 6.5) and Hedges's g among them. So are the symbols composed of Greek letters (the same two sections) and those its sample tables leave undefined (B, \beta, R^2, \Delta R^2, Cohen's d). This is also spicy's default rule, the one "nejm", "annals" and "aer" apply.

Not encoded: the one-decimal rule for means of integer scales (depends on what the variable measures, which spicy cannot know), and the thousands separator (see Known gaps below). Nor the star thresholds. The official correlation and ANOVA sample tables mark .05 / .01 / .001, which is what stars = TRUE gives you – but as spicy's own default, not as anything this theme pins: one stars lever carries both the thresholds and the decision to show them, and the APA regression sample table shows none. So the theme sets no stars, and style = "apa" never switches them on.

"aer" – American Economic Review / AEA journals

Source: AER Style Guide, American Economic Association (⁠https://www.aeaweb.org/journals/aer/style-guide⁠), consulted 2026-08-14. The Tables section is shared with AEJ: Applied, AEJ: Macro, AEJ: Policy, JEL and AEA P&P.

Encoded:

• leading zero on every decimal fraction, p-values included – "Place a zero in front of the decimal point in all decimal fractions (e.g., 0.357, not .357)."

• no significance stars, pinned – "Do not use asterisks to denote significance of estimation results. Report the standard errors in parentheses." This is the only outright written ban on stars in the whole surveyed corpus, so it is encoded even though spicy already defaults to stars = FALSE. Ask for show_columns = c("b", "se") for the standard-error layout.

Not encoded: the guide fixes no number of decimals, no p-value floor, no interval format and no decimal mark, so spicy's defaults apply. Horizontal-rules-only, no shading, a nine-column maximum and "Panel A / Panel B" blocks are layout, not number formatting. No rule on the abbreviations of a table note was found, so the note defines them as spicy's default does.

Known gaps

Two rules the sources state but this release does not encode:

• thousands separator (APA's comma, the EU code's thin no-break space). spicy formats numbers through more than one path, and a separator applied to some of them only would print ⁠1,234⁠ in one column and 1234 in the next – the exact inconsistency the SI brochure forbids ("the format used should not vary within one column").

• significant-figure rounding of estimates (Epidemiology's nn / n.n / ⁠0.nn⁠, Science's "report only significant digits"). spicy's digits is a decimals contract applied per column family; a blanket significant-figure mode would also round fit statistics, which those rules do not ask for.

Journals deliberately absent: BMJ (its house-style page could not be read from any official source, and the widely repeated "95% CI 1.2 to 3.4" rule traces to no BMJ document), Econometrica (verified negative: the official guidelines contain no numeric table rule), QJE (its instructions page could not be read), Epidemiology (see Known gaps). Naming any of them would mean inventing their rules.

Examples

fit <- lm(mpg ~ wt + hp, data = mtcars)

# A named theme.
table_regression(fit, style = "jama")

# An argument you type beats the theme.
table_regression(fit, style = "jama", p_digits = 4)

# A style composed by hand.
table_regression(fit, style = spicy_style(decimal_mark = ",",
                                          p_style = "standard"))

# A theme with one rule changed.
table_regression(fit, style = spicy_style("lancet", ci_sep = " to "))

# Document-wide scope.
old <- options(spicy.style = "apa")
table_continuous(mtcars, c(mpg, wt))
options(old)

# Every abbreviation defined, for readers outside the field.
table_continuous(mtcars, c(mpg, wt),
                 style = spicy_style(abbreviations = "all"))

# What a theme encodes, and where it comes from.
spicy_style("lancet")

Spicy table engine

Description

Index page for the ASCII rendering engine that produces every spicy console table (freq(), cross_tab(), the ⁠table_*()⁠ family, and the association-measure printers). The engine supports Unicode line drawing, ANSI colors via crayon (with monochrome fallback), automatic color-aware width detection, configurable integer padding (0L / 2L / 4L), per-column alignment, and horizontal paneling for tables wider than the console.

User-facing entry points

• freq() – one-way frequency tables

• cross_tab() – two-way cross-tabulations

• table_categorical(), table_continuous(), table_continuous_lm() – multi-variable summary tables

Rendering primitives (internal API)

• spicy_print_table() – user-facing wrapper that adds title, note, table-type-aware alignment defaults, and paneling.

• build_ascii_table() – the underlying string renderer.

See Also

spicy for the full package overview, including the API stability tiers and the classed-condition taxonomy.

Row sums with an optional minimum-valid-values rule

Description

Computes row-wise sums across selected numeric columns of a data.frame or matrix. Missing values are handled per row via min_valid (an integer count or proportion of non-NA values required); rows that fail the rule return NA, and rows with no valid values at all return NA even when min_valid = 0. Non-numeric columns are dropped silently (set verbose = TRUE to see which). Designed to flow inside dplyr::mutate(): when called without an explicit data argument, the current data context is used.

Usage

sum_n(
  data = NULL,
  select = tidyselect::everything(),
  exclude = NULL,
  min_valid = NULL,
  digits = NULL,
  regex = FALSE,
  verbose = FALSE,
  user_na = TRUE
)

Arguments

Value

A numeric vector of row-wise sums.

Declared missing values

Survey files imported with haven often carry declared missing values: codes such as ⁠8 = Don't know⁠ or 9 = Refused that the source file marks as missing while keeping them distinct from a plain NA. Two kinds of declaration exist: na_values / na_range metadata on haven::labelled_spss() vectors, and tagged missing values created by haven::tagged_na() (the Stata .a, .b, ... convention). haven::read_sav() keeps the na_values / na_range declaration only with user_na = TRUE: its default turns the declared codes into NA on import.

spicy honors the declaration by default (user_na = TRUE): declared missing values are excluded from every statistic exactly like NA – valid percentages, means, chi-squared tests, association measures, row-wise summaries, and group definitions – but they are not erased from display. freq() lists each observed declared value as its own row of the Missing block, with its value label; cross_tab(), table_categorical(), and table_continuous() disclose the exclusion in the table note (⁠Declared missing values removed: x (2).⁠); varlist() counts them as missing in N_valid / NAs / N_distinct while still listing the declared codes in Values; code_book() counts them in n_declared_missing and flags them in its values table.

Every function involved offers the same escape hatch: set user_na = FALSE to ignore the declaration and treat the declared codes as valid values (the behavior of spicy before 0.13.0). Tagged missing values are genuine NAs either way; for them, user_na = FALSE only collapses the per-tag breakdown back into the regular NA count.

See Also

Other row-wise summaries: count_n(), mean_n()

Examples

library(dplyr)

# Create a simple numeric data frame
df <- tibble(
  var1 = c(10, NA, 30, 40, 50),
  var2 = c(5, NA, 15, NA, 25),
  var3 = c(NA, 30, 20, 50, 10)
)

# Compute row-wise sums (all values must be valid by default)
sum_n(df)

# Require at least 2 valid (non-NA) values per row
sum_n(df, min_valid = 2)

# Require at least 50% valid (non-NA) values per row
sum_n(df, min_valid = 0.5)

# Round the results to 1 decimal
sum_n(df, digits = 1)

# Select specific columns
sum_n(df, select = c(var1, var2))

# Select specific columns using a pipe
df |>
  select(var1, var2) |>
  sum_n()

# Exclude a column
sum_n(df, exclude = "var3")

# Select columns ending with "1"
sum_n(df, select = ends_with("1"))

# Use with native pipe
df |> sum_n(select = starts_with("var"))

# Use inside dplyr::mutate()
df |> mutate(sum_score = sum_n(min_valid = 2))

# Select columns directly inside mutate()
df |> mutate(sum_score = sum_n(select = c(var1, var2), min_valid = 1))

# Select columns before mutate
df |>
  select(var1, var2) |>
  mutate(sum_score = sum_n(min_valid = 1))

# Show verbose message
df |> mutate(sum_score = sum_n(min_valid = 2, digits = 1, verbose = TRUE))

# Add character and grouping columns
df_mixed <- mutate(df,
  name = letters[1:5],
  group = c("A", "A", "B", "B", "A")
)
df_mixed

# Non-numeric columns are ignored
sum_n(df_mixed)

# Use inside mutate with mixed data
df_mixed |> mutate(sum_score = sum_n(select = starts_with("var")))

# Use everything(), but exclude known non-numeric
sum_n(df_mixed, select = everything(), exclude = "group")

# Select columns using regex
sum_n(df_mixed, select = "^var", regex = TRUE)
sum_n(df_mixed, select = "ar", regex = TRUE)

# Apply to a subset of rows
df_mixed[1:3, ] |> sum_n(select = starts_with("var"))

# Store the result in a new column
df_mixed$sum_score <- sum_n(df_mixed, select = starts_with("var"))
df_mixed

# With a numeric matrix
mat <- matrix(c(1, 2, NA, 4, 5, NA, 7, 8, 9), nrow = 3, byrow = TRUE)
mat
mat |> sum_n(min_valid = 2)

Categorical summary table

Description

Builds a publication-ready frequency or cross-tabulation table for one or many categorical variables selected with tidyselect syntax.

With by, produces grouped cross-tabulation summaries (using cross_tab() internally) with a p-value per variable, from Pearson's chi-squared test or Fisher's exact test (see test), and optional association measures. Without by, produces one-way frequency-style summaries.

Multiple output formats are available via output: a printed ASCII table ("default"), a numeric data.frame ("data.frame", the displayed table, or "long", one row per variable, level and group), or publication-ready tables ("tinytable", "gt", "flextable", "excel", "clipboard", "word").

Usage

table_categorical(
  data,
  select = tidyselect::everything(),
  by = NULL,
  labels = getOption("spicy.var_labels", FALSE),
  note_labels = NULL,
  levels_keep = NULL,
  include_total = TRUE,
  total_row = FALSE,
  drop_na = FALSE,
  weights = NULL,
  rescale = getOption("spicy.rescale", FALSE),
  correct = FALSE,
  simulate_p = FALSE,
  simulate_B = 2000,
  test = c("auto", "chisq", "fisher", "midp", "n1"),
  p_value = NULL,
  p_adjust = "none",
  percent = c("column", "row"),
  percent_base = c("valid", "total"),
  percent_digits = 1,
  p_digits = 3,
  effect_size_digits = 2,
  assoc_measure = "auto",
  assoc_ci = FALSE,
  smd = FALSE,
  decimal_mark = ".",
  align = c("decimal", "center", "right"),
  note = NULL,
  note_add = NULL,
  output = c("default", "data.frame", "long", "tinytable", "gt", "flextable", "excel",
    "clipboard", "word"),
  indent_text = "  ",
  indent_text_excel_clipboard = strrep(" ", 6),
  add_multilevel_header = TRUE,
  blank_na_wide = FALSE,
  excel_path = NULL,
  excel_sheet = NULL,
  clipboard_delim = "\t",
  word_path = NULL,
  user_na = TRUE,
  style = NULL,
  v_digits
)

Arguments

Value

Depends on output:

• "default": a data.frame of class "spicy_categorical_table" carrying the rendering metadata as attributes. Its columns are internal and can change without notice: read the numbers from "data.frame", "long", broom::tidy(), broom::glance() or as_structured(). The object is returned visibly, so a bare table_categorical(...) call auto-prints the styled ASCII table at the console while t <- table_categorical(...) stays silent (print t to display the table).

• "data.frame": the displayed table with its numbers, what as.data.frame() of the default object returns: one row per printed row – the header row of each variable, which carries its p-value and its association measure, then one row per level. The key columns are variable (the column name), label (the label the rows display for it, see labels), level and .row_role ("factor_header", "level", "missing" for the row of missing values the table adds, or "total" for the Total row of total_row = TRUE), then the printed columns: one pair ⁠<group> n⁠ / ⁠<group> %⁠ per group level (plus Total when include_total = TRUE), p (absent with p_value = FALSE), the association measure (named by its header: the symbol of the measure, V, its name for a measure without one, or ⁠Effect size⁠ when the row variables do not share one), its bounds ⁠95% CI LL⁠ / ⁠95% CI UL⁠ with assoc_ci = TRUE, and SMD with smd = TRUE. When by = NULL, the printed columns are n and ⁠%⁠.

• "long": a long data.frame, one row per variable, level and group, with columns variable, label, level, .row_role (the role of level: "level", "missing" for the row of missing values, or "total" for the Total row of total_row = TRUE), then, when by is used, group, .group_role (the role of group: "group", "missing" for the column of missing by values, or "total" for the margin) and total (TRUE on the rows of the margin and of the Total row), then n, pct (the percentage the table displays, in the direction of percent), then, with by, the test of the variable unless p_value = FALSE: test_type ("chi_squared" for Pearson's, "n1_chi_squared" for the N-1 chi-squared, "fisher_exact", "fisher_midp" for the Fisher mid-p test, or "fisher_exact_mc" for the Monte Carlo estimate of Fisher's exact test), statistic and df (the chi-squared, Pearson's or the N-1, NA for a variable tested by an exact test), p.value (and p_unadjusted under p_adjust); and the association measure, whichever measure it is: es_type names it per row ("cramer_v", "phi", ...), es_value holds it, es_ci_lower / es_ci_upper its interval (NA unless assoc_ci = TRUE), and smd_type ("binary" or "multinomial", the kernel the value came from) / smd_value the standardized mean difference. The measure and SMD columns are there whether or not they were requested, NA when not, so the schema does not move with an argument. The statistics of a variable sit on every row of its block.

• "tinytable": a tinytable object.

• "gt": a gt_tbl object.

• "flextable": a flextable object.

• "excel" / "word": writes to disk and returns the file path invisibly.

• "clipboard": copies the table and returns the copied text invisibly.

The note opens with the sample size, "N = 159." or, with by, "N = 159: Women (n = 80), Men (n = 79).": the rows of the data the table describes, and those of each group column in column order, the column of missing by values included, so that the n add up to N. A row missing by under drop_na = TRUE and a row with a missing weight leave the table and are not counted; the note says how many. Under weights the cells hold weighted counts and N counts rows: "N = 60 (unweighted).". One N per table, the missing values of a variable in its "(Missing)" row or in the note. With by, the direction of the percentages follows, then the weights. Their base takes no sentence: the table shows it (see percent_base).

The note, the drop_na = TRUE disclosure included, travels with the table on every route, not just the console: "default" prints it under the ASCII table, "tinytable" / "gt" / "flextable" / "word" carry it as a table note, "excel" writes it below the body, and the default object and the data frames of "data.frame" / "long" keep the whole note as printed, its lead-in included, in attr(x, "note") (NULL when there is nothing to say), so a pipeline that renders the numbers itself can still state what left the table. The default object also keeps the title the console prints, in attr(x, "title"). The same three objects record the direction of their percentages in attr(x, "percent"): "column" or "row" (see percent), and "column" for a table without by; and their base in attr(x, "percent_base"), "valid" or "total". The percentage columns of "data.frame", pct in "long" and the proportion of broom::tidy() hold the shares the table displays, in that direction and on that base: NA on the "(Missing)" row under "valid". On the "tinytable" route the note is set one size down; options(spicy.note_style) governs that (see table_regression()).

The Excel sheet carries the same title the console prints on its first row; the table itself starts on row 3.

Tests

When by is used, each selected variable is cross-tabulated against the grouping variable with cross_tab() and tested on the complete cases of its observed levels, a "(Missing)" level and a declared level nobody holds left out: one p-value per variable, in the p column. A table left with a single row or column (a variable observed at one level, or in one group) is uninformative and gets no test and no association measure, whatever test and assoc_measure say: its p and measure cells show an en dash, the undefined cell, and the note names no measure for it. A blank cell only means a statistic that was not requested or does not apply.

The chi-squared approximation is unreliable when expected counts are small. Under test = "auto", the default, a variable takes Pearson's chi-squared test (stats::chisq.test()) when every expected count of its table is at least 5, and Fisher's exact test (stats::fisher.test()) otherwise: the rule gtsummary's add_p() applies, with the same p-values. Fisher's exact test of a table larger than 2x2 is the Freeman-Halton extension. When its exact enumeration fails, which happens on large sparse tables, the p-value is its Monte Carlo estimate over simulate_B tables drawn with the observed margins: it is random, so call set.seed() first to reproduce it. test = "chisq" tests every variable by the chi-squared, the behavior before 0.14.0, and test = "fisher" every variable by the exact test.

Fisher's exact test is conservative: its actual level is often well below the nominal one, at a cost in power. test = "midp" gives a 2x2 table (a two-level variable by two groups) the Fisher mid-p test, as Fagerland, Lydersen and Laake (2017, equation 1.12, p. 28, and section 4.4.6, p. 97) and Lydersen, Fagerland and Laake (2009, equation 12, p. 1165) define it: the tables with the observed margins are ordered by their hypergeometric probability, and the p-value adds the probabilities of the tables less probable than the observed one to half the probabilities of the tables as probable, the observed one included, ties being read within the relative tolerance of stats::fisher.test(). The mid-p test can exceed the nominal level, usually by little, and Fagerland, Lydersen and Laake (2017, p. 175) recommend it for all sample sizes. A variable whose table is not 2x2 follows "auto", and the note names the test of each variable. The central variant, twice the smaller one-sided mid-p (the exact2x2 and epitools packages; Agresti, 2019, p. 49), coincides with this one when the row totals or the column totals are equal, except that it gives 1 for the most probable table; it differs otherwise and is not computed.

test = "n1" applies the rule of Campbell (2007, pp. 18-19) to a 2x2 table. When every expected count is at least 1, the table takes the N-1 chi-squared test: Pearson's statistic, with no continuity correction, multiplied by (N - 1)/N and referred to a chi-squared distribution with 1 degree of freedom, which is the Mantel-Haenszel statistic of a single 2x2 table; statistic and df hold that statistic in the long output. Otherwise it takes Fisher's exact test, two-sided by Irwin's rule as stats::fisher.test() computes it. Campbell found the N-1 test close to its nominal level under that restriction, not without it. A variable whose table is not 2x2 follows "auto", and the note names the test of each variable.

The note names the test behind the p-values, "P-values: Pearson chi-squared test (sex, education); Fisher exact test (smoking).", or the one test when it covers them all, "P-value:" when the table shows a single p-value. test_type in the long output gives the test of each variable. See ⁠@param correct⁠ / simulate_p to switch on Yates' continuity correction or Monte Carlo p-values for the chi-squared test, and ⁠@param assoc_measure⁠ for the per-row dispatch table used by "auto" (2x2 -> Phi, both ordered -> Kendall's Tau-b, otherwise Cramér's V). Without by, the table reports the marginal frequency distribution of each variable with no inferential statistics.

The exact tests condition on counts. Under weights, they run on the weighted table when its cells are whole numbers (frequency weights); otherwise a variable that a rule sends to Fisher's exact test keeps the chi-squared test, Pearson's under test = "auto" and the N-1 under Campbell's rule, with a warning (spicy_fallback), and test = "fisher", or test = "midp" on a 2x2 table, is an error. For survey weights, table_categorical_svy() gives the design-based test.

The test and the measure are two decisions with two arguments: p_value = FALSE removes the test, assoc_measure = "none" the measure. Together they give a purely descriptive table, which keeps the group columns and their headers; smd stays available.

For model-based comparisons (cluster-robust SE, weighted contrasts, fitted means) on continuous outcomes, see table_continuous_lm(). For descriptive (empirical) comparisons on continuous outcomes, see table_continuous().

Groups with no data

A variable with no observed value in a group of by that holds rows, typically a question not asked in that group, has no data there, which is not a missing answer. Its cells in that group show an en dash (NA in the data frames, in tidy() and in as_structured()), and its rows there are left out of everything computed for that variable: the missing values the note counts, the Total column, the "(Missing)" row, the test, the association measure and the SMD. A variable left with fewer than two groups with data is not compared: its p and measure cells show the dash, and the note names no test and no measure for it. The note says "No data for X in G.", in one sentence for the variables with no data in the same groups ("No data for X and Y in G."). Without by, a variable with no observed value at all keeps its declared levels (its one row when it declares none) with the dash, and the note says "No data for X." The column of missing by values is never such a group, and a declared level of by that holds no row keeps its zero column.

Multiple-comparison adjustment

The p-values of a descriptive table describe: they test no prespecified hypothesis. STROBE (explanation of item 14) and the SAMPL guidelines advise against significance tests in descriptive and baseline tables, hence the default p_adjust = "none".

When a journal or a protocol asks for adjusted p-values anyway, p_adjust applies stats::p.adjust() to the family of every test in the table: one p-value per variable (one per block in table_outcome()), never the rows of one variable, which share one test. "holm" suits a confirmatory set of comparisons, "BH" a screening one; table_regression() lists the methods. A test that returned no p-value stays out of the family.

The adjustment runs before any formatting, so the p column and its ⁠<.001⁠ threshold show the adjusted values, and the table note gives the number of tests and the method. The raw p-values stay in the object: a p_unadjusted column next to the p-value column of the returned data frames, and col_meta$p$p_unadjusted (with the method in p_adjust and the family size in p_adjust_m) in as_structured(). Without by, or with p_value = FALSE, the table shows no p-value to adjust, and a p_adjust other than "none" is an error.

Standardized mean difference

smd = TRUE adds an SMD column with the balance diagnostic of the Table 1 literature, on the variable row beside p. For a two-category variable it is the Bernoulli form,

\mathrm{SMD} = \frac{p_1 - p_2}{\sqrt{(p_1(1-p_1) + p_2(1-p_2)) / 2}}

with p the proportion of the SECOND category, signed, group 1 minus group 2 in the order the table displays them. Note the denominator: the Bernoulli variance p(1-p) at n, not var() at n-1, which would be 19% off on a small table.

"Second category" is the order the table shows, which is worth knowing for a logical variable: spicy displays TRUE then FALSE, so the sign is taken on FALSE, where tableone and cobalt coerce with factor() (FALSE, TRUE) and take it on TRUE – the same magnitude with the opposite sign. Convert to a factor with the level order you want if the direction matters.

For three or more categories it is the multivariate form of Yang and Dalton (2012, SAS Global Forum 335-2012),

\mathrm{SMD} = \sqrt{T' S^{-} T}

with T the difference of the two profiles of proportions (first category dropped) and S the mean of their multinomial covariance matrices. This is a Mahalanobis distance: it is unsigned, it is not bounded by 1, and S^{-} is a pseudo-inverse, because a declared-but-unobserved category makes S singular and solve() would abort where the pseudo-inverse returns exactly the value that category's absence implies. Which kernel a row took is published as smd_type in the "long" output, and the unsigned reading is stated in the table note whenever a variable has more than two categories. The MASS package is needed for this arm only.

Two profiles with no category in common have an infinite standardized distance. The pseudo-inverse would quietly publish a finite number there, so the cell is an en-dash and a classed warning says why. The same applies when each group is constant on a different category, where the naive route publishes 0 – "perfectly balanced" for the most imbalanced variable possible.

Conventions shared with table_continuous(): exactly two groups (three or more are refused, not averaged over pairs); complete cases on the observed groups, so a drop_na = FALSE "(Missing)" level is displayed and never enters the diagnostic; no confidence interval and no p-value, by design. Under weights the profiles are the weighted proportions, which makes this column agree with both the frequency and the survey-design readings – a profile of proportions is invariant to a global rescaling of the weights, so rescale cannot move it. (Only the continuous arm has a convention to choose there.)

The SMD cell keeps its leading zero where the association cell drops it: the APA strip belongs to a bounded measure, and this one is not bounded. The two columns therefore print 0.45 and .45 side by side, on purpose.

A balance table usually shows no test: p_value = FALSE removes the p column here as it does in table_continuous(), so a table mixing continuous and categorical variables can drop both. inline() quotes the cell from the variable row (inline(tbl, smoking, column = "smd")).

Display conventions

Decimal alignment, p-value formatting, and required suggested packages per output engine are documented under ⁠@param align⁠, ⁠@param p_digits⁠, and ⁠@param output⁠ respectively.

Counts are displayed as integers: weighted counts are rounded (ties half to even, the R convention) at display time only, in cells and margins alike – the SPSS Crosstabs convention. Cells and margins are rounded independently, so small display discrepancies are possible (e.g. two cells of exactly 0.5 each display as 0 while their Total of 1.0 displays as 1). The machine outputs ("data.frame", "long") carry the exact weighted counts and full-precision percentages.

Declared missing values

Survey files imported with haven often carry declared missing values: codes such as ⁠8 = Don't know⁠ or 9 = Refused that the source file marks as missing while keeping them distinct from a plain NA. Two kinds of declaration exist: na_values / na_range metadata on haven::labelled_spss() vectors, and tagged missing values created by haven::tagged_na() (the Stata .a, .b, ... convention). haven::read_sav() keeps the na_values / na_range declaration only with user_na = TRUE: its default turns the declared codes into NA on import.

spicy honors the declaration by default (user_na = TRUE): declared missing values are excluded from every statistic exactly like NA – valid percentages, means, chi-squared tests, association measures, row-wise summaries, and group definitions – but they are not erased from display. freq() lists each observed declared value as its own row of the Missing block, with its value label; cross_tab(), table_categorical(), and table_continuous() disclose the exclusion in the table note (⁠Declared missing values removed: x (2).⁠); varlist() counts them as missing in N_valid / NAs / N_distinct while still listing the declared codes in Values; code_book() counts them in n_declared_missing and flags them in its values table.

Every function involved offers the same escape hatch: set user_na = FALSE to ignore the declaration and treat the declared codes as valid values (the behavior of spicy before 0.13.0). Tagged missing values are genuine NAs either way; for them, user_na = FALSE only collapses the per-tag breakdown back into the regular NA count.

References

Agresti, A. (2019). An Introduction to Categorical Data Analysis (3rd ed.). Wiley.

Campbell, I. (2007). Chi-squared and Fisher-Irwin tests of two-by-two tables with small sample recommendations. Statistics in Medicine, 26(19), 3661-3675. doi:10.1002/sim.2832

Fagerland, M. W., Lydersen, S., & Laake, P. (2017). Statistical Analysis of Contingency Tables. Chapman and Hall/CRC. doi:10.1201/9781315374116

Lydersen, S., Fagerland, M. W., & Laake, P. (2009). Recommended tests for association in 2 x 2 tables. Statistics in Medicine, 28(7), 1159-1175. doi:10.1002/sim.3531

See Also

table_continuous() for empirical comparisons on continuous outcomes; table_continuous_lm() for the model-based companion (heteroskedasticity-consistent / cluster-robust / bootstrap / jackknife SE, fitted means, weighted contrasts); cross_tab() for two-way cross-tabulations; freq() for one-way frequency tables.

Other spicy tables: table_continuous(), table_continuous_lm()

Examples

# --- Basic usage ---------------------------------------------------------

# Default: ASCII console table grouped by sex.
table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = sex
)

# One-way frequency-style table (no `by`).
table_categorical(
  sochealth,
  select = c(smoking, physical_activity)
)

# Purely descriptive grouped table: no test, no association measure.
table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = sex,
  p_value = FALSE,
  assoc_measure = "none"
)

# A small sample: `smoking` has an expected count below 5 and takes
# Fisher's exact test; the note names the test of each variable.
table_categorical(
  sochealth[1:40, ],
  select = c(smoking, physical_activity),
  by = sex
)

# Pretty labels keyed by column name.
table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = education,
  labels = c(
    smoking           = "Current smoker",
    physical_activity = "Physical activity"
  )
)

# Survey weights with rescaling.
table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = education,
  weights = "weight",
  rescale = TRUE
)

# Confidence interval for the association measure.
table_categorical(
  sochealth,
  select = smoking,
  by = education,
  assoc_ci = TRUE
)

# --- Per-variable association measure ----------------------------------

# Default (`assoc_measure = "auto"`): one measure per row variable based on
# the variable type (2x2 -> Phi, both ordered factors -> Kendall's Tau-b,
# otherwise Cramer's V). When the chosen measures differ across rows, the
# column header collapses to `"Effect size"` and the note names the
# measure used for each variable.
table_categorical(
  sochealth,
  select = c(smoking, education),
  by = sex
)

# Force a uniform measure across all row variables: its symbol, V,
# heads the column, and the note defines it.
table_categorical(
  sochealth,
  select = c(smoking, education),
  by = sex,
  assoc_measure = "cramer_v"
)

# Per-variable override (recommended named form).
table_categorical(
  sochealth,
  select = c(smoking, education, self_rated_health),
  by = sex,
  assoc_measure = c(
    smoking           = "phi",        # binary x binary
    education         = "cramer_v",   # multi-category nominal
    self_rated_health = "tau_b"       # ordinal x binary, Tau-b
  )
)

# --- Output formats -----------------------------------------------------

# The rendered outputs below all wrap the same call:
#   table_categorical(sochealth,
#                     select = c(smoking, physical_activity),
#                     by = sex)
# only `output` changes. Assign each result to a variable -- some
# engines auto-print as a console-friendly text fallback inside
# the `?` help viewer.

# Wide data.frame (one row per modality).
table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = sex,
  output = "data.frame"
)

# Long data.frame (one row per (modality x group)).
table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = sex,
  output = "long"
)


# Rendered HTML / docx objects -- best viewed inside a
# Quarto / R Markdown document or a pkgdown article.
if (requireNamespace("tinytable", quietly = TRUE)) {
  tt <- table_categorical(
    sochealth, select = c(smoking, physical_activity), by = sex,
    output = "tinytable"
  )
}
if (requireNamespace("gt", quietly = TRUE)) {
  tbl <- table_categorical(
    sochealth, select = c(smoking, physical_activity), by = sex,
    output = "gt"
  )
}
if (requireNamespace("flextable", quietly = TRUE)) {
  ft <- table_categorical(
    sochealth, select = c(smoking, physical_activity), by = sex,
    output = "flextable"
  )
}

# Excel and Word: write to a temporary file.
if (requireNamespace("openxlsx2", quietly = TRUE)) {
  tmp <- tempfile(fileext = ".xlsx")
  table_categorical(
    sochealth, select = c(smoking, physical_activity), by = sex,
    output = "excel", excel_path = tmp
  )
  unlink(tmp)
}
if (
  requireNamespace("flextable", quietly = TRUE) &&
    requireNamespace("officer", quietly = TRUE)
) {
  tmp <- tempfile(fileext = ".docx")
  table_categorical(
    sochealth, select = c(smoking, physical_activity), by = sex,
    output = "word", word_path = tmp
  )
  unlink(tmp)
}


## Not run: 
# Clipboard: writes to the system clipboard.
table_categorical(
  sochealth, select = c(smoking, physical_activity), by = sex,
  output = "clipboard"
)

## End(Not run)

Categorical summary table from a survey design

Description

The design twin of table_categorical(): counts and estimated percentages of categorical variables computed from a survey::svydesign() or survey::as.svrepdesign() object instead of a data frame.

Every statistic is survey's. survey::svymean() estimates the percentages and their design effects, survey::svyciprop() their confidence intervals, and survey::svychisq() tests the association, Rao-Scott corrected and referred to the design degrees of freedom.

Usage

table_categorical_svy(
  design,
  select = tidyselect::everything(),
  by = NULL,
  labels = getOption("spicy.var_labels", FALSE),
  note_labels = NULL,
  levels_keep = NULL,
  include_total = TRUE,
  drop_na = FALSE,
  proportion_ci = FALSE,
  ci_method = c("logit", "likelihood", "asin", "beta", "mean", "xlogit", "wilson"),
  ci_level = 0.95,
  chisq_statistic = c("F", "Chisq", "Wald", "adjWald", "saddlepoint"),
  deff = FALSE,
  df = NULL,
  p_value = NULL,
  p_adjust = "none",
  percent_digits = 1,
  p_digits = 3,
  decimal_mark = ".",
  align = c("decimal", "center", "right"),
  note = NULL,
  note_add = NULL,
  output = c("default", "data.frame", "long", "tinytable", "gt", "flextable", "excel",
    "clipboard", "word"),
  indent_text = "  ",
  indent_text_excel_clipboard = strrep(" ", 6),
  excel_path = NULL,
  excel_sheet = NULL,
  clipboard_delim = "\t",
  word_path = NULL,
  user_na = TRUE,
  style = NULL
)

Arguments