Package 'glyph'

Description

Add animation/transition behavior

Usage

animate(
  spec,
  transition = "morph",
  duration = 500,
  stagger = 0,
  by = NULL,
  easing = "ease-in-out",
  loop = FALSE
)

Arguments

Value

Modified glyph_spec

Examples

# Entrance animation: bars grow from baseline
glyph(mtcars, x = cyl, y = mpg) |>
  mark_bar() |>
  animate(transition = "slide", stagger = 50)

# Keyframe animation: morph between groups
glyph(mtcars, x = wt, y = mpg) |>
  mark_point(size = hp, color = cyl) |>
  animate(by = gear, transition = "morph", duration = 800)

Description

Animations in glyph are declarative state transitions, not frame-by-frame rendering. You describe what changes and how it should interpolate, and the renderer handles the rest.

Details

Two animation paradigms:

• Transitions: animate between data states (e.g. year 2020 → 2021). Marks morph smoothly, entering/exiting as data changes.

• Entrances: animate marks appearing on first render (stagger bars growing from zero, points fading in).

Description

Compile a glyph spec to a resolved representation

Usage

compile(spec, engine = "auto", width = NULL, height = NULL)

## S3 method for class 'glyph_spec'
compile(spec, engine = "auto", width = NULL, height = NULL)

## S3 method for class 'glyph_layout'
compile(spec, engine = "auto", width = NULL, height = NULL)

Arguments

Value

A glyph_compiled object (a list with resolved data + JSON)

A glyph_compiled object containing the resolved spec, JSON string, and engine selection

A glyph_compiled object containing the resolved layout spec and JSON string

Description

Compose multiple glyph specs into a layout

Usage

compose(
  ...,
  type = "hstack",
  widths = NULL,
  heights = NULL,
  gap = 10,
  shared_scales = FALSE,
  linked_selections = FALSE,
  title = NULL
)

Arguments

Value

A glyph_layout object

Examples

p1 <- glyph(mtcars, x = wt, y = mpg) |> mark_point()
p2 <- glyph(mtcars, x = wt, y = hp) |> mark_point()
p3 <- glyph(mtcars, x = hp, y = mpg) |> mark_line()

# Horizontal stack
compose(p1, p2, type = "hstack")

# Grid with linked brushing
compose(p1, p2, p3, type = "wrap",
        linked_selections = TRUE, shared_scales = "x")

Description

Export to various formats

Usage

export(spec, file, width = 800, height = 600)

Arguments

Details

A single self-contained .html file needs pandoc. RStudio ships with pandoc, so this works out of the box there; elsewhere, install pandoc and make sure it is on your PATH. Without pandoc, export() still writes the .html file but puts the JavaScript it needs in a ⁠<name>_files⁠ folder next to it, and tells you so. Keep the two together when moving or sharing the plot.

Value

Invisibly returns the output file path

Description

Splits a plot into small multiples, one panel for each value of rows, cols, or both. Panels share their axes unless free_scales lets them vary. With a single faceting variable, wrap sets how many panels go in each row.

Usage

facet(spec, rows = NULL, cols = NULL, free_scales = "none", wrap = NULL)

Arguments

Value

Modified glyph_spec

Description

Entry point for the glyph grammar. Creates a specification that describes a visualization declaratively. The spec is a plain nested list: it can be inspected, serialized to JSON, and compiled into an interactive HTML widget.

Usage

glyph(data = NULL, ...)

Arguments

Value

A glyph_spec object

Examples

spec <- glyph(mtcars, x = wt, y = mpg) |>
  mark_point()
summary(spec)

Description

Add an inset plot

Usage

inset(spec, inset, position = "top-right")

Arguments

Value

Modified glyph_spec

Description

Add interactive behaviors to a glyph spec

Usage

interact(
  spec,
  tooltip = FALSE,
  zoom = FALSE,
  brush = FALSE,
  hover = NULL,
  click = NULL,
  crossfilter = FALSE,
  nearest = FALSE
)

Arguments

Value

Modified glyph_spec

Examples

glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  interact(
    tooltip = "{cyl} cylinders\n{mpg} mpg at {wt} tons",
    zoom = TRUE,
    hover = "enlarge",
    brush = TRUE,
    crossfilter = TRUE
  )

Description

Tooltips, hover effects, clicks, zoom, brushing and linked selections are part of the plot specification. They are declared with interact() and selection() in the same pipeline as the marks, stored in the spec, and run in the browser by the D3 renderer.

Details

Design philosophy: interactions are selections that filter or highlight marks. This follows Vega-Lite's insight that most interactions are really about defining subsets of the data. A tooltip is "select the nearest point, show its values." Brushing is "select points in a rectangle, highlight them."

Description

Built-in multi-plot composition. No external packages needed. Layouts can express grids, stacks, insets, marginal plots, and arbitrary nesting. Composed plots can share selections for cross-filtering (linked brushing).

Description

Draws the distribution of the x and y variables along the edges of the plot, as a histogram, density curve or boxplot.

Usage

marginals(spec, x = "histogram", y = "histogram", size = 0.15)

Arguments

Value

Modified glyph_spec

Examples

glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  marginals(x = "histogram", y = "density")

Description

Add an area mark

Usage

mark_area(spec, ..., data = NULL, style = list())

Arguments

Value

Modified glyph_spec object with the area mark added

Description

Add a bar mark

Usage

mark_bar(spec, ..., data = NULL, style = list(), orient = "vertical")

Arguments

Value

Modified glyph_spec object with the bar mark added

Description

Draws one box per group: the box spans the first to third quartile, the line inside it is the median, and the whiskers reach the most extreme values within coef times the interquartile range of the box. Values beyond the whiskers are drawn as outlier points.

Map y to the numeric variable and x to the grouping variable, which is treated as categorical even when it is numeric. Without x, all rows form one box. Mapping color to a different variable than x places one box per colour side by side within each x group.

The statistics are computed in R when the plot is compiled, using stats::quantile() with its default type = 7. Rows with a missing x or y are dropped first, with a warning.

Usage

mark_boxplot(
  spec,
  ...,
  data = NULL,
  style = list(),
  coef = 1.5,
  outliers = TRUE,
  width = 0.7
)

Arguments

Value

Modified glyph_spec object with the boxplot mark added

Examples

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

Description

Counts how many rows fall into each bin of a numeric x variable and draws one bar per bin. Bins are closed on the right, like graphics::hist(), and the lowest bin also includes its left edge. Mapping color stacks one bar segment per colour within each bin.

With neither bins nor binwidth, the number of bins follows Sturges' rule and the edges are rounded to tidy values, as in graphics::hist(). All facet panels share the same bins.

The counts are computed in R when the plot is compiled. Rows with a missing x are dropped first, with a warning.

Usage

mark_histogram(
  spec,
  ...,
  data = NULL,
  style = list(),
  bins = NULL,
  binwidth = NULL
)

Arguments

Value

Modified glyph_spec object with the histogram mark added

Examples

glyph(mtcars, x = mpg) |>
  mark_histogram(binwidth = 2.5)

Description

Add a line mark

Usage

mark_line(spec, ..., data = NULL, style = list(), interpolate = "monotone")

Arguments

Value

Modified glyph_spec object with the line mark added

Description

Add a link/edge mark (for networks, sankeys, slope graphs)

Usage

mark_link(spec, ..., data = NULL, style = list())

Arguments

Value

Modified glyph_spec object with the link mark added

Description

Add a point mark (scatterplot)

Usage

mark_point(spec, ..., data = NULL, style = list())

Arguments

Value

Modified glyph_spec

Examples

spec <- glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl, size = hp, tooltip = "{cyl} cyl, {mpg} mpg")

Description

Draws closed shapes from x/y vertices. Rows that share a value of group are the vertices of one polygon, joined in row order, and the last vertex is joined back to the first. Without a group mapping, all rows form one polygon. Mapping color fills each polygon by its value; a polygon whose rows have different colours is split into one polygon per colour.

Each polygon is one element: its tooltip shows the polygon rather than a single vertex, and brushing or clicking it selects all of its rows. A tooltip template can use any column that has the same value on every row of the polygon, such as a name or an id. Rows with a missing x or y are dropped first, with a warning, and polygons left with fewer than three vertices are not drawn.

Usage

mark_polygon(spec, ..., data = NULL, style = list(), radius = 0)

Arguments

Value

Modified glyph_spec object with the polygon mark added

Examples

triangles <- data.frame(
  id = rep(c("a", "b"), each = 3),
  x = c(0, 1, 0.5, 1.5, 2.5, 2),
  y = c(0, 0, 1, 0, 0, 1)
)
glyph(triangles, x = x, y = y) |>
  mark_polygon(group = id, color = id)

Description

Add a ribbon/band mark (for confidence intervals, ranges)

Usage

mark_ribbon(spec, ..., data = NULL, style = list())

Arguments

Value

Modified glyph_spec object with the ribbon mark added

Description

Add a rule (reference line) mark

Usage

mark_rule(
  spec,
  ...,
  data = NULL,
  style = list(),
  x_intercept = NULL,
  y_intercept = NULL
)

Arguments

Value

Modified glyph_spec object with the rule mark added

Description

Draws every row as a point, spread sideways within its group in proportion to the density of values at that height. The points fill the same outline a mark_violin() with the same settings would draw, so the two combine well.

Each point is still a row of the data, so tooltips, brushing and linked selections work on individual rows, as they do for mark_point(). The sideways positions are computed in R when the plot is compiled and are the same every time.

Usage

mark_sina(
  spec,
  ...,
  data = NULL,
  style = list(),
  bw = "nrd0",
  adjust = 1,
  width = 0.9
)

Arguments

Value

Modified glyph_spec object with the sina mark added

Examples

glyph(mtcars, x = factor(cyl), y = mpg) |>
  mark_violin() |>
  mark_sina()

Description

Add a text/label mark

Usage

mark_text(spec, ..., data = NULL, style = list(), smart_repel = TRUE)

Arguments

Value

Modified glyph_spec object with the text mark added

Description

Draws the distribution of a numeric variable for each group as a mirrored kernel density curve, trimmed to the range of the group's values. All violins in the mark use the same density scale, so their widths can be compared directly.

Map y to the numeric variable and x to the grouping variable, which is treated as categorical even when it is numeric. Without x, all rows form one violin. Mapping color to a different variable than x places one violin per colour side by side within each x group.

The densities are computed in R when the plot is compiled, with stats::density(). A group needs at least two distinct values; groups with fewer are left out with a warning.

Usage

mark_violin(
  spec,
  ...,
  data = NULL,
  style = list(),
  bw = "nrd0",
  adjust = 1,
  width = 0.9
)

Arguments

Value

Modified glyph_spec object with the violin mark added

Examples

glyph(mtcars, x = factor(cyl), y = mpg) |>
  mark_violin()

Description

Marks are the layers that draw data: points, lines, bars, areas, text, rules, ribbons, links and polygons. Each ⁠mark_*()⁠ call adds one layer to the spec. mark_boxplot(), mark_violin(), mark_sina() and mark_histogram() summarise the distribution of a variable; their statistics are computed from the data when the plot is compiled.

Mappings are passed as bare column names or expressions, and are added to the global mappings set in glyph(). A mark can also take its own data, so one plot can draw from several data frames. Fixed visual properties that don't depend on the data, such as size, opacity or stroke_width, go in style. Interaction and animation are set for the whole plot with interact() and animate().

Description

A printed layout draws itself, the same way a single plot does. At the console it opens in the viewer, and in R Markdown, Quarto and vignettes it is embedded in the document. Call render() only to set the width and height, and use summary() for a text description.

In a non-interactive session that isn't knitting a document, such as Rscript, there is nowhere to draw, so printing gives a one-line description instead.

Usage

## S3 method for class 'glyph_layout'
print(x, ...)

## S3 method for class 'glyph_layout'
knit_print(x, ..., options = NULL)

Arguments

Value

print() invisibly returns x. knit_print() returns the rendered widget's HTML for knitr to include in the document.

Description

A printed spec draws itself. At the console it opens in the viewer, and in R Markdown, Quarto and vignettes it is embedded in the document. Call render() only to set the width and height, and use summary() for a text description.

In a non-interactive session that isn't knitting a document, such as Rscript, there is nowhere to draw, so printing gives a one-line description instead.

Usage

## S3 method for class 'glyph_spec'
print(x, ...)

## S3 method for class 'glyph_spec'
knit_print(x, ..., options = NULL)

Arguments

Value

print() invisibly returns x. knit_print() returns the rendered widget's HTML for knitr to include in the document.

Description

Render a glyph spec as an htmlwidget

Usage

render(spec, width = NULL, height = NULL)

Arguments

Value

An htmlwidget object that renders the visualization in an HTML viewer

Description

The rendering pipeline compiles a glyph_spec into output. The spec is first resolved (evaluate quosures, drop rows with missing mapped values, merge defaults), then serialized to JSON, then handed to a backend:

• "html" (default): htmlwidgets + D3.js for interactive viewing. This is currently the only implemented renderer; the visual output is SVG, drawn by D3 inside the widget.

• "svg", "canvas", "webgl", "pdf": standalone static/ large-data export backends. Planned, not yet implemented.

Details

A glyph spec is a plain data structure, and nothing is drawn until the compile() step resolves it into a concrete render tree. That means you can:

• Inspect the compiled spec as JSON (for debugging or export)

• Serialize it and render on a different machine

• Export it to Vega-Lite JSON (near 1:1 mapping)

• Add new backends later without changing the user-facing spec API

Description

Define a scale for an aesthetic channel

Usage

scale(
  spec,
  aesthetic,
  type = "auto",
  domain = NULL,
  range = NULL,
  nice = TRUE,
  zero = FALSE,
  reverse = FALSE,
  label = NULL,
  format = NULL,
  base = NULL
)

Arguments

Value

Modified glyph_spec

Examples

glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  scale("y", "linear", zero = TRUE, label = "Miles per gallon") |>
  scale("color", "ordinal", range = "Set2")

Description

Scales map data values to visual properties. Every scale is set with one function, ⁠scale(<aesthetic>, <type>, ...)⁠, where the aesthetic is the channel (such as "x" or "color") and the type is how values are mapped (such as "log" or "time"). scale_color(), scale_log() and scale_time() are shortcuts for common cases.

Usage

scale_color(spec, palette = "Tableau10", ...)

scale_log(spec, aesthetic = "y", base = 10, ...)

scale_time(spec, aesthetic = "x", ...)

Arguments

Value

Modified glyph_spec object

Modified glyph_spec object

Modified glyph_spec object

Functions

• scale_color(): Set color palette by name

• scale_log(): Log-transform an axis

• scale_time(): Time/date axis

Description

For complex interactions: define a named selection that can be referenced by marks and scales. This is how you build linked views, conditional encoding, and interactive legends.

Usage

selection(
  spec,
  name,
  type = "point",
  on = "click",
  fields = NULL,
  resolve = "global"
)

Arguments

Value

Modified glyph_spec

Examples

# Interactive legend: click legend entries to filter
glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  selection("legend_filter", type = "legend", fields = "cyl")

Description

Summarize a glyph layout

Usage

## S3 method for class 'glyph_layout'
summary(object, ...)

Arguments

Value

No return value, called for side effects (prints a summary of the layout to the console)

Description

Summarize a glyph specification

Usage

## S3 method for class 'glyph_spec'
summary(object, ...)

Arguments

Value

No return value, called for side effects (prints a summary of the specification to the console)

Description

Set theme tokens

Usage

theme_tokens(
  spec,
  preset = NULL,
  font = NULL,
  font_size = NULL,
  bg = NULL,
  fg = NULL,
  accent = NULL,
  grid = NULL,
  border = NULL,
  padding = NULL,
  title_size = NULL
)

Arguments

Value

Modified glyph_spec

Examples

glyph(mtcars, x = wt, y = mpg) |>
  mark_point() |>
  theme_tokens(preset = "dark")

glyph(mtcars, x = wt, y = mpg) |>
  mark_point() |>
  theme_tokens(font = "IBM Plex Sans", bg = "#fafafa", grid = "y")

Description

A theme is set with design tokens: a small set of named values (font, colours, spacing, sizes) that cascade through the whole plot, much like CSS custom properties.

Details

Tokens cascade: setting bg changes the background, but also automatically adjusts text color for contrast, grid line opacity, and tooltip styling. You override only what you want; everything else adapts.

Description

Add a title, subtitle, or caption

Usage

titles(spec, title = NULL, subtitle = NULL, caption = NULL)

Arguments

Value

Modified glyph_spec object with updated title metadata

Description

Because glyph's spec is structurally similar to Vega-Lite, we can export to Vega-Lite JSON for use in Python (Altair), JavaScript, or the Vega Editor.

Usage

to_vegalite(spec)

Arguments

Value

A JSON string in Vega-Lite format