Package {tabxplor}

A tabxplor_fmt object.

The name of the field to extract.

A tabxplor_tab.

For $, a column name. For dplyr::pull, the column to use to name the result – see its documentation.

A column name.

Passed on.

A tabxplor_tab.

See dplyr::pull.

A tabxplor_grouped_tab object.

Indices.

The new value.

A tabxplor_grouped_tab object.

Indices

For matrices and arrays. If TRUE the result is coerced to the lowest possible dimension (see the examples). This only works for extracting elements, not for the replacement.

A tabxplor_grouped_tab object.

Indices

The new value.

A tibble of class tabxplor_tab.

<data-masking> Variables, or functions of variables. Use desc() to sort a variable in descending order.

By default, will sort first by grouping variable. Set to FALSE to avoid this behaviour.

By default, will put totals at the end of their group. Set to FALSE to avoid this behaviour.

By default, only the rows with the same display than the first row are arranged : if the first row of the group displays percentages, rows with n or pvalues are kept at the same place (typically, at the end of the group). The synthetic n / percentage / p-value rows are found by their stored row kind, so they are kept at the same place too. Set to FALSE to avoid this behaviour.

The locale to sort character vectors in.

A table or data frame containing tabxplor_fmt columns.

A numeric vector of confidence levels, each between 0 and 1 (e.g. c(0.95, 0.99)).

Number of digits to round to (default 2). Rounding keeps color legends readable ("+1.96" rather than "+1.959964"); pass Inf for the exact values.

A data frame.

A named list used modify columns. A NULL value should remove an existing column.

A data frame.

Template to use for restoring attributes

A data frame.

A numeric or logical vector that indexes the rows of .data.

Future parameters.

The data frame.

<tidy-select> The variables to recode.

The input data frame's name (default: the expression given as data).

The output data frame's name, if different from name_in.

Print each level's frequency and count as a comment; defaults to TRUE when 5 or fewer variables are given.

"mutate" (default) writes a dplyr::mutate() call; "base" writes ⁠data$var <-⁠.

Print a "new" = "old" syntax reminder. Default TRUE.

Print to console, or open a temporary file when there are more than 5 variables; FALSE returns a data frame of the recode text instead.

The underlying count, as an integer vector of length n(). It is used to calculate confidence intervals.

What the column estimates, as a single string (an attribute, not a field): one key into the declared library of estimate scales. It says which field holds the estimate, what its null value is, whether the scale is additive or multiplicative, and which colour ladder it reads.

• "level_n": counts

• "level_pct": percentages (pct_type says of what)

• "level_mean": means (from numeric variables)

• "points": a difference between two percentages, in percentage points

• "mean_diff": a difference between two means, in the outcome's own units

• "raw_diff": a regression coefficient / marginal effect in the outcome's units

• "pct_ratio", "mean_ratio": the ratio of two percentages / two means

• "odds_ratio": a multiplicative effect (odds ratio, risk ratio, rate ratio)

• "log_coef": a link-scale coefficient (a log-odds, a log-rate)

• "mixed": what binding columns of unlike scales collapses to

The number of digits, as an integer, or an integer vector the length of n.

The display type : the name of the field you want to show when printing the vector, as a single string or a character vector the length of n. Every accepted value is listed in Every display token below; a named layout or a {} template combining several (e.g. "\{pct\} (n=\{n\})") is also accepted — see tabxplor-display.

The underlying weighted counts, as a double vector the length of n. It is used in certain operations on fmt, like means.

The percentages, as a double vector the length of n. Calculate with tab_pct.

The means, as a double vector the length of n.

The differences (from totals or first cells), as a double vector the length of n. Used to set colors for means and row or col percentages. Built by tab.

The ratio to the reference (relative risk for percentages, mean ratio for means), as a double vector the length of n.

The contributions of cells to (sub)tables variances, as a double vector the length of n. Used to print colors when color = "contrib". The mean contribution of each (sub)table is written on total rows (then, colors don't print well without total rows). Built by tab. The cell's adjusted standardized residual is not a field of its own: it is recovered from pvalue and this field's sign, and readable with display = "resid" (see tab).

The cells variances, as a double vector the length of n. Used with scale = "level_mean" to calculate confidence intervals.

The confidence interval half-width (margin of error), as a double vector the length of n. Kept for backward compatibility: it is stored as the symmetric bounds ci_inf/ci_sup and read back by get_ci().

The lower and upper bounds of the confidence interval, as double vectors the length of n. Built by tab.

The per-cell significance p-value, as a double vector the length of n.

The odds ratio (for a 3+ level variable, the OR of each level versus the reference), as a double vector the length of n.

The cell's own (unweighted) percentage base, as a double vector the length of n.

The effective sample size used for this cell's confidence interval, p(1-p) / Var_design(p) (a mean: s^2 / Var_design(mean)): from survey::svyrecvar under a survey::svydesign, from the closed-form flat-design variance when the weighted basis is asked for (tab(design_effect = TRUE)), else NA (the CI falls back to the raw unweighted base). It records the base that was used: a finite value where the design or weights corrected it, NA where nothing did, and the raw count where a correction was asked for but this cell could not carry one. Populated for descriptive cells (a crosstab/mean cell, a tab_reg Obs_* column whose interval came from a closed form); a coefficient column, and any column whose interval came from a fit instead, carry none. A double vector the length of n. Non-displayed.

The value this cell's estimate is COMPARED TO by the tab_reg colour measures "adjustment" / "between_groups", on the cell's own scale: the observed (crude) effect beside a model effect, or – under tab_vars with color = "between_groups" – the reference group's estimate. NA on cross-tables and wherever there is no counterpart (leaving those cells uncoloured). A double vector the length of n; displayable as display = "\{obs\}".

The standard error of the GAP between this cell's estimate and obs, on the estimate's own test scale. Written by tab_reg where the two estimates are independent (tab_vars groups), so color = "between_groups" can honour color_signif; NA elsewhere. A double vector the length of n. Non-displayed.

What kind of row the cell sits in — one of "data" (an ordinary body row), "total", and the synthetic display rows "n", "pct", "pvalue", "gof", "blank". A character vector the length of n. It supersedes the logical in_totrow field, kept as a soft-deprecated argument and read-only $in_totrow.

TRUE when the cell is part of a total table

TRUE when the cell is part of a reference row (cf. ref)

Use row_kind = "total".

FALSE when the comparison level is the subtable/group, TRUE when it is the whole table

The type of difference of the vector. Cf. tab.

For a percentage column, what the percentage is a percentage OF, and hence which axis its reference lies on (as a single string): "row", "col", "all" (frequencies by subtable / group, i.e. by tab_vars), "all_tabs" (frequencies for the whole table), or "none" (counts, means, coefficients).

The name of the col_var used to calculate the vector

The sub-population this column's block belongs to: a level of a spread_vars variable (tab_spread), or a tab_reg tab_vars group. "" (the default) when the table was never spread. Together with col_var it identifies a column BLOCK: two blocks may show the same variable for two sub-populations, and exports head them on two lines.

TRUE when the vector is a total column

TRUE when the vector is a reference column

The colour measure, as a single string — how a cell's value is compared to colour it (significance is handled separately by color_signif):

• "no": no colors are printed.

• "diff" ("difference"): the cell's difference from the reference (a total, or the first cell when ref = "first") — percentage points for factors, a standardized difference for means.

• "ratio": the ratio to the reference (relative risk for percentages, mean ratio).

• "or" ("odds_ratio"): the odds ratio, for row/col percentages.

• "contrib": the cell's contribution to the table's variance. Under color_signif = "guaranteed_effect" it switches to the absolute adjusted standardized residual — see tab.

• "adjustment" / "between_groups": the two tab_reg measures, which compare a cell to another column rather than to a reference row. A hand-built column may carry them, provided it fills the obs field they score.

The value is validated and normalised: every accepted spelling — the discipline's acronyms included ("RD", "RR", "IRR", "RoM", "OR" and their lowercase twins) — is stored as its canonical measure name, and an unknown one is an error. The tabxplor 1.x combined strings "diff_ci" / "after_ci" still work but are superseded by the color + color_signif pair; here they resolve to their measure half only, so pass the significance policy through color_signif.

How significance gates the color, as a single string ("ignore" / "grey_non_signif" / "guaranteed_effect"). See tab.

For regression tables (tab_reg): the column's model family ("binomial", "gaussian", "poisson", "multinomial", "ordinal"), as a single string. Empty ("") on cross-tables. Lets a table mix several outcomes with different families, each column keeping its own effect wording.

For regression tables (tab_reg): the column's role, "model" for a model-estimate column or "emp" for an empirical (crude) companion column. Empty ("") on cross-tables. Read by the colour legend to name each column's effect without matching its label.

The confidence level this column's interval and thresholds were computed at, as a single number in (0, 1). NA (default) means "unknown" — the colour engine then falls back to options("tabxplor.conf_level"). Stored per COLUMN, because colours are resolved per column at print time and cannot see the table's conf_level argument.

The degrees of freedom this column's interval is referred to. On a cross-table that is the survey design's #PSU - #strata, which matters below ~30 primary sampling units; on a regression it is the fitted model's own residual df (for an svyglm, degf + 1 - p), so a model column and its observed companion legitimately differ. NA (default) means "refer to the normal quantile".

How this column's interval and significance were computed — "n" (the raw sample size), "weights" (the design effect of the weights), "design" (a full survey design), or "design_partial" (a design was given but its variance could not be computed). Default "n". A per-COLUMN fact, so a table states honestly what its numbers carry even after a pipeline drops the table's metadata; binding columns keeps the WEAKEST basis.

Which interval ENGINE built this column's bounds — "wilson", "wald", "beta" (a cell proportion), "newcombe", "ac" (a difference of proportions), "katz" (a ratio of proportions), "welch", "student", "ols" (a difference of means), "robust", "quasipoisson", "poisson" (a ratio of means), "woolf", "wald_log", "profile"; "" (default) when the column carries no interval. Read back by the colour legend, so it always names the method the bounds were built with.

In fmt(), it exists only for the arguments retired in tabxplor 2.0.0: type is translated into scale + pct_type (see tabxplor-type), ci_type gets an error naming its replacement. In the accessor methods below, to add arguments in the future.

The object to test, to get a field in, or to modify.

A tabxplor_fmt vector, or a data.frame (then every fmt column is read).

The attribute: one of "scale", "comp_all", "ref", "pct_type", "col_var", "col_group", "totcol", "refcol", "color", "color_signif", "model_family", "role", "conf_level", "degf", "basis", "ci_method". An unknown name is an error naming the set.

The new value. Written through the attribute's own setter, so it is validated exactly as set_scale() and friends validate it.

The object to test, to get a field in, or to modify.

In fmt(), it exists only for the arguments retired in tabxplor 2.0.0: type is translated into scale + pct_type (see tabxplor-type), ci_type gets an error naming its replacement. In the accessor methods below, to add arguments in the future.

What the column estimates, as a single string (an attribute, not a field): one key into the declared library of estimate scales. It says which field holds the estimate, what its null value is, whether the scale is additive or multiplicative, and which colour ladder it reads.

• "level_n": counts

• "level_pct": percentages (pct_type says of what)

• "level_mean": means (from numeric variables)

• "points": a difference between two percentages, in percentage points

• "mean_diff": a difference between two means, in the outcome's own units

• "raw_diff": a regression coefficient / marginal effect in the outcome's units

• "pct_ratio", "mean_ratio": the ratio of two percentages / two means

• "odds_ratio": a multiplicative effect (odds ratio, risk ratio, rate ratio)

• "log_coef": a link-scale coefficient (a log-odds, a log-rate)

• "mixed": what binding columns of unlike scales collapses to

For a percentage column, what the percentage is a percentage OF, and hence which axis its reference lies on (as a single string): "row", "col", "all" (frequencies by subtable / group, i.e. by tab_vars), "all_tabs" (frequencies for the whole table), or "none" (counts, means, coefficients).

TRUE when the vector is a total column

By default, get_comp_all takes NA in comparison level to be a FALSE (=comparison at subtables/groups level). Set to FALSE to avoid this behavior.

FALSE when the comparison level is the subtable/group, TRUE when it is the whole table

The type of difference of the vector. Cf. tab.

The name of the col_var used to calculate the vector

For regression tables (tab_reg): the column's model family ("binomial", "gaussian", "poisson", "multinomial", "ordinal"), as a single string. Empty ("") on cross-tables. Lets a table mix several outcomes with different families, each column keeping its own effect wording.

TRUE when the vector is a reference column

The colour measure, as a single string — how a cell's value is compared to colour it (significance is handled separately by color_signif):

• "no": no colors are printed.

• "diff" ("difference"): the cell's difference from the reference (a total, or the first cell when ref = "first") — percentage points for factors, a standardized difference for means.

• "ratio": the ratio to the reference (relative risk for percentages, mean ratio).

• "or" ("odds_ratio"): the odds ratio, for row/col percentages.

• "contrib": the cell's contribution to the table's variance. Under color_signif = "guaranteed_effect" it switches to the absolute adjusted standardized residual — see tab.

• "adjustment" / "between_groups": the two tab_reg measures, which compare a cell to another column rather than to a reference row. A hand-built column may carry them, provided it fills the obs field they score.

The value is validated and normalised: every accepted spelling — the discipline's acronyms included ("RD", "RR", "IRR", "RoM", "OR" and their lowercase twins) — is stored as its canonical measure name, and an unknown one is an error. The tabxplor 1.x combined strings "diff_ci" / "after_ci" still work but are superseded by the color + color_signif pair; here they resolve to their measure half only, so pass the significance policy through color_signif.

How significance gates the color, as a single string ("ignore" / "grey_non_signif" / "guaranteed_effect"). See tab.

The object to test, to get a field in, or to modify.

The value you want to inject in some fmt vector's vctrs::field or attribute using a given "set" function.

In fmt(), it exists only for the arguments retired in tabxplor 2.0.0: type is translated into scale + pct_type (see tabxplor-type), ci_type gets an error naming its replacement. In the accessor methods below, to add arguments in the future.

The kind of row a cell sits in (see get_row_kind).

Use row_kind = "total".

TRUE when the cell is part of a total table

TRUE when the cell is part of a reference row (cf. ref)

The fmt vector to get the html color codes from.

The style type, "text" to color the text, "bg" to color the background.

Is your console or html table background "light" or "dark" ? Default to the current setting (RStudio theme when detectable, else "light").

Absorbs deprecated arguments (e.g. html_24_bit); ignored.

A table made with tab or tab_reg, or a list of tab. A list of tables sharing the same col_vars (and no tab_vars) is merged into one; any other list — several row_vars and/or tab_vars — is rendered one table after another, each keeping its own sub-tables.

Value columns to draw, by name. NULL (the default) draws the model columns of a regression table and every value column of a cross-table.

"auto" (the quantity the table's own interval is centred on), "effect" (the contrast: difference, ratio or odds ratio) or "level" (the percentage or mean – for a regression table this needs effect = "marginal").

For a regression table with empirical = TRUE: "auto", "band" (the observed value with the margin of error of the gap), "point", "ci" (the classic two-interval figure) or "none".

What marks the estimate: "n" (the default) a square whose area is the level's own base, with the value printed just above it; "estimate" the value alone; "none" a constant square and no value, for a plot with many panels.

What that value prints – a {} display template, as set_display takes ("\{est\} (\{base\})", "est_ci", ...). NULL (the default) prints the cell's own primary token.

Which axis is read and which is faceted: "keep" (the default) reads the table's rows, "transpose" reads its columns, "auto" picks whichever has more levels (more legible whenever the table is much wider than tall). A regression table is never transposed.

NULL for one panel per estimate column, FALSE for a single panel.

Set to FALSE for a plain plot with no colour measure.

"gridlines" (the default), "bands" (shade the panel between the colour breaks – the teaching mode, which makes a cell's colour and its position one statement) or "none".

Draw the regression Constant row.

Draw total rows and total columns.

How far below the estimate the observed value sits, as a fraction of a row; raise it for a tall figure with few rows. Under an adjustment colour the arrow takes this row and the observed value drops one further.

How far above the estimate its value is printed, as a fraction of a row.

Area of the largest marker, when center = "n" maps the base to it.

"short" (the default) the console's own footer, "full" the exports' longer one, or "none". Both are wrapped and set flush left.

Characters per footer line, since a ggplot caption does not wrap on its own. Use a larger number for a wide figure, smaller for a narrow one.

Where the colour legend goes: "auto" (the bottom), "right", "left", "top" or "none". When several ladders apply it cannot be a guide and goes to the caption instead.

"light", "dark" or one of the black-and-white publication palettes ("print_ready" and friends – a mark then reads its magnitude off a grey ramp). NULL follows getOption("tabxplor.export_theme").

Colour-legend language: NULL (auto from the R/OS locale, English fallback), "en" or "fr".

A caption. NULL keeps the table's own.

Include the table's subtext and footer lines in the caption.

Return the long estimate tibble instead of the plot.

Retired arguments, accepted and ignored with a deprecation message since 2.0.0. Anything else is an error naming the argument you meant, as it already was in tab().

A fmt object.

Other parameters.

Should html tags be added (to print confidence intervals as subscripts) ?

How NAs should be printed. Default to NA.

Set to TRUE to print more verbose results, like indicating which is the reference row or col for differences.

Append significance stars after the value (opt-in; default FALSE). Stars appear only where a per-cell p-value was stored (diff-type CIs / regression coefficients) and are right-padded so numbers stay aligned. They support the number rather than compete with it: in every theme they are drawn like an aside – the chrome's secondary grey, never bold, italic or underlined – so a run of symbols never shouts louder than the value it qualifies. The main display (console, tab_kable(), tab_md()) sets this TRUE; tooltip / secondary-field re-renders leave it FALSE, so stars never leak.

Which palette the cells are being rendered in. Only the black-and-white publication palettes use it: theme = "print_marks" writes a repeated superscript mark after each value instead of the significance stars, drawn exactly like them (see stars). NULL (the default) renders no palette annotation at all.

Internal (default FALSE): when TRUE, attach a per-cell primary_nchar attribute giving the bold-prefix width of a composite "{pct} (n={n})" cell, so exporters can bold only the primary field in a bold row. Off by default -> the output is attribute-free.

The character used to align numbers: it pads values (composite displays, significance stars, confidence intervals, a mean with no sd) and separates thousands. Defaults to a plain space, or to a figure space (U+2007, exactly one digit wide) when html = TRUE. Media read in a monospace font (the console, markdown) want the plain space; media rendered in a proportional font (html, Excel) need the figure space, since an ASCII space is only half a digit wide there – and CSS collapses runs of them. One glyph for both jobs, so the thousands mark can never disagree with the padding around it.

"text" (default) returns the rendered display strings; "excel" returns the per-cell Excel number-format codes used by tab_xl() (the raw value is written unchanged).

Internal: precomputed reference masks list(cells=, all_totals=) (derive-once speed-up passed by the exporter prep); computed internally when NULL.

Internal: the precision one token was named at in a composite template ("{base:1}"), passed by the composite expander; overrides every declared default.

The formatted number in which you want to find data for "get" functions, to modify data for "set" functions.

A tabxplor_tab.

A tibble of class tabxplor_tab.

Variables or computations to group by.

When FALSE, the default, group_by() will override existing groups. To add to the existing groups, use .add = TRUE.

Drop groups formed by factor levels that don't appear in the data? The default is TRUE except when .data has been previously grouped with .drop = FALSE.

An object to test.

A data.frame.

The row variable, which will be printed with one level per line. If numeric, it will be converted to factor. If several row variables are provided, it's not possible to add any tab_vars.

One column is printed for each level of each column variable. For numeric variables means are calculated, in a single column.

One subtable is made for each combination of levels of the tab variables. All tab variables are converted to factor. Leave empty to make a simple table. Not used when there are several row_vars.

A weight variable, of class numeric. Leave empty for unweighted results.

The type of percentages to calculate :

• "row": row percentages.

• "col": column percentages.

• "all": frequencies for each subtable/group, if there is tab_vars.

• "all_tabs": frequencies for the whole (set of) table(s).

Which measure to use for color helpers, as a single string. The values are the measure names tab() itself takes (the short spellings "diff" / "OR" stay valid aliases in R).

• "no": by default, no colors are printed.

• "auto": a smart per-column-type default (percentage-point difference on the text plus a relative-risk highlight on the background for factors, mean ratio for numeric columns).

• "difference": color the difference of each cell from its total (or reference cell). For factors this is a percentage-point difference; for numeric columns the standardized (SD-scaled) mean difference.

• "ratio": color the relative risk (factors) or mean ratio (numeric).

• "odds_ratio": for pct == "col" or pct == "row", color based on odds ratios. To PRINT them, set display (the colour and the printed quantity are two questions).

• "contrib": color cells based on their contribution to variance (factor columns only).

How significance gates these colors is set separately by color_signif.

How statistical significance gates the colors, as a single string.

• "ignore": by default, color every deviation by its observed size.

• "grey_non_signif": color by observed size, but grey out cells whose deviation is not significant (at conf_level). A confidence interval on the difference is computed automatically.

• "guaranteed_effect": color by the guaranteed (confidence-bound) effect – all cells whose interval clears the threshold show, with dimmer colors.

Set to TRUE to add a test p-value row: a Chi-square test for categorical column variables and an ANOVA F-test for numeric ones (chosen automatically per column type). Also enables colouring cells by their contribution to variance.

Which F statistic to display for numeric column variables when the test is on: Welch's F (default, does not assume equal variances) or the classic pooled F.

The policy to adopt with missing values. It must be a single string.

• na = "keep": by default, prints NA's as explicit "NA" level.

• na = "drop": each column variable drops its own NA's, so tables made with different column variables may have a different number of observations.

• na = "drop_all": drops every observation missing on the row variable, any column variable or a tab variable (all columns then share one base).

• na = "common_base": fixes a single population (non-missing on the row variable and the first column variable), while secondary column variables keep their own NA's. Reproduces the historical tab() behaviour.

The levels of col_vars to keep.

• "all": by default, all levels are kept.

• "first": only keep the first level of each col_vars

• "auto": keep the first level when col_var is only two levels, keep all levels otherwise.

By default, clean levels names, by removing prefix numbers like "1-", and text in parenthesis. Set to FALSE to avoid this behaviour.

.

.

.

.

The reference cell to calculate differences and ratios (used to print colors) :

• "auto": by default, cell difference from the corresponding total (rows or cols depending on pct = "row" or pct = "col") is used for diff ; cell ratio from the first line (or col) is use for OR (odds ratio/relative risks ratio).

• "tot": totals are always used.

• "first": calculate cell difference or ratio from the first cell of the row or column (useful to color temporal developments).

• n: when ref is an integer, the nth row (or column) is used for comparison.

• "regex": when ref is a string, it it used as a regular expression, to match with the names of the rows (or columns). Be precise enough to match only one column or row, otherwise you get a warning message.

• "no": not use ref and not calculate diffs to gain calculation time.

With OR = OR (odds-ratios) and a 3+ levels factor, a second reference cell is needed to calculate relative risks ratios. First cell by default.

The comparison level : by subtables/groups, or for the whole table.

What the confidence interval is anchored on – one question, four answers. The GEOMETRY of the interval is not asked here: it follows the comparison the table makes (set by color / display), so a difference table gets a difference interval and a ratio table a ratio one.

• "auto": build the comparison interval when something reads it (stars, or a color_signif policy), and none otherwise.

• "no": no interval at all.

• "cell": each cell's own interval (a percentage / a mean with its own bounds). It anchors nothing to compare, so stars and color_signif are informed and switched off.

• "ref": the interval of the comparison with the reference cell – what stars and color_signif read.

The confidence level, a single numeric between 0 and 1 — 0.95 by default.

With ci = "diff", print significance stars (* ** ***) for the difference of each cell from its reference. Read from the same confidence interval that is displayed, so stars and bracket always agree.

For a WEIGHTED table, make the confidence intervals, the significance stars, the colour thresholds AND the p-values account for the unequal weighting (the exact flat survey-design variance) instead of using the raw number of respondents. Sets options(tabxplor.design_effect). Off by default; it moves every interval in the table, not only the p-value.

The proportion confidence-interval method for ci = "cell": "wilson" (the score interval, default) or "wald" (the normal approximation).

The proportion confidence-interval method for ci = "diff". "newcombe" (default) is the dual of the two-proportion score test, so the interval and the significance stars always agree.

The confidence-interval method for the difference of numeric means (means with ci = "diff"): Welch (default), Student (the two groups pooled) or OLS (pooled over every level of the variable, i.e. the interval a linear model gives that coefficient).

The confidence-interval method for a ratio of numeric means (means with ci = "ratio").

How the table is painted, in the results panel and in every export. "light" is the colour palette; "print_ready" says the same thing typographically — bold, italics, underlines and marks instead of blue and red — for a page that has no colour. See tab_css.

The total table, if there are subtables/groups (i.e. when tab_vars is provided). Vectorised over row_vars.

• "line": by default, add a general total line (necessary for calculations with comp = "all")

• "table": add a complete total table (i.e. row_var by col_vars without tab_vars).

• "no": not to draw any total table.

By default, rownames are wrapped when larger than 30 characters.

By default, colnames are wrapped when larger than 12 characters.

What each cell shows. Every value here is a tab(display =) value: a bare field name, a named layout such as "base_ci" (each value with its interval), or a {} template combining fields. "auto" keeps whatever the table was built with. A template naming a field the table does not carry renders empty and says which argument would fill it.

How many people the table is about: "range" prints the unweighted base beside the Total cell (as min-max when the column variables rest on different people), "min" the smallest base only, "no" no count at all.

Set to TRUE to add a column with the frequencies of the row variable (for pct = "row") or a row with the frequencies of the column variable (for pct = "col")

A character vector to print rows of legend under the table.

The number of digits to print, as a single integer (0-6). In R, tab() also accepts an integer vector the same length as col_vars.

A pure display filter (0 = off). A row is dropped only when its largest base across the column variables is below n_min; surviving cells whose own base is below n_min are blanked. Under pct = "col" weak columns are dropped instead. Totals, the added-n row/column and the p-value line are always kept. Recomputes nothing.

The export file format: Excel (.xlsx), HTML (.html) or Markdown (.md).

Press to export the table to the chosen format (the button label follows the format).

The folder to save the exported file in. Blank or ~/Documents auto-detects your real Documents folder (a redirected D:/Documents or network Documents included). Type any other folder to override; a leading ~ there expands to your home folder.

The bare file name, with NO extension (the chosen format adds it). Illegal characters are removed automatically. Blank saves as "Table".

Reset the folder and file name to their defaults (your Documents folder and "Table").

"Set to TRUE to overwrite an existing file."

A data.frame.

The outcome variable(s). One model is built per outcome. Set each outcome's family (and, for a binomial outcome, its modelled level or number of trials) in the Model table.

The explanatory variables of the model. Factors are shown one line per level (the reference level as the neutral value); numeric predictors as a single line.

A grouping variable. The same model is fitted within each of its levels and the tables are stacked (like tab_vars for crosstables).

A survey weight variable. Switches to design-based estimation (scale-invariant sandwich standard errors). Leave empty for unweighted results.

.

WHICH MEASURE THE MODEL ESTIMATES – the only argument that changes the model. A link IS a measure, so it takes the same words as measure. Chosen per outcome, in the Model table beside family: "auto" is the family's own (a logistic regression for a binary outcome, a linear one for a quantity, a Poisson one for a count), and "odds_ratio" / "ratio" / "difference" name the model whose coefficient IS that measure – on a binary outcome, the logistic fit, the modified Poisson (Zou 2004) and the identity-link additive-risk one. The picker only ever offers the links the chosen family can be fitted on.

.

.

WHERE THE NUMBER COMES FROM, once the model and the reported measure are fixed.

• "auto": the coefficients when the reported measure IS the model's own, the model's predictions otherwise. Nobody needs to change this.

• "conditional": read off the model's own coefficients.

• "marginal": worked out from the model's predictions for every observed person, then averaged.

• "at_reference": the same, at one profile (every other predictor at its reference level / mean).

WHICH MEASURE IS REPORTED. It never changes the model: where it is not the measure the model estimates (see link), it is worked out from the model's predictions.

• "auto": the model's own measure – follow from the left. On a prediction route it steps back to the outcome's own (a percentage reads as "x times as likely"), because a marginal odds ratio is a specialist quantity, asked for by name.

• "odds_ratio" / "ratio" / "difference": the named measure, when the outcome's level can carry it. One it cannot says so, and lists what it does offer.

• "raw_coefficient": the model's own coefficient, un-transformed — the log of the reported measure wherever that measure is multiplicative, and the additive estimate itself on a model that is already additive.

Show the crude, unadjusted, single-predictor effect beside each model effect — the bivariate association that IS the modelised quantity when there is a single predictor, so the gap between the two is what adjustment changed.

.

"drop_by_outcome" (default) fits every model OF ONE OUTCOME on the same complete cases, which is what makes the observed columns comparable to the model beside them and lets the likelihood-ratio comparison run; "drop_by_model" gives each model its own complete cases (a model on a different population then gets no observed effect); "drop_all" shares one population across every outcome as well.

.

.

.

.

.

.

.

The confidence level for intervals and the significance stars.

Wald intervals (also the only option for weighted models) or profile-likelihood intervals (unweighted binomial / poisson only; needs MASS). A profile interval is an output of the likelihood at one confidence level, so it cannot be cached: every change refits the models.

Show per-cell significance stars (the colours read the confidence interval either way).

WHAT the effect cells are coloured by. The colour LADDER always comes from what the column estimates (an odds ratio is read on the odds-ratio scale, a beta on the standardized-difference one), so what is left to choose is what the estimate is compared TO.

• "measure": the effect's own size (compared to no effect).

• "no": no colours.

• "adjustment": how far the ADJUSTED effect moved from the crude one – needs empirical.

• "between_groups": how far each group's effect is from the first group's – needs tab_vars.

How significance interacts with the colours: observed size + grey out non-significant cells, colour only the guaranteed (error-adjusted) effect, ignore significance.

The estimate-cell LAYOUT (never the estimand: a display may fold in another quantity of the SAME fit, it can never change the fit). The same named layouts tab() offers, written in the same {} grammar: est is whatever the column estimates and base the level it sits on (an adjusted probability, an adjusted mean). "auto" keeps the built-in layout.

The column giving the number of observations behind each predictor level: "range" prints min-max when several models were fitted on different people, "min" the smallest count only, "no" no column at all.

The minimum number of digits to print, as a single integer (0-6): each measure keeps its own precision where that is finer (an odds ratio reads at two decimals, a mean score at one). In R, tab_reg() also names one display field at a time, digits = c(ratio = 3).

Strip numeric prefixes from factor level labels.

A free note printed below the table.

How the table is painted, in the results panel and in every export. "light" is the colour palette; "print_ready" says the same thing typographically — bold, italics, underlines and marks instead of blue and red — for a page that has no colour. See tab_css.

.

.

.

Press to export the table to the chosen format (the button label follows the format).

The folder to save the exported file in. Blank or ~/Documents auto-detects your real Documents folder (a redirected D:/Documents or network Documents included). Type any other folder to override; a leading ~ there expands to your home folder.

The bare file name, with NO extension (the chosen format adds it).

Reset the folder and file name to their defaults (your Documents folder and "Regression").

Excel export only: draw the model-check plots (reg_check_plots()) under each table in the workbook — the panels that apply to the fitted family (tab_xl(check = "auto")). Needs ggplot2 and gridExtra; without them the export says so and writes the table alone.

"Set to TRUE to overwrite an existing file."

A data.frame.

Ignored.

A tabxplor_fmt column.

Name-value pairs. The name gives the name of the column in the output (do not change it).

The value can be:

• A vector of length 1, which will be recycled to the correct length.

• A vector the same length as the current group (or the whole data frame if ungrouped).

A factor (or anything factor() accepts).

One of "level", "var", "tab_var".

The variable name the labels belong to; NA on a merged levels column.

A named logical vector, one entry per variable, saying whether that variable was ordered in the source data. A single-variable column keeps its own ordered class as well.

A table, stored into a tibble data.frame. It is generally made with tab, tab_reg or tab_plain.

A character vector to print legend lines under the table.

A tidy tibble storing whole-table test results (Chi2 for factor columns, ANOVA F for mean columns), filled by tab_chi2.

Soft-deprecated alias of test.

The table's metadata, as a single named list gathering (all optional, NULL when unset):

• render_extras – display-only intent for the base count and the add_pct companion, list(n =, add_pct =), materialised at print/export time from this attribute rather than baked into the table.

• spec – the table's identity, list(kind =, vars =, call =): its kind ("crosstab" or "regression"); vars, what no column can carry (list(wt =, caption =, outcomes =, var_labels =) – see set_caption), the rest of the variable model being derived from the declared index columns and from the columns' own col_var; and call, the producer's own recipe (a regression's model record – family, outcome, predictors, reference level, and the fit_spec reg_check_plots refits from).

• empirical_tips – multinomial crude-companion tooltip data (a tibble keyed by column, predictor and level), set by tab_reg(empirical = TRUE).

• assumptions – one record PER OUTCOME, keyed by it, each holding the observed curve of every continuous predictor (weighted quantile bins of the outcome on the family's link scale, one block per tab_vars group), set by tab_reg: the data behind the sparkline – drawn in a continuous predictor's n cell, or in the shape table below the footer – and behind reg_check_plots's linearity panel.

• color_breaks – a per-table override of the colour break scales (see set_color_breaks), merged over the global option at render time.

meta sub-fields left NULL are dropped, so a table given nothing carries no attribute.

Needed to implement subclasses.

Needed to implement subclasses.

The grouping data.

A fmt object.

Other parameter.

Internal: precomputed reference masks, as list(cells =, all_totals =), threaded to format() to avoid deriving them again (exporters compute them once for the whole table). NULL (the default, and the console path) recomputes them. Not for direct use.

Object to format or print.

Width of text output to generate.

Passed on to tbl_format_setup().

Number of rows to show.

Number of extra columns to print abbreviated information for, if the width is too small for the entire tibble.

Maximum number of footer lines.

Minimum number of characters for the row variable. Default to 30.

Set to TRUE to get the text as a character vector instead of a printed output.

A html table returned by tab_kable.

Passed to the next print method.

Object to format or print.

Width of text output to generate.

Passed on to tbl_format_setup().

Number of rows to show.

Number of extra columns to print abbreviated information for, if the width is too small for the entire tibble.

Maximum number of footer lines.

Minimum number of characters for the row variable. Default to 30.

Set to TRUE to get the text as a character vector instead of a printed output.

A tabxplor_tabs object (the list returned by tab / tab with output_list = TRUE for a multi-table result).

Passed to the per-table print method.

A tab_reg() table, or a fitted model (lm / glm / svyglm / polr / multinom / svyolr).

The data frame or survey::svydesign the table was built from. Usually unnecessary: a table records the name it was called with, and when that name still holds data of the same size, it is used — otherwise the call stops rather than draw the wrong model. Give data explicitly when the table was built from an expression rather than a named object (tab_reg(gss |> dplyr::filter(...), ...)), or when the name has since changed. Ignored with a bare model.

Which panels to draw. "auto" (default) draws the panels that decide something the footer cannot say in one number — linearity, residuals, normality, influence, and proportionality for an ordinal outcome. "all" adds dispersion and collinearity, whose footer row is normally enough. Or name them: any of "linearity", "residuals", "normality", "dispersion", "influence", "collinearity", "proportionality" — the same words the footer rows and tab_reg()'s stats argument use.

Optional: restrict the linearity panel to these continuous predictors.

Number of panel columns in the assembled grid (default: as square as it can be, 3 at most).

Number of facet columns inside a panel (default: 2 for linearity, 4 for proportionality).

"light", "dark", or a black-and-white publication palette ("print_ready" and friends). Defaults to options("tabxplor.theme"), like the table exporters.

Language of the titles and captions ("en", "fr", ...). Defaults to options("tabxplor.lang").

Thin the raw-point layers to about this many observations; statistics and verdicts are always computed on the full data.

Bins of the linearity panel's observed curve (default 10).

Confidence level of the Q-Q band. Default 0.95.

Seed of the randomised quantile residuals (NULL for a fresh draw each time).

Unused, for future extension.

A table built by tab_reg().

A data frame (or a survey design), as for tab_reg().

The outcome column name.

The model family. "auto" (default) lists every family this kind of outcome can take, the detected one first — which is the choice to make before the others.

Which measure the model estimates. "auto" (default) reads the table at each family's own model; "all" adds every other link it fits; name one to read it at that model alone.

A tibble of class tabxplor_tab.

Columns to move. will move columns to the left-hand side; specifying both is an error.

A tibble of class tabxplor_tab.

Use new_name = old_name to rename selected variables.

A tibble of class tabxplor_tab.

A function used to transform the selected .cols. Should return a character vector the same length as the input.

Columns to rename; defaults to all columns.

Additional arguments passed onto .fn.

A tibble of class tabxplor_tab.

Variables to be preserved when calling summarise(). This is typically a set of variables whose combination uniquely identify each row.

A tibble of class tabxplor_tab.

Variables to be preserved when calling summarise(). This is typically a set of variables whose combination uniquely identify each row.

A data.frame.

The name of the score variable to create (unquoted or a string); an existing column of that name is replaced.

The factors to count, as a character vector. For each one only its first level counts (as 1); every other level, including missing values, counts as 0.

A tibble of class tabxplor_tab.

One or more unquoted expressions separated by commas. Variable names can be used as if they were positions in the data frame, so expressions like x:y can be used to select a range of variables.

A tabxplor_tab (or a tabxplor_tabs list of them).

A single string, or NULL / NA to remove any stored caption.

Light-theme palettes (4 hex each): the text (font) and background (fill) colours for the over- (*_colors) and under-represented (*_colors_neg) sides.

The dark-theme counterparts (4 hex each).

(4 hex each) The FONT stand-in for background_colors in the colour legend of media that cannot fill a run (Excel); the defaults are the background colours at -0.2 OKLCH lightness. Setting background_colors without these makes them follow it unchanged (readable only if your fills already are). There is no dark counterpart: an Excel legend cell is on a white page whatever the theme, and the dark fills read there as-is.

Which palette theme. In set_color_palette(): "light" or "dark" for the console / exports, or "auto" to detect the console's colour scheme now (the RStudio theme, the Positron theme, or COLORFGBG; "light" when it cannot be told). Detection is best-effort and resolved ONCE: call again after changing your editor's theme. (This is the console only — tab_css / tab_html take their own theme = "auto", which follows the reader's browser.) In get_color_style(): "light", "dark" or one of the black-and-white publication palettes ("print_minimalistic", "print_emphasis", "print_marks"); "auto" resolves to "light" there, a palette being always one definite thing. Both default to the current setting.

Which palette, or which half of a break scale — the word means one thing per function, and both are given here because they share this page. In get_color_style() and the deprecated set_color_style(): "text" (font colour), "bg" (background fill), or "bg_legend" (mode = "color_code" only), the darker FONT stand-in for the background palette, for media that cannot fill a run (an Excel rich-text run) – see the colour legend. In get_color_breaks(): "positive" (the default) returns a readable form – a plain vector of magnitudes when the scale is symmetric, a list(over =, under =) otherwise – and "all" the signed / reciprocal thresholds the engine actually compares against (c(-x, x) for additive scales, c(1/x, x) for multiplicative ones).

Inert since 2.0.0 (exports are always 24-bit).

A former 10/11-slot palette; its 4 over- and 4 under-represented colours are mapped onto set_color_palette().

By default, get_color_style returns a list of terminal (ANSI) coloring functions (the historical value "crayon", now built with cli). Set to "color_code" to return html color codes, or "face" to return the palette's TYPOGRAPHY – a list bold / italic / underline of 8 logicals each (plus a semantic flag), which is how a publication palette says "over-represented cells are bold, under-represented ones italic". The colour palettes report bold on every text slot and nothing on the background ones, i.e. exactly how they have always been drawn.

Scales passed individually and named, e.g. set_color_breaks(pct_diff = c(0.05, 0.1, 0.2), mean_ratio = c(1.15, 1.5, 2, 4)). Each value is either a plain vector of signed / reciprocal literals (negatives, or ratios < 1, are the under-represented side; a one-sided vector auto-mirrors; NA skips an intensity slot) or a list(over =, under =) of magnitudes (no mirror; omit a side to switch it off, e.g. list(over = 2) for the "only x2" rule). The old pct_breaks / mean_breaks / contrib_breaks arguments are soft-deprecated but still work (mapped onto the new scales).

A named list of scales to set, e.g. list(pct_diff = c(0.05, 0.1, 0.2, 0.3), pct_ratio = list(over = 2)). Unset scales keep their current value.

When missing, return the full named list of the ten break scales – the same shape set_color_breaks accepts, so it round-trips (an asymmetric scale comes back as list(over =, under =), a standardized one with std = TRUE). Specify one scale name to return only its breaks. The old aliases "pct" (-> pct_diff) and "mean" (-> mean_ratio) are still accepted.

A numeric vector.

A single string, or a number of groups — see The shapes below.

Optional weights, the same length as x. Quantile breaks and the mean/SD landmarks are then weighted — equal shares of the population, not of the sample.

The variable's name, written onto the first level only ("age: [18,35) low"), so a table that names the variable nowhere else still says what the levels are levels of. NULL (the default here) writes nothing. It applies to the two CUTS, whose levels are intervals and band words; "values_to_levels" keeps the raw values, which name themselves.

Whether the resulting factor is ordered. Bands and quantile groups do have a real order; a model fit does not want one (an ordered factor takes polynomial contrasts instead of contrasts against a reference), which is why tab_reg() cuts unordered.

A tibble of class tabxplor_tab.

Name-value pairs of summary functions. The name will be the name of the variable in the result.

Grouping structure of the result.

A data frame.

<tidy-select> The row variable(s), printed with one level per line, and the column variable(s), one level per column. A numeric variable gives a single column of means. Each accepts one variable or several, c(var1, var2).

<tidy-select> The column variable(s) — see row_vars. An interaction is written a*b, as in tab_reg(), and only col_vars takes one: two factors give one column per observed cell of the pair, a number crossed with a factor one mean column per level. See vignette("tabxplor").

<tidy-select> Tab variables: one subtable per combination of their levels. Leave empty for a simple cross-table.

A weight variable, of class numeric. Leave empty for unweighted results.

Arguments taken by name, and kept out of the signature. Past the variable roles every argument must be named, and an unknown name is refused with a suggestion. tot Which totals to show: c("row", "col") or "both" (default), "row", "col", or "no" (removed after the calculations that need them). shape How a numeric variable enters the table. Cut it into groups and it becomes an ordinary factor — one row (or column) per group. One value for every numeric variable, or one per variable: shape = c(age = "quintiles"). On the row and tab axes a number always gets one, "auto" by default; a numeric col_vars keeps its means. shape_numeric_var lists the whole vocabulary. shape_name Whether a shaped variable writes its own name onto its first level ("age: [18,30) low"), so a table whose leading text columns are stripped still says what the levels are levels of. FALSE by default. Retired in 2.0.0, still taken by name, each warning once and saying what to use instead: row_var, col_var, sup_cols, totaltab_name, total_names, OR, chi2, method_cell, method_diff, add_n, names_prefix, names_sort, other_level. The dot-prefixed names (.cache, .defer_level_merge, .return_armed, .levels_order, .levels_collapse) are internal plumbing, not user arguments.

The percentages to calculate, as a single string or a vector the same length as col_vars: "row", "col", "all" (frequencies within each subtable), "all_tabs" (frequencies over every table) or "no" (default, counts). Everything else — the reference, the interval, the colour — follows from this choice.

Which measure of deviation to color — a deviation being how far a cell sits from its reference, the measure which of the ways of expressing it you read. "no" (default, FALSE equivalently) prints no color; TRUE picks one per column type. Otherwise:

• "difference" ("RD", "diff"): the cell's difference from its reference (percentage points for factors, Glass's \Delta for means).

• "ratio" ("RR", "IRR", "RoM"): relative risk (factors) or mean ratio (numerics) vs the reference.

• "odds_ratio" ("OR"): the odds ratio, on percentage tables, coloured on its own symmetric scale.

• "contrib": signed contribution to the chi-squared (reference-free).

The acronyms in brackets are permanent aliases, the same words tab_reg's measure takes. An acronym here always names a measure, where display = names a field and ref2 = a level. Position picks the channel (1st value -> text, 2nd -> background) and names pick the column type: c("difference", "ratio"), c(pct = "difference", mean = "ratio"), or both with a list(). Only difference / ratio may go on the background; thresholds come from set_color_breaks.

How significance gates the color, as a single string:

• "ignore" (default): color every deviation by its observed size.

• "grey_non_signif": color by the observed size, but grey out cells whose deviation is not significant at conf_level. A coloured cell is then significantly different from its reference; a grey one may still be significant, only too small to colour.

• "guaranteed_effect": color by the guaranteed (confidence-bound) effect – only cells whose interval clears the threshold, with dimmer, conservative colors.

With color = "contrib", which has no interval to floor, the first two color the relative contribution and "guaranteed_effect" the adjusted standardized residual. See vignette("tabxplor").

Set to TRUE to test each (sub)table for independence: Chi-squared for factor col_vars, Welch's F for numeric ones, with an effect size beside it. Needed by color = "contrib", and added automatically for it. The footer names the test you actually got — see vignette("tabxplor-weights").

The policy to adopt for missing values, as a single string :

• "keep" (default): every NA becomes an explicit "NA" level.

• "drop": each column is computed on its own non-missing observations, so bases can differ between col_vars.

• "drop_all": drop every observation missing on any variable, so all columns share one base.

• "common_base": one population — non-missing on the row_vars and the first col_vars — while the other col_vars keep their own NA's as a level within it. Microdata only.

The levels of col_vars to keep, as a single string or a vector the same length as col_vars: "all" (default), "first" (only the first level of each — a compact summary of many items), or "auto" (the first level of a two-level variable, all of them otherwise). For finer selections use dplyr::select on the finished table.

Set to TRUE to clean level names, by removing prefix numbers like "1-" and text in parentheses. NULL (default) reads options(tabxplor.cleannames) — FALSE.

When set to a positive integer, levels with less count than it will be merged into an "Others" level.

The reference cell that differences and ratios are computed against:

• "auto" (default): the corresponding total for a difference, the first row (or column) for an odds ratio. "tot": always the total.

• "first" / "last": the first or last level — useful to color a temporal development. A total is not a level and is never selected.

• an integer, the nth row (or column); a string, a regular expression matched against the row (or column) names. "no": no reference.

One reference per row_vars with a named vector, ref = c(race = "first"); an unnamed one goes by position.

The second reference level for odds ratios, needed only for a factor with 3 levels or more (the "OR of each level versus ref2"); the first level by default. Ignored for a binary factor, where each level's OR is taken against the other. Same values as ref.

What each cell is compared with: "tab" (default) compares it inside its own tab_vars subtable, "all" against the total table's own reference line.

What the confidence interval is anchored on. Its geometry is not asked here: it follows the comparison the table makes, so an odds-ratio table gets an odds-ratio interval.

• "auto" (default): on the comparison where the table makes one, on the cell for plain frequencies, none where nothing needs one.

• "ref": on the cell's deviation from its reference. "cell": on the cell's own percentage or mean. "no": none.

"cell" and "no" anchor nothing to compare, so stars and color_signif are disabled (with a message). The method is chosen with ci_method and named in the table's legend.

The confidence level, as a single numeric between 0 and 1. NULL (default) reads options(tabxplor.conf_level) — 0.95.

Logical. With ci = "ref", print significance stars for each cell's difference from its reference, read from the displayed interval itself. NULL (default) reads options(tabxplor.stars) — FALSE.

The interval method, one kind at a time, as ONE named vector – partial, like ref or pct, so an unnamed kind keeps its default. Example: ci_method = c(cell = "beta", diff = "ac").

• cell, a proportion's own interval: "wilson" (default), "wald", "beta".

• diff, a proportion minus its reference: "newcombe" (default), "ac", "wald".

• mean_diff: "welch" (default), "student", "ols".

• mean_ratio: "robust" (default), "quasipoisson", "poisson".

A proportion ratio has only one method (Katz), so it is not a choice.

Which one-way ANOVA F the p-value line shows for numeric col_vars: "welch" (does not assume equal variances) or "classic" (the pooled F). NULL (default) reads options(tabxplor.anova) — "welch". Both are always computed, so this only chooses which row is shown.

Whether the intervals, stars and colour thresholds of a weighted table account for the weighting's own design effect instead of using the raw sample size. NULL (default) reads options(tabxplor.design_effect) — FALSE. Ignored without wt. See vignette("tabxplor-weights").

The total table, when tab_vars makes subtables: "line" (default, a general total line), "table" (a complete total table — row_vars by col_vars, without tab_vars) or "no".

With several row_vars, FALSE (default) shows one Total row per row variable; TRUE collapses the identical ones into a single shared Total. Genuinely different totals (which only na = "drop" can produce) are never merged.

How many people this table is about. NULL (default) reads options(tabxplor.n) — "range", which prints the unweighted base beside the Total cell, 100% (9 838), or the whole range where the columns do not rest on the same people, 100% (6 712-9 838), so an unequal base cannot pass unnoticed. "min" prints the smallest base only; "no" none.

A single positive integer (default 0, off). A pure display filter applied last: it hides cells resting on too few people, without recomputing anything. Totals and the p-value line are always kept.

Set to TRUE to add a column with the frequencies of the row variable (for pct = "row") or a row with the frequencies of the column variable (for pct = "col").

A character vector to print rows of legend under the table.

A title for the table. It is stored on the table, so it survives a dplyr pipeline and travels into every export — html, Markdown, Excel, forest_plot() — where an exporter's own caption still wins. set_caption() attaches one after the fact, get_caption() reads it back.

The number of digits to print, as a single integer, or an integer vector the same length as col_vars.

What each value cell shows (text output only – the console, tab_kable and tab_md; Excel falls back to the primary field). NULL (default) keeps each cell's plain value. Three ways to ask: a named layout ("est_ci", "base_ratio"), a single field ("ci", "diff"), or a {} template of your own ("\{pct\} (n=\{n\})"). The whole vocabulary is in tabxplor-display; set_display changes it on a table already built. A layout showing an interval prints the one the table computed, so pair it with a ci = value or a color that needs one.

A per-table override of the colour thresholds, in the form set_color_breaks accepts; unset scales keep the global ones.

Logical (default FALSE). With several row_var, FALSE merges the mirror tables into a single tabxplor_tab; TRUE returns a list with one table per row_var. With tab_vars, tables stay a list regardless.

<tidy-select> The tab_vars to show ACROSS the page instead of down it: each of their levels becomes a block of columns, and the table becomes as compact as it can be. A variable named here alone is added to tab_vars for you. Pair it with comp = "all" to compare every block against the overall total, and with levels = "first" to keep one column per block. Because the columns are multiplied, a cell layout you did not ask for narrows to its bare estimate — a numeric column shows its mean alone, without the coefficient of variation; name a layout with display = to keep one.

A dplyr::filter to apply to the data first, as a single string. Prefer filtering upstream of tab().

Subclasses of data frame.

For future extensions.

Argument names for x and y. These are used in error messages to inform the user about the locations of incompatible types.

Argument names for x and to. These are used in error messages to inform the user about the locations of incompatible types.

Argument names for x and y. These are used in error messages to inform the user about the locations of incompatible types.

A tibble of class tab, made with tab_plain or tab.

Which elements of the Chi2 summary to compute, as a selection in c("ctr", "p", "var", "counts") : contributions to variance, pvalue, variance and unweighted count. All of them by default.

Comparison level, when tab_vars are present : contributions to variance are calculated for each subtable/group (by default, comp = "tab") or for the whole set of tables (comp = "all"). It must be set once and for all the first time you use tab_pct with rows, tab_ci or tab_chi2.

The type of colors to print, as a single string: "no" (the default), "all" (color all cells by their contribution to variance, except mean columns), "all_pct" (all percentage cells), or "auto" (only columns with counts, pct = "all" or pct = "all_tabs").

Internal pipeline seam. The design-based omnibus grid (one row per subtable x col_var, carrying Rao-Scott's mean generalized design effect), used as the divisor of the color = "contrib" residual's base when the table's inference basis is not "n". NULL — the default, and every direct call — keeps the unweighted base.

A tibble of class tab made with tab_plain or tab.

What the interval is anchored on : "ref" (the comparison with the reference cell), "cell" (the cell's own value), "no", or "auto" — a comparison interval for means and row/column percentages, a cell interval for plain frequencies. "diff" and "ratio" are the older spellings of "ref". With ci = "cell" the result prints as ⁠[inf;sup]⁠; display = "base_moe" writes it as ⁠pct +- margin of error⁠ instead. See tab, which is where this is normally set.

Comparison level, when tab_vars are present : the interval compares within each subtable/group (by default, comp = "tab") or over the whole set of tables (comp = "all"). It must be set once and for all the first time you use tab_pct with rows, tab_ci or tab_chi2.

The confidence level, as a single numeric between 0 and 1. Default to 0.95 (95%).

The type of colors to print, as a single string: "no" (the default), "diff_ci" (colour percentages and means by their difference from the total or first cell, dropping the colour when the interval of that difference is wider than the difference itself) or "after_ci" (idem, but cutting the interval off the difference first) — the 1.x spelling of tab's color = "difference" plus color_signif set to "grey_non_signif" / "guaranteed_effect".

By default confidence intervals are calculated and used to set colors, but not printed. Set to TRUE to print them in the result.

Logical (opt-in; default FALSE, or options("tabxplor.stars") when NULL). Print per-cell significance stars for the difference from the reference, read from the same interval that is displayed, so the stars and the bracket never disagree.

The method of each kind of interval, as ONE named vector (c(cell = , diff = , mean_diff = , mean_ratio = ), partial) – see tab. The cell slot also takes "beta" (Korn-Graubard), the textbook design-based cell interval, conservative near 0 and 1.

Use ci_method = c(cell = , diff = ) instead.

The scale a comparison interval is expressed on: "diff" (default, a difference interval, neutral 0) or "ratio" (a ratio interval, neutral 1 — Katz's log-risk-ratio for proportions, a ratio of means for numeric variables). tab() sets it from the colour: the measure the reader sees owns the interval.

The design's degrees of freedom, the reference distribution of every interval (#PSU - #strata). NULL (default) takes the value the table itself carries when it was built from a survey::svydesign; Inf is the large-sample normal pivot.

A tabxplor_tab.

One of "console", "html", "md", "runs", "plain". "runs" is for the media that draw the legend as coloured TEXT and cannot fill, such as an Excel rich-text cell (tab_xl). It returns the runs unrendered, and draws the background channel from the darker bg_legend palette (see set_color_palette).

"terse" (compact, console default) or "prose" (full sentences, export default).

NULL (auto from locale) / "en" / "fr".

Whether to colour the break-words.

Palette theme (default from options).

medium = "html" only: emit the break-words as CSS slot classes rather than inline hex, because a tabxplor stylesheet ships with the output (tab_html()). Then the legend follows a theme toggle exactly like the cells it describes. FALSE (a table rendered without a stylesheet of ours) keeps inline hex.

A tabxplor_tab / tabxplor_grouped_tab, or any data.frame holding fmt columns.

A list of tabxplor_tab (or a tabxplor_tab)

A data frame.

Singular aliases of row_vars/col_vars (which now accept several variables). Kept working.

<tidy-select> Tab variables: one subtable per combination of their levels. Leave empty for a simple cross-table.

The column holding the unweighted count for each cell (long tidy shape).

Optional column holding the weighted count for each cell. Leave empty for an unweighted table.

<tidy-select> For a wide data.frame: the columns holding the col_var levels.

Name of the (synthesised) column variable when cols is used.

For input = "pct": the column holding each row's sample size N.

"counts" (default) or "pct" (with cols and base: the level columns hold frequencies, and counts are rebuilt from them and base).

Every other argument of tab() – pct, color, ci, tot, ... – passed by name. See tab(); a typo gets a suggestion.

"light", "dark", a black-and-white publication palette ("print_ready", "print_marks", "print_emphasis", "print_minimalistic"; "bw" is a synonym of the last – see the section below), or – opt-in – "auto" to follow the reader's colour scheme (their operating system, and any dark-mode toggle of the host page: Quarto, Bootstrap 5.3, Tailwind). Defaults to getOption("tabxplor.theme"), i.e. "light": a dark table is always a deliberate choice. "auto" emits every rule four times (a light base, the OS media query, then both toggle directions), which is also what lets tab_html()'s own Viewer page force the editor's theme.

Which output the stylesheet is for, in tab_export()'s own vocabulary. "html" (the default) is the full stylesheet tab_html() needs: the colour classes and the table's own look (font, background, border colours, the greys). "md" emits the colour classes only, which is what tab_md() wants — bare selectors you can map in your own editor's or publisher's CSS.

Wrap the CSS in a ⁠<style>⁠ tag (default TRUE).

Optional path to write to instead of returning.

Also emit a black-and-white publication palette inside an ⁠@media print⁠ block, so a coloured page prints (or saves to PDF) publication-ready with no further action. Defaults to getOption("tabxplor.print_rules"). Set to FALSE if your printer is a colour one and the colours are the point, or name a palette ("print_emphasis") to print in that one. "print_marks" cannot be used here: its marks are cell text, and a print rule can restyle a page but not add characters to it. It adds roughly 1.5 KB to a light/dark stylesheet and 6 KB to an "auto" one.

Retired arguments, accepted and ignored with a deprecation message since 2.0.0 (color_type): the text channel always uses the text palette, and the colour CHANNEL is chosen by color = c(text, background) (see tab()). Anything else is an error naming the argument you meant, as it already was in tab().

A table from tab or tab_reg.

Value columns to keep, by name. NULL (the default) keeps the model columns of a regression table and every value column of a cross-table.

"auto" (the quantity the stored interval is centred on – so a ci = "cell" table gives percentages, a ci = "ref" table differences, an odds-ratio table odds ratios), "effect" or "level".

"auto", "band", "point", "ci" or "none" – whether the observed (crude) counterpart of a regression estimate is included.

Keep the regression Constant row.

Keep total rows and total columns.

Palette theme for the colour columns ("light" / "dark" / a publication palette; NULL follows getOption("tabxplor.export_theme")).

A table made with tab or tab_reg, or a list of tab. A list of tables sharing the same col_vars (and no tab_vars) is merged into one; any other list — several row_vars and/or tab_vars — is rendered one table after another, each keeping its own sub-tables.

One of "html" (the default), "md" (Markdown), "xl" (Excel) or "forest" (a forest plot of the estimates, see forest_plot).

Optional output file. For "xl" it is the workbook path; for "md" and "html" the rendered text is written to it; ignored for "forest".

By default ("light") a white table with black text; "dark" for the inverse (the colours follow the theme). "auto" follows the reader's colour scheme (their operating system, and any dark-mode toggle of the host page); it needs a stylesheet, so it works for format = "html" and "md" and resolves to "light" for the static "xl" backend. The black-and-white publication palettes render a table for a page that has no colour: "print_ready" picks the right one per table, or name it yourself – "print_marks", "print_emphasis", "print_minimalistic" ("bw"). Defaults to getOption("tabxplor.theme"). See tab_css for what each says.

Set to FALSE to render the table without colours (monochrome).

Print the colour legend below the table (with the subtext). TRUE by default, and a no-op on a table that carries no colours.

Colour-legend language: NULL (auto from the R/OS locale, English fallback), "en" or "fr".

Set to TRUE to transpose each table before export (rows become columns) – the col-percentages-with-several-row-variables use case.

A single caption / title for the table.

Which variable names to write beside the table: "both" (the default), "rows", "cols" or "none". The row-variable name is the leading column a table with several row_vars uses to name each block (written once per block); the column-variable names are the spanning row above their level columns. Level headers always keep their name.

Format-specific arguments passed to the underlying exporter. Retired arguments (color_type, html_24_bit, engine, html_font, full_width, position, n_min, hide_near_zero) are caught here, reported once, and not forwarded; the exporter this hands to refuses anything else it cannot use.

A tibble of class tab, made with tab, tab_reg or tab_plain.

A character vector naming the roles you want: "row_var", "col_vars" or "tab_vars".

A data.frame.

For data.frame of class tabxplor_tab, remove tab_vars.

Number of characters lengths between columns.

A table made with tab or tab_reg, or a list of tab. A list of tables sharing the same col_vars (and no tab_vars) is merged into one; any other list — several row_vars and/or tab_vars — is rendered one table after another, each keeping its own sub-tables.

By default ("light") a white table with black text; "dark" for a black table with white text; "auto" (opt-in) to follow whoever is reading the table:

• in a file or a knitted document, the reader's browser decides – their operating system, plus any dark-mode toggle of the host page (Quarto, Bootstrap 5.3, Tailwind);

• printed to the Viewer, your editor decides. Its webview reports the operating system rather than the editor's colour theme, so the theme is resolved in R instead (RStudio's, or Positron's, best-effort).

Defaults to getOption("tabxplor.theme"), i.e. "light" – a dark table is always a deliberate choice.

"print_ready", "print_marks", "print_emphasis" and "print_minimalistic" ("bw") are the black-and-white publication palettes: a greyscale print loses the colour palette's direction entirely (both ramps convert to the same greys), so each says it with something else — see tab_css for what. Their typography is written as real ⁠<b>⁠/⁠<i>⁠/⁠<u>⁠ markup as well as CSS, so it survives a stylesheet-less destination (a paste into Word, GitHub's markdown). You rarely need to ask for one: any coloured table already prints in the first, see tab_css's print_rules.

Set to FALSE to render the table without colours (monochrome).

By default, takes getOption("tabxplor.tab_kable_tooltips") (TRUE unless set): html tooltips display additional informations at mouse hover. Set to FALSE to discard (or set the option to FALSE once per document, e.g. in a vignette or report where every table auto-prints).

By default, takes getOption("tabxplor.kable_popover"). When FALSE, html tooltips are of the base kind: they can't be used with a floating table of contents in rmarkdown documents. Set to TRUE for click popovers instead, which are compatible with a floating toc. Both are bound automatically, in the Viewer and in a knitted document alike, provided rmarkdown and htmltools are installed.

Print the colour legend below the table (with the subtext). TRUE by default, and a no-op on a table that carries no colours.

Colour-legend language: NULL (auto from the R/OS locale, English fallback), "en" or "fr".

The table caption. For formatting, you need to use a css with ⁠caption{}⁠in rmarkdown.

Set to TRUE to transpose each table before export (rows become columns) – the col-percentages-with-several-row-variables use case.

Which variable names to write beside the table: "both" (the default), "rows", "cols" or "none". The row-variable name is the leading column a table with several row_vars uses to name each block (written once per block); the column-variable names are the spanning row above their level columns. Level headers always keep their name.

Get the transformed data instead of the html table.

By default, rownames are wrapped when larger than 30 characters.

By default, colnames are wrapped when larger than 12 characters.

Set to FALSE to wrap also on non whitespace characters.

Inline the stylesheet with the table, so the output is self-contained (default, from getOption("tabxplor.tab_kable_css")). Set FALSE in a many-table document that emits tab_css once at the top – the stylesheet is table-independent, so one copy styles every table. With FALSE and no tab_css call, tables render uncoloured.

Retired arguments, accepted and ignored with a deprecation message since 2.0.0: color_type, html_24_bit, engine, html_font, full_width, position. The table is rendered by one dependency-free ⁠<table>⁠ engine whose every look is a CSS class you can restyle – font, width, colour and placement are all tab_css's business now. Anything else is an error naming the argument you meant, as it already was in tab.

A data frame, or a survey::svydesign.

The variable roles — see tab(). With data, the only arguments that may be passed by position: everything else must be named, because tab()'s argument order differs.

Passed on to tab().

Use tab()'s test.

Use tab()'s tot. A total row is always computed and exactly one total column is shown, so both are cosmetic; totcol = "each" and "all_col_vars" now give that same single total column instead of erroring.

Use tab()'s output_list (inverted).

<tidy-select> Use tab()'s filter: na_drop_all = c(a, b) is filter = !is.na(a) & !is.na(b).

A dplyr::filter to apply to the data frame first — see tab(). Prefer filtering upstream.

A table made with tab or tab_reg, or a list of tab. A list of tables sharing the same col_vars (and no tab_vars) is merged into one; any other list — several row_vars and/or tab_vars — is rendered one table after another, each keeping its own sub-tables.

Bold reference/total rows with markdown ⁠**...**⁠.

Passed to format(). When TRUE, shows "ref:" prefix on diff reference cells, "mean:" on ctr totals, sigma on means.

Max width for row labels before truncation. NULL (default) never truncates (lossless – the column grows); set a number to cap the label width. A markdown pipe cell cannot hold a raw newline, so md "wrapping" means "do not truncate".

Print chi2/footnotes below the table.

When TRUE (default) and the table carries colours (e.g. built with tab(..., color = "difference")), each fmt cell is wrapped in a short pandoc bracketed span ⁠[value]{.class}⁠ so the markdown renders coloured in Quarto / RMarkdown / pandoc (and tab_css(format = "md") styles the classes). FALSE produces plain monochrome markdown. Uncoloured tables never get spans.

Print the colour legend below the table (with the subtext). TRUE by default, and a no-op on a table that carries no colours.

Colour-legend language: NULL (auto from the R/OS locale, English fallback), "en" or "fr".

Colour palette selector (as in tab_html); it only affects the CSS emitted by css = TRUE / tab_css, since the span class names are palette- and theme-independent. Accepts "auto" (follow the reader's colour scheme).

Optional table caption, rendered as a pandoc caption line ⁠: caption⁠ (captions only the first table of a list).

Set to TRUE to transpose each table before export (rows become columns) – the col-percentages-with-several-row-variables use case.

Which variable names to write beside the table: "both" (the default), "rows", "cols" or "none". The row-variable name is the leading column a table with several row_vars uses to name each block (written once per block); the column-variable names are the spanning row above their level columns. Level headers always keep their name.

When TRUE (the default), prepend an inline ⁠<style>⁠ block so the exported markdown is self-contained and renders coloured and compact on its own. Set FALSE inside an .Rmd/.qmd document once the host page brings the stylesheet (or call tab_css once at the top for the whole document) – otherwise the ⁠<style>⁠ block is duplicated per table. A plain uncoloured table renders byte-identical either way.

Copy output to clipboard via clipr::write_clip() (requires clipr).

Path to write the markdown to a file. NULL (default) skips.

If TRUE, print via cat() and return invisibly; if FALSE, return the string.

Renamed to caption.

Replaced by var_names: col_var_names = FALSE is var_names = "rows" (or "none").

Retired arguments, accepted and ignored with a deprecation message since 2.0.0 (color_type, html_24_bit): colour is a CSS class, and exports are always 24-bit. Anything else is an error naming the argument you meant, as it already was in tab().

A data frame.

Singular aliases of row_vars/col_vars (which now accept several variables). Kept working.

<tidy-select> The column variable(s) — see row_vars. An interaction is written a*b, as in tab_reg(), and only col_vars takes one: two factors give one column per observed cell of the pair, a number crossed with a factor one mean column per level. See vignette("tabxplor").

<tidy-select> Tab variables: one subtable per combination of their levels. Leave empty for a simple cross-table.

A weight variable, of class numeric. Leave empty for unweighted results.

Every other argument of tab() – color, ci, tot, digits, ... – passed by name. See tab(); a typo gets a suggestion.

Set to TRUE to obtain a table with normal numeric vectors (not fmt).

Set to TRUE to obtain a plain data.frame (not a tibble), with normal numeric vectors (not fmt). Useful, for example, to pass the table to correspondence analysis with FactoMineR.

Internal. .fine is a pre-computed count-aggregate to roll up from instead of scanning the raw data (used by tab_counts and the scan-fusion path); .by_table forces the table-by-table path.

A tibble of class tab made with tab_plain or tab.

The type of percentages : "row", "col", "all" (frequencies of each subtable/group when tab_vars are provided), or "all_tabs" (frequencies of the whole set of tables).

The number of digits to print for percentages. As a single integer, or an integer vector the same length than col_vars.

The reference cell differences and ratios — and so colors — are calculated from : "tot" (the corresponding total row or column), "first" (the first cell of the row or column, useful to color temporal developments), an integer (the nth row or column), a string (a regular expression matching one row or column name, precise enough to match only one), or "no" to skip differences entirely. See tab for the full vocabulary.

Comparison level, when tab_vars are present : "tab" (the default) compares each cell to the total row of its own subtable, "all" to the total row of the total table (and, with ref = "first", to the first cell of the total table). It doesn't affect column percentages, and must be set once and for all the first time you use tab_pct with rows, tab_ci or tab_chi2.

Set to TRUE to color the resulting tab based on those differences.

Set to TRUE when percentages are already calculated and you only want to recalculate differences.

A data frame.

Singular aliases of row_vars/col_vars (which now accept several variables). Kept working.

<tidy-select> Tab variables: one subtable per combination of their levels. Leave empty for a simple cross-table.

A weight variable, of class numeric. Leave empty for unweighted results.

Every other argument of tab() – pct, color, ci, tot, ... – passed by name. See tab(); a typo gets a suggestion.

Set to TRUE to obtain a table with normal numeric vectors (not fmt).

Set to TRUE to obtain a plain data.frame (not a tibble), with normal numeric vectors (not fmt). Useful, for example, to pass the table to correspondence analysis with FactoMineR.

Internal. .fine is a pre-computed count-aggregate to roll up from instead of scanning the raw data (used by tab_counts and the scan-fusion path); .by_table forces the table-by-table path.

A data.frame.

Ignored.

A dataframe.

Variables then to be passed in tab_plain.

<tidy-select> Removes all observation with a NA in any of the chosen variables.

Set to TRUE to clean levels names, by removing prefix numbers like "1-", and text in parentheses.

When set to a positive integer, levels with less count than it will be merged into an "Others" level.

The name of the "Other" level, as a character vector of length one.

A named list, one element per variable, each a named list of character vectors: the levels to merge, named by the merged level's label (the shape forcats::fct_collapse takes). Applied before other_if_less_than. NULL merges nothing.

A tabxplor_tab (with chi2 table as attribute).

A data frame, or a prebuilt survey design (survey::svydesign()). A design's weights, clustering, stratification and calibration drive the estimation, and wt is ignored.

<tidy-select> The outcome variable(s) — bare names, quoted names, or any selection helper, exactly as in tab() — or a model formula (the escape hatch; leave predictors unset). Several names give one effect column per outcome; with a predictors list, a single name is required. reg_formulas() shows what was fitted.

<tidy-select> The predictors of one model — or a named list, one model per element, its name labelling the column, each element selected on its own (list(m1 = c(race, age), m2 = starts_with("inc"))), which is how models are compared. Leave NULL when outcome is a formula. A bare name is a column of data first, then an object, so a variable holding names works without all_of().

a*b is an interaction, R's own spelling, bare or quoted — "a's effect, allowed to vary with b". Two categorical variables give one row per cell of the pair; a continuous a gives its slope within each level of b. An interaction supplies both its variables, so do not list them beside it, which is what makes "with and without" an ordinary model comparison. a:b, which drops the main effects, is refused. See the regression vignette.

<tidy-select> Optional. One grouping variable — the same argument as tab()'s: one sub-table per group, the same model(s) fitted within each level. Two readings of "does this effect hold in every subgroup?" come with it: color = "between_groups" colours and tests each effect against the first group's, row by row, and stats = c(..., "group_interaction") adds the aggregated test, once per predictor. For an interaction between two PREDICTORS of one model, write it in predictors as a*b instead.

<tidy-select> Optional. One weight column, switching to design-based survey estimation (survey::svyglm()). For clustering, stratification, a finite-population correction or calibration, build the design with survey::svydesign() and pass it as data. See vignette("tabxplor-weights").

The model family, resolved per outcome so several outcomes with different families can share one table. "auto" (default) detects each one and says so: a binary outcome gives "binomial", an ordered 3+ level "ordinal", a nominal 3+ level "multinomial", any other numeric "gaussian" — a genuine count is yours to name. Or set it: "gaussian" (linear), "binomial" (logistic), "poisson" / "quasipoisson" (counts), "multinomial", "ordinal". A scalar applies to every outcome; a vector aligned to outcome, or a named vector keyed by outcome (e.g. c(income = "poisson", satisfied = "binomial")), sets one family per outcome. Mixed families need a character predictors.

It answers one question — what kind of number the outcome is — and never picks a link behind your back: on a binary outcome family = "poisson" is refused, naming the two things it could have meant, link = "ratio" and measure = "ratio".

Which measure the model estimates — the only argument that changes the model. A link is a measure (the one a model gives you directly), so it takes measure's own words:

• "auto" (default) — the family's own: logistic for a binary outcome, linear for a quantity, Poisson for a count.

• "odds_ratio" — the logit fit (binomial, multinomial, ordinal).

• "ratio" — the log link: the modified Poisson on a binary outcome (a conditional risk ratio), Poisson on a count, Poisson pseudo-likelihood on a continuous one.

• "difference" — the identity link; on a binary outcome the risk difference. It can fail to converge, and the linear probability model then takes over, with a message.

Reach for it when you want the model's coefficient to be that measure; to report a measure without changing the model, set measure instead. "log" is the one word the two arguments do not share: here the log link, on measure a spelling of "raw_coefficient".

Which measure of deviation is reported — a deviation being how far a group sits from the reference, the measure which of the ways of expressing it you read. The one argument most readers ever set, and the one that never changes the model. "auto" (default) is the model's own. The full word is canonical, the discipline's acronym a synonym:

• "odds_ratio" ("OR") — the odds of the outcome, times what.

• "ratio" ("RR", "IRR", "RoM") — how many times as likely, as frequent, as large. Reach for it when the outcome is common, where an odds ratio is far from the risk ratio people hear in it, and because a risk ratio stays comparable across nested models.

• "difference" ("RD", "diff") — how much more, in the outcome's own units.

• "raw_coefficient" ("coef", "log", ...) — the model's own coefficient, un-transformed.

On an ordered outcome the first three read the whole predicted distribution rather than one category, so they stay in one column: Somers' D and the win ratio. Where the measure IS the model's own it is read off the coefficients, otherwise from its predictions — so it is available whichever model you fit. "auto" never lands on a predicted odds ratio, a specialist quantity to be asked for by name. Call reg_measures() to see what an outcome offers.

Where the reported number comes from, once the model and the measure are fixed. "auto" (default) needs no thought: the model's own coefficients when the reported measure is the model's, its predictions otherwise. The other values name a reading:

• "conditional" — read off the coefficients ("holding the other predictors constant"). Only where measure is the model's own; otherwise the abort names the two cures.

• "marginal" — the average marginal effect: the model's prediction for every observed person, averaged. Comparable across models (Mood 2010), and always available.

• "at_reference" — the same at one profile, every other predictor at its reference.

The contrast is a marker on the measure in the header, so the acronym stays the one thing to look up: Model_OR, Model_mRR, Model_refRD. The observed companion carries the measure alone (Obs_RR), a univariable effect having no adjustment to be marginal over.

Which level of the outcome to single out, as a named vector keyed by outcome name — outcome_level = c(married = "Married"). It is the twin of ref: ref names the level you compare AGAINST, outcome_level the one you MODEL.

• binomial: the level whose probability is estimated; it becomes the column header. Defaults to the outcome's first level. A 0/1 numeric outcome may be named either way.

• multinomial: the baseline category the other categories' columns are compared to.

• ordinal and numeric outcomes: refused, with the reason.

Grouped-binomial (summed-score) outcomes only. The number of items behind the score, fitting cbind(score, trials - score) as a binomial. NULL (default) fits an ordinary binary logit; an integer (or a vector named by outcome) sets the item count; TRUE uses each outcome's observed maximum. Requires family = "binomial".

Show the observed, unadjusted (crude) effect beside each modelled one — the same quantity fitted with a single predictor, on exactly the same people. The distance between the two is what adjustment changed, read left to right; it is the feature the package exists for. TRUE (the default) or FALSE; three spellings say where it goes, and in every one but "no" it is stored in the obs field and read by ⁠$obs⁠, color = "adjustment", forest_plot() and the hover tooltip:

• TRUE — a crude column beside the model one, except where that would double a table already wide (tab_vars groups, a 3+ level outcome), which take "tooltip".

• "column" — always the column, per outcome category if that is what it takes.

• "tooltip" — computed, printed nowhere. The narrowest table.

• "cell" — inside the model cell, ⁠(1/1.69) 1/1.63***⁠. display overrides it.

The two columns are the same column twice: same estimand, same colour ladder, one legend block. Each cell prints the effect with the level it sits on — the observed percentage or mean on the crude side, the adjusted prediction on the model side. A continuous predictor has no levels, so its crude cell is the univariable slope, which assumes linearity: check that with shape first.

How many people the table is about. NULL (default) reads options(tabxplor.n) — "range", which adds an n column holding the unadjusted count behind each predictor level, on the model's own complete cases. Where several models rest on different people it prints the whole range (⁠5 139-9 862⁠), so an unequal base cannot pass unnoticed; "min" shows the smallest count only, "no" none. Continuous predictors are left blank: their count is the model N, the first footer row.

Colouring of the effect cells. color = "measure" (default, TRUE equivalently) grades each cell on its own measure, so the ladder follows what the column estimates; color = FALSE turns colouring off. color_signif is the significance policy — NULL (default) is "grey_non_signif" here, where tab() defaults to "ignore".

What is left to choose is what each effect is compared to. color is positional, c(text, background), so color = c("measure", "adjustment") answers "how strong is this effect?" and "how much did the model change it?" in one glance:

• "adjustment" — how far each modelled effect sits from its observed (crude) counterpart: what adjusting for the other predictors did to it. It turns empirical = TRUE on. Set its thresholds with set_color_breaks() (adj_ratio, adj_diff, adj_diff_std).

• "between_groups" — with tab_vars, how far each group's effect sits from the first group's: a per-predictor reading of effect modification.

The two are mutually exclusive, and each always tests its own gap: a gap whose interval covers zero is greyed whatever color_signif says — so a cell can be filled while neither estimate carries a star, which is correct rather than odd. A conditional odds ratio is not collapsible, so there the colours stay descriptive and are not tested. Read a coloured cell as "adjustment moved this effect", not as "this variable is a confounder". See the regression vignette.

Logical (default TRUE for regression tables, where significance stars are standard). When FALSE, the per-cell p-value is dropped and no stars are shown (colours still read the interval).

The reference every effect is measured from — one argument, one meaning per kind of predictor. For a factor it is the level the others are compared against (a level name, or "first" (default) / "last"); for a continuous predictor the value it is anchored at (a number, or "mean" (default), "median", "min", "max").

Anchoring a continuous predictor does not change its own effect — a slope is the same wherever you start reading it from — but it does move the Constant row; its own row says where the anchor sits, ⁠per SD/13.5 (at mean/42.4)⁠. The default is the mean because zero is usually outside the data: nobody is 0 years old.

ref, multiplier and shape share one grammar: a value on its own is the default for every predictor it can apply to, a named one overrides that variable — ref = c("median", "last", race = "Black").

For the level of the outcome, see outcome_level: ref names the level you compare AGAINST, outcome_level the one you MODEL.

How a continuous predictor's effect is scaled — the unit its row reports. One unit is rarely a readable amount (a one-year change in age barely moves the odds), so the default is two standard deviations: roughly the span a binary predictor's own contrast covers, which is what makes a continuous row and a factor row comparable at a glance (Gelman 2008). Values: "2sd" (default), "sd", or a number of units (10 = per decade). Same grammar as ref: multiplier = c("sd", age = 10).

The estimate, its interval and the observed companion all scale together; the p-value does not move. Because the default is not 1, a continuous predictor's ⁠Model_*⁠ cell does not equal exp(coef(glm(...))) unless you pass multiplier = 1.

How a continuous predictor enters the model, when one straight line is not enough. The Linearity footer row and the little curve drawn in the predictor's n cell tell you whether a line is enough; this argument is how you fix it without leaving the framework. Same grammar as multiplier and ref — shape = "quintiles" cuts every continuous predictor, shape = c(age = "quadratic") only that one, and anything unnamed stays linear:

"linear"

one slope (the default).

"quintiles" / "quartiles" / an integer k

cut into k quantile groups, so the predictor becomes an ordinary factor: one estimate per group, its own observed companion, counts and colours per group — the non-linearity becomes visible in the printed numbers. Start here; it is the most readable answer.

"sd_bands"

cut at the mean and one standard deviation either side — the classic low / average / high reading, whose cut points mean the same thing across sub-samples, where quantiles move with each one. The bands are not balanced: prefer quantiles when the group sizes matter.

"quadratic"

adds a curvature term, so the predictor takes two rows — the slope at the mean, and whether it flattens or accelerates away from it.

"log" / "sqrt"

fit log(x) / sqrt(x) instead of x — diminishing returns.