Render using vegawidget

The central side-effect of this package is to render a vegawidget, an htmlwidget.

A vegawidget is built by the vegawidget() function, using a vegaspec. However, in many cases, your call to vegawidget() may be implied in a print method, rather than being made explicitly.

The vegawidget() function has three main arguments:

embed - to provide vega-embed
width, height - to provide width and height to vw_autosize()

Because your call to vegawidget may be implicit, there are a number of ways to provide these arguments.

using explicit arguments (embed, width, height) to the vegawidget() function
setting R options (vega.embed, vega.width, and vega.height) in a knitr chunk
setting R options using options()

These methods are listed in order of precedence; the embed argument to the vegawidget() function will be used in favor of getOption("vega.embed"). Furthermore, if you specify the embed argument, vegawidget() will ignore any part of the embed-object that may have been set in getOption("vega.embed").

These options make the most sense if you are rendering an HTML document. If you are rendering to a non-HTML format, this package’s image-writing functions will conspire to try to do the right thing.

Please note that automatic conversion to vegawidget works only for objects with class vegaspec. If you are working a promise, such a promise will have to return a vegawdget.

Using vegawidget arguments

When you print a vegaspec, its print method calls vegawidget().

library("vegawidget")

spec_mtcars

In addition to spec, the function vegawidget() has arguments to embed and to specify the overall dimensions, width and height. Setting the options using vegawidget() arguments will override options set any other way.

The embed argument is used to specify the embedding options, according to the API to the vega-embed library. There are a lot of options; to make things easier, you can use the helper function vega_embed(), it mirrors the options available to the version of the vega-embed library supported by this package (see vega_version()). The most important arguments are:

renderer: character, either "canvas" (default) or "svg"
actions: named list of logicals to indicate the presence of action-links; names (default value) can be export (TRUE), source (TRUE), compiled (FALSE), or editor (TRUE).

For example, you can change the renderer to SVG:

vegawidget(spec_mtcars, embed = vega_embed(renderer = "svg"))

You can remove the actions “bug” that is otherwise placed at the top-right of the chart:

vegawidget(spec_mtcars, embed = vega_embed(actions = FALSE))

The arguments width and height in vegawidget() are used to autosize the spec before rendering, using vw_autosize():

vegawidget(spec_mtcars, width = 300, height = 300)

Here, the width and height refer to the overall dimensions of the rendered vegaspec. Please see the vegaspec article for more details on how sizing works.

The base_url argument lets you specify the a common root for when you specify data using a URL. Consider this vegaspec:

spec_precip <-
  list(
    `$schema` = vega_schema(),
    data = list(url = "seattle-weather.csv"),
    mark = "tick",
    encoding = list(
     x = list(field = "precipitation", type = "quantitative")
    )
  ) %>%
  as_vegaspec()

We have included this file as an example dataset for this package; it is also available as a part of vega-datasets:

path_local <- system.file("example-data", package = "vegawidget")
url_remote <- "https://vega.github.io/vega-datasets/data"

By using a base_url, you can specify the file-location at rendering, rather than as a part of the specification. If you want to use the local copy of the data:

# not run
vegawidget(spec_precip, base_url = path_local)

Using a local path will work only for interactive work on your computer. It will not work if you knit your work; a warning will be issued.

If you are sharing your work, using a remote URL will be more robust, but requires that the data be publicly accessible.

vegawidget(spec_precip, base_url = url_remote)

Setting R options

In the previous section, you saw how to specify the rendering options using the vegawidget() function explicitly. You may wish to set the options implicitly: you can do so using the R options vega.embed, vega.width, and vega.height.

You can use the function vw_set_base_url() to set the base_url in the vega.embed option. You need do this only once in an R session or an RMarkdown document; this avoids you having to invoke vegawidget() explicitly:

vw_set_base_url(url_remote)
spec_precip

Another way to set options is in a knitr chunk:

```{r vega.embed=vegawidget::vega_embed(actions = FALSE)}
spec_mtcars
```

```{r vega.width=300, vega.height=300}
spec_mtcars
```

We can set options explicitly using the options() function. There are a few ways you can do this:

for base_url only, use vw_set_base_url()
put an options() call in a code chunk in your .Rmd file
use the config package, with !expr options(...) in your YML configuration file.

Here, we use a variation of the second option, making an explicit options() call to set the width and height:

# render spec using temporary options
withr::with_options(
  new = list(vega.width = 300, vega.height = 300),
  vegawidget(spec_mtcars)
)

Knitting strategies

There are two things to keep in mind when knitting a document that contains a vegawidget:

the type of document: HTML-based format or non-HTML-based format.
the sizing of the vegawidget: different formats have different sizing options available.

Format

In some situations, you may knit to an HTML-based format, like html_document; in others you may knit to a non-HTML-based format, like github_document, or pdf_document. This article is an example of knitting to an html_document; this package’s GitHub README is an example of knitting to a github_document (using SVG).

If you are knitting to an HTML-based format, the only supported options are vega.width, vega.height (as pixels) and vega.embed options (as a list).

If you are knitting to a non-HTML-based format, you additionally have the options dev ("png", "svg", or "pdf"), out.width and out.height; sizing is discussed in the following section.

Knitting to a non-HTML-based format calls this package’s image functions. This requires:

the packages: V8, fs, withr, rsvg, and png.
if you are using MacOS, knitr’s SVG device will require an X11 system, such as XQuartz, to be installed.

If you are knitting to a LaTeX format (e.g. pdf_document) and you specify dev as "svg", it will be implemented as "pdf".

Sizing

The biggest thing to keep in mind about sizing a Vega visualization is that very often the chart tells you how much space it needs, rather than than you tell it how much space it has available. In the future, it may reveal itself how to manage better this “conversation” between you and the chart.

One consequence of this “Vega-tells-you” sizing philosophy is that the options fig.width and fig.height are not useful. Either the chart will tell you the size based on its defaults, or you will specify some dimensions in the vegaspec: width, height, or size of rectangles. If your chart is a single view, i.e. not faceted, concatenated, or repeated, you can specify the size of the chart using the options vega.width and vega.height.

vega.width and vega.height are passed to vegawidget() as width and height, respectively. These values are coerced to numeric, so it is ineffective to specify a percentage. They are passed to vw_autosize(), which will resize the chart, if possible.
For HTML-formats, setting the values of out.width and out.height will not affect the rendered size of your chart.
For non-HTML-formats, you can use out.width or out.height to scale the size of the image within your document. Because the image will already have an aspect ratio, it is recommended to specify no more than one of these.

2024-01-13

Using vegawidget arguments

Setting R options

Knitting strategies

Format

Sizing