In ggvis, there are two types of layers. Simple layers correspond directly to vega marks and represent geometric primitives like points, lines and rectangles. Compound layers combine data transformations with one or more simple layers.

Marks

Marks are the fundamental building block. Each type of mark represents a different type of geometric object, and so in some sense they are the equivalent of geoms in ggplot2. However, there are a far fewer marks than geoms because marks tend to be more capable, and because they never perform any statistical transformation.

Most of the time you don’t use marks directly - you instead use their layer wrappers. That’s because most of the time you don’t want to think about the difference between simple and compound layers - you just want to make a plot. But if you want to understand more deeply how things work, or create your own layer functions, it’s important to understand the distinction.

ggvis exposes five vega marks that have very similar ggplot2 equivalents:

There are two marks that have no equivalent in ggplot2:

And two vega marks that are not currently implemented in ggvis:

All marks take two optional arguments which are only needed if you want to override the values inherited from parent:

Adding a layer to a plot

For example, the following two plots are equivalent. In the first one, the data and props are defined at the top level and inherited by the mark, and in the second, they are defined in the mark itself. Note that the order of the arguments to ggvis() and the mark function are different: this is because you’ll usually set the data in top-level plot object, and usually only override props in the mark.

ggvis(mtcars, props(x = ~wt, y = ~mpg, stroke := "red")) +
  layer_point()
ggvis() +
  layer_point(data = mtcars, props(x = ~wt, y = ~mpg, stroke := "red"))

You can add layers on to plots created by qvis(), but we don’t recommend it if you’re setting custom props. Using two different ways of describes props makes the code harder to read.

qvis(mtcars, ~wt, ~mpg) +
  layer_smooth(props(stroke := "red"))
#> Guessing method = loess
#> Guessing formula = y ~ x
# This is only a little more typing but more symmetric
ggvis(mtcars, props(~wt, ~mpg)) +
  layer_point() +
  layer_smooth(props(stroke := "red"))
#> Guessing method = loess
#> Guessing formula = y ~ x

Mark details

The following sections describe particular details related to individual marks.

layer_rect

Must set two of x, x2, and width, and two of y, y2 and height.

If you have an ordinal scale, set width and/or height to prop_band() to occupy the complete band corresponding to that categorical value.

hec <- as.data.frame(xtabs(Freq ~ Hair + Eye, HairEyeColor))

ggvis(hec, props(x = ~Hair, y = ~Eye, fill = ~Freq),
  layer_rect(props(width := band(), y := band())))

layer_path

layer_path produces lines if fill is empty, and polygons if it is set to a value.

df <- data.frame(x = c(1, 1, 2, 2), y = c(2, 1, 1, 2))
ggvis(df, props(x = ~x, y = ~y, stroke := "red"), layer_path())
# Add a fill colour to make it a polygon
ggvis(df, props(x = ~x, y = ~y, fill := "red"), layer_path())

You can not currently set the component of lines to different colours: track progress at https://github.com/trifacta/vega/issues/122.

To create a line that spans the complete range of the plot, use prop_group():

ggvis() +
  layer_point(props(x = ~disp, y = ~wt), mtcars) +
  layer_path(props(y = ~mean(mtcars$wt), x := 0, x2 := prop_group())) +
  layer_path(props(x = ~mean(mtcars$disp), y := 0, y2 := prop_group()))

Note that this won’t work because prop_group() hasn’t been written yet: track progress at https://github.com/rstudio/ggvis/issues/38.

layer_area

You need to set two of y, y2 and height:

df <- data.frame(x = 1:10, y = (1:10) ^ 2)
ggvis(df, props(x = ~x, y = ~y, y2 := 0), layer_area())
# Set height in pixels
ggvis(df, props(x = ~x, y = ~y, height := 20), layer_area())

Height can only be mapped to a constant, because it does not have an obvious scale associated with it. You could force height to use the y scale, but that doesn’t work - the area hangs below the y line, and increasing the value of height makes the area narrower! What’s going on is that the underlying graphics device has (0, 0) in the top-left corner, and so the y-scale is upside down. As you increase height, it’s mapped like a y variable so bigger values are further away.

ggvis(df, props(x = ~x, y = ~y, height := prop(80, scale = "y"))) +
  layer_area()
df <- data.frame(x = 1:10, y = (1:10) ^ 2)
ggvis(df, props(x = ~x, y = ~y),
  layer_area(props(height = prop(input_slider(0, 100), scale = "y"))),
  layer_path(props(stroke := "red", strokeWidth := 10))
)
#> Warning: Can't output dynamic/interactive ggvis plots in a knitr document.
#> Generating a static (non-dynamic, non-interactive) version of plot.

If you want to set the height in data units, you need to compute the offsets yourself:

ggvis(df, props(x = ~x, y = ~y - 2, y2 = ~y + 2), layer_area())

The distinction between dimension and location is important in other graphics system, and a grid vignette vignette("locndimn", package = "grid") has a little more information about how things work in grid.

Grouping

In ggplot2, grouping was a special aesthetic; in ggvis, grouping is a data transformation: use by_group() to split your data up into pieces given a specified variable, or auto_split() to split up by any categorical variable included in the plot:

ggvis(mtcars, props(~wt, ~mpg)) +
  layer_point() +
  layer_path(data = by_group(cyl))
ggvis(mtcars, props(~wt, ~mpg, stroke = ~factor(cyl))) +
  layer_point() +
  layer_path(data = auto_split())

Some layers, like layer_line(), include auto_split() so will split automatically:

ggvis(mtcars, props(~wt, ~mpg, stroke = ~factor(cyl))) +
  layer_line()

Compound layers

Simple layers map directly to vega’s primitive drawing functions (marks). Compound layers combine data transformation and simple layers (potentially multiple of each) to more sophisticated graphics. For example:

All layers start with layer_. The source is usually relatively simple - the complexity generally comes when figuring out how to map properties supplied to the layer to individual marks:

layer_smooth
#> function(..., se = FALSE) {
#>   comps <- parse_components(..., drop_named = TRUE)
#> 
#>   line_props <-  merge_props(props(x = ~x, y = ~y, strokeWidth := 2), comps$props)
#>   se_props <- merge_props(props(x = ~x, y = ~y_lower__, y2 = ~y_upper__,
#>     fillOpacity := 0.2), comps$props)
#> 
#>   # Line shouldn't get fill-related props, and se area shouldn't get
#>   # stroke-related props.
#>   line_props <- drop_props(line_props, c("fill", "fillOpacity"))
#>   se_props <- drop_props(se_props, c("stroke", "strokeOpacity"))
#> 
#>   layer(
#>     transform_smooth(..., se = se),
#>     layer(
#>       comps$data,
#>       comps$marks,
#>       if (!identical(se, FALSE)) mark_area(se_props),
#>       mark_path(line_props)
#>     )
#>   )
#> }
#> <environment: namespace:ggvis>
layer_histogram
#> function(...) {
#>   layer(
#>     transform_bin(...),
#>     layer(
#>       props(x = ~xmin__, x2 = ~xmax__, y = ~count__, y2 = 0),
#>       mark_rect(),
#>       ...,
#>       drop_named = TRUE
#>     )
#>   )
#> }
#> <environment: namespace:ggvis>

If you find yourself using a set of marks commonly, it might be worth writing your own layer function. Typically, the first argument should be props and ... should be passed on to the tranform function.

Conversion from ggplot2

The following list provides a conversion from ggplot2 geoms to vega marks. However, because ggvis currently provides few transformations, many translations don’t currently exists - but they are on the roadmap and will be added over time.