% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hd-object.R
\name{hd}
\alias{hd}
\title{Initialise a Composable highdir Figure}
\usage{
hd(
  data,
  x = NULL,
  y = NULL,
  group = NULL,
  n = NULL,
  colour = NULL,
  backend = getOption("highdir.backend", "highcharter")
)
}
\arguments{
\item{data}{A \code{data.frame} \strong{or} an \code{\link[=hd_spec]{hd_spec()}} object.  When an
\code{hd_spec} is supplied every other mapping argument (\code{x}, \code{y}, …) is
ignored - the spec carries them already.}

\item{x}{Character. Column name for the x-axis variable.
Ignored when \code{data} is an \code{hd_spec}.}

\item{y}{Character. Column name for the y-axis variable.
Ignored when \code{data} is an \code{hd_spec}.}

\item{group}{Character or \code{NULL}. Column used to split data into multiple
series.  Ignored when \code{data} is an \code{hd_spec}.}

\item{n}{Character or \code{NULL}. Column of raw counts shown in
highcharter tooltips alongside the y value.
Ignored when \code{data} is an \code{hd_spec}.}

\item{colour}{Character or \code{NULL}. ggplot2 colour aesthetic column.
Defaults to \code{group} when \code{NULL} and \code{group} is set.
Ignored when \code{data} is an \code{hd_spec}.}

\item{backend}{Character. Rendering engine - \code{"highcharter"} (default,
interactive) or \code{"ggplot2"} (static), or any engine added with
\code{\link[=register_backend]{register_backend()}}.  Falls back to \code{getOption("highdir.backend", "highcharter")}.}
}
\value{
An S3 object of class \code{"hd"} with slots:
\describe{
\item{\verb{$spec}}{An \code{\link[=hd_spec]{hd_spec()}} object.}
\item{\verb{$geom}}{\code{NULL} until a \verb{+ hd_geom_*()} layer is added.}
\item{\verb{$opts}}{An \code{\link[=hd_opts]{hd_opts()}} object (defaults until overridden).}
\item{\verb{$backend}}{Character. The resolved engine name.}
}
}
\description{
Creates an \code{hd} object that accumulates geometry and presentation layers
via \code{+}, then renders when printed.  This mirrors the way \code{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 \code{print()} / \code{knit} call).
}
\details{
\code{hd()} accepts either raw data columns \strong{or} an existing \code{\link[=hd_spec]{hd_spec()}} object.
Passing an \code{hd_spec} is the recommended bridge for code that already
constructs specs separately (e.g. in Shiny or a reporting pipeline).
}
\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", backend = "ggplot2") +
  hd_geom_column() +
  hd_opts(title = "Static version")

}
\seealso{
\code{\link[=hd_geom_column]{hd_geom_column()}}, \code{\link[=hd_geom_line]{hd_geom_line()}}, \code{\link[=hd_geom_arearange]{hd_geom_arearange()}},
\code{\link[=hd_opts]{hd_opts()}}, \code{\link[=hd_make]{hd_make()}}
}
