A full-featured function to create, manipulate and format many cross-tables
as one, 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,
arrange, filter
or mutate.
Only breaks for attractions/over-representations (in green) should be given, as a vector of positive doubles, with length between 1 and 5. Breaks for aversions/under-representations (in orange/red) will simply be the opposite.
tab_many(
data,
row_vars,
col_vars,
tab_vars,
wt,
levels = "all",
na = "keep",
na_drop_all,
digits = 0,
totaltab = "line",
totaltab_name = "Ensemble",
totrow = TRUE,
totcol = "last",
total_names = "Total",
pct = "no",
diff = "tot",
comp = "tab",
chi2 = FALSE,
ci = "no",
conf_level = 0.95,
method_cell = "wilson",
method_diff = "ac",
color = "no",
subtext = "",
cleannames = NULL,
rare_to_other = FALSE,
n_min = 30,
other_level = "Others",
filter
)tab_get_vars(tabs, vars = c("row_var", "col_vars", "tab_vars"))
is_tab(x)
set_color_style(
type = c("text", "bg"),
theme = NULL,
html_24_bit = c("blue_red", "green_red", "no"),
custom_palette = NULL
)
get_color_style(
mode = c("crayon", "color_code"),
type = NULL,
theme = NULL,
html_24_bit = NULL
)
set_color_breaks(pct_breaks, mean_breaks, contrib_breaks)
get_color_breaks(brk, type = c("positive", "all"))
A data frame.
The row variable, which will be printed with one level per line. If numeric, it will be converted to factor. If more than one row_var if provided, a different table is made for each of them.
<tidy-select>
One column is printed for each level of each column variable.
For numeric variables means are calculated, in a single column.
To pass many variables you may use syntax col_vars = c(col_var1, col_var2, ...).
<tidy-select>
One subtable is made for each combination of levels of the tab variables.
To pass many variables you may use syntax tab_vars = c(tab_var1, tab_var2, ...).
All tab variables are converted to factor. Leave empty to make a simple table.
A weight variable, of class numeric. Leave empty for unweighted results.
The levels of col_vars to keep (for more complex selections
use dplyr::select). The argument is vectorised over col_vars.
"all": by default, all levels are kept.
"first": only keep the first level of each col_vars
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": removes NA levels before making each table
(tabs made with different column variables may have a different number of
observations, and won't exactly have the same total columns).
<tidy-select>
Removes all observations with a NA in any of the chosen variables, for all tables
(tabs for each column variable will have the same number of observations).
The number of digits to print, as a single integer, or an integer vector
the same length as col_vars. The argument is vectorisez over col_vars.
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.
The name of the total table, as a single string.
By default, total rows are printed.
Set to FALSE to remove them (after calculations if needed).
Vectorised over row_vars.
The policy with total columns. Vectorised over col_vars.
"last": by default, only prints a total column for the last
column variable (of class factor, not numeric).
"each": print a total column for each column variable.
"no": remove all total columns (after calculations if needed).
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.
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).
The argument is vectorised over both row_vars and col_vars. You can then write as
the following :
pct = list(row_var1 = list("row", "col", "col"), row_var2 = list("col", "row", "row"))
The reference cell to calculate differences (used to print colors).
Vectorisez over row_vars.
"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).
n: when diff is an integer, the nth row (or column) is used for comparison.
"regex": when diff 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 diffs.
The comparison level : by subtables/groups, or for the whole table.
Vectorised over row_vars.
"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 reference line of the total table
when diff = "first", an integer or a regular expression.
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"). Vectorised over row_vars.
The type of confidence intervals to calculate, passed to tab_ci.
Vectorised over row_vars.
"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.
The confidence level, as a single numeric between 0 and 1. Default to 0.95 (95%).
Character string specifying which method to use with percentages
for ci = "cell". This can be one out of:
"wald", "wilson", "wilsoncc", "agresti-coull", "jeffreys", "modified wilson",
"modified jeffreys", "clopper-pearson", "arcsine", "logit", "witting", "pratt",
"midp", "lik" and "blaker". Defaults to "wilson".
See BinomCI.
Character string specifying which method to use with percentages
for ci = "diff". This can be one out of: "wald", "waldcc", "ac", "score",
"scorecc", "mn", "mee", "blj", "ha", "hal", "jp". Defaults to "ac", Wald interval with
the adjustment according to Agresti, Caffo for difference in proportions and
independent samples. See BinomDiffCI.
The type of colors to print, as a single string. Vectorised over row_vars.
"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".
A character vector to print rows of legend under the table.
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.
When set to TRUE, levels with less count
than n_min will be merged into an "Other" level.
The count under which a level is aggregated in the "Other" level.
The name of the "Other" level, as a single string.
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.
In tab_get_vars, a character vector containing the wanted vars names:
"row_var", "col_vars" or "tab_vars".
A object to test with is_tab.
Default to "positive", which just print breaks for positive spreads.
Set to all to get breaks for negative spreads as well.
For set_color_style and get_color_style, is your console
or html table background "light" or "dark" ? Default to RStudio theme.
Should specific 24bits colors palettes be used for html tables ?
With light themes only. Default to getOption("tabxplor.color_html_24_bit")
Possibility to provide a custom color styles, as a character
vector of 10 html color codes (the five first for over-represented numbers,
the five last for under-represented ones). The result is saved to
options("tabxplor.color_style"). To discard, relaunch the function with
custom_palette = NULL.
By default, get_color_style returns a list of crayon coloring
functions. Set to "color_code" to return html color codes.
If they are to be changed, the breaks used for percentages.
Default to c(0.05, 0.1, 0.2, 0.3) : first color used when the pct of a cell
is +5% superior to the pct of the related total ; second color used when
it is +10% superior ; third +20% superior ; fourth +30% superior.
The opposite for cells inferior to the total.
With color = "after_ci", the first break is subtracted from all breaks
(default becomes c(0, 0.05, 0.15, 0.25) : +0%, +5%, +15%, +25%).
If they are to be changed, the breaks used for means.
Default to c(1.15, 1.5, 2, 4) : first color used when the mean of a cell
is superior to 1.15 times the mean of the related total row ; second color
used when it is superior to 1.5 times ; etc.
The opposite for cells inferior to the total.
With color = "after_ci", the first break is divided from all breaks
(default becomes c(1, 1.3, 1.7, 3.5)).
If they are to be changed, the breaks used for contributions to
variance. Default to c(1, 2, 5, 10) : first color used when the contribution of
a cell is superior to the mean contribution ; second color used when it is superior to
2 times the mean contribution ; etc. The global color (for example green or
red/orange) is given by the sign of the spread.
When missing, return all color breaks. Specify to return a given color
break, among "pct", "mean", "contrib", "pct_ci" and
"mean_ci".
A tibble of class tab, possibly with colored reading helpers.
When there are two row_vars or more, a list of tibble of class tab.
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.
A list with the variables names.
A single logical.
Set global options "tabxplor.color_style_type" and
"tabxplor.color_style_theme", used when printing tab objects.
A vector of crayon color functions, or a vector of color html codes.
Set the global option "tabxplor.color_breaks" as a list different double vectors, and also returns it invisibly.
The color breaks as a double vector, or list of double vectors.
tab_get_vars: Get the variables names of a tabxplor tab
is_tab: a test function for class tabxplor_tab
set_color_style: define the color style used to print tab.
get_color_style: get color styles as crayon functions or html codes.
set_color_breaks: set the breaks used to print colors
get_color_breaks: get the breaks currently used to print colors
# NOT RUN {
# Make a summary table with many col_vars, showing only one specific level :
# }
# NOT RUN {
library(dplyr)
first_lvs <- c("Married", "$25000 or more", "Strong republican", "Protestant")
data <- forcats::gss_cat %>% mutate(across(
where(is.factor),
~ forcats::fct_relevel(., first_lvs[first_lvs %in% levels(.)])
))
tab_many(data, race, c(marital, rincome, partyid, relig, age, tvhours),
levels = "first", pct = "row", chi2 = TRUE, color = "auto")
# }
# NOT RUN {
# Can be used with map and tribble to program several tables with different parameters
# all at once, in a readable way:
# }
# NOT RUN {
library(purrr)
library(tibble)
pmap(
tribble(
~row_var, ~col_vars , ~pct , ~filter , ~subtext ,
"race" , "marital" , "row", NULL , "Source: GSS 2000-2014",
"relig" , c("race", "age"), "row", "year %in% 2000:2010", "Source: GSS 2000-2010",
NA_character_, "race" , "no" , NULL , "Source: GSS 2000-2014",
),
.f = tab_many,
data = forcats::gss_cat, color = "auto", chi2 = TRUE)
# }
# NOT RUN {
set_color_style(type = "bg")
set_color_breaks(
pct_breaks = c(0.05, 0.15, 0.3),
mean_breaks = c(1.15, 2, 4),
contrib_breaks = c(1, 2, 5)
)
# }
Run the code above in your browser using DataLab