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-embedwidth
, 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.
embed
, width
, height
) to the vegawidget()
function vega.embed
, vega.width
, and vega.height
) in a knitr chunkoptions()
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
.
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)
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 ```
spec_mtcars
```{r vega.width=300, vega.height=300} spec_mtcars ```
spec_mtcars
We can set options explicitly using the options()
function.
There are a few ways you can do this:
base_url
only, use vw_set_base_url()
options()
call in a code chunk in your .Rmd
file !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) )
There are two things to keep in mind when knitting a document that contains a vegawidget:
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:
If you are knitting to a LaTeX format (e.g. pdf_document
) and you specify dev
as "svg"
, it will be implemented as "pdf"
.
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.
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.