In vegawidget/vegadown: 'knitr' Engine to Render 'YAML' and 'JSON' into 'Vega'

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library("vegadown")

# makes it easier to set data URL in specs
vw_set_base_url("https://cdn.jsdelivr.net/npm/vega-datasets@2")

Using only vegawidget, you have to compose a Vega or Vega-Lite spec (vegaspec) using lists:

as_vegaspec(
  list(
    `$schema` = vega_schema(),
    data = list("url" = "data/cars.json"),
    mark = "point",
    encoding = list(
      x = list(field = "Horsepower", type = "quantitative"),
      y = list(field = "Miles_per_Gallon", type = "quantitative")
    )  
  ) 
)

It can feel a bit awkward to code using so many lists.

First steps

Using vegadown, you can compose specs using JSON or YAML code chunks in RMarkdown:

• use vegajson or vegayaml (vegayml) as the language of your code chunk.
• afterwards, you can access the vegaspec of a given chunk using vegadown().

If you label a code chunk as json-cars, the vegaspec will be available using vegadown("json-cars"). You can get the names of available specs using vegadown_names().

Examples

Here's what your code chunk would look like:

```{vegajson json-cars}`r ''`
{
  "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
  "data": {"url": "data/cars.json"},
  "mark": "point",
  "encoding": {
    "x": {"field": "Horsepower", "type": "quantitative"},
    "y": {"field": "Miles_per_Gallon", "type": "quantitative"}
  }
}
```

Here's how it would appear:

```{vegajson json-cars, echo=FALSE} { "$schema": "https://vega.github.io/schema/vega-lite/v4.json", "data": {"url": "data/cars.json"}, "mark": "point", "encoding": { "x": {"field": "Horsepower", "type": "quantitative"}, "y": {"field": "Miles_per_Gallon", "type": "quantitative"} } }

As noted above, you can also use YAML (`vegayaml` or `vegayml`); we can also specify sizing options, just as with vegawidget. Here's what the code-chunk front matter would look like:

````
```{vegayaml yaml-cars, vega.height=300, vega.width=300}`r ''`

````

Here's how it would look in your rendered document:

```{vegayaml yaml-cars, vega.height=300, vega.width=300} $schema: "https://vega.github.io/schema/vega-lite/v4.json" data: url: "data/cars.json" mark: point encoding: x: field: Weight_in_lbs type: quantitative "y": field: Miles_per_Gallon type: quantitative

Note that we quoted the `"y"` for the y-encoding; this is because of the (many) [reserved Boolean keywords](https://yaml.org/type/bool.html) in YAML.

You can access a particular spec using `vegadown()`:

```r
vegadown("json-cars")

To get the labels of chunks that use vegadown (thus far in the RMarkdown document):

vegadown_labels()

Interpolation from R

Writing a spec by hand is feasible if your data is available through a URL. However, it would be tedious to specify the data values manually. This is where interpolation is useful.

Let's introduce this topic using palmerpenguins, by Allison Horst, Alison Hill, and Kristen Gorman:

library("palmerpenguins")

penguins

Let's also choose an adjective for the title of our chart:

adjective <- sample(
  c("wonderful", "amazing", "interesting", "penguiny"),
  size = 1
)

We use glue-like notation to interpolate objects from the R environment into the spec; in fact, behind the scenes, we use glue::glue(). Instead of using {} as interpolation delimiters, we use the JavaScript interpolation delimiters, ${}:

```{vegayaml interp} $schema: "${vega_schema()}" data: values: ${penguins} title: "Such ${adjective} penguins!" mark: point encoding: x: field: bill_length_mm type: quantitative scale: zero: false "y": field: bill_depth_mm type: quantitative scale: zero: false color: field: species type: nominal

For YAML, these delimiters work either quoted or unquoted. 

There are two interpolation contexts: 

- **substitution**, e.g. `"${vega_schema()}"`, `"${penguins}"`: if the entire string is interpolated, it substitutes the object itself; the object is not coerced to a string.
  This lets us interpolate data frames into a spec.
- **inline**, e.g. `"Such ${adjective} penguins!"`: this is traditional string-interpolation; the interpolated object is coerced to a string. 

The structure of the spec shows the interpolation:

```r
str(vegadown("interp"))

Behind the scenes

There's not a lot to this package; it offers:

• re-exported vegawidget functions to handle the rendering.
• functions to access the parsed specs: vegadown(), vegadown_labels().
• some internal functions to handle interpolation from the R environment.
• custom-language knitr engines for vegajson and vegayaml (vegayml).

Putting this together, I learned a lot by studying the knitr-engine code for r2d3. As well, this blog post by Jeff Allen had exactly what I needed to learn to get the vegadown() function to work.

vegawidget/vegadown documentation built on Jan. 23, 2021, 10:34 a.m.