Package 'vellumplot'

Description

add_marginal() draws a distribution of the panel's x variable along the top edge and/or of its y variable along the right edge, each sharing the main panel's axis so it lines up with the scatter (the vellumplot analogue of ggExtra::ggMarginal()). It is a plot-level modifier, like facet_wrap() or coord_flip(): it takes no encoding of its own and instead reads x, y (and, with group = TRUE, color) from the first layer that maps a numeric x and y (typically your mark_point()).

Usage

add_marginal(
  plot,
  type = c("density", "histogram"),
  sides = "tr",
  size = 0.15,
  adjust = 1,
  bins = 30,
  group = FALSE
)

Arguments

Details

The marginals are drawn without their own axes or background. This version supports a single panel only: combining it with facet_wrap() / facet_grid(), a non-Cartesian coordinate system (coord_flip(), coord_polar(), coord_fixed(), coord_sf()), or a locked aspect ratio is an error.

Value

The modified PlotSpec.

See Also

mark_density(), mark_histogram(), facet_wrap()

Examples

vplot(faithful) |>
  mark_point(x = eruptions, y = waiting) |>
  add_marginal()

vplot(faithful) |>
  mark_point(x = eruptions, y = waiting) |>
  add_marginal(type = "histogram", sides = "t")

Description

Attach a SelectionSpec (from the free-standing form of select_point() / select_interval()) to a plot, marking that the selection's gesture is active on this plot's marks. Use it when a selection is defined once and shared across views in a composition (define + add_selection() on one plot, filter_by() on another).

Usage

add_selection(plot, selection)

Arguments

Value

The PlotSpec, with the selection registered.

See Also

select_point(), filter_by()

Description

Used inside a ⁠mark_*()⁠ encoding to reference a variable produced by the layer's statistical transform rather than a raw data column, e.g. y = after_stat(count) or y = after_stat(density).

Usage

after_stat(x)

Arguments

Value

Its argument (the marker is interpreted at compile time).

Description

anim_save() renders a vellum_animation (from animate()) to an animated image, tweening the frames between keyframes and encoding them in one parallel, streaming pass in vellum's Rust backend. The format follows the file extension:

Usage

anim_save(filename, animation)

Arguments

Details

• .gif — a looping GIF (universal compatibility).

• .png — an animated PNG (APNG; lossless, alpha).

• .svg — a single animated SVG: every frame is emitted as vector markup and shown in turn by a CSS step animation. It is resolution-independent (crisp at any size, in print and on retina) and honours prefers-reduced-motion (a reader who has asked their system not to animate gets the first frame, held).

Value

filename, invisibly.

Choosing a format

Pick by scene complexity, not preference. An animated SVG emits every frame in full, so its size grows with the number of marks times the number of frames; a raster format (GIF/APNG) does not. So SVG wins clearly on line art — a few moving marks, the common explanatory case — and loses on a dense scatter, where a raster format is the right answer. anim_save() says so when a .svg scene is dense enough that a raster format would likely be smaller.

See Also

animate()

Examples

## Not run: 
a <- vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  transition_states(cyl) |>
  animate()
anim_save("cyl.gif", a)
anim_save("cyl.svg", a) # resolution-independent

## End(Not run)

Description

animate() compiles a plot carrying a transition_states() into one keyframe scene per state, training the scales once over all states and freezing them, and returns a vellum_animation. Write it with anim_save(); printing it shows the first keyframe as a preview.

Usage

animate(plot, nframes = 50, fps = 25)

Arguments

Details

Per-state statistics (e.g. a smooth) are recomputed per keyframe, but no scale domain retrains — the frozen scales are the observable proof the animation stayed non-reactive (axis breaks do not move between frames).

Value

A vellum_animation.

See Also

transition_states(), ease_aes(), anim_save()

Examples

## Not run: 
vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  transition_states(cyl) |>
  animate(nframes = 50, fps = 25)

## End(Not run)

Description

Draw a single mark (or a short vector of them) from values supplied directly, rather than mapping a data column. The values become a small inline layer data frame, so annotations are independent of the plot data (and repeat on every facet panel). Supported geoms: "text", "label", "point", "segment", "rect", "grob", and "sparkline".

Usage

annotate(
  plot,
  geom,
  x = NULL,
  y = NULL,
  xend = NULL,
  yend = NULL,
  xmin = NULL,
  xmax = NULL,
  ymin = NULL,
  ymax = NULL,
  label = NULL,
  ...
)

Arguments

Details

"grob" places an arbitrary vellum grob (or a PlotSpec, e.g. a vsparkline()) at data coordinate(s), in a box of physical size — a general "glyph / chart in a panel" seam. "sparkline" is the convenience for the common case: pass ⁠values =⁠ and it builds and places a vsparkline().

Value

The modified PlotSpec.

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  annotate("text", x = 4, y = 30, label = "note") |>
  annotate("rect", xmin = 3, xmax = 4, ymin = 15, ymax = 20, alpha = 0.2)
## Not run: 
vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  annotate("sparkline", x = 4, y = 30, values = cumsum(rnorm(30)))

## End(Not run)

Description

An area() is a rectangular block of grid cells (1-based, inclusive) that a sub-plot occupies. Pass a list of area()s (one per plot, in order) as concat(..., design = ) to place plots on an explicit, possibly spanning, grid.

Usage

area(t, l, b = t, r = l)

Arguments

Value

An area spec.

Examples

a <- vplot(mtcars) |> mark_point(x = wt, y = mpg)
b <- vplot(mtcars) |> mark_point(x = hp, y = mpg)
concat(a, b, design = list(area(1, 1, 1, 2), area(2, 1, 2, 1)))

Description

as_spec() turns a PlotSpec into a plain, nested, serializable R list (data, layers, encodings, scales, coordinates, facets, labels, page size); from_spec() rebuilds a PlotSpec from that list. Together with spec_to_json() / spec_from_json() this makes a vellumplot plot a portable document — the substrate for the LLM / agent tooling (spec_fields(), vplot_from_spec()) and the Vega-Lite bridge (spec_to_vegalite()).

Usage

as_spec(plot)

from_spec(spec, data = NULL, env = globalenv())

Arguments

Details

The spec is a subset of the full grammar — the encoding-level state that a portable document can carry faithfully. State that a JSON document cannot represent (custom transform functions, paint/pattern fills, hand-drawn sketch() geometry, secondary axes, sf CRS objects, per-layer data) is refused with a classed vellumplot_unserializable error naming the exact slot — it is never silently dropped. The single exception is theme element customisation, which is styling orthogonal to the data spec: the theme preset name and its scalar settings round-trip, but custom ⁠element_*()⁠ overrides are dropped with a warning.

Channel expressions are stored as text (a column name, or an expression like log(x)); the quosure's captured environment is dropped, so an encoding that closes over a local variable will not round-trip.

Data is inlined when small (at most a few thousand cells and all-atomic columns) and otherwise stored by reference (name + content hash + column schema); a by-reference spec needs from_spec(spec, data = ) to recompile.

Value

as_spec() returns a named list; from_spec() returns a PlotSpec.

See Also

spec_to_json(), spec_to_vegalite(), vplot_from_spec()

Examples

p <- vplot(mtcars) |> mark_point(x = wt, y = mpg, color = cyl)
spec <- as_spec(p)
spec$layers[[1]]$mark
p2 <- from_spec(spec)

Description

Make the aes view of this plot's panel follow an interval selection defined on another (overview) plot: dragging the overview brush pans and zooms this (detail) panel to the selected range. This is a display-tier view change (pan/zoom), not a scale retrain.

Usage

bind_scale(plot, selection, aes = c("x", "y"))

Arguments

Value

The PlotSpec, with the bind registered.

See Also

select_interval()

Description

Restrict where a plot's marks show, by a shape rather than the panel rectangle. clip_to() is a hard clip: only marks inside region are drawn (or, with invert = TRUE, only those outside) – the way to fill a raster / hexbin / tile heatmap into a country outline (a textured choropleth). set_mask() is a soft mask: a radial luminance ramp that fades the panel out towards its edges (a vignette / spotlight).

Usage

clip_to(plot, region, invert = FALSE)

clip_layer(plot, region, invert = FALSE)

set_mask(plot, region = NULL, type = c("luminance", "alpha"), feather = 0.35)

Arguments

Details

clip_to() / set_mask() mask the whole panel; clip_layer() masks only the most-recently-added layer (the one just piped in), so one raster layer can be clipped to a shape while the axes and other layers stay full-bleed.

All three attach to the plot and resolve at render into an isolated masked layer (vellum::as_mask()), so the static output is unchanged when none is set. Cartesian coordinates only (not polar or a nonlinear coord_trans()).

A smooth feathered edge on an arbitrary polygon needs a blur the renderer does not provide yet, so clip_to() is hard-edged; use set_mask() for a soft (radial) fade.

Value

The modified PlotSpec.

Examples

## Not run: 
# clip a raster heatmap to a country outline
vplot(grid) |> mark_raster(x = x, y = y, fill = z) |> clip_to(country_sf)

# a vignette
vplot(mtcars) |> mark_point(x = wt, y = mpg) |> set_mask(feather = 0.5)

## End(Not run)

Description

Add figure-level text (a title, subtitle, caption) spanning the whole composition, and/or auto-tag the sub-plots (A, B, C, …). Because every PlotComposition carries its own annotation, this works at any nesting level (unlike patchwork, where annotation is top-level only).

Usage

compose_annotation(
  plot,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag_levels = NULL,
  tag_prefix = "",
  tag_suffix = ""
)

Arguments

Value

The modified PlotComposition.

See Also

theme(), which also accepts a composition to set the figure-level chrome (title bands, collected legend, panel spacing, tags).

Examples

a <- vplot(mtcars) |> mark_point(x = wt, y = mpg)
b <- vplot(mtcars) |> mark_point(x = hp, y = mpg)
hconcat(a, b) |> compose_annotation(title = "Fuel economy", tag_levels = "A")

Description

Compose several independent plots into one image. hconcat() lays them in a row, vconcat() in a column, and concat() on a grid of ncol/nrow cells. Each sub-plot keeps its own scales, axes, and legend (this is view composition, not faceting).

Usage

concat(
  ...,
  ncol = NULL,
  nrow = NULL,
  byrow = TRUE,
  widths = NULL,
  heights = NULL,
  guides = c("collect", "keep"),
  design = NULL,
  width = NULL,
  height = NULL,
  dpi = NULL
)

wrap_plots(
  plots,
  ncol = NULL,
  nrow = NULL,
  byrow = TRUE,
  widths = NULL,
  heights = NULL,
  guides = c("collect", "keep"),
  design = NULL,
  width = NULL,
  height = NULL,
  dpi = NULL
)

hconcat(..., guides = c("collect", "keep"), height = NULL)

vconcat(..., guides = c("collect", "keep"), width = NULL)

Arguments

Details

Sub-plot panels are aligned across the grid (a shared track grid lines up panel edges even when axis labels differ), and identical legends are collected into one shared legend by default (guides = "collect"). Pass PlotCompositions in ... to nest a sub-grid. Annotate the whole figure with compose_annotation().

Value

A PlotComposition (renders via render_plot() / vellum::render()).

Examples

a <- vplot(mtcars) |> mark_point(x = wt, y = mpg)
b <- vplot(mtcars) |> mark_histogram(x = mpg, bins = 10)
hconcat(a, b)

Description

Use condition() as the value of a mark aesthetic to make that aesthetic depend on whether an element is in a selection: members get if_true, non-members get if_false. This is the general form of highlight-on-interaction.

Usage

condition(selection, if_true, if_false, empty = TRUE)

Arguments

Details

condition() is recognised where it appears in a ⁠mark_*()⁠ encoding; calling it directly is an error. The if_true branch is drawn on a static render and trains scales exactly as the equivalent plain encoding, so color = condition("s", g, "grey80") produces the same colour scale and legend as color = g. With empty = TRUE (the default) an empty selection matches everything, so a static / initial render shows if_true for all elements and interaction dims non-members to if_false.

Value

Used only inside a ⁠mark_*()⁠ encoding; not called directly.

See Also

select_point(), filter_by()

Description

coord_cartesian() is the default Cartesian system; pass xlim/ylim to zoom the view (out-of-range marks are clipped, not dropped — unlike a ⁠scale_*(limits=)⁠, which here behaves the same but is the data-scale's job). coord_flip() swaps the x and y axes, e.g. for horizontal bars. coord_fixed() / coord_equal() lock the aspect ratio so one data unit on the y axis occupies ratio times the physical length of one unit on x (the panel shrinks to fit and is centred). Coordinate limits take precedence over scale limits.

Usage

coord_cartesian(plot, xlim = NULL, ylim = NULL)

coord_flip(plot, xlim = NULL, ylim = NULL)

coord_fixed(plot, ratio = 1, xlim = NULL, ylim = NULL)

coord_equal(plot, ratio = 1, xlim = NULL, ylim = NULL)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> coord_cartesian(xlim = c(2, 4))
vplot(mtcars) |> mark_bar(x = factor(cyl)) |> coord_flip()
vplot(mtcars) |> mark_point(x = wt, y = mpg) |> coord_fixed()

Description

coord_polar() projects the panel into polar space: one position aesthetic becomes the angle and the other the radius. With theta = "x" (the default) the x aesthetic maps to angle and y to radius — a categorical bar chart becomes a wind-rose / coxcomb, a line becomes a radar/spider trace, a point cloud is positioned by ⁠(angle, radius)⁠. With theta = "y" a stacked bar becomes a pie (see also the mark_pie() / mark_donut() shortcuts). The panel is locked to a square. Lines, areas, and ribbons are interpolated into smooth arcs.

coord_radial() is a fuller polar system (ggplot2 3.5's name): besides theta/start/direction it takes end to sweep only a partial arc (e.g. a half-circle gauge) and inner_radius to open a donut hole. With end = NULL and inner_radius = 0 it is identical to coord_polar().

Usage

coord_polar(plot, theta = "x", start = 0, direction = 1)

coord_radial(
  plot,
  theta = "x",
  start = 0,
  end = NULL,
  direction = 1,
  inner_radius = 0
)

Arguments

Value

The modified PlotSpec.

See Also

mark_pie(), mark_donut()

Examples

vplot(mtcars) |> mark_bar(x = factor(cyl)) |> coord_polar(theta = "x")
vplot(mtcars) |>
  mark_bar(x = factor(cyl)) |>
  coord_radial(theta = "x", inner_radius = 0.3)

Description

coord_sf() is the coordinate system for mark_sf() maps. Before scale training it reprojects every sf layer to a common CRS (via sf::st_transform()), so the renderer only ever sees projected Cartesian coordinates, and it locks the panel aspect ratio so the map is not stretched: 1 for a projected CRS, and the equirectangular correction 1/cos(mean_latitude) for unprojected longitude/latitude data.

Usage

coord_sf(
  plot,
  crs = NULL,
  xlim = NULL,
  ylim = NULL,
  graticule = FALSE,
  graticule_labels = TRUE
)

Arguments

Details

sf is an optional dependency (in Suggests); coord_sf() errors with an install hint if it is not available at render time.

Value

The modified PlotSpec.

See Also

mark_sf(), mark_scalebar(), mark_compass()

Examples

## Not run: 
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
vplot(nc) |> mark_sf(fill = BIR74) |> coord_sf(crs = "OGC:CRS84")
vplot(nc) |> mark_sf(fill = BIR74) |> coord_sf(crs = 3857, graticule = TRUE)

## End(Not run)

Description

coord_trans() applies a nonlinear transform to the display of one or both position axes, after the scale has trained. This differs from a ⁠scale_*(trans=)⁠: a scale transform rescales the data and picks its breaks in the transformed space (so a log scale is labelled ⁠1, 10, 100⁠), whereas coord_trans() keeps the trained breaks at their original data values and only warps where they are drawn — so the axis is still labelled with the raw values, the gridlines bunch up, and straight lines curve. Use it to show data on, say, a log display without relabelling the axis in powers of ten.

Usage

coord_trans(plot, x = "identity", y = "identity")

Arguments

Details

The transform is separable per axis. Each of x/y is a transform name ("identity", "log10", "sqrt") or a ⁠scales::transform_*()⁠ object. It is intended for continuous position axes; "reverse" is better expressed as scale_*(trans = "reverse").

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> coord_trans(y = "log10")

Description

ease_aes() chooses the easing function that shapes how the interpolation fraction moves through each transition — e.g. "cubic-in-out" starts and ends gently. By default it applies to every interpolated aesthetic; the position/color/size/alpha arguments override it for one class each, so marks can glide into place on a cubic curve while their colour crossfades evenly.

Usage

ease_aes(
  plot,
  ease = "linear",
  position = NULL,
  color = NULL,
  size = NULL,
  alpha = NULL,
  colour = NULL
)

Arguments

Value

The modified PlotSpec.

See Also

transition_states(), animate()

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  transition_states(cyl) |>
  ease_aes("cubic-in-out")

# Marks settle into place gently, but the colour crossfade stays even.
vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = factor(gear)) |>
  transition_states(cyl) |>
  ease_aes("cubic-in-out", color = "linear")

Description

Typed building blocks for theme(). Each describes how a family of theme slots is drawn; any property left NULL is inherited from the slot's parent in the theme tree. element_blank() draws nothing.

Usage

element_text(
  family = NULL,
  face = NULL,
  colour = NULL,
  color = NULL,
  size = NULL,
  cex = NULL,
  hjust = NULL,
  vjust = NULL,
  angle = NULL,
  lineheight = NULL,
  margin = NULL
)

element_line(
  colour = NULL,
  color = NULL,
  linewidth = NULL,
  linetype = NULL,
  lineend = NULL,
  sketch = NULL
)

element_rect(
  fill = NULL,
  colour = NULL,
  color = NULL,
  linewidth = NULL,
  linetype = NULL,
  sketch = NULL
)

element_blank()

Arguments

Value

An element object for use in theme().

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  theme(plot.title = element_text(size = 16), panel.grid.minor = element_blank())

Description

facet_wrap() lays panels out in a ribbon wrapped into ncol/nrow; facet_grid() arranges them on a 2-D grid defined by a rows ~ cols formula. Position scales are shared across panels by default (so axes align); pass scales = "free_x", "free_y", or "free" to train them per panel. Colour and size scales (and their legends) are always shared in this version.

Usage

facet_wrap(
  plot,
  facets,
  ncol = NULL,
  nrow = NULL,
  scales = c("fixed", "free_x", "free_y", "free")
)

facet_grid(plot, facets, scales = c("fixed", "free_x", "free_y", "free"))

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> facet_wrap(~cyl)
vplot(mtcars) |> mark_point(x = wt, y = mpg) |> facet_grid(am ~ cyl)

Description

Show only the rows in selection, hiding the rest (a display-tier hide, not a re-aggregation). Point a second view's filter_by() at a selection whose gesture lives in a first view and you get cross-filtering: brush one panel, a linked panel redraws to just those rows.

Usage

filter_by(plot, selection)

Arguments

Value

The PlotSpec, with the filter registered.

See Also

select_interval(), add_selection()

Description

A render effect for stroked, point, and text marks, in the spirit of mplcyberpunk: a widened copy of the mark is drawn beneath the crisp original and softened with a real Gaussian blur (vellum's vl_viewport(blur=)), composited additively (a "screen" blend) into a soft neon halo. Pass it to a mark's effects argument, e.g. mark_line(..., effects = list(glow())). Pairs naturally with theme_cyberpunk().

Usage

glow(size = 6, layers = 6L, alpha = 0.12, blend = "screen", color = NULL)

Arguments

Details

The glow is applied per style group, so a colour-mapped multi-series line glows each series in its own hue. It applies to mark_point(), mark_line(), mark_step(), mark_rule(), mark_segment(), mark_edges(), mark_nodes(), mark_edge_bundle(), mark_flow_map(), and text marks (mark_text() / mark_label()); other marks reject it.

Value

A GlowSpec object for a mark's effects list.

See Also

outline(), shadow(), theme_cyberpunk()

Examples

df <- data.frame(x = 1:20, y = cumsum(rnorm(20)))
vplot(df) |>
  mark_line(x = x, y = y, color = "#00e5ff", effects = list(glow())) |>
  theme_cyberpunk()

Description

Thin re-exports of vellum::linear_gradient() and vellum::radial_gradient(). A gradient is an unscaled value for the fill aesthetic: pass it directly, e.g. mark_area(x = t, y = y, fill = linear_gradient(c("#00e5ff", "#00e5ff00"))), and the filled region (area / ribbon / bar) is painted with the paint as a single grob. Use "transparent" (or an "#RRGGBB00" colour) as a stop to fade out — the "glow fade under a line" look. The gradient's x1/y1/x2/y2 (in units, "npc" by default) set its direction. A gradient cannot be mapped to a data column (it is one paint per region).

Usage

linear_gradient(colours, stops = NULL, ...)

radial_gradient(colours, stops = NULL, ...)

Arguments

Value

A vellum_gradient object usable as a fill value.

See Also

glow(), theme_cyberpunk()

Examples

df <- data.frame(x = 1:20, y = cumsum(abs(rnorm(20))))
vplot(df) |>
  mark_area(x = x, y = y, fill = linear_gradient(c("#00e5ff", "#00e5ff00"),
    x1 = 0, y1 = 1, x2 = 0, y2 = 0))

Description

gt_vsparkline() renders a list-column of numeric vectors as a per-row vsparkline(), embedded as inline SVG in a gt::gt() table — so a gt table (with all of gt's formatting and theming) gains a vellum sparkline column. Needs the gt package, and HTML output (inline SVG is not embedded by gt's LaTeX / Word backends).

Usage

gt_vsparkline(
  gt_object,
  column,
  type = "line",
  ...,
  width = 30,
  height = 8,
  units = "mm"
)

Arguments

Details

The vectors are recovered from the gt object's data in its current row order; apply gt_vsparkline() before any gt row reordering / grouping.

Value

The modified gt object.

See Also

vsparkline(), vtable(), plot_svg()

Examples

## Not run: 
df <- data.frame(metric = c("A", "B"))
df$trend <- list(cumsum(rnorm(20)), cumsum(rnorm(20)))
gt::gt(df) |> gt_vsparkline(trend, type = "line")

## End(Not run)

Description

guides() overrides the legend (guide) for one or more aesthetics without respelling the whole ⁠scale_*()⁠. Pass "none" (or guide_none()) to hide a legend, guide_legend() to tweak a keyed legend (reverse the key order, override the title, restyle the keys with override.aes), guide_colourbar() to size, tick and style a continuous colour bar, or guide_coloursteps() to draw a binned colour scale as a segmented bar instead of swatches. Applies to the non-position legends (color/fill, size, shape, alpha, linetype); position axes are unaffected.

Usage

guides(plot, ...)

guide_none()

guide_legend(
  title = NULL,
  reverse = FALSE,
  override.aes = NULL,
  nested = FALSE
)

guide_colourbar(
  title = NULL,
  barwidth = NULL,
  barheight = NULL,
  ticks = TRUE,
  ticks.colour = "white",
  label.position = NULL,
  n.breaks = NULL,
  reverse = FALSE
)

guide_colorbar(
  title = NULL,
  barwidth = NULL,
  barheight = NULL,
  ticks = TRUE,
  ticks.colour = "white",
  label.position = NULL,
  n.breaks = NULL,
  reverse = FALSE
)

guide_coloursteps(
  title = NULL,
  barwidth = NULL,
  barheight = NULL,
  ticks = FALSE,
  ticks.colour = "white",
  label.position = NULL,
  reverse = FALSE
)

guide_colorsteps(
  title = NULL,
  barwidth = NULL,
  barheight = NULL,
  ticks = FALSE,
  ticks.colour = "white",
  label.position = NULL,
  reverse = FALSE
)

Arguments

Value

guides(): the modified PlotSpec. guide_none() / guide_legend(): a guide specification for use inside guides().

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = factor(cyl)) |>
  guides(color = "none")

vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = factor(cyl)) |>
  guides(color = guide_legend(reverse = TRUE))

# legible keys over faint, tiny points
vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = factor(cyl), alpha = 0.15, size = 0.6) |>
  guides(color = guide_legend(override.aes = list(size = 5, alpha = 1)))

# a taller, wider colour bar with left-side labels and no ticks
vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = hp) |>
  guides(color = guide_colourbar(
    barwidth = 8, barheight = 60, ticks = FALSE, label.position = "left"
  ))

# about four ticks on the bar instead of the automatic count
vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = hp) |>
  guides(color = guide_colourbar(n.breaks = 4))

# a binned colour scale as a segmented bar
vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = hp) |>
  scale_color_binned() |>
  guides(color = guide_coloursteps())

# a proportional-symbol (nested-circle) size legend
vplot(mtcars) |>
  mark_point(x = wt, y = mpg, size = hp) |>
  scale_size(range = c(2, 12)) |>
  guides(size = guide_legend(nested = TRUE))

Description

Place plot as an inset over base, positioned by fractional coordinates (0–1) of the chosen reference box. Returns a 1-cell PlotComposition carrying the inset (compose it further or render directly).

Usage

inset(
  base,
  plot,
  left = 0.6,
  bottom = 0.6,
  right = 0.98,
  top = 0.98,
  align_to = c("panel", "plot", "full"),
  on_top = TRUE
)

Arguments

Value

A PlotComposition.

Examples

a <- vplot(mtcars) |> mark_point(x = wt, y = mpg)
b <- vplot(mtcars) |> mark_histogram(x = mpg, bins = 8)
inset(a, b, left = 0.55, bottom = 0.55, right = 0.98, top = 0.98)

Description

Declare that a host should surface the source data rows behind an element when the user clicks (or hovers) it — the "click-to-source" affordance. It is inert on a static render; a host (vellumwidget::as_widget()) reads the compiled scene's provenance (provenance_join() / provenance_payload()) to answer the gesture, and under Shiny reports the clicked element's rows to ⁠input$<id>_source⁠.

Usage

inspect_source(plot, on = c("click", "hover"), values = FALSE)

Arguments

Details

This is opt-in because the row mapping adds to the widget payload; declaring it on the plot (rather than as a host flag) keeps interactivity a property of the spec.

Value

The PlotSpec, with source inspection registered.

See Also

provenance_payload(), select_point()

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  inspect_source()

Description

Returns the serialisable declaration block a host needs to enact a plot's declarative interactivity (selections, conditional encodings, filters, and scale-domain binds), or NULL when the plot declares none. This is the plot-level companion to the per-element metadata carried on the compiled scene; vellumwidget::as_widget() reads it to wire gestures to reactions.

Usage

interaction_model(x)

Arguments

Value

A named list (selections, conditions, filters, binds, and source when inspect_source() is declared), or NULL if there is no declared interactivity.

Description

Add plot-level text — a title, subtitle, caption, and tag — and override the titles of individual axes and legends (x, y, color, size). The title, subtitle, and tag are drawn in a band above the panels; the caption in a band below. Repeated labs() calls merge, with later values winning.

Usage

labs(
  plot,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  x = NULL,
  y = NULL,
  color = NULL,
  colour = NULL,
  fill = NULL,
  size = NULL,
  alt = NULL,
  ...
)

Arguments

Details

Axis/legend overrides set here are used unless a matching ⁠scale_*(name = )⁠ is also given, which takes precedence. With neither, the title is derived from the mapping.

Value

The modified PlotSpec.

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  labs(title = "Fuel economy", x = "Weight", y = "MPG")

Description

Convenience wrappers that declare a scale carrying only its limits, instead of spelling out a full ⁠scale_*()⁠. xlim() / ylim() set the position range; lims() sets limits for any named aesthetic. They are shortcuts for scale_*(limits = ...): like there, an explicit range sets the trained (view) window and marks outside it are clipped.

Usage

lims(plot, ...)

xlim(plot, ...)

ylim(plot, ...)

Arguments

Value

The modified PlotSpec.

See Also

scale_x_continuous()

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> xlim(0, 6)
vplot(mtcars) |> mark_point(x = wt, y = mpg) |> lims(x = c(0, 6), y = c(10, 35))

Description

Cartographic furniture for coord_sf() maps. mark_scalebar() draws a segmented distance bar; mark_compass() draws a north arrow. Both are fixed-position decorations pinned to a panel corner (they take no data aesthetics). Graticule lines (meridians and parallels) are added through coord_sf()'s graticule argument, not a mark, so they render behind the map.

Usage

mark_scalebar(
  plot,
  distance = NULL,
  unit = "km",
  position = "bottomleft",
  segments = 4L,
  height = 2.5,
  pad = 4,
  text_size = 7,
  color = "black",
  fill = "white",
  data = NULL
)

mark_compass(
  plot,
  position = "topright",
  size = 10,
  pad = 4,
  rotation = 0,
  color = "black",
  fill = "black",
  text = TRUE,
  data = NULL
)

Arguments

Value

The modified PlotSpec.

See Also

coord_sf(), mark_sf()

Examples

## Not run: 
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
vplot(nc) |>
  mark_sf(fill = BIR74) |>
  coord_sf(crs = 3857, graticule = TRUE) |>
  mark_scalebar() |>
  mark_compass()

## End(Not run)

Description

mark_abline() draws a sloped reference line y = slope * x + intercept across the panel (the diagonal cousin of mark_rule()'s horizontal/vertical lines). mark_function() draws a curve y = fun(x) sampled over the panel's x range — e.g. a theoretical density over a histogram, or a reference curve over a scatter. Both take no data encodings; they reuse the panel's existing x/y scales, so add them on top of a data layer. Both assume linear axes.

Usage

mark_abline(
  plot,
  ...,
  slope = 1,
  intercept = 0,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_function(
  plot,
  ...,
  fun,
  n = 101,
  args = list(),
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> mark_abline(slope = -5, intercept = 37)
vplot(data.frame(x = rnorm(200))) |>
  mark_histogram(x = x, y = after_stat(density)) |>
  mark_function(fun = dnorm)

Description

mark_area() fills the region between a y line and the zero baseline; mark_ribbon() fills between ymin and ymax; mark_step() draws a staircase line. All connect points in x order.

Usage

mark_area(
  plot,
  ...,
  position = "stack",
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_ribbon(plot, ..., blend = NULL, sketch = NULL, data = NULL)

mark_step(
  plot,
  ...,
  direction = "hv",
  auto = FALSE,
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

Arguments

Value

The modified PlotSpec.

See Also

scale_linewidth()

Examples

vplot(pressure) |> mark_area(x = temperature, y = pressure)

Description

mark_boxplot() draws a box-and-whisker per x category from the raw y values (box = Q1-Q3, median line, 1.5*IQR whiskers, outlier points). mark_errorbar() draws vertical bars from ymin to ymax with horizontal caps; mark_linerange() omits the caps. mark_summary() aggregates y per x with fun (default mean) and draws the result as points.

Usage

mark_boxplot(plot, ..., blend = NULL, sketch = NULL, data = NULL)

mark_errorbar(plot, ..., width = 0.5, blend = NULL, sketch = NULL, data = NULL)

mark_linerange(plot, ..., blend = NULL, sketch = NULL, data = NULL)

mark_summary(plot, ..., fun = mean, blend = NULL, sketch = NULL, data = NULL)

mark_pointrange(plot, ..., blend = NULL, sketch = NULL, data = NULL)

mark_crossbar(plot, ..., width = 0.5, blend = NULL, sketch = NULL, data = NULL)

Arguments

Details

mark_pointrange() draws a point at ⁠(x, y)⁠ with a vertical line from ymin to ymax (an identity mark — supply the summary values yourself, e.g. from a model). mark_crossbar() draws a box spanning ymin..ymax with a horizontal line at y. Both are the identity counterparts of the aggregating mark_interval().

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_boxplot(x = factor(cyl), y = mpg)

Description

mark_contour() draws iso-density contour lines of a 2-D point cloud (x, y); mark_contour_filled() fills the bands between them. By default the field is a kernel density estimate (needs the MASS package); map a z aesthetic to instead contour a supplied surface over a regular x/y grid. Contours are coloured by level automatically — mark_contour() maps color = after_stat(level), mark_contour_filled() maps fill. Contour tracing is done by the engine (vellum::vl_contour()), so no extra package is needed for the lines; a density field additionally needs MASS.

Usage

mark_contour(
  plot,
  ...,
  bins = 10,
  binwidth = NULL,
  breaks = NULL,
  n = 100,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_contour_filled(
  plot,
  ...,
  bins = 10,
  binwidth = NULL,
  breaks = NULL,
  n = 100,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

Value

The modified PlotSpec.

Examples

vplot(faithful) |>
  mark_point(x = eruptions, y = waiting) |>
  mark_contour(x = eruptions, y = waiting)
vplot(faithful) |> mark_contour_filled(x = eruptions, y = waiting)

Description

mark_count() collapses coincident ⁠(x, y)⁠ observations to one point sized by how many fall there (ggplot2's geom_count() / stat_sum()) — the honest way to show overplotting on a discrete or rounded grid. size defaults to after_stat(n) (the overlap count); map it to after_stat(prop) for the proportion instead.

Usage

mark_count(plot, ..., blend = NULL, sketch = NULL, data = NULL)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mpg <- data.frame(cyl = mtcars$cyl, gear = mtcars$gear)) |>
  mark_count(x = cyl, y = gear)

Description

For data too dense to draw one marker each (overplotted, up to millions of points), mark_datashade() bins the points into a canvas-sized grid in one pass and colours each cell by density (via vellum::datashade()), drawing a single raster that fills the panel. Cost is decoupled from point count and overplotting.

Usage

mark_datashade(
  plot,
  ...,
  width = 400,
  height = 300,
  colors = NULL,
  how = "eq_hist",
  span = NULL,
  clip = NULL,
  spread = NULL,
  blend = NULL,
  data = NULL
)

Arguments

Details

Map a discrete color (or fill) aesthetic to shade categorically (datashader's count_cat): each category is aggregated separately and every cell is coloured by the count-weighted average of the category hues it holds, with opacity from its total density — so you see which category dominates where, and where they mix, with a colour legend. The category hues come from the usual discrete colour scale (so scale_color_manual() etc. apply). Without a mapped colour, cell colour encodes plain density via the colors ramp.

Value

The modified PlotSpec.

Examples

n <- 1e5
d <- data.frame(x = rnorm(n), y = rnorm(n), g = sample(c("a", "b"), n, TRUE))
vplot(d) |> mark_datashade(x = x, y = y)
# categorical: colour by group
vplot(d) |> mark_datashade(x = x, y = y, color = g)

Description

Marks that summarise the distribution of a variable. mark_ecdf() draws the empirical cumulative distribution of x as a step; mark_rug() draws marginal ticks at each datum; mark_qq() draws a quantile-quantile plot of a sample against a theoretical distribution, with mark_qq_line() adding the reference line. All respect a mapped color/fill grouping.

Usage

mark_ecdf(plot, ..., blend = NULL, sketch = NULL, data = NULL)

mark_rug(plot, ..., sides = "bl", length = 0.03, blend = NULL, data = NULL)

mark_qq(
  plot,
  ...,
  distribution = "qnorm",
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_qq_line(
  plot,
  ...,
  distribution = "qnorm",
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_ecdf(x = mpg)
vplot(mtcars) |> mark_point(x = wt, y = mpg) |> mark_rug()
vplot(mtcars) |> mark_qq(sample = mpg) |> mark_qq_line(sample = mpg)

Description

Marks that summarise a set of ⁠(x, y)⁠ points (per group, when a color or fill is mapped) as a single enclosing region drawn over the raw points.

Usage

mark_ellipse(
  plot,
  ...,
  type = "t",
  level = 0.95,
  segments = 51L,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_hull(plot, ..., expand = 0, blend = NULL, sketch = NULL, data = NULL)

Arguments

Details

• mark_ellipse() draws a covariance ellipse: a t distribution (type = "t", the default, robustly estimated via MASS), a multivariate normal ("norm"), or a Euclidean circle of radius level ("euclid"). The algorithm follows ggplot2's stat_ellipse().

• mark_hull() draws the convex hull of the points.

Both are unfilled by default (a boundary), matching ggplot2; map or set a fill to shade the region. A region needs at least 3 points per group; smaller groups are skipped with a warning.

Value

The modified PlotSpec.

Examples

vplot(iris) |>
  mark_point(x = Sepal.Length, y = Sepal.Width, color = Species) |>
  mark_ellipse(x = Sepal.Length, y = Sepal.Width, color = Species)
vplot(iris) |>
  mark_point(x = Sepal.Length, y = Sepal.Width, color = Species) |>
  mark_hull(x = Sepal.Length, y = Sepal.Width, color = Species)

Description

Draw a node-link diagram on a PlotSpec from vgraph(). mark_edges() draws the edges (straight lines, batched), mark_nodes() the vertices (points), mark_node_text() the vertex labels, and mark_edge_text() labels on the edges. Draw order is fixed regardless of the order you pipe them: edges under edge labels under nodes under node labels. Edges (and edge labels) default to the edge table (vgraph()'s edge_data), nodes and node labels to the node table; the x/y/xend/yend/label/name columns those tables carry are mapped automatically, so bare mark_edges() |> mark_nodes() just works.

Usage

mark_edges(
  plot,
  ...,
  color = NULL,
  linewidth = NULL,
  alpha = NULL,
  linetype = NULL,
  arrow = FALSE,
  routing = c("straight", "elbow"),
  elbow_at = c("mid", "start", "end"),
  elbow_axis = c("auto", "v", "h"),
  gradient = FALSE,
  auto = FALSE,
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

mark_edge_bundle(
  plot,
  ...,
  type = c("force", "divided", "stub", "path", "hammer", "mingle"),
  color = NULL,
  linewidth = NULL,
  alpha = NULL,
  linetype = NULL,
  params = list(),
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

mark_flow_map(
  plot,
  ...,
  root,
  type = c("spiral", "steiner"),
  weight = NULL,
  width_range = c(0.3, 3),
  color = NULL,
  alpha = NULL,
  params = list(),
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

mark_nodes(
  plot,
  ...,
  size = NULL,
  shape = NULL,
  fill = NULL,
  color = NULL,
  alpha = NULL,
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

mark_node_text(
  plot,
  ...,
  label = NULL,
  color = NULL,
  size = NULL,
  alpha = NULL,
  dist = 0,
  top_n = NULL,
  by = NULL,
  repel = FALSE,
  box_padding = 1,
  point_padding = 1,
  min_segment_length = 2,
  seed = NULL,
  effects = list(),
  blend = NULL,
  data = NULL
)

mark_edge_text(
  plot,
  ...,
  label = NULL,
  color = NULL,
  size = NULL,
  alpha = NULL,
  angle = NULL,
  effects = list(),
  blend = NULL,
  data = NULL
)

mark_node_hull(
  plot,
  ...,
  fill = NULL,
  color = NULL,
  alpha = 0.25,
  expand = 0.08,
  data = NULL
)

mark_node_pie(
  plot,
  cols,
  ...,
  size = 4,
  inner = 0,
  fill = NULL,
  color = "white",
  linewidth = 0.5,
  alpha = NA,
  data = NULL
)

Arguments

Details

Edge colour, opacity, and line type train on their own scales (scale_edge_color(), scale_edge_alpha(), scale_edge_linetype(), plus scale_edge_width()), independent of the node colour/alpha/linetype scales – so a plot can map node fill to a discrete community and edge colour to a continuous weight without the two legends colliding.

mark_node_text() has the label-legibility tools a dense graph needs: repel = TRUE nudges overlapping labels apart with leader lines, dist pushes labels radially clear of the node markers, top_n/by label only the hubs, and effects = list(shadow()) drops a shadow behind each label so it stays readable over edges. mark_edge_text() takes the same effects. (Only shadow() applies to text; a glyph outline / glow is not available yet.)

Two more decorations: mark_node_hull() shades communities with a convex hull behind the graph (grouped by a mapped fill, drawn under the edges), and mark_node_pie() replaces node markers with pie / donut glyphs whose wedges come from a set of compositional columns.

mark_edge_bundle() is a drop-in alternative to mark_edges() that routes the edges as bundled curves instead of straight lines, so a hairball collapses into a few legible trunks. It delegates the geometry to the edgebundle package (install it) and draws the returned paths with the edge aesthetics – type picks the algorithm ("force", "divided", "stub", "path", "hammer", "mingle") and params passes tuning through. Bundled edges are faint by default (alpha = 0.3) so overlapping trunks read as density.

mark_flow_map() draws a flow map: a single root fans out to many destinations along smooth, merging branches whose width tracks the flow volume (the Minard / migration-map idiom). It expects a one-to-many (star) graph rooted at root, laid out at fixed coordinates; edge weight drives the flow. type = "spiral" (default, an angle-restricted spiral tree) needs only edgebundle; type = "steiner" (an approximate Steiner tree) additionally needs interp. Branch width is mapped from the computed flow into width_range, and each branch is drawn as one tapering ribbon: where tributaries merge and the flow changes along a branch, the width varies continuously rather than stepping. (That only arises for type = "steiner", whose flow is per-vertex; a spiral tree's flow is constant along each branch.) A ⁠sketch =⁠ flow map falls back to one uniform stroke per branch, since a hand-drawn ribbon would jitter its outline rather than the pen.

These are thin over the point / segment / text marks; igraph need not be installed to use them (only vgraph() needs it). mark_edge_bundle() and mark_flow_map() also need the edgebundle package.

Value

The modified PlotSpec.

See Also

vgraph(), scale_edge_width(), scale_edge_color()

Examples

## Not run: 
g <- igraph::make_graph("Zachary")
vgraph(g) |>
  mark_edges(alpha = 0.5) |>
  mark_nodes(size = 4, fill = "steelblue")

## End(Not run)

Description

Marks for visualising a distribution's shape and its summary intervals together, in the style of the ggdist package — a natural fit for posterior draws or bootstrap samples (one row per draw, grouped by a categorical x).

Usage

mark_halfeye(
  plot,
  ...,
  .width = c(0.66, 0.95),
  point = "median",
  adjust = 1,
  scale = 0.9,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_interval(
  plot,
  ...,
  .width = c(0.66, 0.95),
  point = "median",
  blend = NULL,
  data = NULL
)

Arguments

Details

• mark_halfeye() draws, per x category, a one-sided density "slab" (a half violin) with a point-interval at its base: the median (or mean) as a point, a thick bar for the inner interval and a thin bar for the outer one.

• mark_interval() draws the point-interval alone (no slab).

Intervals are equal-tailed quantile intervals at the .width probabilities (widest drawn thinnest). Supply many draws per x (e.g. posterior samples).

Value

The modified PlotSpec.

Examples

set.seed(1)
draws <- data.frame(
  grp = rep(c("a", "b", "c"), each = 400),
  val = rnorm(1200, rep(c(0, 1, 2), each = 400))
)
vplot(draws) |> mark_halfeye(x = grp, y = val)
vplot(draws) |> mark_interval(x = grp, y = val)

Description

Marks that apply a statistical transform before drawing. mark_histogram() bins a continuous x and draws the per-bin counts as bars. mark_smooth() fits a model of y on x (per group) and draws the fitted line, with a confidence ribbon when se = TRUE.

Usage

mark_histogram(
  plot,
  ...,
  bins = 30,
  position = "stack",
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_smooth(
  plot,
  ...,
  method = "auto",
  formula = NULL,
  span = 0.75,
  se = TRUE,
  level = 0.95,
  method.args = list(),
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

Details

mark_smooth() supports several methods:

• "auto" (default) picks "loess" for small groups (< 1000 points) and "gam" for large ones.

• "lm" / "glm" — linear and generalised linear fits (glm takes a family via method.args, e.g. binomial() for logistic).

• "loess" — local regression, controlled by span.

• "gam" — a generalised additive model with a smooth term (default y ~ s(x)); needs the mgcv package.

• "rq" — quantile regression at a single method.args$tau (default the median); needs the quantreg package and draws the fitted line only (no confidence ribbon). For several quantiles, add one layer per tau.

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_histogram(x = mpg, bins = 10)
vplot(mtcars) |> mark_point(x = wt, y = mpg) |> mark_smooth(x = wt, y = mpg)
# local regression with a wider neighbourhood
vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  mark_smooth(x = wt, y = mpg, method = "loess", span = 0.9)

Description

mark_image() draws a bitmap image (e.g. a flag or logo) at each ⁠(x, y)⁠, replacing the usual point marker. src is a column of local image file paths (per datum) or a single constant path (the same image at every point). Images are sized by size (height in millimetres); each image's native aspect ratio is preserved.

Usage

mark_image(
  plot,
  ...,
  src = NULL,
  size = 5,
  nudge_x = 0,
  nudge_y = 0,
  interpolate = TRUE,
  blend = NULL,
  data = NULL
)

Arguments

Details

Reading image files requires the suggested magick package (which decodes PNG, JPEG, SVG, GIF and more); mark_image() errors with an install hint if it is not available.

Value

The modified PlotSpec.

Examples

## Not run: 
d <- data.frame(x = 1:3, y = c(2, 1, 3),
                flag = c("de.png", "fr.png", "it.png"))
vplot(d) |> mark_image(x = x, y = y, src = flag, size = 8)

## End(Not run)

Description

mark_outlier_label() labels only the outlying points — the extremes, where the story usually is — instead of every datum. It keeps the rows whose y is an outlier (per colour/fill group) and labels just those, repelled apart with the same solver as mark_text(). Layer it over the raw points.

Usage

mark_outlier_label(
  plot,
  ...,
  method = c("iqr", "sd"),
  k = 1.5,
  size = NULL,
  repel = TRUE,
  box_padding = 1,
  min_segment_length = 2,
  blend = NULL,
  data = NULL
)

Arguments

Details

The default method = "iqr" flags y outside ⁠[Q1 - k*IQR, Q3 + k*IQR]⁠ (the boxplot whisker rule); method = "sd" flags ⁠|y - mean| > k * sd⁠. Map a label to name each outlier; with none mapped, the outlier's y value is the label.

Value

The modified PlotSpec.

See Also

mark_text(), mark_boxplot()

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  mark_outlier_label(x = wt, y = mpg, label = rownames(mtcars))

Description

Convenience marks for part-of-whole charts. mark_pie() draws a pie: each value becomes a wedge whose angle is its share of the total, coloured by fill. mark_donut() is a pie with a hollow centre (inner_radius, a fraction of the radius). Both are shorthand for a stacked bar projected through coord_polar() with theta = "y", which they set on the plot; they error if the plot already carries a non-polar coordinate.

Usage

mark_pie(
  plot,
  value,
  fill = NULL,
  ...,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_donut(
  plot,
  value,
  fill = NULL,
  inner_radius = 0.5,
  ...,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

Value

The modified PlotSpec.

See Also

coord_polar()

Examples

df <- data.frame(part = c("a", "b", "c"), n = c(3, 5, 2))
vplot(df) |> mark_pie(value = n, fill = part)
vplot(df) |> mark_donut(value = n, fill = part, inner_radius = 0.6)

Description

Each ⁠mark_*()⁠ appends a drawing layer to a PlotSpec. Encodings are bare column names (or expressions) captured with tidy evaluation, e.g. ⁠x = wt, y = mpg, color = hp⁠. Scalar values (e.g. size = 3, color = "red") are treated as constant aesthetics rather than data mappings.

Usage

mark_point(
  plot,
  ...,
  size = NULL,
  shape = NULL,
  position = "identity",
  auto = FALSE,
  seed = NULL,
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

mark_line(
  plot,
  ...,
  window = NULL,
  auto = FALSE,
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

mark_rule(
  plot,
  ...,
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

mark_bar(
  plot,
  ...,
  position = "stack",
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

Details

mark_bar() draws bars from a zero baseline. With an explicit y it uses the y values as heights; with no y it counts rows per category (the "count" stat). When color/fill is mapped, grouped bars are stacked by default; use position = "dodge" for side-by-side bars or "fill" to normalise to 1.

Value

The modified PlotSpec.

Interactivity

Any mark accepts reserved, per-row arguments (captured like encodings, via tidy evaluation) that make its elements addressable — and stylable — by an interactive host without changing what a static render draws:

• data_id — a per-element data key (e.g. data_id = model). Emitted by the SVG backend as data-key on each element and returned by vellum::scene_model(); it is the join key a host uses to map a hover/click back to a datum, and to link the same datum across views.

• tooltip — per-element tooltip text (a column expression or a constant), surfaced in scene_model() metadata.

• hover_group — a field grouping elements for linked emphasis (consumed by a host in a later phase).

• hover_color, selected_color — per-element outline colours applied by the host when the element is hovered / selected (a constant, or mapped from a column so different marks highlight differently). They override the widget-wide theme set by vellumwidget::as_widget(hover_color=, selected_color=).

These are inert for PNG/PDF and for an SVG opened without a JS host: a plot with none of them compiles and renders exactly as before. Declaring any of them without data_id defaults the key to the row index, so the element is still addressable. They currently apply to stat = "identity" marks (points, bars, tiles, segments, edges, hexbins, sf features, …); aggregating stats (histogram/count/density) drop them, since rows no longer map 1:1 to elements.

How these flow into the vellum scene (the scene_model() element table, the SVG data-key / ⁠data-vellum-*⁠ attributes, and the reserved meta key vocabulary) is described in vellum's "The scene contract" vignette (vignette("scene-contract", package = "vellum")).

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg, color = hp)

# Declare interactivity (inert on a static render):
df <- data.frame(wt = mtcars$wt, mpg = mtcars$mpg, model = rownames(mtcars))
vplot(df) |> mark_point(x = wt, y = mpg, tooltip = model, data_id = model)

Description

mark_raincloud() is a convenience that composes a raincloud: a one-sided density "cloud" (mark_halfeye()) with the raw observations as "rain" below it (mark_point() with sina spread). It is exactly plot |> mark_halfeye(...) |> mark_point(..., position = position_sina()), so any color/fill mapping in ... flows to both layers.

Usage

mark_raincloud(plot, x, y, ..., width = 0.4, alpha = 0.5)

Arguments

Value

The modified PlotSpec.

See Also

mark_halfeye(), position_sina()

Examples

set.seed(1)
d <- data.frame(g = rep(c("a", "b", "c"), each = 100),
                y = rnorm(300, rep(c(0, 1, 2), each = 100)))
vplot(d) |> mark_raincloud(x = g, y = y)

Description

mark_segment() draws a straight line from ⁠(x, y)⁠ to ⁠(xend, yend)⁠ per row.

Usage

mark_segment(
  plot,
  ...,
  auto = FALSE,
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

Arguments

Value

The modified PlotSpec.

See Also

scale_linewidth()

Examples

d <- data.frame(x = 1, y = 1, xend = 5, yend = 4)
vplot(d) |> mark_segment(x = x, y = y, xend = xend, yend = yend)