gbar: Bar chart

In R4VN: Health Data Analysis and Publication-Ready Reporting

Bar chart

Description

Draws counts, percentages, means, or medians by a categorical variable. An optional by variable creates grouped or stacked bars. The function uses base R graphics and accepts unquoted variable names. vars() can request several x variables. With by = vars(province, sex, outcome), province and sex are nested strata and outcome is the innermost in-graph grouping.

Usage

gbar(
  data = NULL, x = NULL, vars = NULL, y = NULL, by = NULL,
  stat = c("mean", "median"), percent = FALSE, position = c("dodge", "stack"),
  ci = FALSE, label = FALSE, digits = 1, xlab = NULL, ylab = NULL,
  xtitle = NULL, ytitle = NULL, ybreaks = NULL, title = NULL, subtitle = NULL,
  note = NULL, color = NULL, palette = "default", alpha = 1,
  border_color = NA, border_lwd = 1, legend = TRUE,
  legend_position = "topright", missing = FALSE, missing_label = "Missing",
  xline = NULL, yline = NULL, ref_color = "gray40", ref_lty = 2, ref_lwd = 1,
  theme = "journal", size = 11, combine = FALSE, ncol = NULL, file = NULL,
  width = 7, height = 5, dpi = 300, show = TRUE, bg = "white", vline = NULL,
  hline = NULL
)

Arguments

data	A data frame. It may be omitted when an active R4VN data frame exists.
x	Categorical variable on the horizontal axis. Supply an unquoted name or a character name.
vars	Optional vars(...) selector used to request several variables in one call.
y	Optional numeric variable. When omitted, bars show counts or percentages. When supplied, bars show a mean or median.
by	Optional grouping variable or hierarchical vars(...) specification.
stat	Summary for y: "mean" or "median".
percent	For count charts: FALSE for counts, TRUE or "x" for percentages within each x category, "by" for percentages within each by group, or "total" for percentages of all observations.
position	"dodge" for side-by-side bars or "stack" for stacked bars.
ci	Show a 95 percent confidence interval for mean bars. Only available when y is supplied and stat = "mean".
label	Add values above or inside bars.
digits	Number of digits in value labels.
xlab	Optional category labels. Use an unnamed vector in displayed order or a named vector such as c(M = "Male", F = "Female").
ylab	Optional y-axis tick labels.
xtitle, ytitle	Axis titles. Variable names or variable labels are used automatically when possible.
ybreaks	Numeric positions used with ylab.
title, subtitle, note	Main title, subtitle, and note.
color	A color name or vector of colors. When NULL, palette is used.
palette	One of "default", "journal", "blue", "green", "warm", "gray", or "colourblind"; alternatively, a color vector.
alpha	Color opacity from 0 to 1.
border_color, border_lwd	Bar-border colour and line width. Use NA for no border.
legend	Show the legend when by is supplied.
legend_position	Base-R legend position, for example "topright" or "topleft".
missing	Include missing x or by values as a category.
missing_label	Label used for missing values.
xline, yline	Optional numeric reference lines on the x and y axes. Thus xline draws vertical lines and yline draws horizontal lines.
ref_color, ref_lty, ref_lwd	Color, line type, and width for reference lines; vectors are recycled for multiple lines.
theme	Graph theme: "journal", "clean", "minimal", or "classic".
size	Base font size.
combine	When several graphs are produced, draw them as labelled panels in one figure.
ncol	Optional number of columns in a combined figure.
file	Optional output file ending in png, jpg, tiff, pdf, or svg.
width, height	Output width and height in inches.
dpi	Resolution for raster output.
show	Draw the graph in the current graphics device.
bg	Background color for exported files.
vline, hline	Deprecated aliases for xline and yline.

Value

An object of class r4vn_graph. Its data component contains the plotted summary.

Examples

d <- data.frame(
  sex = factor(c("Male", "Female", "Female", "Male", "Female")),
  hypertension = factor(c("No", "Yes", "No", "Yes", "No")),
  age = c(32, 45, 37, 51, 29)
)
gbar(d, x = sex)
gbar(d, x = sex, by = hypertension, percent = "x")
gbar(d, x = sex, y = age, ci = TRUE, ytitle = "Mean age")

# Extended usage examples

d <- data.frame(sex = factor(c("Male", "Female", "Female", "Male", "Female")),
                outcome = factor(c("No", "Yes", "No", "Yes", "No")),
                age = c(32, 45, 37, 51, 29))
gbar(d, x = sex, show = FALSE)
gbar(d, x = sex, percent = TRUE, label = TRUE, show = FALSE)
gbar(d, x = sex, by = outcome, percent = "x", position = "dodge", show = FALSE)
gbar(d, x = sex, by = outcome, percent = "total", position = "stack", show = FALSE)
gbar(d, x = sex, y = age, stat = "mean", ci = TRUE, show = FALSE)
gbar(d, x = sex, y = age, stat = "median", show = FALSE)
gbar(d, x = sex, title = "Participants by sex", palette = "journal", show = FALSE)
f <- tempfile(fileext = ".png")
gbar(d, x = sex, file = f, show = FALSE)

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.