Getting Started

For a comprehensive introduction to Vega-Lite, please visit the its web site.

Vega(-Lite) specifications are just text, formatted as JSON. However, in R, we can use lists to build specifications:

library("vegawidget")

spec_mtcars <-
  list(
    `$schema` = vega_schema(), # specifies Vega-Lite
    description = "An mtcars example.",
    data = list(values = mtcars),
    mark = "point",
    encoding = list(
      x = list(field = "wt", type = "quantitative"),
      y = list(field = "mpg", type = "quantitative"),
      color = list(field = "cyl", type = "nominal")
    )
  ) %>% 
  as_vegaspec()

The as_vegaspec() function is used to turn the list into a vegaspec; many of this package’s functions are built to support, and render, vegaspecs:

spec_mtcars

Please note that, in an effort to reduce the size of this vignette, the charts are displayed as SVG files rather than using native Vega.

This package is a low-level interface to Vega-Lite and the Vega ecosystem, which has a lot of powerful capabilities, highlighted in this series of articles:

Specify using vegaspec: how to construct and render a vegaspec.
Render using vegawidget: advanced rendering options.
Extend using Shiny: how to interact with Vega charts using Shiny.
Extend using JavaScript: how to interact with Vega charts using JavaScript.
Create Images: how to create and save PNG or SVG images.
Work with Dates and Times: dates and times in Vega(-Lite) work a little differently from R.
Import into Other Packages: how to import vegawidget functions into your package, then re-export them.

To share your Vega(-Lite) creation on the Blocks website, you can use the vegablock package.

Integration with other packages

Although there is an article dedicated to this aspect of the package, it warrants further emphasis.

This package provides functions to render Vega(-Lite) specifications; although it provides some helpers, it does not provide higher-level functions to build specifications. Rather, this is left to other packages. Even though you can use its functions directly, you are invited to import and re-export them for use in your package.

Accordingly, this package offers a templating function, use_vegawidget(), to help you integrate vegawidget functions into your package. For example, it is used to import and re-export vegawidget functions for the altair package.

Known limitations

Vega(-Lite) interprets dots in field (variable) names as an indicator of nesting. To escape this interpretation, you can escape the dot with two backslashes, \\, or surround the name with square brackets, []. These escape-methods mess up the default axis-titles, so you may wish to set those manually.

For example:

library("vegawidget")

list(
  `$schema` = vega_schema(), 
  data = list(values = freeny),
  mark = "point",
  encoding = list(
    x = list(
      field = "income\\.level", 
      type = "quantitative",
      scale = list(zero = FALSE),
      title = "income.level"
    ),
    y = list(
      field = "[market.potential]", 
      type = "quantitative",
      scale = list(zero = FALSE),
      title = "market.potential"
    )
  )
) %>% 
as_vegaspec()

There are limitations associated with vegaspecs that contain datasets specified using remote URLs:

The RStudio IDE may not let you access remote URLs for security reasons. A chart that accesses remote data may not render in the IDE; it will render in a browser window.
The image functions use V8 to create SVG strings. If you are accessing remote data in your chart (i.e. your spec uses an HTTP(S) URL), you will need to make sure that R has access to the remote data (i.e. if you use a proxy, it is set up in R).

- Integration with other packages
- Known limitations