Skip to contents

Build a formatted ASCII table

Source: R/tables_ascii.R
build_ascii_table.Rd

Low-level rendering engine that constructs a visually aligned ASCII table from a data.frame. Supports Unicode line-drawing characters, ANSI colors via crayon, automatic colored-text-aware width detection, configurable padding, and per-column alignment.

Usage

build_ascii_table(
  x,
  padding = 2L,
  first_column_line = TRUE,
  row_total_line = TRUE,
  column_total_line = TRUE,
  bottom_line = FALSE,
  lines_color = "darkgrey",
  align_left_cols = c(1L, 2L),
  align_center_cols = integer(0),
  center_headers = FALSE,
  spanners = NULL,
  group_sep_rows = integer(0),
  total_row_idx = NULL,
  display_labels = NULL,
  ...
)

Arguments

x

A data.frame or spicy_table object containing the table to format. Typically, this includes columns such as Category, Values, Freq., Percent, etc.

padding

Non-negative integer giving the number of extra characters added to each column's auto-computed width (the maximum of the cell-content width and the header width). Defaults to 2L, which gives a Stata- / cli-like compact look. Each cell additionally receives a one-space gutter on each side, so a padding = 2L column whose content is at most 5 characters wide occupies 9 characters in total (1 + 5 + 2 + 1).

The string choices "compact", "normal" and "wide" from spicy < 0.11.0 were removed; pass 0L, 2L or 4L instead. Passing a string raises an actionable error.

first_column_line

Logical. If TRUE (the default), a vertical separator is drawn after the first column (useful for separating categories from data).

row_total_line, column_total_line

Logical. Control horizontal rules before total rows or columns. Both default to TRUE.

bottom_line

Logical. If FALSE (the default), no closing line is drawn. If TRUE, draws a closing line at the bottom of the table.

lines_color

Character. Color used for table separators. Defaults to "darkgrey". The color is applied only when ANSI color support is available (see crayon::has_color()).

align_left_cols

Integer vector of column indices to left-align. Defaults to c(1L, 2L) (the layout used by freq()-style tables); pass an explicit vector for other layouts.

align_center_cols

Integer vector of column indices to center-align. Defaults to integer(0) (no centered columns). Columns not in align_left_cols or align_center_cols are right-aligned.

center_headers

Logical. When TRUE, column headers are centered above their column content even when the data itself is right-aligned (the publication convention for coefficient / summary tables; matches Stata regress and SPSS REGRESSION output). Left-aligned columns (per align_left_cols) keep their header on the left. Defaults to FALSE for backward compatibility; the print.spicy_regression_table method enables it.

spanners

Optional named list defining a column group row drawn above the column headers (the "spanner" / "supra-header" convention; APA Manual 7 §7.13). Names are spanner labels; values are integer vectors of 1-based column indices the label spans (must be contiguous). A thin underline rule is drawn below each spanner across its span. Used by print.spicy_regression_table() to display the model name above each model's block of sub-columns. Defaults to NULL (no spanner row).

group_sep_rows

Integer vector of row indices before which a light dashed separator line is drawn. Defaults to integer(0).

total_row_idx

Optional integer vector of 1-based row indices identifying the totals rows; a horizontal rule is drawn just before each. When NULL (the default), falls back to a regex match on "Total" / "Column_Total" in the formatted row text, which can mis-fire if a user category is literally named "Total" or "Sub-Total". Cross-tabs and frequency tables built by cross_tab() and freq() set this attribute on their result so the print methods are immune to that false positive.

display_labels

Optional character vector of length ncol(x) used to override colnames(x) for the rendered header row only. The data.frame's actual names are kept for indexing; only the visual header is swapped. Used by print.spicy_regression_table() so a B + AME table shows the bare label (95% CI, p) in both blocks rather than R's deduplicated 95% CI.2 / p.2. Defaults to NULL (use colnames(x) verbatim).

...

Additional arguments (currently ignored).

Value

A single character string containing the full ASCII-formatted table, suitable for direct printing with cat().

Details

Most users should not call this directly: it is wrapped by spicy_print_table() and the internal print.spicy_* methods, which add titles, notes, and table-type-aware alignment defaults. Reach for build_ascii_table() only when you need to render an arbitrary data.frame to a string with the same look as spicy's tables.

See also

spicy_print_table() for a user-facing wrapper that adds titles and notes.

Examples

# Internal usage example (for developers)
df <- data.frame(
  Category = c("Valid", "", "Missing", "Total"),
  Values = c("Yes", "No", "NA", ""),
  Freq. = c(12, 8, 1, 21),
  Percent = c(57.1, 38.1, 4.8, 100.0)
)

cat(build_ascii_table(df, padding = 0L))
#>  Category │ Values  Freq.  Percent 
#> ──────────┼────────────────────────
#>  Valid    │ Yes        12     57.1 
#>           │ No          8     38.1 
#>  Missing  │ NA          1      4.8 
#> ──────────┼────────────────────────
#>  Total    │            21      100