The vegawidget package is designed to be a low-level interface to the Vega and Vega-Lite visualization frameworks. As such, we hope that the functions provided here can serve as a foundation for other, presumably higher-level, packages. To make it easier for authors of such packages, we offer a function
use_vegawidget() to help incorporate vegawidget functions.
You can use
use_vegawidget() to import and re-export from vegawidget:
If you implement an S3 class in your package, you can call
use_vegawidget() with the name of your class. This will add more boilerplate code; you will have to provide the code to convert from your class to a
If you want to re-export vegawidget’s interactivity functions, you can then use
use_vegawidget_interactive() to import and re-export:
For example, the altair package provides an R interface to the Altair Python package. The altair package itself provides the connection to Python, using reticulate; altair’s focus is to provide a means to build a Vega-Lite specification - using higher-level abstractions than lists.
The rendering part of altair is handled by the vegawidget package. A number of vegawidget functions are imported into altair, then re-exported. From altair’s perspective, this import-export operation is handled by a single vegawidget function:
This new file contains roxygen directives that will handle the importing and exporting the next time you build the package’s documentation. Now, people who install this package will have access to the pipe operator without having to refer explicitly to the magrittr package. It “just works”.
We wish to bring a similar robustness and ease-of-use to package authors who want to incorporate vegawidget. To demonstrate how to do this, we will show the process we use for altair.
use_vegawidget() function makes a couple of related assumptions about your package. It assumes that your package builds Vega and Vega-Lite specifications, and that the object that you use to contain a specification may be an object with an S3 class. In the case of altair, the name of this S3 class is
The first step is generic. In your package-project, your R working directory is the package’s root directory. When you run
use_vegawidget(), you can provide the name of the S3 class. In the case of altair, we run:
usethis::use_pipe() example, this call does two things:
However, you have a little bit more work to do before you’re done. You need to edit your new copy of
utils-vegawidget-altair.vegalite.v3.api.TopLevelMixin to tell it how to convert your S3 class to a
vegaspec. The part of the file that you need to edit is at the very top.
In the case of altair, the name of the function is
use_vegawidget() function has already named it using the class-name provided.
Here, the commented example code is exactly what is needed. The altair “chart” object,
altair.vegalite.v3.api.TopLevelMixin, has a method,
to_json() to write out the specification to JSON. The vegawidget
as_vegaspec() generic has a method for JSON-formatted strings (it also has a method for lists). So our “finished” product looks like:
At this point, once you document and re-build the package, vegawidget is fully integrated into it.