Draw a Scatter Plot — draw_scatter • rtemis.draw

Quick scatter plot from x/y data with optional fitted line and confidence band.

Usage

draw_scatter(
  x,
  y,
  size = NULL,
  group = NULL,
  fit = NULL,
  se = TRUE,
  fit_alpha = 0.25,
  n_fit = 200L,
  palette = NULL,
  xlim = NULL,
  ylim = NULL,
  pad = DEFAULT_PAD,
  square = FALSE,
  equal_axes = FALSE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  theme = NULL,
  margins = DEFAULT_MARGINS,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  se_times = 1.96,
  rsq = FALSE,
  diagonal = FALSE,
  diagonal_color = NULL,
  legend_position = "top",
  legend_placement = "outside",
  fit_name = NULL,
  rug = FALSE,
  hover = NULL
)

Arguments

x: Numeric: X values.
y: Numeric: Y values.
size: Optional Numeric: Symbol sizes.
group: Optional Atomic vector or single-column data frame: Grouping variable for multiple series.
fit: Optional Character {"glm", "gam"}: Fit method. NULL disables fitting. "gam" for mgcv::gam(). The fitted line and standard-error band are computed per group when group is provided.
se: Logical: Whether to show the confidence band.
fit_alpha: Numeric [0, 1]: Opacity for the confidence-band fill.
n_fit: Integer [2, Inf): Number of evaluation points for the fit.
palette: Optional Character: Series color palette — a single color string or character vector that overrides the theme palette for this chart. When group is set, colors are assigned per group in order. color takes precedence over the theme palette.
xlim: Optional Numeric [length 2]: X-axis limits c(min, max). Defaults to range(x) extended by pad.
ylim: Optional Numeric [length 2]: Y-axis limits c(min, max). Defaults to range(y) extended by pad.
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.
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 a true-versus-predicted plot whose identity line should run at 45 degrees; the two axes are then made to span the same interval. 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.
margins: Optional Named numeric vector or named list: Plot margins in pixels (or percentage strings) for any of "top", "right", "bottom", "left". Unspecified sides keep echarts' default auto-sizing. See draw_line() for details.
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().
se_times: Numeric [0, Inf): Standard-error multiplier for the band.
rsq: Logical: Include the fitted model's R-squared in series labels. This describes the overlay fit, not predictive performance against the identity line. Constant responses have undefined R-squared, labeled NA.
diagonal: Logical: Draw a dashed identity line within the axis limits.
diagonal_color: Optional Character: Identity-line color.
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.
fit_name: Optional Character: Label for fitted layers.
rug: Logical: Draw marginal marks on both axes.
hover: Optional Character: One literal tooltip label per observation.

Value

htmlwidget: Widget object.

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

# True versus predicted: square box, equal scale, identity line at 45 deg.
draw_scatter(
  x = c(1, 2, 3, 4),
  y = c(1.1, 1.9, 3.4, 3.7),
  square = TRUE,
  equal_axes = TRUE,
  xlab = "True",
  ylab = "Predicted"
)