Skip to contents

Add a visualization to the collection

add_viz.Rd

Adds a single visualization specification to an existing collection. Visualizations with the same tabgroup value will be organized into tabs on the generated page. Supports nested tabsets through hierarchy notation.

Usage

add_viz(
  x,
  type = NULL,
  ...,
  tabgroup = NULL,
  title = NULL,
  title_tabset = NULL,
  text = NULL,
  icon = NULL,
  text_position = NULL,
  text_before_tabset = NULL,
  text_after_tabset = NULL,
  text_before_viz = NULL,
  text_after_viz = NULL,
  height = NULL,
  filter = NULL,
  data = NULL,
  drop_na_vars = FALSE,
  show_when = NULL
)

Arguments

x

A viz_collection or page_object to add visualization to

type

Visualization type: "stackedbar", "heatmap", "histogram", "timeline", "scatter", "bar"

...

Additional parameters passed to the visualization function

tabgroup

Optional group ID for organizing related visualizations. Supports:

  • Simple string: "demographics" for a single tab group

  • Slash notation: "demographics/details" or "demographics/details/regional" for nested tabs

  • Named numeric vector: c("1" = "demographics", "2" = "details", "3" = "regional") for explicit hierarchy

title

Display title for the visualization (shown above the chart)

title_tabset

Optional tab label. If NULL, uses title for the tab label. Use this when you want a short tab name but a longer, descriptive visualization title.

text

Optional markdown text to display above the visualization

icon

Optional iconify icon shortcode for the visualization

text_position

Position of text relative to visualization ("above" or "below")

text_before_tabset

Optional markdown text to display before the tabset

text_after_tabset

Optional markdown text to display after the tabset

text_before_viz

Optional markdown text to display before the visualization

text_after_viz

Optional markdown text to display after the visualization

height

Optional height in pixels for highcharter visualizations (numeric value)

filter

Optional filter expression to subset data for this visualization. Use formula syntax: ~ condition. Examples: ~ wave == 1, ~ age > 18, ~ wave %in% c(1, 2, 3)

data

Optional dataset name when using multiple datasets. Can be:

  • NULL: Uses default dataset (or only dataset if single)

  • String: Name of dataset from named list (e.g., "survey", "demographics")

drop_na_vars

Whether to drop NA values from variables (default FALSE)

show_when

Conditional display expression for sidebar-driven visibility

Value

The updated viz_collection object

Examples

if (FALSE) { # \dontrun{
# Simple tabgroup
page1_viz <- create_viz() %>%
  add_viz(type = "stackedbar", x_var = "education", stack_var = "gender",
          title = "Education by Gender", tabgroup = "demographics")

# Nested tabgroups using slash notation
page2_viz <- create_viz() %>%
  add_viz(type = "stackedbar", title = "Overview",
          tabgroup = "demographics") %>%
  add_viz(type = "stackedbar", title = "Details",
          tabgroup = "demographics/details")

# Nested tabgroups using named numeric vector
page3_viz <- create_viz() %>%
  add_viz(type = "stackedbar", title = "Regional Details",
          tabgroup = c("1" = "demographics", "2" = "details", "3" = "regional"))

# Filter data per visualization
page4_viz <- create_viz() %>%
  add_viz(type = "histogram", x_var = "response",
          title = "Wave 1", filter = ~ wave == 1) %>%
  add_viz(type = "histogram", x_var = "response",
          title = "Wave 2", filter = ~ wave == 2) %>%
  add_viz(type = "histogram", x_var = "response",
          title = "All Waves", filter = ~ wave %in% c(1, 2, 3))

# Multiple datasets
page5_viz <- create_viz() %>%
  add_viz(type = "histogram", x_var = "age", data = "demographics") %>%
  add_viz(type = "histogram", x_var = "response", data = "survey") %>%
  add_viz(type = "histogram", x_var = "outcome", data = "outcomes")

# Separate tab label from visualization title
page6_viz <- create_viz() %>%
  add_viz(
    type = "histogram",
    x_var = "age",
    tabgroup = "demographics",
    title_tabset = "Age",  # Short tab label
    title = "Age Distribution of Survey Respondents by Gender and Region"  # Long viz title
  )
} # }