Column functions for defining table columns in tabviz.

Basic Columns

col_text

Text column for displaying character data.

col_text(field, header = NULL, width = NULL)
Argument Description
field Column name in data
header Display header (defaults to field name)
width Column width in pixels

col_numeric

Numeric column with automatic formatting, significant figures support, and large number abbreviation.

col_numeric(field, header = NULL, width = NULL,
            decimals = 2, digits = NULL, abbreviate = FALSE)
Argument Description
field Column name in data
header Display header
width Column width in pixels
decimals Fixed decimal places (default: 2)
digits Significant figures (overrides decimals if set)
abbreviate Abbreviate large numbers with K/M/B suffixes

Examples:

# Fixed 2 decimal places (default)
col_numeric("value")

# Significant figures instead
col_numeric("value", digits = 3)

# Abbreviate large numbers: 1,234,567 → "1.2M"
col_numeric("population", abbreviate = TRUE)

col_interval

Confidence interval display showing point estimate with bounds.

col_interval(point, lower, upper, header = "95% CI", width = 160,
             decimals = 2, sep = " ", imprecise_threshold = NULL)
Argument Description
point Field name for point estimate (required)
lower Field name for lower bound (required)
upper Field name for upper bound (required)
header Column header (default: “95% CI”)
width Column width in pixels (default: 160)
decimals Decimal places for formatting (default: 2)
sep Separator between point and CI (default: ” “)
imprecise_threshold When upper/lower ratio exceeds this threshold, display “—” instead

Examples:

# Default formatting
col_interval(point = "hr", lower = "lower", upper = "upper")

# Custom header and formatting
col_interval(point = "hr", lower = "lower", upper = "upper",
             header = "HR (95% CI)", decimals = 1, sep = ", ")

# Show alternative effect from different columns
col_interval(point = "pp_hr", lower = "pp_lower", upper = "pp_upper",
             header = "Per-Protocol")

# Hide imprecise estimates where CI ratio > 10
col_interval(point = "hr", lower = "lower", upper = "upper",
             imprecise_threshold = 10)

Focal Visualization Columns (viz_*)

Focal visualization columns have their own axes and scales, designed for direct visual comparison across rows.

viz_forest

Forest plot column showing point estimates with confidence intervals.

viz_forest(
  point = NULL, lower = NULL, upper = NULL,
  effects = NULL,
  header = NULL, width = 200,
  scale = "linear", null_value = NULL,
  axis_label = NULL, axis_range = NULL, axis_ticks = NULL, axis_gridlines = FALSE,
  annotations = NULL
)
Argument Description
point Column name for point estimates (single effect mode)
lower Column name for lower CI bounds (single effect mode)
upper Column name for upper CI bounds (single effect mode)
effects List of effect_forest() objects (multi-effect mode)
header Column header text
width Column width in pixels (default: 200)
scale "linear" or "log"
null_value Reference line value (typically 0 for linear, 1 for log)
axis_label Label text below the axis
axis_range Fixed range as c(min, max)
axis_ticks Custom tick positions
axis_gridlines Show vertical gridlines
annotations List of refline() objects

viz_bar

Horizontal bar chart with shared axis for comparing values across rows.

viz_bar(
  effects,
  header = NULL, width = 150,
  scale = "linear",
  axis_range = NULL, axis_ticks = NULL, axis_gridlines = FALSE,
  axis_label = "Value", show_axis = TRUE
)
Argument Description
effects List of effect_bar() objects
header Column header text
width Column width in pixels (default: 150)
scale "linear" or "log"
axis_range Fixed axis range as c(min, max)
axis_ticks Custom tick positions
axis_gridlines Show vertical gridlines (default: FALSE)
axis_label Label text below axis (default: “Value”)
show_axis Show the axis (default: TRUE)

Effect helper:

effect_bar(value, label = NULL, color = NULL, opacity = 0.85)

viz_boxplot

Box-and-whisker plot showing median, quartiles, and outliers.

viz_boxplot(
  effects,
  header = NULL, width = 150,
  scale = "linear",
  axis_range = NULL, axis_ticks = NULL, axis_gridlines = FALSE,
  show_outliers = TRUE, whisker_type = "iqr",
  axis_label = "Value", show_axis = TRUE
)
Argument Description
effects List of effect_boxplot() objects
header Column header text
width Column width in pixels (default: 150)
scale "linear" or "log"
axis_range Fixed axis range as c(min, max)
axis_ticks Custom tick positions
axis_gridlines Show vertical gridlines (default: FALSE)
show_outliers Show outlier points (default: TRUE)
whisker_type "iqr" (1.5×IQR) or "minmax" (default: “iqr”)
axis_label Label text below axis (default: “Value”)
show_axis Show the axis (default: TRUE)

Effect helper (two modes):

# Mode 1: From array data (auto-compute stats)
effect_boxplot(data = "values_column", label = NULL, color = NULL, fill_opacity = 0.7)

# Mode 2: From pre-computed summary stats
effect_boxplot(min = "min_col", q1 = "q1_col", median = "med_col",
                   q3 = "q3_col", max = "max_col", outliers = "outliers_col",
                   label = NULL, color = NULL, fill_opacity = 0.7)

viz_violin

Violin plot showing distribution shape via kernel density estimation.

viz_violin(
  effects,
  header = NULL, width = 150,
  scale = "linear",
  axis_range = NULL, axis_ticks = NULL, axis_gridlines = FALSE,
  bandwidth = NULL, show_median = TRUE, show_quartiles = FALSE,
  axis_label = "Value", show_axis = TRUE
)
Argument Description
effects List of effect_violin() objects
header Column header text
width Column width in pixels (default: 150)
scale "linear" or "log"
axis_range Fixed axis range as c(min, max)
axis_ticks Custom tick positions
axis_gridlines Show vertical gridlines (default: FALSE)
bandwidth KDE bandwidth (NULL = auto via Silverman’s rule)
show_median Show median line (default: TRUE)
show_quartiles Show Q1/Q3 dashed lines (default: FALSE)
axis_label Label text below axis (default: “Value”)
show_axis Show the axis (default: TRUE)

Effect helper:

effect_violin(data, label = NULL, color = NULL, fill_opacity = 0.5)

Inline Visualization Columns

col_bar

Simple horizontal bar chart for showing magnitude (inline, no shared axis).

col_bar(
  field,
  header = NULL,
  width = NULL,
  max_value = NULL,
  show_label = TRUE,
  color = NULL
)
Argument Description
field Column name containing numeric values
header Column header
width Column width in pixels
max_value Maximum value for scaling (auto if NULL)
show_label Show value label (default: TRUE)
color Bar color

col_pvalue

P-value column with optional significance stars and smart formatting. Very small values are displayed using Unicode superscript notation (e.g., 1.2×10⁻⁵) for improved readability.

col_pvalue(
  field = "pvalue",
  header = "P-value",
  stars = TRUE,
  thresholds = c(0.05, 0.01, 0.001),
  format = c("auto", "scientific", "decimal"),
  digits = 2,
  exp_threshold = 0.001,
  abbrev_threshold = NULL,
  width = 100
)
Argument Description
field Column name containing p-values
header Column header (default: “P-value”)
stars Show significance stars (default: FALSE)
thresholds Numeric vector of 3 significance thresholds (default: c(0.05, 0.01, 0.001))
format Display format: "auto", "scientific", or "decimal"
digits Number of significant figures (default: 2)
exp_threshold Values below this use exponential notation (default: 0.001)
abbrev_threshold Values below this display as “<threshold” (e.g., “<0.0001”)
width Column width in pixels (default: 100)

Formatting behavior:

  • Values ≥ exp_threshold: displayed as decimal (e.g., 0.042)
  • Values < exp_threshold: displayed with Unicode superscript (e.g., 2.3×10⁻⁴)
  • Values < abbrev_threshold: displayed as “<threshold” (e.g., “<0.0001”)

Significance levels (when stars = TRUE):

  • * p < 0.05
  • ** p < 0.01
  • *** p < 0.001

Examples:

# Default: 2 significant figures, exponential below 0.001
col_pvalue("pval")

# More precision
col_pvalue("pval", digits = 3)

# Use exponential notation earlier (below 0.01)
col_pvalue("pval", exp_threshold = 0.01)

# Show very small values as "<0.0001"
col_pvalue("pval", abbrev_threshold = 0.0001)

# With significance stars
col_pvalue("pval", stars = TRUE)

col_sparkline

Inline sparkline chart for trend visualization.

col_sparkline(field, header = NULL, width = 80, type = "line")
Argument Description
field Column name containing numeric vector
header Column header
width Column width (default: 80)
type "line", "bar", or "area"

Note: The field should contain list-columns with numeric vectors.

col_n

Sample size column with optional abbreviation for large values.

col_n(field = "n", header = "N", width = NULL,
      digits = NULL, decimals = 0, abbreviate = FALSE)
Argument Description
field Column name (default: “n”)
header Column header (default: “N”)
width Column width (NULL = auto)
digits Significant figures (optional, mutually exclusive with decimals)
decimals Fixed decimal places (default: 0)
abbreviate Abbreviate large values with K/M suffixes

Examples:

# Default display
col_n("sample_size")

# Abbreviate large sample sizes: 10,500 → "10.5K"
col_n("sample_size", abbreviate = TRUE)

col_percent

Percentage column for displaying proportions.

col_percent(field, header = NULL, width = NULL,
            decimals = 1, digits = NULL, multiply = TRUE, symbol = TRUE)
Argument Description
field Column name containing values
header Column header
width Column width (NULL = auto)
decimals Fixed decimal places (default: 1, mutually exclusive with digits)
digits Significant figures (optional)
multiply Multiply by 100 (default: TRUE, expects 0-1 proportions)
symbol Show % symbol (default: TRUE)

Examples:

# Proportion 0-1 → percentage: 0.25 → "25.0%"
col_percent("rate")

# Already a percentage (0-100): 25 → "25.0%"
col_percent("pct", multiply = FALSE)

# Significant figures instead of fixed decimals
col_percent("rate", digits = 2)

col_events

Events column showing “events/n” format for clinical data.

col_events(events_field, n_field, header = "Events",
           width = NULL, separator = "/", show_pct = FALSE,
           abbreviate = FALSE)
Argument Description
events_field Column name for event count
n_field Column name for total N
header Column header (default: “Events”)
width Column width (NULL = auto)
separator Separator between events and N (default: “/”)
show_pct Show percentage after (default: FALSE)
abbreviate Abbreviate large numbers

Examples:

# Basic: "45/120"
col_events("events", "n")

# With percentage: "45/120 (37.5%)"
col_events("events", "n", show_pct = TRUE)

col_icon

Icon column for displaying emoji or unicode symbols.

col_icon(field, header = NULL, width = NULL, mapping = NULL)
Argument Description
field Column name containing values to map
header Column header
width Column width (NULL = auto)
mapping Named list mapping values to icons

Example:

col_icon("status", mapping = list(
  "success" = "✓",
  "failure" = "✗",
  "pending" = "○"
))

col_badge

Badge column for colored status labels.

col_badge(field, header = NULL, width = NULL, variant = "default")
Argument Description
field Column name containing badge text
header Column header
width Column width (NULL = auto)
variant "default", "success", "warning", "error", "info", "muted"

col_stars

Star rating column (1-5 scale).

col_stars(field, header = NULL, width = NULL, max_stars = 5, color = NULL)
Argument Description
field Column name containing numeric rating
header Column header
width Column width (NULL = auto)
max_stars Maximum stars (default: 5)
color Star color

col_img

Image column for inline images from URLs.

col_img(field, header = NULL, width = NULL, shape = "square")
Argument Description
field Column name containing image URLs
header Column header
width Column width (NULL = auto)
shape "square", "circle", or "rounded"

col_reference

Reference column for DOIs, citations, or links with truncation.

col_reference(field, header = NULL, width = NULL, href_field = NULL)
Argument Description
field Column name containing reference text
header Column header
width Column width (NULL = auto)
href_field Column name containing URLs for links

col_range

Range column showing min-max values.

col_range(min_field, max_field, header = NULL, width = NULL, separator = " – ")
Argument Description
min_field Column name for minimum value
max_field Column name for maximum value
header Column header
width Column width (NULL = auto)
separator Separator between values (default: ” – “)

Example:

# Age range: "18 – 65"
col_range("age_min", "age_max", header = "Age Range")

Cell-Level Styling

All col_*() functions support per-cell styling through these optional parameters:

Parameter Type Description
bold Column name or formula Bold text when TRUE
italic Column name or formula Italic text when TRUE
color Column name or formula Text color (CSS color string)
bg Column name or formula Background color (CSS color string)
badge Column name or formula Badge label
icon Column name or formula Emoji/unicode icon
emphasis Column name or formula Theme-aware emphasis styling
muted Column name or formula Theme-aware muted styling
accent Column name or formula Theme-aware accent styling

Formula Expressions with .x

Style parameters accept formula expressions that are evaluated per row. Use .x to reference the column’s own values:

Code 
# Bold p-values below 0.05
col_pvalue("pval", bold = ~ .x < 0.05)

# Color HR values based on direction
col_numeric("hr", "HR",
  color = ~ ifelse(.x < 1, "#16a34a", "#dc2626")
)

# Complex conditional styling
col_numeric("change", "% Change",
  color = ~ case_when(
    .x < -10 ~ "#16a34a",  # Strong improvement
    .x > 5 ~ "#dc2626",    # Worsening
    TRUE ~ "#71717a"       # Neutral
  )
)

Referencing Other Columns

Formulas can also reference other columns in your data:

Code 
# Color HR based on significance
col_numeric("hr", "HR",
  color = ~ ifelse(pval < 0.05, "#16a34a", "#71717a")
)

# Bold based on combined conditions
col_interval(point = "hr", lower = "lower", upper = "upper",
  bold = ~ pval < 0.05 & hr < 1
)

Column Name vs Formula

You can use either approach:

Code 
# Column name approach (requires pre-computed column)
data <- data |> mutate(is_sig = pval < 0.05)
col_pvalue("pval", bold = "is_sig")

# Formula approach (computed on the fly)
col_pvalue("pval", bold = ~ .x < 0.05)
Approach Best For
Formulas Simple conditions, self-referential logic
Column names Complex logic, reused across multiple columns

Column Groups

col_group

Group multiple columns under a shared header.

col_group(header, ...)
Argument Description
header Group header text
... Column specifications to group

Examples

Mixed Column Types

Code 
data <- data.frame(
  study = c("Trial A", "Trial B", "Trial C"),
  hr = c(0.72, 0.85, 0.68),
  lower = c(0.55, 0.70, 0.52),
  upper = c(0.95, 1.03, 0.89),
  n = c(245, 180, 320),
  weight = c(35, 28, 37),
  pval = c(0.018, 0.092, 0.003)
)

tabviz(data,
  label = "study",
  columns = list(
    col_n("n"),
    col_bar("weight"),
    viz_forest(point = "hr", lower = "lower", upper = "upper",
               scale = "log", null_value = 1),
    col_interval("HR (95% CI)", point = "hr", lower = "lower", upper = "upper"),
    col_pvalue("pval")
  )
)

Column Groups

Code 
columns = list(
  col_n("n"),
  col_group("Treatment Effect",
    col_numeric("hr", "HR"),
    col_interval("95% CI", point = "hr", lower = "lower", upper = "upper")
  ),
  col_pvalue("pval")
)

Fluent Column Styling

set_column_style

Apply per-cell styling to a column after spec creation. See Customizing Plots guide.

spec |> set_column_style(column, bold = NULL, italic = NULL, color = NULL, bg = NULL, badge = NULL, icon = NULL)
Argument Description
column Field name of the column to style
bold Column name or formula for bold text
italic Column name or formula for italic text
color Column name or formula for text color
bg Column name or formula for background color
badge Column name or formula for badge text
icon Column name or formula for icon

Examples:

Code 
# Using formula expressions
tabviz(data,
  label = "study",
  columns = list(col_pvalue("pval"))
) |>
  set_column_style("pval",
    bold = ~ .x < 0.05,
    color = ~ ifelse(.x < 0.05, "#16a34a", "#71717a")
  )

See Also