fmt {tabxplor}

Create a vector of class formatted numbers

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

Usage

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)

Arguments

n

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

type

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

digits

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

display

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.

wn

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

pct

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

mean

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

diff

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.

ctr

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.

var

The cells variances, as a double vector the length of n. Used with type = "mean" to calculate confidence intervals. Calculate with tab_plain.

ci

The confidence intervals, as a double vector the length of n. Used to print colors ("diff_ci", "after_ci"). Calculate with tab_ci.

in_totrow

TRUE when the cell is part of a total row

in_tottab

TRUE when the cell is part of a total table

in_refrow

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

comp_all

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

diff_type

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)

ci_type

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

col_var

The name of the col_var used to calculate the vector

totcol

TRUE when the vector is a total column

refcol

TRUE when the vector is a reference column

color

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

x

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

value

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.

replace_na

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.

Value

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.

Functions

• 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

Examples

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