Repository files navigation

Vega-Lite is an implementation ofthe grammar-of-graphics, rendered in the browser with interactivity.

The goal of vegawidget is to render Vega-Lite and Vega specifications ashtmlwidgets, and to help you communicate with a Vega chart usingJavaScript or Shiny. Its ambition is to be alow-level interface tothe Vega(-Lite) API, so that other packages can build upon it.

Accordingly, this package may be useful to:

• build (using lists of lists) re-usable Vega and Vega-Litespecifications for deployment elsewhere.
• develop higher-level, user-friendly packages to compose specific typesof plots, or even to build a general ggplot2-like framework, usingthis package as the rendering foundation.

• vegawidget now supports the last two Vega-Lite major-versions,currently versions 5 and 4.

  However, for a given R session (e.g. rendering of an RMarkdown file),thevegawidget() function can use onlyone major-version; thisversion is determined using the$schema element of the firstvegaspec evaluated usingvegawidget().

  This restriction does not apply to the image functions,e.g. vw_to_svg(), or to the compilation function,vw_to_vega().

• usevega_version_all() to see the available versions:

library("vegawidget")vega_version_all()#>   widget vega_lite   vega vega_embed#> 1    vl5    5.16.3 5.24.0     6.22.2#> 2    vl4    4.17.0 5.17.0     6.12.2

• Compiling a spec and creating an image now uses theV8 package, rather thandepending on a local installation of nodejs.

You can install vegawidget from CRAN with:

install.packages("vegawidget")

The development version of vegawidget is available from GitHub with:

# install.packages("devtools")devtools::install_github("vegawidget/vegawidget")

Note: There are documentation websites for both theCRANversion and thedevelopmentversion of this package.

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

library("vegawidget")spec_mtcars<-list(`$schema`= vega_schema(),# specifies Vega-Litedescription="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()

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

spec_mtcars

The rendering of the chart above depends on where you are reading it:

• On this package’spkgdownsite, it is rendered aspart of an HTML environment, showing its full capabilities.

• At itsGitHub code site,the chart is further rendered to a static SVG file, then incorporatedinto the Markdown rendering.

Alearnr tutorial isavailable:learnr::run_tutorial("overview", package = "vegawidget").

For more, please see ourGettingStartedarticle. Additionally, theVega-Litewebsite has a comprehensiveintroduction.

Other articles for this package:

• Specify usingvegaspec:how to construct and render a vegaspec.
• Render usingvegawidget:advanced rendering options.
• Extend usingShiny:how to interact with Vega charts using Shiny.
• Extend usingJavaScript:how to interact with Vega charts using JavaScript.
• CreateImages:how to create and save PNG or SVG images.
• Work with Dates andTimes:dates and times in Vega(-Lite) work a little differently from R.
• Import into OtherPackages:how to import vegawidget functions into your package, then re-exportthem.

• Alicia Schep has been instrumentalin guiding the evolution of the API, and for introducing new features,particularly the JavaScript and Shiny functions.
• Haley Jeppson andStuartLee have provided valuable feedback andcontributions throughout the package’s development.
• Bob Rudis and thevegalite package provided alot of the inspiration for this work, providing a high-level interfaceto Vega-Lite.
• TheAltair developers, for furtherpopularizing the notion of using a programming language (Python) tocreate and render Vega-Lite specifications.
• TheVega-Lite developers, forproviding a foundation upon which the rest of this is built.

Contributions are welcome, please see thisguide.Please note that this project is released with aContributor Code ofConduct.By participating in this project you agree to abide by its terms.