Package 'tabxplor'

Description

5 226 people arrested for possession of a small quantity of marijuana. The outcome is whether the person was released with a summons rather than held. This is the running example of the All else equal article: 86 % of white arrestees were released against 74 % of black arrestees, and the article asks what survives of that gap when people alike on everything else are compared.

Usage

car_arrests

Format

A tibble of 5 226 rows and 8 columns.

released

Released with a summons? "Yes" first – it is what the article studies.

colour

The arrestee's race as the police recorded it: "White" first, then "Black".

year

1997 to 2002.

age

Age in years.

sex

Female or Male.

employed

Employed? "Yes" first.

citizen

A Canadian citizen? "Yes" first.

checks

On how many of six police databases the person's name already appeared, 0 to 6.

Source

The complete Arrests data of the carData package (John Fox, Sanford Weisberg and Brad Price), GPL (>= 2) – with thanks; gathered by Michael Friendly for a series in the Toronto Star. tabxplor's copy changes only the level order: the yes/no items read "Yes" first, and colour starts at "White".

Examples

tab(car_arrests, colour, released, pct = "row", color = "difference")

Description

Nine months' salary for 397 professors at one US college, collected by the institution to monitor a pay gap. Used in the Reading a regression article to show a gap that grows under adjustment, and then a mediator: rank explains the gap away, but rank is itself part of what is unequal.

Usage

car_salaries

Format

A tibble of 397 rows and 7 columns.

rank

AsstProf, AssocProf, then Prof.

discipline

"A" (theoretical) or "B" (applied).

yrs.since.phd

Years since the PhD.

yrs.service

Years of service.

sex

Female or Male.

salary

Nine-month salary, in US dollars.

is_prof

Full professor or not: the same information as rank, asked as the yes/no question a percentage can answer. Added by tabxplor.

Source

The complete Salaries data of the carData package (John Fox, Sanford Weisberg and Brad Price), GPL (>= 2) – with thanks. tabxplor's copy adds is_prof and orders rank from assistant to full professor.

Examples

tab_reg(car_salaries, "salary", c("sex", "discipline"))

Description

Turn one or several confidence levels into the two-sided normal (z) thresholds they correspond to, rounded for readability. It is a convenience for writing the zscore color break scale (set_color_breaks) in the vocabulary you already use elsewhere — confidence levels — instead of remembering that 95 % is 1.96. The scale itself always stores plain z magnitudes, so conf_level_to_z(0.95) and 1.96 are strictly interchangeable.

Usage

conf_level_to_z(conf_level, digits = 2)

Arguments

Value

A numeric vector of positive z thresholds, the same length as conf_level.

Examples

conf_level_to_z(c(0.95, 0.99))

# the default `zscore` break scale (color = "contrib", color_signif = "guaranteed_effect")
conf_level_to_z(c(0.95, 0.99, 0.9999, 1 - 2e-9))


set_color_breaks(zscore = conf_level_to_z(c(0.95, 0.999)))
set_color_breaks(zscore = c(2, 3, 4, 6))  # or plain z values, identically

Description

A survey of 300 tea drinkers, used here for its three batteries of yes/no items – the shape a multiple-answer question ("which of these apply to you?") arrives in. Six items say when people drink tea, six say where, and fourteen say what they think it does for them. See vignette("tabxplor") for what a battery does in a table, and score_from_lv1() for turning one into a single summed score.

Usage

facto_tea

Format

A tibble of 300 rows and 36 columns. The ones the vignettes use:

breakfast, tea.time, evening, lunch, dinner, always

When do you drink tea?

home, work, tearoom, friends, resto, pub

Where do you drink tea?

Sport

Do you play a sport?

SPC

Socio-professional category, 7 levels.

sex

F or M.

The other columns describe the tea itself (Tea, How, sugar, how, where, price, frequency), the drinker (age, age_Q), and what they associate tea with (healthy, relaxing, exciting, slimming, and ten more). Every two-level item reads "yes" first.

Source

The complete tea data of the FactoMineR package (Francois Husson, Julie Josse, Sebastien Le and Jeremy Mazet), GPL (>= 2) – with thanks. tabxplor's copy changes only the level order: in each yes/no item the "yes" answer comes first, and its label loses the separator dot the original spells it with ("Not.tea time" becomes "Not tea time").

Examples

tab(facto_tea, SPC, c(breakfast, evening), pct = "row", levels = "first", na = "drop")

Description

Recoding a factor with forcats::fct_recode() means typing every level name exactly, and a typo is silently ignored. fct_recode_helper() writes that code for you: it prints a ready-to-paste mutate() call with one fct_recode() per variable, each level already written as "level" = "level". You then only edit the new names on the left, and delete the lines you keep.

With a few variables, each level carries its frequency and count as a comment, which is what tells you which small levels to merge. A column with a label attribute (data imported by haven) gets that label as a comment title.

Usage

fct_recode_helper(
  data,
  .cols = -where(is.numeric),
  name_in,
  name_out,
  freq = NULL,
  style = c("mutate", "base"),
  reminder = TRUE,
  cat = TRUE
)

Arguments

Value

With cat = TRUE (default), the text printed to console (or written to a temp R file for more than 5 variables), returned invisibly. With cat = FALSE, a tibble of the recode text.

Examples

fct_recode_helper(forcats::gss_cat, c(marital, race))

Description

fmt vectors, of class tabxplor_fmt, powers tabxplor and tab tibbles. As a record, they stores all data necessary to calculate percentages, Chi2 metadata or confidence intervals, but also to format and color the table to help the user read it. You can access this data with vctrs::field, or change it with vctrs:field<-. Its per-cell fields are listed below. The other arguments are attributes, attached not to each value but to the whole vector, like scale, col_var, totcol or color. You can get them with attr and modify them with attr<-. Special functions listed below are made to facilitate programming with with tabxplor formatted numbers. taxplfmt vectors can use all standard operations, like +, -, sum(), or c(), using vctrs.

Usage

fmt(
  n = integer(),
  scale = "level_n",
  digits = rep(0L, length(n)),
  display = est_default_display(scale[1]),
  wn = rep(NA_real_, length(n)),
  pct = rep(NA_real_, length(n)),
  mean = rep(NA_real_, length(n)),
  diff = rep(NA_real_, length(n)),
  ratio = rep(NA_real_, length(n)),
  ctr = rep(NA_real_, length(n)),
  var = rep(NA_real_, length(n)),
  ci = rep(NA_real_, length(n)),
  ci_inf = rep(NA_real_, length(n)),
  ci_sup = rep(NA_real_, length(n)),
  pvalue = rep(NA_real_, length(n)),
  or = rep(NA_real_, length(n)),
  tot_n = rep(NA_real_, length(n)),
  n_eff = rep(NA_real_, length(n)),
  obs = rep(NA_real_, length(n)),
  gap_se = rep(NA_real_, length(n)),
  row_kind = rep("data", length(n)),
  in_tottab = rep(FALSE, length(n)),
  in_refrow = rep(FALSE, length(n)),
  in_totrow = NULL,
  comp_all = NA,
  ref = "",
  pct_type = "none",
  col_var = "",
  col_group = "",
  totcol = FALSE,
  refcol = FALSE,
  color = "",
  color_signif = "ignore",
  model_family = "",
  role = "",
  conf_level = NA_real_,
  degf = NA_real_,
  basis = "n",
  ci_method = "",
  ...
)

is_fmt(x)

Arguments

Value

A vector of class tabxplor_fmt.

A logical vector.

Functions

• is_fmt(): a test function for class fmt.

The fields of a cell

A fmt cell carries 21 fields. Many are NA when the quantity was not requested; read one with x$field or vctrs::field(), and see them all with vctrs::vec_data():

• n — the unweighted count.

• display — which field this cell shows (a bare name, or a {} template).

• digits — how many decimals this cell prints.

• wn — the weighted count.

• pct — the percentage.

• mean — the mean, on a numeric column variable.

• diff — the difference from the reference cell (percentage points, or the outcome's own units).

• ratio — the ratio to the reference cell (a relative risk, or a ratio of means).

• ctr — the cell's contribution to the table's Chi-2.

• var — the column's variance quantity – which one is given by its scale.

• ci_inf — the lower bound of the confidence interval.

• ci_sup — the upper bound of the confidence interval.

• pvalue — the cell's own significance p-value, which the stars read.

• or — the odds ratio against the ref2 level.

• tot_n — the cell's own base — the count its percentage is computed on.

• n_eff — the effective sample size its interval was computed on (weights or a survey design).

• obs — tab_reg() only: the observed (crude) effect the modelled one is compared to.

• gap_se — tab_reg() only: the standard error of the gap between the estimate and obs.

• row_kind — what kind of row the cell sits in — see get_row_kind().

• in_tottab — is the cell in a total table (logical).

• in_refrow — is the cell in a reference row (logical).

Every display token

Generated from the package's own display table, so it cannot drift from what get_num() reads. Each of pct, n, wn, mean, diff, ratio, or, ctr, var, obs, pvalue shows the field of the same name, described above. The rest are composed or derived by the pipeline itself, and the last few are not meant to be typed:

• est — the estimate, whatever this column estimates — an odds ratio, a risk difference, a coefficient, a percentage. The one token that means the same thing on every table.

• base — the level the estimate sits on: the percentage, the mean or the count. On a plain percentage table it is the same number as est; beside a regression effect it is the adjusted prediction.

• ci — the confidence interval of whatever the column compares, as [low;high].

• moe — the margin of error — the same interval as ci, written as the half-width +/-x around the estimate. Void where the column compares a RATIO: a ratio's interval is symmetric on the LOG scale, so it has no half-width.

• odds — the odds — pct / (1 - pct), the quantity an odds ratio is a ratio of. Printed on the odds ratio's own ladder, so a cell below 1 reads its inverse ("1/2.60") unless options(tabxplor.ratio_print = "raw") asks for the plain number. Void where the percentage is 1 and the odds infinite.

• sd — the standard deviation, in the variable's own unit.

• cv — the coefficient of variation — the standard deviation as a percentage of the mean.

• resid — the adjusted standardized residual – whether the cell departs from independence. Derived from the p-value and the sign of ctr, so it is read-only.

• coef — the estimate on the model's LINK scale — the coefficient a linear or log-link model fitted. The same number as est where the column is already additive, its logarithm where the column shows a ratio.

• gap — how far adjustment moved the effect: the gap between the modelled estimate and its observed counterpart, on the estimate's own scale. What color = "adjustment" grades — readable in print and Excel, not only in an html tooltip.

• gof — a model-fit statistic (N, R2, AIC, BIC, dispersion).

• gof_warn — a model-fit statistic past the threshold its check is read against.

• n_range — the unweighted base: one count, or a min-max range over the table.

• blank — nothing: a cell masked by n_min.

• rr — the legacy synonym of ratio, still accepted.

• OR — the acronym spelling of or, still accepted.

See Also

tabxplor-display for the {} grammar and the named layouts display accepts; fmt_fields and fmt_attributes for the accessors.

Examples

library(dplyr)

f <- fmt(n = c(7, 19, 2), pct = c(0.25, 0.679, 0.07),
         scale = "level_pct", pct_type = "row")
f

# To get the currently displayed field :
get_num(f)

# To modify the currently displayed field :
set_num(f, c(1, 0, 0))


# See all the underlying fields of a fmt vector (a data frame with a number of rows
#  equal to the length of the vector) :
vctrs::vec_data(f)

# To get the numbers of digits :
vctrs::field(f, "digits")
f$digits

# To get the count :
vctrs::field(f, "n")
f$n

# To get the display :
vctrs::field(f, "display")
f$display

# To modify a field, you can use `dplyr::mutate` on the fmt vector,
# referring to the names of the columns of the underlying data.frame (`vctrs::vec_data`) :
vctrs::`field<-`(f, "pct", c(1, 0, 0))
mutate(f, pct = c(1, 0, 0))

# See all the attributes of a fmt vector :
attributes(f)

# To modify the "pct_type" attribute of a fmt vector (what the percentage is a percentage OF) :
set_pct_type(f, "col")

# To modify the "color" attribute of a fmt vector :
set_color(f, "contrib")




tabs <- tab(starwars, sex, hair_color, gender, na = "drop", pct = "row",
            other_if_less_than = 5)

# To identify the total columns, and work with them :
is_totcol(tabs)
tabs |> mutate(across(where(is_totcol), ~ "total column"))

# To identify the total rows, and work with them :
is_totrow(tabs)
tabs |>
  mutate(across(
    where(is_fmt),
    ~ if_else(is_totrow(.), true = "into_total_row", false = "normal_cell")
  ))

# To identify the total tables, and work with them :
tottabs <- is_tottab(tabs)
tabs |> tibble::add_column(tottabs) |>
  mutate(total = if_else(tottabs, "part of a total table", "normal cell"))

# To access the displayed numbers, as numeric vectors :
tabs |> mutate(across(where(is_fmt), get_num))

# To access the displayed numbers, as character vectors (without colors) :
tabs |> mutate(across(where(is_fmt), format))

# To access the (non-displayed) differences of the cells percentages from totals :
tabs |> mutate(across(where(is_fmt), ~ vctrs::field(., "diff")))


# To do more complex operations, like creating a new column with standard deviation and
# print it with 2 decimals, use `dplyr::mutate` on all the fmt columns of a table :

tab(forcats::gss_cat, race, c(age, tvhours), marital, digits = 1L, comp = "all",
    color = "auto") |>
  dplyr::mutate(dplyr::across( #Mutate over the whole table.
    c(age, tvhours),
    ~ dplyr::mutate(.,         #Mutate over each fmt vector's underlying data.frame.
                    var     = sqrt(var),
                    display = "var",
                    digits  = 2L) |>
      set_color("no"),
    .names = "{.col}_sd"
  ))

Description

The generic form of the ⁠get_*()⁠ / ⁠set_*()⁠ family: one function covering every per-column attribute a tabxplor_fmt vector carries, so a helper can loop over them instead of naming each. The named accessors (get_scale(), get_col_var(), is_totcol(), …) remain the readable way to address one known attribute.

Usage

fmt_attr(x, name)

fmt_attr(x, name) <- value

Arguments

Value

The stored value (its declared default when the attribute is unset). On a data.frame, one entry per fmt column, named. Writing returns the modified vector.

See Also

tab_columns() for every column's attributes at once; fmt() for what each one means.

Examples

x <- fmt(n = c(10, 20), pct = c(0.3, 0.7), scale = "level_pct", pct_type = "row")
fmt_attr(x, "scale")
fmt_attr(x, "col_var") <- "region"
fmt_attr(x, "col_var")

Description

Read and write the facts that hold for a whole column: what it estimates, which percentage base it rests on, which reference it is compared to, how it is coloured, and how its confidence interval was built. They are stored on the vector, not on the table, so a column keeps them when it is extracted, renamed or piped through dplyr.

fmt_attr() reaches any of them by name — these are the readable way to address one you know. tab_columns() shows them all, for every column of a table at once.

Usage

get_scale(x, ...)

set_scale(x, scale)

get_pct_type(x, ...)

set_pct_type(x, pct_type)

is_totcol(x, ...)

as_totcol(x, totcol = TRUE)

get_comp_all(x, replace_na = TRUE)

set_comp_all(x, comp_all = FALSE)

get_ref_type(x, ...)

set_ref_type(x, ref)

set_diff_type(x, ref)

get_col_var(x, ...)

set_col_var(x, col_var)

get_col_group(x, ...)

get_model_family(x, ...)

set_model_family(x, model_family)

get_ci_method(x, ...)

is_refcol(x, ...)

as_refcol(x, refcol = TRUE)

get_color(x, ...)

get_color_bg(x, ...)

get_color_signif(x, ...)

set_color(x, color)

set_color_signif(x, color_signif)

Arguments

Value

A getter returns the stored value — its declared default where the attribute was never set ("" for a name, FALSE for a flag, NA where there is none) — and answers once per fmt column when given a data.frame. A setter returns the modified fmt vector.

Functions

• get_scale(): get the estimate scale of fmt columns (at fmt level or tab level)

• set_scale(): set the estimate scale attribute of a fmt vector

• get_pct_type(): get which kind of percentage fmt columns hold (at fmt level or tab level)

• set_pct_type(): set the percentage-type attribute of a fmt vector

• is_totcol(): test function for total columns (at fmt level or tab level)

• as_totcol(): set the "totcol" attribute of a fmt vector

• get_comp_all(): get comparison level of fmt columns

• set_comp_all(): set the comparison level attribute of a fmt vector

• get_ref_type(): get differences type of fmt columns (at fmt level or tab level)

• set_ref_type(): set the reference attribute of a fmt vector — which row or column a comparison is made against. It is the writer of the attribute get_ref_type() reads.

• set_diff_type(): Use set_ref_type(), which shares its stem with the getter get_ref_type() and with the ref attribute both of them address.

• get_col_var(): get names of column variable of fmt columns (at fmt level or tab level)

• set_col_var(): set the "col_var" attribute of a fmt vector

• get_col_group(): get the sub-population of fmt columns (at fmt level or tab level)

• get_model_family(): get the regression model family of fmt columns (at fmt or tab level)

• set_model_family(): set the "model_family" attribute of a fmt vector (the per-column regression family, "" on crosstabs)

• get_ci_method(): get the interval method of fmt columns (at fmt level or tab level)

• is_refcol(): test function for reference columns (at fmt level or tab level)

• as_refcol(): set the "ref_col" attribute of a fmt vector

• get_color(): get color (at fmt level or tab level)

• get_color_bg(): get the background-channel color measure (NA when there is none)

• get_color_signif(): get the significance policy ("ignore" / "grey_non_signif" / "guaranteed_effect")

• set_color(): set the "color" attribute of a fmt vector

• set_color_signif(): set the significance policy attribute of a fmt vector

See Also

fmt_attr() to address an attribute by name; tab_columns() for a whole table; fmt() for what every attribute means; fmt_fields for the per-cell values.

Description

Read and write the values that vary from cell to cell: the displayed number, its decimals, its p-value, and the kind of row each cell sits in. Every fmt vector carries all of them, an inapplicable one stored as NA — so these always answer, even on a column where the field means nothing.

Use them on a single fmt vector or, through dplyr::across(where(is_fmt), ...), on a whole table. To reach a field these do not name, use ⁠x$<field>⁠ or vctrs::field().

Usage

get_num(x)

set_num(x, value)

is_totrow(x, ...)

get_row_kind(x)

set_row_kind(x, row_kind)

as_totrow(x, in_totrow = TRUE)

is_tottab(x, ...)

as_tottab(x, in_tottab = TRUE)

set_display(x, value)

is_refrow(x, ...)

as_refrow(x, in_refrow = TRUE)

get_digits(x)

get_pvalue(x)

set_digits(x, value)

set_pvalue(x, value)

Arguments

Value

A getter returns a vector the length of x; a setter the modified fmt vector. Given a data.frame, a getter answers once per fmt column.

Functions

• get_num(): get the currently displayed field

• set_num(): set the currently displayed field (not changing display type)

• is_totrow(): test function to detect cells in total rows (at fmt level or tab level)

• get_row_kind(): get the "row_kind" field: what kind of row each cell sits in (see the Row kinds section).

• set_row_kind(): set the "row_kind" field

• as_totrow(): set the "total" row kind (belong to total row)

• is_tottab(): test function to detect cells in total tables (at fmt level or tab level)

• as_tottab(): set the "in_tottab" field (belong to total table)

• set_display(): set the "display" vctrs::field of a fmt vector, or of all of them in the whole tibble.

• is_refrow(): test function to detect cells in reference rows (at fmt level or tab level)

• as_refrow(): set the "in_refrow" field (belong to reference row)

• get_digits(): get the "digits" field

• get_pvalue(): get the per-cell p-value (what the significance stars read)

• set_digits(): set the "digits" field

• set_pvalue(): set the per-cell p-value. set_pvalue(x, NA_real_) is how a duplicated, purely descriptive copy of a column loses its stars: the stored p-value is their only source.

Row kinds

The row_kind field says what kind of row a cell sits in.

"data"

a real body row.

"total"

a total row (the only kind is_totrow() asks about).

"n"

the base-count row.

"pct"

the add_pct percentage row.

"pvalue"

an appended test row: a crosstab's chi2 or F, a regression's per-term test.

"gof"

a regression goodness-of-fit / model-summary footer row.

"blank"

a spacer row between footer blocks.

See Also

fmt() for what every field means and how to build a cell; fmt_attributes for the per-column facts; vignette("tabxplor-programming").

Description

The html color code of a fmt vector

Usage

fmt_get_color_code(x, type = "text", theme = "light", ...)

Arguments

Value

A character vector with html color codes, of the length of the initial vector.

Examples

tabs <- tab(forcats::gss_cat, race, marital, pct = "row", color = "difference")
dplyr::mutate(tabs, across(where(is_fmt), fmt_get_color_code))

Description

Draws every estimate of a table with its confidence interval, its significance and its colour – for a cross-table from tab as much as for a regression table from tab_reg. It reads the table and never re-fits anything: every number and every colour comes from the cell it was printed from, so the figure and the table cannot disagree. (Its sibling reg_check_plots is the opposite: model checks always re-fit, because they are about residuals, which no table carries.)

Usage

forest_plot(
  x,
  columns = NULL,
  what = c("auto", "effect", "level"),
  observed = c("auto", "band", "point", "ci", "none"),
  center = c("n", "estimate", "none"),
  display = NULL,
  layout = c("keep", "auto", "transpose"),
  facet = NULL,
  color = TRUE,
  guide = c("gridlines", "bands", "none"),
  intercept = FALSE,
  totals = FALSE,
  offset = 0.25,
  label_offset = 0.3,
  max_size = 6,
  footer = c("short", "full", "none"),
  footer_width = 130L,
  legend = "auto",
  theme = NULL,
  lang = NULL,
  caption = NULL,
  subtext = TRUE,
  return_data = FALSE,
  ...
)

Arguments

Details

What is drawn. Always a deviation: the effect a regression estimates, or, for a cross-table, the comparison its color = grades. The level it sits on (the percentage, the mean, the adjusted probability) is printed above each whisker instead, so position and number say two different things; what = "level" swaps them.

The gridlines are the table's colour ladder (set_color_breaks), labelled with the same glyphs as the footer and continued as far as the data goes. The whisker takes the colour of its cell whole, so significance is read off it and there are no stars.

A table that mixes units (an odds ratio beside a mean difference) gets one axis per panel, each in its own transform, with panels measuring the same thing sharing one comparable range.

The observed comparison. With empirical = TRUE, a regression estimate carries its crude counterpart. observed = "band" (the default when testable) draws a bracket at plus-or-minus the margin of error of the difference: the modelled point falls outside it exactly when the gap test rejects. Two correlated intervals should not be compared by overlap, which is why the crude one is not drawn by default; observed = "ci" restores it.

Value

A ggplot (or a list of them), ready for + theme() and ggsave().

See Also

reg_check_plots for the model checks, tab_export to export the table itself.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  t <- tab(forcats::gss_cat, race, marital, pct = "row", ci = "ref", color = TRUE)
  forest_plot(t)
  forest_plot(t, guide = "bands")          # the teaching mode
}

Description

The tests a table carries and prints under itself: a crosstab's chi-squared or ANOVA, a regression's model-fit statistics and global tests. get_test() hands them back as a tidy tibble — one row per test, keyed by var (the row variable, the predictor, or "" for the whole table) and col (the column variable it keys under) — so a test can be filtered, reshaped or reported like any other data. A new kind of test is new rows, never new columns.

The remaining columns name the statistic (test, statistic, df1, df2, pvalue), the base it was computed on (n, min_e, deff) and its effect size (effect_size, es_type). Per-CELL contributions to the chi-squared are not here: they are the ctr field of the cells themselves (tabs$Total$ctr).

Usage

get_test(x)

Arguments

Value

A tibble of tests — empty, with the same columns, when the table ran none (build them with tab(test = TRUE)); NULL only when x has lost its attributes.

See Also

tab() for ⁠test =⁠, tab_structure() and tab_columns() for the rest of a table's metadata.

Examples

tabs <- tab(forcats::gss_cat, race, marital, test = TRUE)
get_test(tabs)

Description

forcats::gss_cat with levels merged into readable groups, and each variable's first level chosen as the reference the colors and the models compare everything else to. The data set most examples and vignettes are built on.

Usage

gss_cat_data_formatting()

Value

A tibble of 21483 rows: the US General Social Survey, 2000-2014.

Description

TRUE for a table built by tab, tab_reg or any of their variants — i.e. for a tabxplor_tab (a tabxplor_grouped_tab with tab_vars). tab_structure answers the fuller question: what structure is it, and what can be done with it.

Usage

is_tab(x)

Arguments

Value

A single logical.

See Also

tab_structure(), tab_get_vars().

Description

Crosstables

Usage

jmvtab(
  data,
  row_vars = NULL,
  col_vars = NULL,
  tab_vars = NULL,
  wt = NULL,
  pct = "no",
  color = "no",
  color_signif = "ignore",
  test = FALSE,
  anova = "welch",
  na = "keep",
  lvs = "all",
  cleannames = TRUE,
  ref_levels = NULL,
  levels_order = NULL,
  levels_collapse = NULL,
  shape = NULL,
  ref = "auto",
  ref2 = "first",
  comp = "tab",
  ci = "auto",
  conf_level = 0.95,
  stars = FALSE,
  design_effect = FALSE,
  ci_method_cell = "wilson",
  ci_method_diff = "newcombe",
  ci_method_mean_diff = "welch",
  ci_method_mean_ratio = "robust",
  tab_theme = "light",
  totaltab = "line",
  wrap_rows = 35,
  wrap_cols = 15,
  display = "auto",
  n = "range",
  add_pct = FALSE,
  subtext = "",
  digits = "0",
  n_min = 0,
  export_format = "excel",
  exportExcel = FALSE,
  export_dir = "~/Documents",
  export_filename = "Table",
  resetPath = FALSE,
  xl_replace = FALSE
)

Arguments

Value

A results object containing:

Description

Regressions

Usage

jmvtabreg(
  data,
  outcome = NULL,
  predictors = NULL,
  tab_vars = NULL,
  wt = NULL,
  family = NULL,
  link = NULL,
  outcome_level = NULL,
  trials = NULL,
  effect = "auto",
  measure = "auto",
  empirical = TRUE,
  models = NULL,
  na = "drop_by_outcome",
  run_compare = FALSE,
  levels_order = NULL,
  levels_collapse = NULL,
  crosses = NULL,
  ref_levels = NULL,
  shape = NULL,
  multiplier = NULL,
  conf_level = 0.95,
  ci_method = "wald",
  stars = TRUE,
  color = "measure",
  color_signif = "grey_non_signif",
  display = "auto",
  n = "range",
  digits = "0",
  cleannames = TRUE,
  subtext = "",
  tab_theme = "light",
  wrap_rows = 35,
  wrap_cols = 15,
  export_format = "excel",
  exportExcel = FALSE,
  export_dir = "~/Documents",
  export_filename = "Reg_model",
  resetPath = FALSE,
  xl_check = FALSE,
  xl_replace = FALSE
)

Arguments

Value

A results object containing:

Description

Build a tabxplor_tab around fmt columns

Usage

new_tab(
  tabs = tibble::tibble(),
  subtext = "",
  test = new_test_tibble(),
  chi2 = NULL,
  meta = NULL,
  ...,
  class = character()
)

new_grouped_tab(
  tabs = tibble::tibble(),
  groups,
  subtext = "",
  test = new_test_tibble(),
  chi2 = NULL,
  meta = NULL,
  ...,
  class = character()
)

Arguments

Value

A tibble of class tabxplor_tab.

A tibble of class tabxplor_grouped_tab.

Description

A French national survey, used to show what adjustment does to a relationship: going to the cinema is strongly patterned by occupation, and also by age – and the two are entangled. See the Reading a regression article for the analysis. It also carries a real sampling weight (poids), so it is the data set to try ⁠wt =⁠ on; see vignette("tabxplor-weights").

Usage

questionr_hdv

Format

A tibble of 2 000 rows and 20 columns. The ones the article uses:

cinema

Went to the cinema in the last 12 months? "Oui" first.

qualif

Occupational qualification, 7 levels, "Cadre" (senior professional) first. 347 values are missing, as in the original.

age

Age in years, 18 to 97.

poids

The survey's own sampling weight.

The rest describe the respondent (sexe, nivetud, occup, freres.soeurs), their views (clso, relig, trav.imp, trav.satisf) and six more leisure activities (sport, cuisine, bricol, lecture.bd, peche.chasse, hard.rock), plus heures.tv and id.

Source

The complete hdv2003 data of the questionr package (Julien Barnier, Francois Briatte and Joseph Larmarange), GPL (>= 2) – with thanks. It comes from the Histoire de vie survey run in 2003 by INSEE, the French national statistics institute. tabxplor's copy changes only the level order: every "Oui"/"Non" item reads "Oui" first, and qualif starts at "Cadre".

Examples

tab(questionr_hdv, qualif, cinema, pct = "row", na = "drop", color = "difference")

Description

A teaching companion, not a decision tool. Every verdict these panels illustrate is already a row in the table's own footer, for every model column, with no plotting package installed (see the stats argument of tab_reg()). This function exists to show what a violation looks like.

One call diagnoses every model in the table: one titled grid per model, drawing the panels its own family allows. Pass a tab_reg() table — the data it was built from is usually found on its own — or a fitted model directly.

Usage

reg_check_plots(
  x,
  data = NULL,
  check = "auto",
  predictors = NULL,
  ncol = NULL,
  facet_ncol = NULL,
  theme = NULL,
  lang = NULL,
  max_points = 2000L,
  nbins = 10L,
  conf = 0.95,
  seed = 20260810,
  ...
)

Arguments

Value

Invisibly, the assembled gtable — or, with several models, the named list of them, one per model, all drawn on the current graphics device.

See Also

tab_reg() and its stats argument (the same checks as footer rows), and forest_plot() for the RESULTS – its opposite contract: it reads the finished table and never re-fits, where a model check always must.

Examples

# \donttest: building a multi-panel ggplot grid costs a few seconds of CPU.

d <- forcats::gss_cat |>
  dplyr::mutate(married = factor(dplyr::if_else(marital == "Married",
                                                "Married", "Not married")))
if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("gridExtra", quietly = TRUE)) {
  t <- tab_reg(d, "married", c("race", "age"), family = "binomial")
  reg_check_plots(t)
}

Description

Shows the formula behind every column of a tab_reg() table — exactly what reached stats::glm(), survey::svyglm(), nnet::multinom() or MASS::polr(). Use it to check what a ⁠shape =⁠, a ⁠trials =⁠ or a model formula really built.

Usage

reg_formulas(x)

Arguments

Details

One row per model: several outcomes give one each, a predictors list one per model. Two things the list does not repeat: under tab_vars the same formula is fitted within each group, and color = "between_groups" (or stats = "group_interaction") fits one extra pooled model for the footer test only.

A summed score (⁠trials =⁠) is fitted on a success / failure pair, so its formula names the two internal columns tabxplor builds for it (.gb_succ, .gb_fail, and .gb_trials in the offset of the risk-ratio link).

The formula names the columns as the user wrote them, but a continuous predictor is fitted anchored at its ref (its mean by default), and a ⁠shape =⁠ may have recoded it — neither changes any effect, only what the Constant row means.

Value

A tibble with one row per model: model (its name in the table), outcome, family (the outcome family), link (the measure that model estimates — the word ⁠link =⁠ takes), fit (the R call it was fitted with) and formula. A svyglm() row also means robust (Huber-White) standard errors: survey's design-based variance IS the sandwich, which is why a ratio or a difference on a binary outcome is fitted through it.

See Also

tab_reg(), reg_measures() (what an outcome can be modelled as).

Examples

d <- forcats::gss_cat
d$married <- as.integer(d$marital == "Married")
reg_formulas(tab_reg(d, "married", c("race", "age"), family = "binomial"))

Description

Lists what tab_reg() can report for one outcome: which models it could fit, and which measure of deviation each of them yields. It reads the same runtime table the argument validator and the error messages read, so what it prints is what the function does. The section below is the same table for every kind of outcome, read without any data.

Usage

reg_measures(data, outcome, family = "auto", link = "auto")

Arguments

Details

The table has two blocks, because the grid factors:

• one row per model you could fit — its link, and the measure that model's own coefficients carry (effect = "conditional");

• then the measures read off the model's predictions, which are the same whichever model you fit — link reads "(any)" there.

So link is the choice that matters, and it decides only which measure comes with a coefficient: everything else is available from any of them.

By default only each family's own model is listed — the one it fits unless told otherwise. link = "all" adds the others, which are specialist choices, and marks the family's own with base_link.

Only what can be built is listed. A measure this kind of outcome does not have simply has no row, and the message says why (an odds ratio needs a probability to take the odds of). One state exists only at run time: a link that does not converge on your data. tab_reg() says so and, for the risk difference, falls back to the linear probability model.

Value

A tibble of family (only when several are listed), link, measure, effect, header (the column name it would produce) and reads_as (what that header's acronym means). With link = "all", a base_link column says which model is the family's own (NA on the prediction rows, which belong to no link in particular).

Which models each outcome offers, and which measures

Generated from the package's own resolution table, so it cannot drift from what tab_reg() builds. A measure that IS the model's own is read off its coefficients; any other is computed from its predictions (effect = "marginal" or "at_reference").

• gaussian — a cell is a mean. Models: link = "difference", the default (linear regression); link = "ratio" (log-link mean regression (Poisson pseudo-likelihood, robust standard errors)). Reported: measure = "difference", "ratio", "raw_coefficient".

• binomial — a cell is a percentage. Models: link = "odds_ratio", the default (logistic regression); link = "ratio" (modified Poisson regression); link = "difference" (additive-risk regression (identity link, robust standard errors)). Reported: measure = "ratio", "difference", "odds_ratio", "raw_coefficient".

• poisson — a cell is a count. Models: link = "ratio", the default (Poisson regression). Reported: measure = "difference", "ratio", "raw_coefficient".

• multinomial — a cell is a percentage. Models: link = "odds_ratio", the default (multinomial logistic regression). Reported: measure = "ratio", "difference", "odds_ratio", "raw_coefficient".

• ordinal — a cell is a position on an ordered scale. Models: link = "odds_ratio", the default (ordinal logistic regression). Reported: measure = "difference", "ratio", "odds_ratio", "raw_coefficient".

See Also

tab_reg() to build the table, reg_formulas() to see the formula each column was fitted with.

Examples

reg_measures(car_arrests, "released")
reg_measures(car_salaries, "salary")

Description

Builds an integer score column counting, for each row, how many of the listed factors sit at their first level (1 if so, 0 otherwise) – the score ranges 0 to length(vars_list). The natural way to sum a battery of yes/no survey items into one score, feeding the grouped-binomial outcome of tab_reg() (its trials argument).

Usage

score_from_lv1(data, name, vars_list)

Arguments

Details

The "first level" is levels(as.factor(x))[1]. Non-factor columns are coerced with as.factor(); missing values are folded into an explicit "NA" level first (via forcats::fct_na_value_to_level()), so NA never counts as the first level.

Value

data with the integer score column name added (or replaced).

See Also

tab_reg() and its trials argument for modelling a summed score as a grouped binomial; vignette("tabxplor"), section "Multiple-answer questions", for a worked example.

Examples

data <- tibble::tibble(group = factor(c("G1", "G1", "G2", "G2", "G3", "G3")),
                       a = factor(c("Oui", "Oui", "Oui", "Oui", "Non", "Oui")),
                       b = factor(c("Oui", "Non", "Non", "Oui", "Non", "Oui")),
                       c = factor(c("Oui", "Oui", "Non", "Non", "Oui", "Oui")))
data |>
  score_from_lv1("score", vars_list = c("a", "b", "c")) |>
  tab(group, score, digits = 1)

Description

Names the columns whose cells carry a horizontal bar behind their figure — a bar chart inside the table, at no cost in width, in html and in Excel. Total and footer rows take none.

One reference per column: every bar in a column is a share of the same ceiling, or two bars could not be compared. That ceiling is the column's own largest data cell by default, which is what spreads the bars over the width available; max states it instead, so that two tables can be read against each other.

It is a display intent, like a caption: the numbers are untouched, and a medium with nowhere to put a bar (the console, a pipe table) ignores it.

Usage

set_bars(x, cols, max = NULL)

get_bars(x)

Arguments

Value

x, with its bar columns set (set_bars) ; a named vector of their ceilings, NA where the column's largest is used, or NULL (get_bars).

See Also

new_tab() for the whole meta record.

Examples

t <- tab(forcats::gss_cat, race, marital, pct = "row")
t <- set_bars(t, "Married")
get_bars(t)

# a full bar means 100 %, whatever the column holds
get_bars(set_bars(t, "Married", max = 1))

Description

Records a caption/title on a tabxplor_tab that survives a dplyr pipeline (it is kept in the table's meta$vars$caption, carried through every verb) and is read by the exporters (tab_md, tab_kable, tab_xl) as the table title, ahead of a regression table's auto-title, when the exporter's own caption= argument is not supplied. get_caption() reads it back (NULL when none is stored).

Usage

set_caption(x, caption)

get_caption(x)

Arguments

Value

x, with its stored caption set (set_caption) ; the caption or NULL (get_caption).

Description

Everything that decides what a coloured cell LOOKS like, and at which value it changes shade. set_color_palette() sets the hues (and the console's light/dark theme); set_color_breaks() sets the thresholds each measure is read on; get_color_style() and get_color_breaks() read them back. All of them act globally, through options(), so one call at the top of a script restyles every table it builds — see tabxplor-options. A single table can override the thresholds with tab(color_breaks =).

Color breaks are a named list of the ten measure scales pct_diff, pct_ratio, odds_ratio, mean_diff, mean_ratio, contrib, zscore, adj_ratio, adj_diff and adj_diff_std. Each is a vector of positive-only thresholds (the under-represented side is mirrored automatically), 1 to 4 values, one per color step.

Every default is the same ladder in another measure, read at ONE reference cell of 50 %: 5 / 10 / 20 / 30 percentage points is also 0.1 / 0.2 / 0.4 / 0.8 SD, x1.1 / x1.2 / x1.5 / x2 as a ratio and x1.2 / x1.5 / x2 / x4 as an odds ratio – so a shade means the same size of deviation whichever measure a table is read on. pct_diff colors percentage-point differences, pct_ratio the relative risk, odds_ratio the odds ratio (color = "odds_ratio"), mean_diff the standardized mean difference (Glass's delta) by default (supply data-unit values for absolute coloring), mean_ratio the mean ratio, contrib the chi2 contribution (in multiples of the mean cell contribution) and zscore an absolute z scale (the adjusted standardized residual) – the absolute scale color = "contrib" switches to under color_signif = "guaranteed_effect". Its default c(1.96, 2.58, 3.89, 6) is written as conf_level_to_z(c(0.95, 0.99, 0.9999, 1 - 2e-9)), and its FIRST value is re-anchored to the significance threshold at print time, so the remaining ones are read as spacings from it. adj_ratio, adj_diff and adj_diff_std are the tab_reg-only scales of color = "adjustment" / "between_groups" – how far a modelled effect sits from the observed one (or from the reference group's). Which one a column reads follows the estimate's own scale: adj_ratio for a multiplicative effect (odds / risk ratio or ratio of means), adj_diff for a probability-scale marginal effect (in percentage points), and adj_diff_std for an additive effect in the outcome's own units (a gaussian beta, a count marginal effect), where the gap is divided by SD(Y) so the same threshold means the same thing whatever unit the outcome is recorded in. An empty/NULL scale drops that measure for its column type.

Two rules shape a default, and a custom one is free to break them. A ladder is MIRRORED unless the quantity it grades is bounded above: a percentage ratio is capped at 1 / base, so a cell can sit far below its reference and never far above it, and pct_ratio is stricter below (list(over = c(1.1, 1.2, 1.5, 2), under = c(1.1, 1.25, 2, 4))) – a ratio of means and a ratio of two estimates have no ceiling and stay symmetric. And a fill is read at a glance, so on the BACKGROUND channel the two ratio scales keep their two loudest rungs only: with the default color = TRUE the text grades every deviation and the background flags the ones whose RELATIVE size is out of proportion.

Usage

set_color_palette(
  text_colors = NULL,
  text_colors_neg = NULL,
  background_colors = NULL,
  background_colors_neg = NULL,
  dark_text_colors = NULL,
  dark_text_colors_neg = NULL,
  dark_background_colors = NULL,
  dark_background_colors_neg = NULL,
  bg_legend_colors = NULL,
  bg_legend_colors_neg = NULL,
  theme = NULL
)

set_color_style(
  type = c("text", "bg"),
  theme = NULL,
  html_24_bit = NULL,
  custom_palette = NULL
)

get_color_style(
  mode = c("crayon", "color_code", "face"),
  type = NULL,
  theme = NULL,
  ...
)

set_color_breaks(breaks = NULL, ...)

get_color_breaks(brk, type = c("positive", "all"))

Arguments

Details

set_color_palette() customises the palette used to print tab. Each palette is 4 hex codes ordered faint -> strong. Provide only the ones you want to change; the OKLCH defaults are used otherwise. The ANSI styles are (re)built once, not per cell.

Value

Sets the internal color palettes (invisibly) and the option "tabxplor.color_style_theme".

A list of 8 terminal (ANSI) color-style functions, a vector of 8 color html codes, or (mode = "face") the palette's typography record.

Sets the global option "tabxplor.color_breaks" (a named list of scales) and returns it invisibly.

The color breaks as a double vector or a list(over =, under =), or a named list of these.

Functions

• set_color_style(): Superseded by set_color_palette(). Kept as a back-compat shim: type/theme still take effect (as options); custom_palette maps its over/under colours onto the new 4+4 palette; html_24_bit is inert (exports are always 24-bit).

• get_color_style(): get the color palette as terminal (ANSI) style functions or html codes: an 8-element vector (4 over-represented intensities then 4 under-represented), indexed by the engine slot.

• set_color_breaks(): set the breaks used to print colors.

• get_color_breaks(): get the color breaks currently in use, in the canonical shape.

Examples

set_color_palette(text_colors = c("#02a5b3", "#0891c9", "#0267c7", "#300dfd"))
set_color_breaks(
  pct_diff   = c(0.05, 0.15, 0.3),
  pct_ratio  = list(over = 2),
  mean_ratio = c(1.15, 2, 4),
  contrib    = c(1, 2, 5)
)
set_color_breaks(get_color_breaks())   # a no-op: the shape round-trips

Description

Records one or more tabxplor_tabs that BELONG to x and are rendered under it by every medium — the console, tab_md, tab_html and tab_xl — exactly as if they had been passed in one list, and which travel with x through a dplyr pipeline (they are kept in x's meta$footer_tabs).

The use is a fact that belongs to the table without being a row of it: the eigenvalues of the axes beside a factorial-analysis summary, a sample description beside the result it describes.

Usage

set_footer_tabs(x, tabs)

get_footer_tabs(x)

Arguments

Value

x, with its subordinate tables set (set_footer_tabs) ; the list of them, or NULL when none (get_footer_tabs).

See Also

new_tab() for the whole meta record.

Examples

main <- tab(forcats::gss_cat, race, marital, pct = "row")
side <- tab(forcats::gss_cat, race)
main <- set_footer_tabs(main, list("Base" = side))
get_footer_tabs(main)

Description

The generated legend names a measure with the discipline's own words — color = "contrib" says contribution to Chi2. A table may legitimately grade the same ladder on another quantity: a factorial axis has no chi-squared, and its cells' contribution is to the variance of the axis. set_legend_words() re-states the words and changes nothing else, so the swatches, the ladder, both registers, the publication palettes, the plot guide and every medium keep working — the console included, which no exporter argument can reach.

Prefer it to writing a legend of your own: replacing the sentence (through set_subtext) costs you the terse/prose pair and the publication palettes' wording.

Usage

set_legend_words(x, ...)

get_legend_words(x)

Arguments

Details

The fields a table may re-state — naming only, never a number:

• word — the short word (the console, a plot guide); word_long — the same named in full, for the export footers; word_std / word_long_std their SD-scale twins.

• word_guar — the color_signif = "guaranteed_effect" head, a template taking the confidence level ("%s%%-guaranteed contribution").

• subject — the noun for what is graded, when it is not the cell itself.

• ref — the baseline noun (the mean contribution), for a measure compared to a concept rather than to a row of the table: the terse form brackets it with its preposition and the prose one points at it bare, both from this one field. Give ref_word / ref_phrase instead only where those two nouns genuinely differ. Re-stating any of them on a measure whose reference is a category or a total is refused — there the legend names what the table itself shows.

• unit_word — the unit the thresholds are counted in.

• lead_over / lead_under — the sentence each side of the ladder opens with, as a template taking %1$s the subject, %2$s the reference and %3$s the null value. Only %1$s is always there: a line names its baseline in full on its first side and not again on its second, so %2$s comes back empty there — where the baseline is the measure's own (a mean contribution, an axis), write it into the sentence rather than interpolate it.

• caveat — one sentence of honesty appended to the line.

An engine fact (raw, scale, sig_source, bounds) and a ladder glyph (break_over, threshold_mult) are refused: a table attribute must never change a number, and a column pulled out of its table must still colour identically.

Written in the language of the call — unlike the words tabxplor generates, which follow lang = at render.

Value

x, with its legend words set (set_legend_words) ; the named list of them, or NULL (get_legend_words).

See Also

set_subtext() for the footer template, set_color_breaks() for the ladder itself.

Examples

t <- tab(forcats::gss_cat, race, marital, pct = "row", color = "contrib")
cat(tab_footer_text(t), sep = "\n")

t <- set_legend_words(t, contrib = "contribution to the axis variance")
cat(tab_footer_text(t), sep = "\n")

Description

A table's footer text, as a template: everything tabxplor generates is a <placeholder> and everything you write is a line, so the order of the lines is the order of the footer. Re-order them and it re-orders; drop <legend> and no colour legend is generated, in the console too.

A subtext naming no placeholder is simply appended to the template — which is what a note has always done, so tab(subtext = "Field: GSS 2000") is unchanged. Writing one placeholder on a line of its own takes the layout over: only what you name is printed. An unknown <...> is not a placeholder and passes through verbatim (\< escapes a literal <).

The template a producer writes names only what this table can say: no <weight> on an unweighted table, no <model> outside a regression. What you read back is therefore what prints, and the way to drop a line is to delete it.

A line opening on a short label and a colon ("Field: GSS 2000") has that label set in bold in every medium; options(tabxplor.subtext_bold_label = FALSE) prints it as written.

Usage

set_subtext(x, subtext)

get_subtext(x)

Arguments

Value

x, with its footer template set (set_subtext) ; the template, as a character vector (get_subtext).

See Also

tab_footer_text() to see what the template prints, set_legend_words() to re-word the generated legend, set_footer_tabs() for a table or a note under the whole block.

Examples

t <- tab(forcats::gss_cat, race, marital, pct = "row", color = "diff")
get_subtext(t)

# your own sentence, with tabxplor's own pieces inside it
t <- set_subtext(t, c("<measure> (<ref>): <breaks>", "<stars>"))
cat(tab_footer_text(t), sep = "\n")

Description

Turn a number into the form you want to read it in: cut it into quantile groups or into bands at the mean and one standard deviation either side (it becomes an ordinary factor), or transform it and keep it a number. This is the same operation tab(shape =) and tab_reg()⁠(shape =)⁠ perform, exposed on its own vector, so a column you cut by hand is identical to one they cut.

Usage

shape_numeric_var(x, shape, w = NULL, name = NULL, ordered = TRUE)

Arguments

Value

For a cut: a factor whose levels carry the real cut points and, in words, where each group sits. For "log" / "sqrt": a numeric vector.

The mean of a transform is not the transform of the mean

"log" and "sqrt" replace the values, so a crosstab column then shows the mean of the logarithm — a different quantity from the logarithm of the mean, and smaller. tab() renames the column for that reason (age becomes log_age), so no header promises the wrong quantity; do the same if you shape a column by hand.

The shapes

• "linear": the number as it is — one slope in a model, one mean in a crosstab. The default for a column variable, and what shape is spelled out as when nothing is done.

• "log": replace the variable by its logarithm — diminishing returns. Needs strictly positive values.

• "sqrt": replace the variable by its square root. Needs non-negative values.

• "sd_bands": four bands cut at the mean and one standard deviation either side. Each level names its own cut (⁠[30,48) ; < mean⁠), so the label can be checked against the interval beside it. The cut points mean the same thing across sub-samples of one variable, where quantile breaks move with each one; but the bands are NOT balanced, and on a skewed variable a landmark falling outside the data is dropped (an exponential variable gets three bands, not four).

• "median": two groups of equal size, cut at the median — the coarsest reading of a number.

• "terciles": three groups of equal size.

• "quartiles": four groups of equal size. The counts are balanced, so every group answers on a comparable base.

• "quintiles": five groups of equal size.

• "deciles": ten groups of equal size. Reads a gradient, but ten rows need a large sample to keep each base usable.

• "values_to_levels": one level per distinct value, in numeric order. Right for a counted number or a 1-7 scale; unreadable for a continuous one, which is what "auto" decides.

• an integer k (2 to 20): k quantile groups of equal size.

See Also

tab() and tab_reg(), whose shape argument is this function applied once to the whole population, before any sub-table or sub-model is split off.

Examples

age <- forcats::gss_cat$age
table(shape_numeric_var(age, "sd_bands", name = "age"))
table(shape_numeric_var(age, "quartiles"))

Description

tab() builds a cross-table of one or several row variables by one or several column variables, and colors the cells so the table is easy to read at a glance — in the R console, or exported to Excel, HTML or Word. Cells can show counts, row or column percentages, or (for a numeric column variable) means, optionally with differences, confidence intervals and tests.

The result is a tibble (of class tabxplor_tab), so every dplyr verb keeps working on it.

New to the package? Four arguments are enough to begin — data, row_vars, col_vars and pct — then add color when you want reading helpers. The Introduction (vignette("tabxplor")) works through them. Package-wide defaults are options(), listed at tabxplor-options.

Usage

tab(
  data,
  row_vars,
  col_vars,
  tab_vars,
  wt,
  ...,
  pct = "no",
  color = "no",
  color_signif = "ignore",
  test = FALSE,
  na = "keep",
  levels = "all",
  cleannames = NULL,
  other_if_less_than = 0,
  ref = "auto",
  ref2 = "first",
  comp = "tab",
  ci = "auto",
  conf_level = NULL,
  stars = NULL,
  ci_method = NULL,
  anova = NULL,
  design_effect = NULL,
  totaltab = "line",
  common_totrow = FALSE,
  n = NULL,
  n_min = 0,
  add_pct = FALSE,
  subtext = "",
  caption = NULL,
  digits = 0,
  display = NULL,
  color_breaks = NULL,
  output_list = FALSE,
  spread_vars,
  filter
)

Arguments

Details

Ordered factors stay ordered through the whole pipeline, which is what lets ref2 = "cumulative" pick its column variables by class. One consequence is worth knowing: the synthetic "Total" and "NA" levels are appended after the real ones, so on an ordered column they compare as the greatest. They are labels, not points on the scale.

Weights and survey designs. A weight (wt) weights the estimates; the intervals still use the raw number of cases unless design_effect = TRUE. Pass a survey::svydesign as data and strata, clusters, fpc and calibration reach every interval, star and colour threshold. The footer always names what you got. See Weighted and survey data (vignette("tabxplor-weights")).

Value

A tibble of class tabxplor_tab. Every numeric column is an fmt vector holding all the data behind the number it shows; the row_vars and tab_vars columns are factors. Any factor column you add later is treated as a tab_vars and used for grouping, so keep added text columns as character.

Significance stars

With stars = TRUE and an interval anchored on the comparison (see ci), each cell says how sure we can be that its deviation from the reference is real and not sampling noise: * at the 10% level, ** at 5%, *** at 1%. The exact p-value is stored per cell, readable with $pvalue or get_pvalue().

No separate test runs behind the scenes: a cell is significant exactly when the interval it prints no longer contains zero, so the stars and the [inf; sup] bracket can never contradict each other. Which classical test that amounts to follows ci_method, and the table's legend names it. An absolute cell interval compares nothing, so it carries no stars.

See Also

tab_reg() (regression tables) and tab_counts() (pre-aggregated counts); the superseded tab_num() (numeric variables) and tab_plain() (one bare cross-table). tabxplor-display says what a cell can show; set_color_breaks() / set_color_palette() customise the colours; tab_structure() reports what a finished table is and what accepts it. Export it with tab_xl() (Excel), tab_kable() (HTML) or tab_md() (Markdown), and chart it with forest_plot(). Package-wide defaults live in tabxplor-options.

color = "contrib" reads as a heatmap of the association pattern. For the specialist contingency-table models built on top of it — quasi-independence, Goodman's RC association models, UNIDIFF — see the logmult package (https://cran.r-project.org/package=logmult).

Examples

# A simple cross-table of counts:
tab(car_arrests, colour, released)


# Row percentages, with the difference to the total coloured:
tab(questionr_hdv, qualif, cinema, pct = "row", na = "drop", color = "difference")

# One subtable per level of a third variable, and colour only what is significant:
tab(questionr_hdv, qualif, cinema, sexe, pct = "row", na = "drop",
    color = "difference", color_signif = "grey_non_signif")

# Several col_vars at once, mixing factors and numeric variables (means):
tab(car_salaries, rank, c(discipline, salary, yrs.service), pct = "row")

# `levels = "first"` keeps one column per variable: a compact summary of many items.
tab(facto_tea, SPC, c(breakfast, evening, home), pct = "row", levels = "first")

# Each cell's contribution to the table's variance, as in a correspondence analysis:
tab(questionr_hdv, qualif, cinema, na = "drop", color = "contrib")

# The result is a tibble, so every dplyr verb works on it. Keep the total rows last:
tab(questionr_hdv, qualif, cinema, pct = "row", na = "drop") |>
  dplyr::arrange(is_totrow(dplyr::pick(dplyr::everything())), dplyr::desc(Oui))

Description

One row per numeric (tabxplor_fmt) column, with the per-column attributes that decide what it shows, what it estimates, how it is coloured and how its confidence interval was computed. The column-axis companion of tab_structure(), which describes the table as a whole.

Usage

tab_columns(x)

Arguments

Value

A tibble, one row per fmt column:

column

the column name.

col_var, col_group

the column variable, and the sub-population its block belongs to ("" when the table was never spread).

scale, pct_type

what the column estimates, and on which percentage base.

display

the display template(s) its cells carry.

ref, comp_all, totcol, refcol

the comparison model: which baseline, whether it compares across sub-tables, and whether this column is a total or the reference.

color, color_bg, color_signif

the colour measure of each channel and the significance policy.

conf_level, degf, basis, ci_method

how this column's interval was computed — the level, the degrees of freedom it is referred to (NA = the normal quantile), whether it rests on the raw count, the weights or the survey design, and by which method.

model_family, role

for a tab_reg() table: the column's model family, and whether it holds the model estimate ("model") or its observed counterpart ("emp").

See Also

tab_structure() for the table's own structure; fmt_attr() to read or write one attribute; fmt() for what each attribute means.

Examples

t <- tab(forcats::gss_cat, marital, race, pct = "row", ci = "ref")
tab_columns(t)

Description

Bind a list of tables into one

Usage

tab_compact(tabs)

Arguments

Value

A tabxplor_tab

Examples

forcats::gss_cat |>
  tab(c(race, rincome), marital, pct = "row", color = "difference", output_list = TRUE) |>
  tab_compact()

Description

tab_counts() builds the same color-coded cross-table as tab(), but from data that is already cross-tabulated — a dplyr::count() result, a contingency table, or a published table of counts or percentages — instead of microdata (one row per individual). Percentages, differences, confidence intervals, chi-squared, colors and totals are all computed from the counts, and the result is identical to the table tab() would build from the microdata behind them.

It accepts four input shapes:

• Long tidy counts (the default): one row per row_var $\times$ col_var ($\times$ tab_vars) combination, with the count in counts (and the weighted count in wt_counts).

• A wide data.frame: a label (row_var) column plus one column per col_var level — select those level columns with cols and name the column variable with col_name.

• A table / xtabs / matrix object: melted automatically, the row and column variables read from the dimnames (or set with row_var / col_var).

• Frequencies + base N: the wide shape, plus input = "pct" and base (the column of row sample sizes); the integer counts are rebuilt from the percentages and the base.

With weighted data, give the real (unweighted) count in counts and the weighted count in wt_counts: estimates use the weighted counts, while confidence intervals and tests use the real unweighted sample size. Counts that are not whole numbers (weighted-only or frequency-only input) disable confidence intervals and chi-squared, with a message.

Usage

tab_counts(
  data,
  row_var,
  col_var,
  tab_vars,
  counts,
  wt_counts,
  cols,
  col_name = "variable",
  base,
  input = c("counts", "pct"),
  ...
)

Arguments

Value

A tabxplor_tab (or tabxplor_grouped_tab when tab_vars are provided).

Examples

# Long tidy counts (as from dplyr::count()) reproduce the microdata table :
counts <- dplyr::count(forcats::gss_cat, marital, race)
tab_counts(counts, marital, race, counts = n, pct = "row")
# tab(forcats::gss_cat, marital, race, pct = "row")   # identical

# A contingency table object :
tab_counts(table(forcats::gss_cat$marital, forcats::gss_cat$race), pct = "row")

# A wide data.frame of counts :
wide <- tidyr::pivot_wider(counts, names_from = race, values_from = n)
tab_counts(wide, row_var = marital, cols = c(Other, Black, White),
           col_name = "race", pct = "row")

Description

The CSS that colours tabxplor tables. It is a constant – a pure function of the colour palette, the channel type and the theme – so it does not take a table: one stylesheet styles every table in a document, whatever their color_breaks.

Usage

tab_css(
  theme = NULL,
  format = c("html", "md"),
  style_tag = TRUE,
  file = NULL,
  print_rules = NULL,
  ...
)

Arguments

Details

Cells carry classes named after the palette slot (.p1-.p4 over-represented text, .m1-.m4 under-represented text, .o1-.o4 / .u1-.u4 for the background channel), so tab_html() and tab_md() share one vocabulary.

Value

The CSS, invisibly when file is given. Printed as-is by knitr with results = "asis".

Two workflows

Self-contained (the default). tab_html(css = TRUE) and tab_md(css = TRUE) inline the stylesheet with the table, so a single file works anywhere (the RStudio/Positron Viewer, jamovi, a standalone .html). Nothing to do.

Once per document. In an .Rmd/.qmd with many tables, emit it once and let every table reuse it:

```{r, results = "asis"}
options(tabxplor.tab_kable_css = FALSE)
tab_css(theme = "auto")
```

Every later tab_html() then emits classes only. Two things to know: with css = FALSE and no tab_css() call the tables render uncoloured; and one stylesheet means one colour theme for the whole document. A black-and-white table (theme = "print_ready" or a publication palette on the table's own call) still renders as such under it: every stylesheet carries the publication palettes, scoped to the tables that wear them.

Restyling a table

Nothing is written inline on a cell, so any of the look can be overridden by adding your own rules after the stylesheet – no !important needed. The cell colour classes are also emitted scoped (⁠.tabxplor-tab .p1⁠) so they survive host pages that style table cells themselves, such as Bootstrap-based sites including pkgdown. Column widths in particular are left to the browser, which sizes each column to its content; to pin one, style its role:

.tabxplor-tab .tx-rv  { min-width: 10em; }   /* the row-variable levels column */
.tabxplor-tab .tx-tot { min-width: 5.5em; }  /* total columns                  */
.tabxplor-tab .tx-num { min-width: 4em; }    /* every number column            */

The roles a cell can carry: .tx-l/.tx-r (alignment), .tx-num (numbers), .tx-rv (the row-variable levels column), .tx-tot (total columns), .tx-bl/.tx-br (side borders), .tx-b (bold), .tx-lbl/.tx-vname (a variable name spanning its block), .tx-pill (a background-coloured value), .tx-span (the variable-name header row), .tx-foot (the footnote). Rows carry .tx-bt/.tx-bb/.tx-bb2 (top / bottom / thick-bottom rules).

Each html table is wrapped in a .tx-scrollbox, which scrolls it sideways rather than let it widen the page. Its title stays outside, so it does not scroll away, and the ⁠@media print⁠ block lifts the clip (a printer has no scrollbar). To let a table widen the page on screen too: ⁠.tx-scrollbox { overflow-x: visible; max-width: none; }⁠.

The black-and-white publication palettes

A greyscale print loses colour entirely — both direction ramps become the same grey — so these palettes say the same thing with something else. theme = "print_ready" is the one to reach for: it picks per table, the marks for a cross-table and the emphasis ladder for a regression, whose cells already carry their own direction symbol. Name one yourself to override that. They share ONE grey fill ramp (a background colour measure keeps carrying its magnitude) and differ in the text channel:

"print_minimalistic"

direction by underline (over) and italic (under); magnitude by an ink ladder.

"print_emphasis"

magnitude by an emphasis ladder (bold, then underline, then double underline) in pure black; direction by the cell's own measure symbol, plus italic under the null.

"print_marks"

magnitude and direction by a repeated superscript mark after the value (no significance stars: the marks take their place, do not use with tab_reg()).

In all of them a non-significant cell is greyed out, and the significance stars stay — except under "print_marks", where the marks take their place (one run of symbols after a value, not two). "bw" is a synonym of "print_minimalistic". One caveat, and only for a document that emits tab_css() once and renders its tables with css = FALSE: a stylesheet is table-independent, so it carries ONE of them. A cross-table is fine whatever it carries (its marks are cell text), but a regression's ladder is css and nothing else — name it there, tab_css(theme = "print_emphasis").

See Also

tab_html(), tab_md(), set_color_palette(), set_color_breaks()

Examples

cat(tab_css(theme = "auto"))
cat(tab_css(format = "md", style_tag = FALSE))  # the markdown flavour

Description

One entry point over the format-specific exporters tab_html (HTML), tab_md (Markdown), tab_xl (Excel) and forest_plot (a chart of the estimates). They share one set of display-option names and defaults; tab_export() forwards them and passes any format-specific argument through ....

Usage

tab_export(
  x,
  format = c("html", "md", "xl", "forest"),
  path = NULL,
  theme = NULL,
  color = TRUE,
  color_legend = TRUE,
  lang = NULL,
  transpose = FALSE,
  caption = NULL,
  var_names = NULL,
  ...
)

Arguments

Details

Each exporter is also callable on its own, which reads better in a pipe (x |> tab_xl()); use tab_export() when the format comes from a variable.

Value

The value of the underlying exporter: an HTML/knitr object ("html"), a markdown string ("md"), x invisibly with the Excel file written ("xl"), or a ggplot ("forest").

Examples

tabs <- tab(forcats::gss_cat, race, marital, pct = "row", color = "difference")
tab_export(tabs, "md")

Description

The lines tabxplor prints under a table, resolved: the template's placeholders built, the user's own lines as written. It is what set_subtext() edits, after the fact.

Usage

tab_footer_text(
  x,
  medium = c("plain", "console", "html", "md"),
  style = NULL,
  lang = NULL,
  theme = NULL
)

Arguments

Value

A character vector, one element per footer line.

See Also

set_subtext() for the template, set_legend_words() for the words.

Examples

t <- tab(forcats::gss_cat, race, marital, pct = "row", color = "diff")
cat(tab_footer_text(t), sep = "\n")

Description

The HTML exporter behind tab_export: tab_export(x, format = "html") calls this, and tab_kable() is a permanent alias of tab_html(). Use it directly for HTML-specific arguments.

Usage

tab_html(
  tabs,
  theme = NULL,
  color = TRUE,
  tooltips = NULL,
  popover = NULL,
  color_legend = TRUE,
  lang = NULL,
  caption = NULL,
  transpose = FALSE,
  var_names = NULL,
  get_data = FALSE,
  cells = NULL,
  wrap_rows = 35,
  wrap_cols = 15,
  whitespace_only = TRUE,
  css = NULL,
  ...
)

tab_kable(
  tabs,
  theme = NULL,
  color = TRUE,
  tooltips = NULL,
  popover = NULL,
  color_legend = TRUE,
  lang = NULL,
  caption = NULL,
  transpose = FALSE,
  var_names = NULL,
  get_data = FALSE,
  cells = NULL,
  wrap_rows = 35,
  wrap_cols = 15,
  whitespace_only = TRUE,
  css = NULL,
  ...
)

Arguments

Details

tab_kable() is a permanent alias of tab_html() – the two are identical. tab_html() names the output (an HTML table); tab_kable() is the name it had when kableExtra rendered it.

Value

A html table. Printing it opens it in the Viewer, on a page painted to match the table – so a theme = "dark" table no longer sits in a white pane. Everything the cell has no room for – the confidence interval, the exact p-value, the other ways of reading the same comparison (difference, ratio, odds ratio), the chi-squared contribution and the base count – is one hover away, each line named after the field it shows.

Examples

tabs <- tab(forcats::gss_cat, race, marital, year, pct = "row", color = "difference")
tab_html(tabs, theme = "light")

Description

Superseded (2.0.0) by tab(), the unified entry point: it accepts several row_vars / col_vars and merges them into one table by default (output_list = TRUE gives the list shape tab_many() returns).