Draw a Line Chart — draw_line • rtemis.draw

Quick line chart from x/y data.

Usage

draw_line(
  x,
  y,
  names = NULL,
  group = NULL,
  smooth = FALSE,
  area = FALSE,
  points = TRUE,
  blocks = NULL,
  block_color = NULL,
  block_opacity = 0.2,
  palette = NULL,
  line_style = NULL,
  pad = DEFAULT_PAD,
  xlim = NULL,
  ylim = NULL,
  square = FALSE,
  equal_axes = FALSE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  theme = NULL,
  zoom = FALSE,
  margins = DEFAULT_MARGINS,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  legend_position = "top",
  legend_placement = "outside"
)

Arguments

x: Vector: X-axis values. Numeric values get a value axis. Date and POSIXct values get a time axis: points are spaced by elapsed time and the labels are chosen adaptively for the span shown (years, then months, then days, down to seconds), and they read as the timestamps do in R whatever timezone the chart is viewed in. Anything else gets a category axis with one slot per distinct value, in order of appearance.
y: Numeric or named list: Y values.
names: Optional Character: Series names used when y is an unnamed list.
group: Optional Atomic vector or single-column data frame: Grouping variable, one value per point. Splits a single y vector into one line per level, named by the level, as draw_scatter() does for points. Cannot be combined with a list y or with blocks. Points whose group is NA are dropped.
smooth: Logical: Whether to smooth lines.
area: Logical: Whether to show area fill.
points: Logical: Whether to show point markers on each data value. Defaults to TRUE; set to FALSE on long time-series where the symbols add visual noise.
blocks: Optional factor, integer, character, or logical of length length(x): Per-x-value group label used to shade vertical background bands. Contiguous runs of the same level become one band. NA entries produce no band.
block_color: Optional Character vector or list of length k, where k is the number of unique levels in blocks: Fill color for each level. Match by name to factor levels if named, else positional. NA, NULL, or "transparent" entries skip that level.
block_opacity: Numeric [0, 1]: Fill opacity applied to all bands. Defaults to 0.2.
palette: Optional Character: Series color palette — a single color string or character vector that overrides the theme palette for this chart. color takes precedence over the theme palette (it sets option.color).
line_style: Optional Character {"solid", "dashed", "dotted"}: Line dash style — one value per series, recycled to match the number of series.
pad: Numeric [0, Inf): Fraction of the data range to extend each axis by when xlim / ylim are not given. The default matches base R's xaxs = "r", which extends the range by 4% at each end. Defaults to the range of all y values across series (no padding).
xlim: Optional Numeric, Date, or POSIXct [length 2]: X-axis limits c(min, max). Only supported when x is numeric or a time; passing xlim with a categorical x errors. On a time axis, give it in the same class as x (or as epoch milliseconds). Defaults to the range of x extended by pad.
ylim: Optional Numeric [length 2]: Y-axis limits c(min, max).
square: Logical: If TRUE, draw the plotting box square – equal height and width in pixels, excluding axis labels and margins.
equal_axes: Logical: If TRUE, give one data unit the same size in pixels on both axes. Set both for a plot that is square and to scale, such as an ROC curve; the two axes are then made to span the same interval. Requires a numeric x. See Details.
xlab: Optional Character: X-axis title.
ylab: Optional Character: Y-axis title.
title: Optional Character: Chart title.
theme: Optional Theme: Theme override. The palette inside the theme can be overridden per-chart with the color argument.
zoom: Logical, DataZoom, or list of DataZoom: Enable x-axis zoom. TRUE adds a slider plus mouse-wheel/drag zoom on the x-axis, with the slider given its own band below the axis title; FALSE (default) disables zoom. Pass DataZoom objects (or a list of them) for full control over zoom behavior, styling, and placement.
margins: Optional Named numeric vector or named list: Plot margins in pixels (or percentage strings) for any of "top", "right", "bottom", "left" — e.g. c(left = 80, right = 20) or list(left = 80, right = "10%"). Unspecified sides keep echarts' default auto-sizing (outerBoundsMode = "same"), which shrinks the grid to fit axis labels and names with no dead space.
width: Optional Character or Numeric: Widget width.
height: Optional Character or Numeric: Widget height.
element_id: Optional Character: Explicit DOM element ID for the widget container. NULL lets htmlwidgets generate one.
filename: Optional Character: If provided, save the widget to this file via save_drawing().
legend_position: Character {"top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"}: Legend anchor. Top/bottom anchors use horizontal rows; left/right anchors use a vertical column. Corner anchors align within the top or bottom row.
legend_placement: Character {"outside", "inside"}: Relation to the plotting area. Outside placement reserves space for the complete legend; inside placement overlays the data. Neither setting adds a missing legend.

Value

htmlwidget: Widget object.

Details

Axis baselines emphasize zero only when it is in the visible orthogonal range. Categorical x axes follow the same rule as numeric and time axes.

Square and equally-scaled plots

square and equal_axes are separate requests. square is about the shape of the plotting box: equal height and width in pixels, measured on the box itself, not including axis labels or margins. equal_axes is about scale: one data unit occupies the same number of pixels on both axes, so a 45-degree line really is a slope of 1.

Either works alone. equal_axes on a chart whose x spans ten units and whose y spans one gives a wide, short box, which is what equal scaling means there.

Asking for both is a statement about the limits, since the only square box in which both axes are equally scaled is one whose axes span the same interval. So both axes are made to span one interval: over all the values when neither limit was given, or the one you gave when you gave exactly one. Giving both xlim and ylim as different intervals is an error rather than a silent override.

The box itself is solved in the browser, which is the only side that knows how wide the container is, and re-solved whenever it resizes.

Examples

# An ROC curve is square by nature, on axes that share their [0, 1] range.
draw_line(
  x = c(0, 0.2, 0.6, 1),
  y = c(0, 0.55, 0.85, 1),
  square = TRUE,
  equal_axes = TRUE,
  xlab = "False positive rate",
  ylab = "True positive rate"
)