vegawidget: Create a Vega/Vega-Lite htmlwidget

View source: R/vegawidget.R

vegawidgetR Documentation

Create a Vega/Vega-Lite htmlwidget

Description

The main use of this package is to render a vegawidget, which is also an htmlwidget. This function builds a vegawidget using a vegaspec.

Usage

vegawidget(
  spec,
  embed = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL,
  base_url = NULL,
  ...
)

Arguments

spec

An object to be coerced to vegaspec, a Vega/Vega-Lite specification

embed

list to specify vega-embed options, see Details on how this is set if NULL.

width

integer, if specified, the total rendered width (in pixels) of the chart - valid only for single-view charts and layered charts; the default is to use the width in the chart specification

height

integer, if specified, the total rendered height (in pixels) of the chart - valid only for single-view charts and layered charts; the default is to use the height in the chart specification

elementId

character, explicit element ID for the vegawidget, useful if you have other JavaScript that needs to explicitly discover and interact with a specific vegawidget

base_url

character, the base URL to prepend to data-URL elements in the vegaspec. This could be the path to a local directory that contains a local file referenced in the spec. It could be the base for a remote URL. Please note that by specifying the base_url here, you will override any loader that you specify using vega_embed(). Please note that this does not work with knitr. See examples.

...

other arguments passed to htmlwidgets::createWidget()

Details

If embed is NULL, vegawidget() uses:

  • getOption("vega.embed"), if that is NULL:

  • an empty call to vega_embed()

The most-important arguments to vega_embed() are:

  • renderer, to specify "canvas" (default) or "svg"

  • actions, to specify action-links for export, source, compiled, and editor

If either width or height is specified, the autosize() function is used to override the width and height of the spec. There are some important provisions:

  • Specifying width and height is effective only for single-view charts and layered charts. It will not work for concatenated, faceted, or repeated charts.

  • In the spec, the default interpretation of width and height is to describe the dimensions of the plotting rectangle, not including the space used by the axes, labels, etc. Here, width and height describe the dimensions of the entire rendered chart, including axes, labels, etc.

Please note that if you are using a remote URL to refer to a dataset in your vegaspec, it may not render properly in the RStudio IDE, due to a security policy set by RStudio. If you open the chart in a browser, it should render properly.

Value

S3 object of class vegawidget and htmlwidget

See Also

vega-embed options, vega_embed(), vw_autosize()

Examples

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

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

  # define local path to file
  path_local <- system.file("example-data", package = "vegawidget")

  # render using local path (does not work with knitr)
  vegawidget(spec_precip, base_url = path_local)

## Not run: 
  # requires network-access

  # define remote path to file
  url_remote <- "https://vega.github.io/vega-datasets/data"

  # render using remote path
  # note: does not render in RStudio IDE; open using browser
  vegawidget(spec_precip, base_url = url_remote)

## End(Not run)

vegawidget/vegawidget documentation built on Jan. 27, 2024, 10:48 a.m.