tables_by_formulas: Tabular Statistics Based on Formulas

In SSBtools: Algorithms and Tools for Tabular Statistics and Hierarchical Computations

Tabular Statistics Based on Formulas

Description

This function acts as an overlay for functions that produce tabular statistics through an interface utilizing the ModelMatrix() function and its formula parameter. Each table (individual statistic) is defined by a formula. The output is a single data.frame that contains the results for all tables.

Usage

tables_by_formulas(
  data,
  table_fun,
  ...,
  table_formulas,
  substitute_vars = NULL,
  auto_collapse = TRUE,
  collapse_vars = NULL,
  total = "Total",
  hierarchical_extend0 = TRUE,
  term_labels = FALSE
)

Arguments

data	The input data to be processed by table_fun.
table_fun	The table-producing function to be used.
...	Additional arguments passed to table_fun.
table_formulas	A named list of formulas, where each entry defines a specific table.
substitute_vars	Allows formulas in table_formulas to be written in a simplified way. If substitute_vars is specified, the final formulas are generated using substitute_formula_vars() with substitute_vars as input.
auto_collapse	Logical. If TRUE, variables are collapsed using total_collapse() with the variables parameter according to substitute_vars.
collapse_vars	When specified, total_collapse() is called with collapse_vars as the variables parameter, after any call triggered by the auto_collapse parameter.
total	A string used to name totals. Passed to both table_fun and total_collapse().
hierarchical_extend0	Controls automatic hierarchy generation for Extend0(). See "Details" for more information.
term_labels	Logical. If TRUE, a term_labels column (as constructed by output_term_labels()) is included as the first column of the output.

Details

To ensure full control over the generated output variables, table_fun is called with avoid_hierarchical or avoidHierarchical set to TRUE. Desired variables in the output are achieved using substitute_vars, auto_collapse, and collapse_vars.

If table_fun automatically uses Extend0(), the parameter hierarchical_extend0 specifies the hierarchical parameter in Extend0() via Extend0fromModelMatrixInput(). When hierarchical_extend0 is TRUE, hierarchies are generated automatically. By default, it is set to TRUE, preventing excessive data extension and aligning with the default behavior of Formula2ModelMatrix(), where avoidHierarchical = FALSE.

An attribute table_formulas is added to formula before table_fun() is called. This attribute contains the version of table_formulas after applying substitute_vars. This allows for special use in the function table_fun().

Note: The use of total_collapse internally allows handling of variable names not present in the data. This ensures flexibility when modifying the table_formulas parameter.

Value

A single data.frame containing results for all tables defined in table_formulas.

See Also

filter_by_variable

Examples

tables_by_formulas(SSBtoolsData("magnitude1"),
                   table_fun = model_aggregate, 
                   table_formulas = list(table_1 = ~region * sector2, 
                                         table_2 = ~region1:sector4 - 1, 
                                         table_3 = ~region + sector4 - 1), 
                   substitute_vars = list(region = c("geo", "eu"), region1 = "eu"), 
                   collapse_vars = list(sector = c("sector2", "sector4")), 
                   sum_vars = "value", 
                   total = "T",
                   term_labels = TRUE)
                   

SSBtools documentation built on Nov. 5, 2025, 6:51 p.m.