In vegawidget/vegablock: Provides an Interface between Vega and Blocks

library("vegablock")
library("vegawidget")

Mike Bostock's blocks service is a great resource for sharing visualizations. Blocks (as they are called) are not persistently stored on the blocks website; they are taken from GitHub gists.

• If you have nodejs installed on your system and the processx and magick packages installed, you can include preview and thumb images with the block.

• If a block (not necessarily yours) has a Vega(-Lite) specification, and the specification is in its own file, you can import a vegaspec from a block.

There are a few things you will have to set up to upload gists. First and foremost you will need a GitHub account. From this account, you will need to:

• Create a Personal Access Token (PAT), then store it in your .Renviron file as an environment variable named GITHUB_PAT. Yalu may have done this already.

• If you will use "https" as your git_method, the default behavior, you will also need to set another environment variable GITHUB_USERNAME, using your GitHub-account name.

As you may know, it can be a frustrating experience to work with git from R - until it isn't. By this, I mean that you can spend a lot of energy to get things working the first time - then they "just work". If this is your situation, and you have not yet reached the "just work" stage, I highly recommend Jenny Bryan's e-book Happy Git and GitHub for the useR to help you get to the essence of git and GitHub issues. If it's a problem, chances are that Jenny has seen it and documented it!

As discussed above, you will need a GitHub PAT to use these functions. Unsurprisingly, there's a book section on GitHub PATs. In particular, I have run into issues with SSH credentialing - for which this troubleshooting section is invaluable.

Create a block

You can create a block using a vegaspec as an argument to vw_create_block(). Here we use the sample vegaspec from vegawidget, spec_mtcars:

vw_create_block(spec_mtcars)

message(
  "block url: https://bl.ocks.org/06a512525fbe7a96e1a2028e1871b61c\n",
  " gist url: https://gist.github.com/06a512525fbe7a96e1a2028e1871b61c"
)

Here's a link to the deployed block.

Arguments

As you can see in the reference for the vw_create_block() function, there are a lot of arguments. Here are some of the highlights:

• embed to supply vega-embed options, using the helper-function vega_embed().

• .block to supply block-configuration options, using the helper-function vw_block_config().

• version is used to determine if the block uses the versions vega libraries associated with this release of this (vegawidget) package, or if they should use the major-release version. The default is to use the same version.

• description is a text string used as a title. If none is supplied here, the function will try to look for a description element in the supplied vegaspec.

• readme text for a Markdown file, or the path to a Markdown file.

Return value

We have two very similar functions vw_create_block() and vw_create_block_gistid(). They have the same arguments and they have the same side-effect; they both create the same gist that can be used as a block. They differ in the return value:

• vw_create_block() returns an invisible copy of the spec argument.

• vw_create_block_gistid() returns a list with the endpoint of the GitHub service used, and the id of the gist created.

Depending on what you are doing, one function may be more-useful to you than the other.

gistid <- vw_create_block_gistid(spec_mtcars)

message(
  "block url: https://bl.ocks.org/650e59f6a81cf63b9004ae291fe90667\n",
  " gist url: https://gist.github.com/650e59f6a81cf63b9004ae291fe90667"
)

gistid <- list(
  endpoint = "https://api.github.com",
  id = "650e59f6a81cf63b9004ae291fe90667"
)

gistid

Retrieve a block

If a block has a JSON file, you can retrieve that JSON file and parse it into a vegaspec. For example, we can retrieve the vegaspec from the block that created above:

vw_retrieve_block(gistid$id)

The default behavior is to return the first file in the gist that has a .json extension. If you need to be more specific, you can use the file argument.

vegawidget/vegablock documentation built on June 19, 2019, 9:56 p.m.