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

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

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", and "rect".

Usage

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

Arguments

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)

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

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

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.

Usage

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

Arguments

Value

The modified PlotSpec.

See Also

mark_pie(), mark_donut()

Examples

vplot(mtcars) |> mark_bar(x = factor(cyl)) |> coord_polar(theta = "x")

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)

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()

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")

## 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

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,
  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

A render effect for stroked and point marks, in the spirit of mplcyberpunk: the mark is drawn as several widened, low-opacity copies composited additively (a "screen" blend) beneath the crisp original, producing 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(), and mark_nodes(); other marks reject it with an error.

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

guides() overrides the legend (guide) for one or more aesthetics without respelling the whole ⁠scale_*()⁠. Pass "none" (or guide_none()) to hide a legend, or guide_legend() to tweak it (reverse the key order, override the title). 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)

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))

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

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

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",
  blend = NULL,
  effects = list(),
  sketch = NULL,
  data = NULL
)

Arguments

Value

The modified PlotSpec.

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)

Arguments

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. Requires the isoband package.

Usage

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

mark_contour_filled(
  plot,
  ...,
  bins = 10,
  binwidth = NULL,
  breaks = NULL,
  n = 100,
  blend = 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

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. Per-point colour/size aesthetics do not apply; cell colour encodes density.

Usage

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

Arguments

Details

Categorical shading (à la datashader's count_cat) has no single-call form, but is reproduced by stacking one datashade layer per category — each with a colors ramp from black to its hue — composited with blend = "screen", so overlapping densities mix additively.

Value

The modified PlotSpec.

Examples

n <- 1e5
d <- data.frame(x = rnorm(n), y = rnorm(n))
vplot(d) |> mark_datashade(x = x, y = y)

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, data = NULL)

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

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

mark_qq_line(plot, ..., distribution = "qnorm", blend = 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

Draw a node-link diagram on a PlotSpec from vgraph(). mark_edges() draws the edges (straight lines, batched), mark_nodes() the vertices (points), and mark_node_text() the vertex labels. Draw order is fixed regardless of the order you pipe them: edges under nodes under labels. Edges default to the edge table (vgraph()'s edge_data), nodes and 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,
  arrow = FALSE,
  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,
  blend = NULL,
  data = NULL
)

Arguments

Details

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

Value

The modified PlotSpec.

See Also

vgraph(), scale_edge_width()

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 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 ("lm" for now) of y on x 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 = "lm",
  se = TRUE,
  level = 0.95,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

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)

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 (hole, 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, ..., sketch = NULL, data = NULL)

mark_donut(
  plot,
  value,
  fill = NULL,
  hole = 0.5,
  ...,
  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, hole = 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,
  ...,
  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_segment() draws a straight line from ⁠(x, y)⁠ to ⁠(xend, yend)⁠ per row.

Usage

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

Arguments

Value

The modified PlotSpec.

Examples

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

Description

mark_sf() draws the geometry column of an sf object as a map layer: POINT/MULTIPOINT render as points, LINESTRING/MULTILINESTRING as polylines, and POLYGON/MULTIPOLYGON as filled paths (holes cut with the even-odd rule, so ring winding need not be canonical). Coordinates come from the geometry, so there are no x/y encodings; other aesthetics map feature attributes as usual, e.g. fill = AREA for a choropleth. Pair with coord_sf() to reproject and lock the map aspect ratio.

Usage

mark_sf(
  plot,
  ...,
  fill = NULL,
  color = NULL,
  alpha = NULL,
  linewidth = NULL,
  size = NULL,
  na_value = "grey80",
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

Details

sf is an optional dependency (in Suggests); mark_sf() errors with an install hint if it is not available.

Value

The modified PlotSpec.

See Also

coord_sf(), scale_fill_binned()

Examples

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

## End(Not run)

Description

mark_text() draws the label aesthetic as text at each ⁠(x, y)⁠; mark_label() adds a filled rounded background behind each label. size is the font size in points; angle (degrees) may be mapped or constant.

Usage

mark_text(
  plot,
  ...,
  size = NULL,
  family = NULL,
  fontface = NULL,
  hjust = "centre",
  vjust = "centre",
  angle = NULL,
  nudge_x = 0,
  nudge_y = 0,
  blend = NULL,
  data = NULL
)

mark_label(
  plot,
  ...,
  size = NULL,
  family = NULL,
  fontface = NULL,
  hjust = "centre",
  vjust = "centre",
  angle = NULL,
  nudge_x = 0,
  nudge_y = 0,
  fill = "white",
  blend = NULL,
  sketch = NULL,
  data = NULL
)

Arguments

Details

The label for mark_text() may be plain text (embedded newlines ⁠\n⁠ wrap onto stacked lines) or rich vellum::md() labels — map ⁠label = md(<expr>)⁠ for a per-datum styled label (bold/italic/super-/subscript/colour). (Rich labels are not yet supported by mark_label()'s background box.)

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_text(x = wt, y = mpg, label = rownames(mtcars))
vplot(mtcars) |> mark_point(x = wt, y = mpg) |>
  mark_text(x = wt, y = mpg, label = rownames(mtcars), nudge_y = 2)

Description

mark_tile() draws a rectangular tile at each ⁠(x, y)⁠ coloured by fill; mark_raster() draws the same as one raster image (a fast path requiring a complete regular grid). mark_bin2d() bins continuous x/y into a grid and colours each cell by count. mark_density() draws a 1-D kernel density of x as a filled curve.

Usage

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

mark_raster(plot, ..., blend = NULL, data = NULL)

mark_bin2d(plot, ..., bins = 30, blend = NULL, data = NULL)

mark_density(plot, ..., adjust = 1, blend = NULL, sketch = NULL, data = NULL)

mark_hex(plot, ..., bins = 30, blend = NULL, data = NULL)

Arguments

Value

The modified PlotSpec.

Examples

d <- expand.grid(x = 1:5, y = 1:5)
d$z <- d$x * d$y
vplot(d) |> mark_tile(x = x, y = y, fill = z)

Description

Marks that draw a variable's distribution as a filled shape. mark_violin() draws a mirrored kernel density of y per categorical x (like a boxplot's footprint); mark_ridgeline() draws a kernel density of x per categorical y as overlapping ridges. mark_dotplot() bins x and stacks one dot per observation.

Usage

mark_violin(plot, ..., adjust = 1, blend = NULL, sketch = NULL, data = NULL)

mark_ridgeline(
  plot,
  ...,
  adjust = 1,
  scale = 1.4,
  blend = NULL,
  sketch = NULL,
  data = NULL
)

mark_dotplot(plot, ..., binwidth = NULL, blend = NULL, data = NULL)

Arguments

Value

The modified PlotSpec.

Examples

df <- data.frame(g = rep(letters[1:3], each = 50), v = rnorm(150))
vplot(df) |> mark_violin(x = g, y = v)
vplot(df) |> mark_ridgeline(x = v, y = g)
vplot(df) |> mark_dotplot(x = v)

Description

A thin wrapper around vellum::md() that builds a rich-text label from a markdown subset: ⁠**bold**⁠, ⁠*italic*⁠ / ⁠_italic_⁠, ⁠^superscript^⁠, ⁠~subscript~⁠, and a colour span ⁠[text]{#c00}⁠. The result can be used anywhere vellumplot draws a title: labs() (title / subtitle / caption / tag / x / y / color) and ⁠scale_*(name = )⁠. Per-element rich labels (in mark_text()) are not yet supported.

Usage

md(text)

Arguments

Value

A vellum_md_label object accepted by vellum::text_grob().

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  labs(title = md("**Fuel** economy"), y = md("Efficiency (mi gal^-1^)"))

Description

Draws one opaque, wider copy of a stroked or point mark beneath the crisp original in a contrasting colour, so the mark stays legible over a busy or dark backdrop (the "sticker" look). Applies to the same marks as glow().

Usage

outline(size = 1, color = "white", alpha = 1)

Arguments

Value

An OutlineSpec object for a mark's effects list.

See Also

glow(), shadow()

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = factor(cyl), size = 3,
    effects = list(outline()))

Description

Returns the description used as the plot's text alternative for assistive technology. If labs() set an explicit alt, that string is returned verbatim; otherwise vellumplot generates a prose summary from the specification — the chart type, what each axis / colour / size encodes, the number of observations, and any faceting.

Usage

plot_alt(x)

Arguments

Details

render_plot() (and any compile through vellum::as_vellum_scene()) passes this text to the scene's description, so the exported SVG carries it in ⁠<desc>⁠ (with role="img") and the exported PDF tags the chart as a Figure whose Alt is this text. The plot title (from labs(title=)) becomes the accessible name. See the Accessibility article.

Value

A single string.

See Also

labs(), vellum::describe()

Examples

p <- vplot(mtcars) |> mark_point(x = wt, y = mpg, color = hp)
plot_alt(p)
plot_alt(labs(p, alt = "Heavier cars get fewer miles per gallon."))

Description

Compiles x and returns its provenance table: one record per emitted mark grob, tying each low-level primitive back to the data rows and trained scales that produced it. Each record's id matches the grob's data-vellum-id in the SVG output (and the id column of vellum::scene_model()), so it is a stable join key between the rendered scene and the grammar — the substrate for interactivity, linked views, and accessibility.

Usage

plot_provenance(x)

Arguments

Details

Each record is a plain, serializable list:

id

stable node id, equal to grob@id / SVG data-vellum-id (join key).

layer

1-based layer index within the (sub-)plot spec.

mark

mark type ("point", "line", …).

kind

"mark" (the core layer) or "effect" (a decorative underlay).

panel

facet panel key ("panel-r-c"), or NA for a single panel.

channels

aesthetic → trained-scale reference (scale, type, domain).

rows

the original input-data row indices this grob draws.

The rows field is refined per element for marks that map rows one-to-one to drawn elements (points, bars, tiles, segments, lines, areas, ribbons, steps, text, boxplots, sf features, edges); for aggregating marks (histogram, density, smooth, datashade, …) it is the whole layer, since rows no longer map to single elements.

Value

A list of provenance records (see Details). Empty for a plot that emits no mark grobs.

See Also

vellum::scene_model() and the scene-contract vignette in vellum.

Examples

df <- data.frame(wt = mtcars$wt, mpg = mtcars$mpg, model = rownames(mtcars))
p <- vplot(df) |> mark_point(x = wt, y = mpg, data_id = model)
prov <- plot_provenance(p)
prov[[1]]$id

Description

Use inside concat() / wrap_plots() (or a design) to leave a gap.

Usage

plot_spacer()

Value

A spacer placeholder.

Examples

a <- vplot(mtcars) |> mark_point(x = wt, y = mpg)
concat(a, plot_spacer(), a, plot_spacer(), ncol = 2)

Description

PlotSpec is the S7 class that vplot() creates and the ⁠mark_*()⁠ / ⁠scale_*()⁠ functions extend. It is a plain, inspectable, serializable data object: data, a list of layers, a list of scale overrides, and the page size. Nothing is drawn until it is compiled with vellum::as_vellum_scene() (e.g. via render_plot()). Printing it draws the plot; inspect its structure with summary().

Usage

PlotSpec(
  data = NULL,
  edge_data = NULL,
  layers = list(),
  scales = list(),
  facet = NULL,
  coord = NULL,
  resolve = list(),
  width = 6,
  height = 4,
  dpi = 96,
  theme = NULL,
  labels = list(),
  marginal = NULL
)

Arguments

Value

A PlotSpec.

See Also

vplot(), mark_point(), scale_x_continuous()

Description

Compiles a PlotSpec into a vellum::vl_scene() and writes it. The output format is taken from the file extension (.png, .svg, .pdf). vellum::render() also works on a plot directly, dispatching through the as_vellum_scene() seam.

Usage

render_plot(plot, path, text = "native", dpi = NULL)

Arguments

Value

path, invisibly.

Examples

p <- vplot(mtcars) |> mark_point(x = wt, y = mpg)
f <- tempfile(fileext = ".png")
render_plot(p, f)
render_plot(p, f, dpi = 300) # denser raster, same physical size

Description

Replicate a plot, re-pointing one or more encodings at a different data field each time, and arrange the copies as a composition (like concat(), so each sub-plot keeps its own scales and axes). Supply each aesthetic as a character vector of column names; all vectors must be the same length N, and are zipped to produce N sub-plots.

Usage

repeat_(plot, ..., ncol = NULL, nrow = NULL)

Arguments

Value

A PlotComposition.

Examples

repeat_(vplot(mtcars) |> mark_point(y = mpg), x = c("wt", "hp", "disp"))

Description

The scale-resolution lattice (after Vega-Lite): for each aesthetic, choose whether faceted panels share one trained scale or train independent ones. Position scales default to "shared"; facet_*(scales = "free_*") is sugar for setting x/y to "independent".

Usage

resolve_scale(plot, ...)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> facet_wrap(~cyl) |>
  resolve_scale(y = "independent")

Description

Declare the scale for a mapped alpha aesthetic: data values map to an opacity range in ⁠[0, 1]⁠. An alpha legend is drawn automatically.

Usage

scale_alpha(plot, range = NULL, limits = NULL, breaks = NULL, name = NULL)

scale_alpha_continuous(
  plot,
  range = NULL,
  limits = NULL,
  breaks = NULL,
  name = NULL
)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg, alpha = hp) |> scale_alpha(range = c(0.2, 1))

Description

Declare a colour scale for the color/fill channel. Continuous data get a perceptual ramp; discrete data get a qualitative palette. ⁠scale_*_manual()⁠ sets exact colours, ⁠scale_*_gradient()⁠ a two-point ramp. The fill variants are identical (colour and fill share one scale). A legend is drawn automatically when colour is mapped.

Usage

scale_color_continuous(
  plot,
  palette = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_color_discrete(
  plot,
  palette = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_color_manual(plot, values, name = NULL)

scale_color_gradient(plot, low = "#132B43", high = "#56B1F7", name = NULL)

scale_fill_continuous(
  plot,
  palette = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_fill_discrete(
  plot,
  palette = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_fill_manual(plot, values, name = NULL)

scale_fill_gradient(plot, low = "#132B43", high = "#56B1F7", name = NULL)

scale_colour_continuous(
  plot,
  palette = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_colour_discrete(
  plot,
  palette = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_colour_manual(plot, values, name = NULL)

scale_colour_gradient(plot, low = "#132B43", high = "#56B1F7", name = NULL)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg, color = hp) |>
  scale_color_continuous(palette = "Batlow")

Description

Use the data values directly as the aesthetic — no training and no legend. The mapped column must already contain valid aesthetic values: colours for scale_color_identity() / scale_fill_identity(), sizes in mm for scale_size_identity(), and shape names for scale_shape_identity(). Useful when a column already holds the exact colours/sizes you want to draw.

Usage

scale_color_identity(plot)

scale_fill_identity(plot)

scale_colour_identity(plot)

scale_size_identity(plot)

scale_shape_identity(plot)

scale_alpha_identity(plot)

scale_linetype_identity(plot)

Arguments

Value

The modified PlotSpec.

Examples

df <- data.frame(x = 1:3, y = 1:3, col = c("red", "green", "blue"))
vplot(df) |> mark_point(x = x, y = y, color = col) |> scale_color_identity()

Description

Declare the scale for a mapped edge linewidth aesthetic (e.g. mark_edges(linewidth = weight) on a vgraph() plot). The data range is rescaled to a line-width range and an edge-width legend is drawn automatically.

Usage

scale_edge_width(plot, range = NULL, limits = NULL, breaks = NULL, name = NULL)

Arguments

Value

The modified PlotSpec.

See Also

mark_edges(), vgraph()

Examples

## Not run: 
g <- igraph::sample_gnp(20, 0.2)
g <- igraph::set_edge_attr(g, "w", value = runif(igraph::ecount(g)))
vgraph(g) |> mark_edges(linewidth = w) |> mark_nodes() |> scale_edge_width(range = c(0.3, 4))

## End(Not run)

Description

scale_fill_binned() / scale_color_binned() cut a continuous aesthetic into classes and colour each class with one step of a sequential palette — the standard choropleth scale. Class breaks are chosen by a classification style. quantile, equal, and pretty need no extra packages; other styles (e.g. "jenks", "fisher", "kmeans", "headtails") delegate to the optional classInt package (in Suggests) and error if it is absent.

Usage

scale_fill_binned(
  plot,
  style = "quantile",
  n = 5,
  breaks = NULL,
  palette = NULL,
  labels = NULL,
  na_value = "grey80",
  name = NULL
)

scale_color_binned(
  plot,
  style = "quantile",
  n = 5,
  breaks = NULL,
  palette = NULL,
  labels = NULL,
  na_value = "grey80",
  name = NULL
)

Arguments

Value

The modified PlotSpec.

See Also

mark_sf(), scale_fill_continuous()

Examples

## Not run: 
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
vplot(nc) |>
  mark_sf(fill = SID74) |>
  scale_fill_binned(style = "quantile", n = 5) |>
  coord_sf()

## End(Not run)

Description

Declare the scale for a mapped (discrete) linetype aesthetic. Levels cycle through a default set of line types unless values is given. A line-type legend is drawn automatically. Applies to line-like marks (mark_line(), mark_step()).

Usage

scale_linetype(plot, values = NULL, name = NULL)

scale_linetype_discrete(plot, values = NULL, name = NULL)

Arguments

Value

The modified PlotSpec.

Examples

df <- data.frame(x = rep(1:10, 2), y = rnorm(20), g = rep(c("a", "b"), each = 10))
vplot(df) |> mark_line(x = x, y = y, linetype = g)

Description

Declare the scale for a mapped (discrete) shape aesthetic. Levels cycle through a default set of marker shapes unless values is given. A shape legend is drawn automatically.

Usage

scale_shape(plot, values = NULL, name = NULL)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg, shape = factor(cyl))

Description

Declare the scale for a mapped size aesthetic: data values map linearly to a point-size range (in mm). A size legend is drawn automatically.

Usage

scale_size(plot, range = NULL, limits = NULL, breaks = NULL, name = NULL)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg, size = hp) |> scale_size(range = c(1, 8))

Description

scale_x_binned() / scale_y_binned() cut a continuous position variable into bins: axis ticks fall at the bin boundaries and each datum is drawn at its bin centre. Breaks use the same classification as the binned colour scales (style/n; classInt for jenks/fisher/… — a Suggest). Handy to summarise a dense continuous axis, or to place mark_bar() on a binned continuous x.

Usage

scale_x_binned(
  plot,
  style = "pretty",
  n = 10,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_y_binned(
  plot,
  style = "pretty",
  n = 10,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> scale_x_binned(n = 6)

Description

Declare a position scale to override the trained default. scale_x_continuous() / scale_y_continuous() handle numeric (and date/time) axes; scale_x_discrete() / scale_y_discrete() handle categorical (band) axes and let you set the level order via limits.

Usage

scale_x_continuous(
  plot,
  limits = NULL,
  trans = "identity",
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_y_continuous(
  plot,
  limits = NULL,
  trans = "identity",
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_x_discrete(plot, limits = NULL, name = NULL)

scale_y_discrete(plot, limits = NULL, name = NULL)

Arguments

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> scale_x_continuous(limits = c(0, 6))
vplot(mtcars) |> mark_point(x = wt, y = mpg) |> scale_y_continuous(trans = "sqrt")

Description

Position scales for Date (⁠scale_*_date⁠), date-time POSIXct (⁠scale_*_datetime⁠), and time-of-day / difftime / hms (⁠scale_*_time⁠) axes. A Date/POSIXct column already gets a sensible date axis automatically; declare one of these to control the break interval or the label format.

Usage

scale_x_date(
  plot,
  limits = NULL,
  date_breaks = NULL,
  date_labels = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_y_date(
  plot,
  limits = NULL,
  date_breaks = NULL,
  date_labels = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_x_datetime(
  plot,
  limits = NULL,
  date_breaks = NULL,
  date_labels = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_y_datetime(
  plot,
  limits = NULL,
  date_breaks = NULL,
  date_labels = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_x_time(
  plot,
  limits = NULL,
  date_breaks = NULL,
  date_labels = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

scale_y_time(
  plot,
  limits = NULL,
  date_breaks = NULL,
  date_labels = NULL,
  breaks = NULL,
  labels = NULL,
  name = NULL
)

Arguments

Value

The modified PlotSpec.

Examples

df <- data.frame(day = as.Date("2020-01-01") + 0:364, y = cumsum(rnorm(365)))
vplot(df) |>
  mark_line(x = day, y = y) |>
  scale_x_date(date_breaks = "3 months", date_labels = "%b %Y")

Description

Draws dark, low-opacity copies of a stroked or point mark beneath the original, offset by (x, y) and softened by stacking a few widened copies — a drop shadow (with an offset) or an ambient shadow (offset 0). Applies to the same marks as glow().

Usage

shadow(
  x = 0.5,
  y = -0.5,
  color = "black",
  alpha = 0.3,
  spread = 1.5,
  layers = 3L
)

Arguments

Details

The offset is an absolute distance in millimetres (+x right, +y up), resolved device-side, so a drop shadow stays the same physical distance and is isotropic regardless of the panel's size or aspect (via vellum's compound npc + mm unit).

Value

A ShadowSpec object for a mark's effects list.

See Also

glow(), outline()

Examples

df <- data.frame(x = 1:20, y = cumsum(rnorm(20)))
vplot(df) |> mark_line(x = x, y = y, effects = list(shadow()))

Description

A re-export of vellum::sketch() — the one vocabulary vellumplot speaks for the hand-drawn look (wobbly outlines, hachure fills, à la Rough.js). Pass a sketch() value to any mark's ⁠sketch =⁠ argument, to an element_line() / element_rect() ⁠sketch =⁠ slot, or set it plot-wide with theme_sketch():

Usage

sketch(...)

Arguments

Details

vplot(mpg) |> mark_point(x = displ, y = hwy, sketch = sketch(roughness = 1.2))

Sketch is a geometry property, not a layer effect: it perturbs the mark itself (its wobble is generated natively in the vellum engine, so it is exact, cross-backend, and works in PDF), rather than compositing extra copies. Text is never sketched — pair a handwriting family with it for a fully hand-drawn plot.

Resolution is most-specific-wins: a mark's ⁠sketch =⁠ beats an element slot, which beats the plot-wide theme_sketch() default. At any level sketch = NA (or FALSE) forces that element crisp, overriding a broader default; sketch = NULL inherits.

Value

A vellum_sketch object.

See Also

theme_sketch(), mark_point(), element_line()

Examples

vplot(mtcars) |>
  mark_point(x = wt, y = mpg, sketch = sketch(roughness = 1.5, seed = 7))

Description

Control the non-data look of a plot. theme_gray() is the default (grey panel, white gridlines); theme_minimal() drops the panel fill for light gridlines on the page; theme_bw() is a white panel with light grey gridlines; theme_classic() has axis lines and no gridlines; theme_void() strips everything but the marks, legend, and titles; theme_cyberpunk() is a dark neon theme (see Details).

Usage

theme_gray(plot)

theme_minimal(plot)

theme_bw(plot)

theme_classic(plot)

theme_void(plot)

theme_cyberpunk(plot)

theme(plot, ...)

set_theme(
  plot,
  panel_bg = NULL,
  grid_col = NULL,
  label_col = NULL,
  strip_bg = NULL
)

Arguments

Details

theme() overrides individual elements on top of the current theme using element_text() / element_line() / element_rect() / element_blank(). set_theme() is a small back-compatible shortcut for the most common colours.

theme_cyberpunk() sets a dark canvas with dim neon gridlines and a bright neon default palette (both discrete and continuous), in the spirit of mplcyberpunk. It pairs with the glow() layer effect and linear_gradient() fills for the full neon look; the palette is only a default, so ⁠scale_*⁠ overrides still win.

Value

The modified PlotSpec.

Examples

vplot(mtcars) |> mark_point(x = wt, y = mpg) |> theme_minimal()
vplot(mtcars) |>
  mark_point(x = wt, y = mpg) |>
  theme(panel.grid.minor = element_blank(), legend.position = "none")

Description

theme_sketch() turns a whole plot hand-drawn in one line: it sets a plot-wide sketch() default that every geometry mark and theme element inherits (wobbly gridlines, axis lines, ticks, and marks), on a warm paper-toned background. Text is never sketched — pass a handwriting font to complete the look.

Usage

theme_sketch(
  plot,
  roughness = 1,
  bowing = 1,
  fill_style = "hachure",
  seed = 1L,
  font = NULL,
  paper = "#f4ecd8",
  ink = "#2b2b2b"
)

Arguments

Details

It is a complete theme (like theme_cyberpunk()): the sketch it sets is only a default, so any mark's ⁠sketch =⁠ argument, any element_line() / element_rect() ⁠sketch =⁠ slot, or a ⁠scale_*⁠ override still wins. Force an individual element crisp with sketch = NA.

Value

The modified PlotSpec.

See Also

sketch(), theme_gray(), mark_point()

Examples

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

# tune the wobble; a crosshatch-filled bar layer that stays crisp
df <- data.frame(g = c("a", "b", "c"), n = c(3, 5, 2))
vplot(df) |>
  mark_bar(x = g, y = n, fill = g) |>
  theme_sketch(roughness = 1.4, fill_style = "crosshatch", seed = 7)

Description

vgraph() begins a node-link diagram from an igraph graph. It computes a layout (vertex x/y), builds a node table and an edge table, and returns a PlotSpec with the aspect locked (coord_equal) and a void theme (no axes or gridlines) – publication-quality defaults with no tuning. Add layers with mark_edges(), mark_nodes(), and mark_node_text(); edges default to the edge table and nodes to the node table.

Usage

vgraph(g, layout = "stress", ..., seed = 42L, width = 6, height = 4, dpi = 96)

Arguments

Details

The default layout is stress majorization (graphlayouts::layout_with_stress): it is deterministic (same graph -> same picture) and minimizes the difference between drawn and graph-theoretic distance. Above 10^4 nodes it falls back to sparse stress automatically. Reciprocal and parallel edges are drawn as parallel straight lines offset off the centre line (not curved); self-loops as small loops.

igraph (and graphlayouts, for its layouts) are optional dependencies (in Suggests); vgraph() errors with an install hint if they are not available.

Value

A PlotSpec whose data is the node table and whose edge_data is the edge table.

See Also

mark_edges(), mark_nodes(), mark_node_text()

Examples

## Not run: 
g <- igraph::make_graph("Zachary")
vgraph(g, layout = "stress") |>
  mark_edges() |>
  mark_nodes(size = 3)

## End(Not run)

Description

vplot() begins a declarative, pipe-first plot. It captures the data and page size and returns an inspectable PlotSpec; nothing is drawn until the spec is compiled (via render_plot() or vellum::as_vellum_scene()). Build the plot up with mark_point() / mark_line() / mark_rule() and the ⁠scale_*()⁠ functions.

Usage

vplot(data, width = 6, height = 4, dpi = 96)

Arguments

Value

A PlotSpec.

Examples

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