Package 'tabstats'

Style specification for corr_matrix()

Description

Constructs a validated style object for use with corr_matrix().

Usage

cm_style(...)

Arguments

...	Named style entries. Names should match the extra field names passed to new_corr_data() (e.g. rho, pval, bf), or the reserved keys title and border_text.

Value

An object of class c("cm_style", "tabstats_style").

Examples

cm_style(rho = "blue_bold", pval = "red", title = "bold")
cm_style(rho = \(x) cli::col_cyan(x))

---

Generate and Display a Cross Tabulation Table

Description

Generate and Display a Cross Tabulation Table

Usage

cross_table(
  data,
  percentage = NULL,
  layout = TRUE,
  expected = TRUE,
  layout_center = FALSE,
  header_underline = FALSE,
  digits = NULL,
  center_table = FALSE,
  style = NULL,
  ...
)

Arguments

data	A matrix or table of observed frequencies.
percentage	Which percentages to show. Options: TRUE/"all", "by_row", "by_col", "by_total", FALSE/NULL.
layout	Show layout legend box? Default TRUE.
expected	Show expected frequencies? Default TRUE.
layout_center	Center the layout box? Default FALSE.
header_underline	Shorten the underline beneath the column header? Default FALSE.
digits	Named list with keys ex, row_pct, col_pct, total_pct. Falls back to getOption("ct_digits").
center_table	Center entire table in terminal? Default FALSE.
style	Named list supplied using ct_style().
...	Reserved for future use.

Value

Invisibly returns the formatted cross-tabulation matrix.

Examples

cross_table(matrix(c(10, 20, 30, 40), nrow = 2))
cross_table(matrix(c(10, 20, 30, 40), nrow = 2), percentage = "all")

---

Style specification for cross_table()

Description

Constructs a validated style object for use with cross_table().

Usage

ct_style(
  observed = NULL,
  expected = NULL,
  row_percentage = NULL,
  col_percentage = NULL,
  total_percentage = NULL,
  total = NULL,
  title = NULL,
  border_text = NULL
)

Arguments

observed	Style for observed frequency cells.
expected	Style for expected frequency values.
row_percentage	Style for row percentage values.
col_percentage	Style for column percentage values.
total_percentage	Style for grand total percentage values.
total	Style for total row/column cells.
title	Style for the table title.
border_text	Style for the horizontal border lines.

Value

An object of class c("ct_style", "tabstats_style").

Examples

ct_style(observed = "blue", expected = "yellow", title = "bold")
ct_style(observed = \(ctx) cli::col_green(ctx$formatted_text))

---

Build a pairwise matrix display specification

Description

Constructs a structured spec object consumed by pairwise_matrix(). Always requires var1 and var2 — the pair pattern they encode determines which triangle(s) of the matrix are filled:

Usage

new_pairwise_data(var1, var2, ...)

new_corr_data(var1, var2, ...)

Arguments

var1	Character vector of first variable names per pair.
var2	Character vector of second variable names per pair.
...	Named character vectors of equal length to var1/var2. Each becomes one display row inside the cell (e.g. rho, pval, bf).

Details

Pattern	Fills
var1 < var2	Lower triangle only
var1 <= var2	Lower triangle + diagonal
var1 > var2	Upper triangle only
var1 >= var2	Upper triangle + diagonal
var1 != var2	Both triangles, no diagonal
var1 == var2	Full matrix (diag forced to 1)

All additional named vectors become display rows inside each cell, rendered in the order they are supplied.

Value

An object of class pairwise_spec.

Examples

new_pairwise_data(
    var1 = c("a", "a", "b"),
    var2 = c("b", "c", "c"),
    rho = c("0.89", "0.79", "0.66"),
    pval = c("<0.001", "<0.001", "<0.001")
)

---

Display a Pairwise Matrix Table in the Console

Description

Display a Pairwise Matrix Table in the Console

Usage

pairwise_matrix(
  display,
  title = NULL,
  name = "Pairwise Matrix",
  diag_1 = TRUE,
  digits = 3,
  layout_view = FALSE,
  layout_center = FALSE,
  center_table = FALSE,
  border_char = getOption("tab_default")$border_char,
  style = list(),
  ...
)

corr_matrix(
  display,
  title = NULL,
  diag_1 = TRUE,
  digits = 3,
  layout_view = FALSE,
  layout_center = FALSE,
  center_table = FALSE,
  border_char = getOption("tab_default")$border_char,
  style = list(),
  ...
)

Arguments

display	A pairwise_spec object from new_pairwise_data(), or a plain symmetric matrix (e.g. from cor()).
title	Label shown above the table. Auto-detected from a title attribute on the spec if present; falls back to name.
name	Short name used in the layout legend box header. Default "Pairwise Matrix".
diag_1	If TRUE, diagonal cells always show "1". Default TRUE.
digits	Decimal places for numeric formatting. Default 3.
layout_view	Show a layout legend box above the table? Default FALSE.
layout_center	Center the layout box in the terminal? Default FALSE.
center_table	Center table in terminal? Default FALSE.
border_char	Border character. Default from getOption("tab_default").
style	A style list. Keys match the extra field names passed to new_pairwise_data() (e.g. rho, pval, bf), plus title and border_text.
...	Reserved for future use.

Value

Invisibly returns the rendered character matrix.

Examples

# From a plain correlation matrix
pairwise_matrix(cor(mtcars[, 1:4]), title = "Pearson Correlation Matrix")

# Customizable example
spec = new_pairwise_data(
    var1 = c("a", "a", "b"),
    var2 = c("b", "c", "c"),
    rho = c("0.89", "0.79", "0.66"),
    pval = c("<0.001", "<0.001", "<0.001")
)
pairwise_matrix(spec, title = "Pearson Correlation Matrix", layout_view = TRUE)

---

Style specification for table_summary()

Description

Constructs a validated style object for use with table_summary().

Usage

sm_style(
  left_col = NULL,
  right_col = NULL,
  border_text = NULL,
  title = NULL,
  sep = NULL
)

Arguments

left_col	Style for the left column. A string (e.g. "blue_bold") or a function ⁠\(x) ...⁠.
right_col	Style for the right column.
border_text	Style for the horizontal border lines.
title	Style for the title text.
sep	A single character used as the column separator (e.g. "|").

Value

An object of class c("sm_style", "tabstats_style").

Examples

sm_style(left_col = "blue_bold", right_col = "green", title = "bold")
sm_style(left_col = \(x) cli::col_red(x), sep = "|")

---

Display a formatted table in the console

Description

Display a formatted table in the console

Usage

table_default(
  x,
  justify_cols = "center",
  digits = 3,
  digits_by_col = NULL,
  scientific = FALSE,
  na_print = "",
  min_width = NULL,
  border_char = options("tab_default")$tab_default$border_char,
  show_row_names = FALSE,
  center_table = FALSE,
  n_space = 2,
  title = NULL,
  style_colnames = NULL,
  style_columns = NULL,
  nrows = getOption("tab_default")$nrows,
  vb = list(),
  auto_wrap = TRUE,
  wrap_threshold = 1,
  ...
)

Arguments

x	A data frame or tibble.
justify_cols	Alignment: a single string, vector, or named list of "left"/"right"/"center".
digits	Digits to round numeric columns to. Default 3.
digits_by_col	Named list of per-column digit overrides.
scientific	Display numerics in scientific notation? Default FALSE.
na_print	String for missing values. Default "".
min_width	Minimum column width. Default NULL.
border_char	Character for borders. Default "\u2500".
show_row_names	Show row names? Default FALSE.
center_table	Center table in terminal? Default FALSE.
n_space	Spaces between columns. Default 2.
title	Optional title string above the table. from td_style(), or a named list where each name is a column name or "title", and each value is either a cli style string (e.g. "blue_bold") or a function ⁠\(ctx) ...⁠ receiving a context list.
style_colnames	Styling for column header cells. A td_style object from td_style(), or a named list where each name is a column name or "title", and each value is either a cli style string (e.g. "blue_bold") or a function ⁠\(ctx) ...⁠ receiving a context list.
style_columns	Styling for data cells. A td_style object from td_style(), or a named list where each name is a column name or column index as a string, and each value is a cli style string or a function ⁠\(ctx) ...⁠ receiving a context list with elements value, formatted_value, col_name, col_index, is_header, data, justify, and width.
nrows	Max rows to display before truncation.
vb	Vertical border spec: list(char = "\u2502", after = c(1, 3)).
auto_wrap	Auto-wrap wide tables? Default TRUE.
wrap_threshold	Fraction of console width before wrapping. Default 1.
...	Reserved for future use.

Value

Invisibly returns the input data as a character matrix after formatting has been applied. The function is called primarily for its side effect of printing a styled table to the R console. Returns invisible(NULL) early if the input has 0 rows and 0 columns, or if it has 0 columns.

Examples

table_default(head(mtcars))
table_default(head(mtcars), style_columns = td_style(mpg = "cyan", cyl = "magenta"))

---

Summarize and Display a Two-Column Data Frame as a Formatted Table

Description

This function takes a two-column data frame and formats it into a summary-like table. The table can be optionally split into two parts, centered, and given a title. It is useful for displaying summary information in a clean, tabular format. The function also supports styling with ANSI colors and text formatting through the {cli} package and column alignment options.

Usage

table_summary(
  data,
  title = NULL,
  l = NULL,
  header = FALSE,
  center_table = FALSE,
  border_char = "-",
  style = list(),
  align = NULL,
  ...
)

Arguments

data	A data frame with exactly two columns. The data to be summarized and displayed.
title	A character string. An optional title to be displayed above the table.
l	An integer. The number of rows to include in the left part of a split table. If NULL, the table is not split.
header	A logical value. If TRUE, the column names of data are displayed as a header.
center_table	A logical value. If TRUE, the table is centered in the terminal.
border_char	Character used for borders. Default is "\u2500".
style	A list controlling the visual styling of table elements using ANSI formatting. Can include the following components: left_col: Styling for the left column values. right_col: Styling for the right column values. border_text: Styling for the border. title: Styling for the title. sep: Separator character between left and right column. Each style component can be either a predefined style string (e.g., "blue", "red_italic", "bold") or a function that takes a context list with/without a value element and returns the styled text.
align	Controls the alignment of column values. Can be specified in three ways: A single string: affects only the left column (e.g., "left", "center", "right"). A vector of two strings: affects both columns in order (e.g., c("left", "right")). A list with named components: explicitly specifies alignment for each column
...	Additional arguments (currently unused).

Value

This function does not return a value. It prints the formatted table to the console.

Examples

# Create a sample data frame
df = data.frame(
    Category = c("A", "B", "C", "D", "E"),
    Value = c(10, 20, 30, 40, 50)
)

# Display the table with a title and header
table_summary(df, title = "Sample Table", header = TRUE)

# Split the table after the second row and center it
table_summary(df, l = 2, center_table = TRUE)

# Use styling and alignment
table_summary(
    df,
    header = TRUE,
    style = list(
        left_col = "blue_bold",
        right_col = "red",
        title = "green",
        border_text = "yellow"
    ),
    align = c("center", "right")
)

# Use custom styling with lambda functions
table_summary(
    df,
    header = TRUE,
    style = sm_style(
        left_col = \(ctx) cli::col_red(ctx), # ctx$value is another option
        right_col = \(ctx) cli::col_blue(ctx)
    ),
    align = list(left_col = "left", right_col = "right")
)

---

Manage package options

Description

This function allows retrieving or modifying the package options across different categories. If called without arguments, it returns all option categories and their values. If category is provided alone, it returns all options in that category. If category and option are provided, it returns the specific option value. If all three parameters are provided, it updates the specified option.

Usage

tabstats_options(category = NULL, option = NULL, value = NULL)

Arguments

category	A character string specifying the option category (e.g., "tab_default", "tab_digits"). If omitted, returns all option categories.
option	A character string specifying the option to retrieve or modify within the category. For backward compatibility, you can also use a specific option name directly as the category parameter.
value	The new value to assign to the specified option. If NULL, the function returns the current value.

Value

If no arguments are provided, returns all option categories and their values. If only category is provided, returns all options in that category. If category and option are provided without value, returns the current value of that option. If all parameters are provided, updates the option and returns the updated option category list invisibly.

Examples

# Get all options across all categories
tabstats_options()

# Get all options in the "tab_default" category
tabstats_options("tab_default")

# Get all options in the "tab_digits" category
tabstats_options("tab_digits")

# Get a specific option
tabstats_options("tab_default", "vb_top")
tabstats_options("tab_digits", "ex")

# Using backward compatibility (system will find the right category)
tabstats_options("vb_top")
tabstats_options("ex")

# Modify an option
tabstats_options("tab_default", "border_char", "+")
tabstats_options("tab_digits", "ex", 2)

# Using backward compatibility for modification
tabstats_options("border_char", "+")
tabstats_options("ex", 2)

---

Style specification for table_default()

Description

Constructs a validated style object for use with table_default().

Usage

td_style(...)

Arguments

...	Named style entries. Each name must be a column name, a column index as a string (e.g. "1"), or "title". Each value is a string or a function ⁠\(ctx) ...⁠ where ctx is a context list.

Value

An object of class c("td_style", "tabstats_style").

Examples

td_style(mpg = "cyan", cyl = "magenta")
td_style(mpg = \(ctx) cli::col_red(ctx$value), title = "bold")

---