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, and datasets in a Vega chart using JavaScript or Shiny.


lifecycle Travis buildstatus CRANstatus

The goal of vegawidget is to render Vega-Lite and Vega specifications as htmlwidgets, and to provide you a means to communicate with a Vega chart using JavaScript or Shiny. Its ambition is to be a low-level interface to the Vega(-Lite) API, such that other packages can build upon it to offer higher-level functions to compose Vega(-Lite) specifications.

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

Installation

You can install vegawidget from CRAN with:

install.packages("vegawidget")

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
#> [1] "2.6.0"
#> 
#> $vega
#> [1] "4.0.0"
#> 
#> $vega_embed
#> [1] "3.25.0"

The first released version of vegawidget supports Vega-Lite 2.6.0, the last release of Vega-Lite that will run using JavaScript version ES5. The next version of Vega-Lite, 3.0.0, will use JavaScript ES6.

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.

Introduction

For a comprehensive introduction to Vega-Lite, please visit the its web site. An interactive tutorial to vegawidget is available at shinyapps.io.

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

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

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:

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

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.

Acknowledgements

  • Alicia Schep has been instrumental in guiding the evolution of the API, and for introducing new features, particularly the JavaScript and Shiny functions.
  • 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.

Contributing

Contributions are welcome, please see this guide. Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

News

vegawidget 0.1.0

  • CRAN release

vegawidget 0.0.7.9000

  • changes API and implementation for "image" functions: vw_to_svg(), vw_to_bitmap(), vw_write_svg() , and vw_write_png() - these functions require that you have node installed on your computer, and the rsvg package, to use vw_to_bitmap() and vw_write_png()

vegawidget 0.0.6.9000

  • adds elementId argument to vegawidget(); had been available as part of ... passed to htmlwidgets::createWidget()

  • compiles Shiny demonstration apps in inst/shiny-demo, adds function vw_shiny_demo() to access them

  • adds Shiny setter-functions: vw_shiny_set_signal(), vw_shiny_set_data(), vw_shiny_run(), getter-functions: vw_shiny_get_signal(), vw_shiny_get_event(), and handler helper-functions vw_handler_signal(), vw_handler_event(), vw_handler_add_effect(), vw_handler_compose(), and vw_handler_body_compose()

vegawidget 0.0.5.9000

  • tries a kinder, gentler method for enforcing sizing by implementing a sizing policy rather than overwriting the enclosing element

  • deprecates block-functions: vw_create_block(), vw_retrieve_block(); moved to vegablock

vegawidget 0.0.4.9000

  • adds learnr tutorial, "Overview"

  • adds datasets: data_seattle_hourly, data_seattle_daily, data_category

  • changes default-display for vw_examine()

  • adds function vw_rename_data() to reanme named datasets within a vegaspec (#34)

vegawidget 0.0.4

  • updates to Vega-Lite 2.6.0, Vega 4.0.0-rc.3, vega-embed 3.16.0.

vegawidget 0.0.3

  • adds function vw_serialize_data() to help format dates and datetimes in data frames (#33)

  • adds function vega_schema() to create a string describing a schema-URL (#32)

  • adds function use_vegawidget() to help other packages use these functions (#21)

  • overhauls the API (#15, with @AliciaSchep)

    • changes write_svg() -> vw_write_svg()
    • changes write_png() -> vw_write_png()
    • changes to_vega() -> vw_to_vega()
    • changes to_svg() -> vw_to_svg()
    • changes to_png() -> vw_to_png()
    • changes png_bin() -> vw_png_bin()
    • changes spec_version() -> vw_spec_version()
    • changes examine() -> vw_examine()
    • changes block_retrieve() -> vw_retrieve_block()
    • changes block_create_gistid() -> vw_create_block_gistid()
    • changes block_create() -> vw_create_block()
    • changes block_config() -> vw_block_config()
    • changes autosize() -> vw_autosize()
    • changes as_json() -> vw_as_json()
    • changes spec_mtcars -> spec_mtcars

vegawidget 0.0.2

  • adds a NEWS.md file to track changes to the package

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("vegawidget")

0.1.0 by Ian Lyttle, 2 months ago


https://github.com/vegawidget/vegawidget


Report a bug at https://github.com/vegawidget/vegawidget/issues


Browse source code at https://github.com/cran/vegawidget


Authors: Ian Lyttle [aut, cre] , Vega/Vega-Lite Developers [aut] , Alicia Schep [ctb] , Stuart Lee [ctb] , Hadley Wickham [ctb] , Kanit Wongsuphasawat [ctb] (Vega/Vega-Lite library) , Dominik Moritz [ctb] (Vega/Vega-Lite library) , Arvind Satyanarayan [ctb] (Vega/Vega-Lite library) , Jeffrey Heer [ctb] (Vega/Vega-Lite library) , Mike Bostock [ctb] (D3 library) , David Frank [ctb] (node-fetch library)


Documentation:   PDF Manual  


MIT + file LICENSE license


Imports jsonlite, htmlwidgets, assertthat, rlang, glue, magrittr, shiny, htmltools

Suggests knitr, rmarkdown, listviewer, httr, testthat, yaml, fs, gistr, webshot, magick, usethis, whisker, crayon, clipr, desc, clisymbols, shinytest, readr, tibble, lubridate, learnr, processx, rsvg, dplyr, png, conflicted, here


See at CRAN