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<-. A fmt vector have 13 fields :
n, digits, display, wn, pct, mean,
diff, ctr, var, ci, in_totrow, in_tottab,
in_refrow. Other arguments are attributes, attached not to each value, but to
the whole vector, like type, 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.
fmt(
n = integer(),
type = "n",
digits = rep(0L, length(n)),
display = dplyr::case_when(type == "mean" ~ "mean", type %in% c("row", "col",
"all", "all_tabs") ~ "pct", TRUE ~ "n"),
wn = rep(NA_real_, length(n)),
pct = rep(NA_real_, length(n)),
mean = rep(NA_real_, length(n)),
diff = rep(NA_real_, length(n)),
ctr = rep(NA_real_, length(n)),
var = rep(NA_real_, length(n)),
ci = rep(NA_real_, length(n)),
in_totrow = rep(FALSE, length(n)),
in_tottab = rep(FALSE, length(n)),
in_refrow = rep(FALSE, length(n)),
comp_all = NA,
diff_type = "",
ci_type = "",
col_var = "",
totcol = FALSE,
refcol = FALSE,
color = ""
)is_fmt(x)
get_num(x)
set_num(x, value)
get_type(x, ...)
set_type(x, type)
is_totrow(x, ...)
as_totrow(x, in_totrow = TRUE)
is_tottab(x, ...)
as_tottab(x, in_tottab = TRUE)
is_totcol(x, ...)
as_totcol(x, totcol = TRUE)
is_refrow(x, ...)
as_refrow(x, in_refrow = TRUE)
get_comp_all(x, replace_na = TRUE)
set_comp_all(x, comp_all = FALSE)
get_diff_type(x, ...)
set_diff_type(x, diff_type)
get_ci_type(x, ...)
set_ci_type(x, ci_type)
get_col_var(x, ...)
set_col_var(x, col_var)
is_refcol(x, ...)
as_refcol(x, refcol = TRUE)
get_color(x, ...)
set_color(x, color)
get_digits(x)
set_digits(x, value)
The underlying count, as an integer vector of length n(). It is used
to calculate confidence intervals.
The type of the column, which defines the type of background calculation to be made (as a single string, since it's not a field but an attribute) :
"n": counts
"mean": mean column (from numeric variables)
"row": row percentages
"col": column percentages
"all": frequencies by subtable/group (i.e. by tab_vars)
"all_tabs": frequencies for the whole table
The number of digits, as an integer, or an integer vector the length
of n.
The display type : the name of the field you want to show when printing
the vector. Among "n", "wn", "pct", "diff", "ctr",
"mean", "var", "ci",
"pct_ci" (percentages with visible confidence interval),
"mean_ci" (means with visible confidence interval). As a single string, or a
character vector the length of n.
The underlying weighted counts, as a double vector the length of
n. It is used in certain operations on fmt, like means.
The percentages, as a double vector the length of n.
Calculate with tab_pct.
The means, as a double vector the length of n.
The differences (from totals or first cells),
as a double vector the length of n. Used to set colors for means and
row or col percentages. Calculate with tab_pct.
The contributions of cells to (sub)tables variances,
as a double vector the length of n. Used to print colors when
color = "contrib". The mean contribution of each (sub)table is written on
total rows (then, colors don't print well without total rows).
Calculate with tab_chi2.
The cells variances, as a double vector the length of n.
Used with type = "mean" to calculate confidence intervals.
Calculate with tab_plain.
The confidence intervals, as a double vector the length of n.
Used to print colors ("diff_ci", "after_ci").
Calculate with tab_ci.
TRUE when the cell is part of a total row
TRUE when the cell is part of a total table
TRUE when the cell is part of a reference row
(cf. diff_type)
FALSE when the comparison level is the subtable/group,
TRUE when it is the whole table
The type of difference of the vector (calculate
with tab_pct) :
"" or "no": no differences have been calculated
"tot": the reference row (or column) is the total row (or column)
"first": the reference row (or column) is the first row (or column)
The type of confidence intervals of the vector (calculate
with tab_ci) :
"" or "no": no ci have been calculated
"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_type = "first").
"auto": "diff" for means and row/col percentages,
"cell" for frequencies ("all", "all_tabs").
The name of the col_var used to calculate the vector
TRUE when the vector is a total column
TRUE when the vector is a reference column
The type of color to print :
"no": 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).
The object to test, to get a field in, or to modify.
The value you want to inject in some fmt vector's vctrs::field
or attribute using a given "set" function.
Used in methods to add arguments in the future.
By default, get_comp_all takes NA in comparison level
to be a FALSE (=comparison at subtables/groups level). Set to FALSE
to avoid this behavior.
A vector of class tabxplor_fmt.
A logical vector.
A double vector.
A modified fmt vector.
A character vector with the vectors type.
A modified fmt vector.
A logical vector with the fmt vectors totrow field.
A modified fmt vector with totrow field changed.
A logical vector with the fmt vectors tottab field.
A modified fmt vector with tottab field changed.
A logical vector with the fmt vectors totcol attribute.
A modified fmt vector with totcol attribute changed.
A logical vector with the fmt vectors in_refrow field
A modified fmt vector with in_refrom field changed.
A modified fmt vector with comp attribute changed.
A logical vector with the fmt vectors type attributes
A modified fmt vector.
A logical vector with the fmt vectors ci_type attributes
A modified fmt vector.
A logical vector with the fmt vectors col_var attributes
A modified fmt vector.
A logical vector with the fmt vectors is_refcol attributes
A modified fmt vector.
A logical vector with the fmt vectors color attributes
A modified fmt vector.
is_fmt: a test function for class fmt.
get_num: get the currently displayed field
set_num: set the currently displayed field (not changing display type)
get_type: get types of fmt columns (at fmt level or tab level)
set_type: set the column type attribute of a fmt vector
is_totrow: test function to detect cells in total rows
(at fmt level or tab level)
as_totrow: set the "in_totrow" field (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)
is_totcol: test function for total columns
(at fmt level or tab level)
as_totcol: set the "totcol" attribute of a fmt vector
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_comp_all: get comparison level of fmt columns
set_comp_all: set the comparison level attribute of a fmt vector
get_diff_type: get differences type of fmt columns (at fmt level or tab level)
set_diff_type: set the differences type attribute of a fmt vector
get_ci_type: get confidence intervals type of fmt columns (at fmt level or tab level)
set_ci_type: set the confidence intervals type attribute of a fmt vector
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
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)
set_color: set the "color" attribute of a fmt vector
get_digits: get the "digits" field
set_digits: set the "digits" field
# NOT RUN {
library(dplyr)
f <- fmt(n = c(7, 19, 2), type = "row", pct = c(0.25, 0.679, 0.07))
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 "type" attribute of a fmt vector :
set_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",
rare_to_other = TRUE, n_min = 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_num(forcats::gss_cat, race, c(age, tvhours), marital, digits = 1L, comp = "all") |>
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"
))
# }
Run the code above in your browser using DataLab