tabxplor (version 1.1.0)

tab: Single cross-table, with color helpers

Description

A full-featured function to create, manipulate and format single cross-tables, using colors to make the printed tab more easily readable (in R terminal or exported to Excel with tab_xl). Since objects of class tab are also of class tibble, you can then use all dplyr verbs to modify the result, like select, like arrange, filter or mutate. Wrapper around the more powerful tab_many.

Usage

tab(
  data,
  row_var,
  col_var,
  tab_vars,
  wt,
  sup_cols,
  na = "keep",
  digits = 0,
  pct = "no",
  color = "no",
  diff = "tot",
  comp = "tab",
  totaltab = "line",
  totaltab_name = "Ensemble",
  tot = c("row", "col"),
  total_names = "Total",
  chi2 = FALSE,
  ci = "no",
  conf_level = 0.95,
  subtext = "",
  cleannames = NULL,
  rare_to_other = FALSE,
  n_min = 30,
  other_level = "Others",
  filter
)

Arguments

data

A data frame.

row_var, col_var

The row variable, which will be printed with one level per line, and the column variable, which will be printed with one level per column. For numeric variables means are calculated, in a single column.

tab_vars

<tidy-select> Tab variables : a subtable is made for each combination of levels of the selected variables. Leave empty to make a simple cross-table. All tab_vars are converted to factor.

wt

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

sup_cols

<tidy-select> Supplementary columns variables, with only the first level printed, and row percentages (for numeric variables, a mean will be calculated for each row_var). To pass many variables you may use syntax sup_cols = c(sup_col1, sup_col2, ...). To keep all levels of other col_vars, or other types of percentages, use tab_many instead.

na

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

• "keep": by default, NA's of row, col and tab variables are printed as an explicit "NA" level.

• "drop": remove NA's in row, col and tab variables before calculations are done. Supplementary columns are then calculated for observations with no NA in any of the row, col and tab variables.

digits

The number of digits to print, as a single integer. To print a different number of digits for each sup_cols, an integer vector of length 1 + sup_cols (the first being the number of digits for the base table).

pct

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

color

The type of colors to print, as a single string :

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

• "diff": color percentages and means based on cells differences from totals (or from first cells when diff = "first").

• "diff_ci": color pct and means based on cells differences from totals or first cells, removing coloring when the confidence interval of this difference is higher than the difference itself.

• "after_ci": idem, but cut off the confidence interval from the difference first.

• "contrib": color cells based on their contribution to variance (except mean columns, from numeric variables).

• "auto": frequencies (pct = "all", pct = "all_tabs") and counts are colored with "contrib". When ci = "diff", row and col percentages are colored with "after_ci" ; otherwise they are colored with "diff".

diff

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

• "tot": by default, cells differences from total rows are calculated with pct = "row", and cells differences from total columns with pct = "col".

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

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

comp

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

• "tab": by default, contributions to variance, row differences from totals/first cells, and row confidence intervals for these differences, are calculated for each tab_vars group.

• "all": compare cells to the general total line (provided there is a total table with a total row), or with the first line of the total table when diff = "first".

totaltab

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

• "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.

totaltab_name

The name of the total table, as a single string.

tot

The totals :

• c("col", "row") or "both" : by default, both total rows and total columns.

• "row": only total rows.

• "col": only total column.

• "no": remove all totals (after calculations if needed).

total_names

The names of the totals, as a character vector of length one or two. Use syntax of type c("Total row", "Total column") to set different names for rows and cols.

chi2

Set to TRUE to calculate Chi2 summaries with tab_chi2. Useful to print metadata, and to color cells based on their contribution to variance (color = "contrib"). Automatically added if needed for color.

ci

The type of confidence intervals to calculate, passed to tab_ci (automatically added if needed for color).

• "cell": absolute confidence intervals of cells percentages.

• "diff": confidence intervals of the difference between a cell and the relative total cell (or relative first cell when diff = "first").

• "auto": ci = "diff" for means and row/col percentages, ci = "cell" for frequencies ("all", "all_tabs").

By default, for percentages, with ci = "cell" Wilson's method is used, and with ci = "diff" Wald's method along Agresti and Caffo's adjustment. Means use classic method. This can be changed in tab_ci.

conf_level

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

subtext

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

cleannames

Set to TRUE to clean levels names, by removing prefix numbers like "1-", and text in parenthesis. All data formatting arguments are passed to tab_prepare.

rare_to_other

When set to TRUE, levels with less count than n_min will be merged into an "Other" level.

n_min

The count under which a level is aggregated in the "Other" level.

other_level

The name of the "Other" level, as a single string.

filter

A dplyr::filter to apply to the data frame first, as a single string (which will be converted to code, i.e. to a call). Useful when printing multiples tabs with tibble::tribble, to use different filters for similar tables or simply make the field of observation more visible into the code.

Value

A tibble of class tab, possibly with colored reading helpers. All non-text columns are of class fmt, storing all the data necessary to print formats and colors. Columns with row_var and tab_vars are of class factor : every added factor will be considered as a tab_vars and used for grouping. To add text columns without using them in calculations, be sure they are of class character.

Examples

# NOT RUN {
# A simple cross-table:
tab(forcats::gss_cat, marital, race)


# With more variables provided, `tab` makes a subtables for each combination of levels:
# }
# NOT RUN {
tab(forcats::gss_cat, marital, tab_vars = c(year, race))
# }
# NOT RUN {
# You can also add supplementary columns, text or numeric:
# }
# NOT RUN {
tab(dplyr::storms, category, status, sup_cols = c("pressure", "wind"))
# }
# NOT RUN {
# Colors to help the user read the table:
data <- forcats::gss_cat %>%
  dplyr::filter(year %in% c(2000, 2006, 2012), !marital %in% c("No answer", "Widowed"))
gss  <- "Source: General social survey 2000-2014"
gss2 <- "Source: General social survey 2000, 2006 and 2012"

# Differences between the cell and it's subtable's total cell:
# }
# NOT RUN {
tab(data, race, marital, year, subtext = gss2, pct = "row", color = "diff")
# }
# NOT RUN {
# Differences between the cell and the whole table's general total cell:
# }
# NOT RUN {
tab(data, race, marital, year, subtext = gss2, pct = "row", color = "diff",
  comp = "all")
# }
# NOT RUN {
# Historical differences:
# }
# NOT RUN {
data2 <- data %>% dplyr::mutate(year = as.factor(year))
tab(data2, year, marital, race, subtext = gss2, pct = "row",
    color = "diff", diff = "first", tot = "col")


# Differences with the total, except if their confidences intervals are superior to them:
tab(forcats::gss_cat, race, marital, subtext = gss, pct = "row", color = "diff_ci")

# Same differences, minus their confidence intervals:
tab(forcats::gss_cat, race, marital, subtext = gss, pct = "row", color = "after_ci")

# Contribution of cells to table's variance, like in a correspondence analysis:
tab(forcats::gss_cat, race, marital, subtext = gss, color = "contrib")
# }
# NOT RUN {
# Since the result is a tibble, you can use all dplyr verbs to modify it :
# }
# NOT RUN {
library(dplyr)
tab(dplyr::storms, category, status, sup_cols = c("pressure", "wind")) %>%
  dplyr::filter(category != "-1") %>%
  dplyr::select(-`tropical depression`) %>%
  dplyr::arrange(is_totrow(.), desc(category))
# }
# NOT RUN {
# }
# NOT RUN {
# With `dplyr::arrange`, don't forget to keep the order of tab variables and total rows:
tab(data, race, marital, year, pct = "row") %>%
  dplyr::arrange(year, is_totrow(.), desc(Married))
  
# }