hd: Initialise a Composable highdir Figure

In highdir: Unified Data Visualization Framework for Dynamic and Static Graphics

Initialise a Composable highdir Figure

Description

Creates an hd object that accumulates geometry and presentation layers via +, then renders when printed. This mirrors the way ggplot2 builds plots: data mapping is declared first; visual decisions are added incrementally; nothing is rendered until the object hits the console (or an explicit print() / knit call).

Usage

hd(
  data = NULL,
  x = NULL,
  y = NULL,
  group = NULL,
  n = NULL,
  colour = NULL,
  mode = NULL,
  backend = lifecycle::deprecated()
)

Arguments

data	A data.frame or an hd_spec() object. When an hd_spec is supplied every other mapping argument (x, y, …) is ignored - the spec carries them already. Default is NULL, which creates an empty data.frame.
x	Character. Column name for the x-axis variable. Ignored when data is an hd_spec.
y	Character. Column name for the y-axis variable. Ignored when data is an hd_spec.
group	Character or NULL. Column used to split data into multiple series. Ignored when data is an hd_spec.
n	Character or NULL. Column of raw counts shown in highcharter tooltips alongside the y value. Ignored when data is an hd_spec.
colour	Character or NULL. ggplot2 colour aesthetic column. Defaults to group when NULL and group is set. Ignored when data is an hd_spec.
mode	Character. Rendering mode - "dynamic" (default, interactive) or "static". "dynamic" uses the highcharter backend, "static" uses the ggplot2 backend and others. See list_modes().
backend	Character. Rendering engine - "dynamic" (default, interactive) or "static", or any engine added with register_backend(). Falls back to getOption("highdir.backend", "dynamic"). This will deprecated in favor of mode in a future release.

Details

hd() accepts either raw data columns or an existing hd_spec() object. Passing an hd_spec is the recommended bridge for code that already constructs specs separately (e.g. in Shiny or a reporting pipeline).

Value

An S3 object of class "hd" with slots:

⁠$spec⁠

An hd_spec() object.

⁠$geom⁠

NULL until a ⁠+ hd_geom_*()⁠ layer is added.

⁠$opts⁠

An hd_opts() object (defaults until overridden).

⁠$mode⁠

Character. The resolved engine name.

See Also

hd_geom_column(), hd_geom_line(), hd_geom_arearange(), hd_opts(), hd_make()

Examples

df <- data.frame(
  age = rep(c("18-24", "25-34", "35-44", "45-54"), each = 2),
  sex = rep(c("Male", "Female"), 4),
  pct = c(42, 38, 55, 61, 48, 52, 60, 57),
  n   = c(120, 115, 200, 210, 180, 175, 160, 155)
)

# Composable style
hd(df, x = "age", y = "pct", group = "sex") +
  hd_geom_column() +
  hd_opts(title = "Health survey", ylim = c(0, 80))

# Pass an existing hd_spec
spec <- hd_spec(df, x = "age", y = "pct", group = "sex", n = "n")
hd(spec) +
  hd_geom_line(smooth = TRUE) +
  hd_opts(title = "Trend")

# Switch backend per figure
hd(df, x = "age", y = "pct", mode = "static") +
  hd_geom_column() +
  hd_opts(title = "Static version")

highdir documentation built on July 31, 2026, 5:06 p.m.