Share with bl.ocks.org

2019-06-19

Source: vignettes/blocks.Rmd 
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)
## block url: https://bl.ocks.org/06a512525fbe7a96e1a2028e1871b61c
##  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:

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

## block url: https://bl.ocks.org/650e59f6a81cf63b9004ae291fe90667
##  gist url: https://gist.github.com/650e59f6a81cf63b9004ae291fe90667
## $endpoint
## [1] "https://api.github.com"
## 
## $id
## [1] "650e59f6a81cf63b9004ae291fe90667"

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:

## retrieving `spec.json` from gist 650e59f6a81cf63b9004ae291fe90667

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.