Htmlwidget Renderer for Vega and Vega-Lite
Vega and Vega-Lite parse text in JSON notation to render
chart-specifications into HTML. This package is used to facilitate the
rendering. It also provides a means to interact with signals, events,
This is the key difference with the vegalite package: it provides a set of higher-level functions to compose specifications, whereas vegawidget concerns itself mainly with the rendering of the htmlwidget.
To be clear, although Vega-Lite offers a grammar-of-graphics, this package does not offer a user-friendly framework to compose graphics, like those provided by ggplot2 or ggvis. However, this package may be useful to:
- build re-usable Vega and Vega-Lite specifications for deployment elsewhere, if you can tolerate the frustration of building specifications using lists.
- develop higher-level, user-friendly packages to build specific types of plots, or even to build a general ggplot2-like framework, using this package as a foundation (or inspiration).
You can install vegawidget from CRAN with:
You can also install vegawidget from GitHub with:
# install.packages("devtools") devtools::install_github("vegawidget/vegawidget")
This package supports these versions of Vega libraries:
library("vegawidget") vega_version() #> $vega_lite #>  "2.6.0" #> #> $vega #>  "4.0.0" #> #> $vega_embed #>  "3.25.0"
In practical terms, this means that this version of vegawidget will be the only version that will display properly using version 1.1.x of the RStudio IDE.
As soon as Vega-Lite makes its 3.0.0 release, we will make another vegawidget release - for which you will need to use a (presently preview) version of the RStudio IDE at least 1.2.x.
Vega(-Lite) specifications are just text, formatted as JSON. However, in R, we can use lists to build specifications:
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()
as_vegaspec() function is used to turn the list into a vegaspec;
many of this package’s functions are built to support, and render,
The appearance of the chart above depends on where you are reading it:
On this package’s pkgdown site, it is rendered as part of an HTML environment, showing its full capabilities.
At its GitHub code site, the chart is further rendered as a static PNG.
This is package 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.
- 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.
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.
The two biggest known limitations are both associated with vegaspecs that contain datasets specified using remote URLs:
The RStudio IDE does not let you access remote URLs for security reasons. A chart that accesses remote data will not render in the IDE; it will render in a browser window.
The image functions use nodejs to create SVG strings. We are not able to configure the proxy in our node scripts, so if your computer uses a proxy to access remote data, our functions will not create the images properly.
- Haley Jeppson and Stuart Lee have provided valuable feedback and contributions throughout the package’s development.
- Bob Rudis and the vegalite package provided a lot of the inspiration for this work, providing a high-level interface to Vega-Lite.
- The Altair developers, for further popularizing the notion of using a programming language (Python) to create and render Vega-Lite specifications.
- The Vega-Lite developers, for providing a foundation upon which the rest of this is built.
Functions in vegawidget
|vega_embed||Vega embed options|
|vw_handler||Construct a vegawidget handler|
|vw_serialize_data||Serialize data-frame time-columns|
|vw_shiny_demo||Run Shiny demonstration-apps|
|.vw_handler_body||Constructor for internal S3 class|
|.vw_handler_def||Constructor for internal S3 class|
|shiny-setters||Set information in a Vega chart from Shiny|
|spec_mtcars||Example vegaspec: mtcars scatterplot|
|vw_as_json||Coerce vegaspec to JSON|
|renderVegawidget||Render shiny-output for vegawidget|
|shiny-getters||Get information from a Vega chart into Shiny|
|vegawidget||Create a Vega/Vega-Lite htmlwidget|
|vegawidgetOutput||Shiny-output for vegawidget|
|data_seattle_daily||Example dataset: Seattle daily weather|
|data_seattle_hourly||Example dataset: Seattle hourly temperatures|
|vega_schema||Create string for schema-URL|
|as_vegaspec||Coerce to vegaspec|
|data_category||Example dataset: Categorical data|
|vw_rename_datasets||Rename datasets in a vegaspec|
|vw_spec_version||Determine vegaspec version|
|vw_to_vega||Convert to Vega specification|
|image||Create or write image|
|use_vegawidget||Add vegawidget functions to your package|
Last month downloads
|License||MIT + file LICENSE|
|Packaged||2019-01-21 01:43:00 UTC; ijlyttle|
|Date/Publication||2019-01-30 18:20:03 UTC|
|imports||assertthat , glue , htmltools , htmlwidgets , jsonlite , magrittr , rlang , shiny|
|suggests||clipr , clisymbols , conflicted , crayon , desc , dplyr , fs , gistr , here , httr , knitr , learnr , listviewer , lubridate , magick , png , processx , readr , rmarkdown , rsvg , shinytest , testthat , tibble , usethis , webshot , whisker , yaml|
|depends||R (>= 2.10)|
|Contributors||Mike Bostock, Kanit Wongsuphasawat, Hadley Wickham, Jeffrey Heer, Arvind Satyanarayan, Stuart Lee, Alicia Schep, Vega/Vega-Lite Developers , Dominik Moritz, David Frank|
Include our badge in your README