5 Sharing

This chapter explains several methods for sharing your interactive data visualizations on the web. After reading this chapter, you will be able to view animints

from a local directory on your personal computer.
in R Markdown documents.
using any web server, including Netlify Drop.
published using GitHub pages, and organized into a group called a gallery.

5.1 Compile to a local directory

When experimenting with different interactive data visualization designs, it is useful to preview them on your personal computer before publishing on the web. This section discusses two methods for compiling animints to a local directory.

So far in previous chapters we have only discussed one method for creating interactive data visualizations. If viz is an animint (list of ggplots and options with class animint), then printing it on the R command line compiles that animint to a temporary directory, using code like this,

set.seed(1)
ten.points <- data.frame(x=0:9, y=rnorm(10))
library(animint2)
animint(
  point=ggplot()+
    geom_point(aes(
      x, y), 
      data=ten.points)
)

The code above saves the animint to a new temporary directory. Rather than saving each animint to a separate temporary directory, you can specify an output directory via the out.dir argument to animint. If you want to save the animint in the "ch05-sharing-ten-points" directory, use:

animint(
  point=ggplot()+
    geom_point(aes(
      x, y), 
      data=ten.points),
  out.dir="ch05-sharing-ten-points"
)

If the parent of out.dir does not exist, that is an error (you can use dir.create to create the parent if necessary). If out.dir does not exist, then it will be created. If out.dir does exist (and contains a file named animint.js), then any files in that directory will be overwritten. To view the data viz, navigate to ch05-sharing-ten-points/index.html in a web browser (which should be done automatically / by default). If the web page is blank, you may need to configure your browser to allow execution of local JavaScript code, as explained on our FAQ.

Internally, R calls the print.animint S3 method, which calls animint2dir to compile it to a new temporary directory on your personal computer. Generally we advise to avoid calling animint2dir directly, but it is useful if you want to avoid opening lots of similar browser windows when repeatedly revising and rendering an animint. You can prevent the default behavior of opening a browser window via:

viz <- animint(
  point=ggplot()+
    geom_point(aes(
      x, y), 
      data=ten.points))
animint2dir(
  viz, 
  out.dir="ch05-sharing-ten-points-again",
  open.browser=FALSE)

5.2 Publish in R Markdown

To include an animint in an R Markdown document, use animint(...) inside of an R code chunk. R will run the knit_print.animint S3 method, which compiles the animint to a local directory, named based on the name of the R code chunk. For example a code chunk named viz-facets will be saved in the directory vizfacets. Make sure to put each animint in its own code chunk (do not put two animints in the same code chunk).

5.3 Publish on a web server

Since animints are just directories with HTML, TSV, and JavaScript files, you can publish them on any web server by simply copying the directory to that server.

For example I executed the World Bank data viz example code to create the WorldBank-facets directory on my personal computer.¹ I copied that directory to my lab web server using rsync -r WorldBank-facets/ monsoon.hpc.nau.edu:genomic-ml/WorldBank-facets/ and so I can view it on my university web server.²

¹ https://github.com/animint/animint2/blob/master/inst/examples/WorldBank-facets.R

² https://rcdata.nau.edu/genomic-ml/WorldBank-facets/

If you don’t have access to a personal/lab web server, try using one of the methods described below, which are free for anyone.

5.4 Publish on Netlify Drop

Netlify Drop is for hosting static web sites. To publish your data viz there, simply drag a directory to that web page (it can be a directory resulting from animint2dir, or from rmarkdown::render if your animint is inside Rmd, as described above). After the upload completes, you will be provided a link which can be used to view the files in that directory. No registration/login is required, but if you do not register an account, your data viz will be deleted after one hour. You can register for a free account if you want your data viz to be available longer. Another limitation is 54,000 files per directory, as mentioned in the Deploy Overview docs.

5.5 Publish on GitHub Pages

GitHub Pages is a service that provides static web site hosting, and can be used to publish animints. To publish an animint on GitHub Pages, you need a GitHub account, and the packages gert (for running git from R), gh (for using the GitHub API from R), and gitcreds (for interacting with the git credential store, easy authentication when pushing to GitHub). First, install those packages. If you don’t have a GitHub account, you can sign up for free. Then make sure to tell R what name/email to use for git commits:

gert::git_config_global_set("user.name", "<your_full_name>")
gert::git_config_global_set("user.email", "<your_email>")

Before publishing, make sure that your viz object has the title and source options, which are required by default, in order to encourage interpretability and reproducibility.

You can then use animint2pages(viz, "new_repo") function to publish your data viz to the gh-pages branch of your_github_username/new_repo (note that your_github_username is not specified in code, because gitcreds will get that information from the git credential store). It should print a message which tells you the URL/link where your data viz will be accessible. It takes a few minutes (usually not more than five) from the time you run animint2pages, to the time the data viz is published for viewing on GitHub Pages.

If you want to update an animint that has already been published on GitHub Pages, you can simply run animint2pages(updated_viz, "existing_repo"), which will update the gh-pages branch of the specified repository.

Beware that GitHub Pages imposes a limit of 100MB per file. For most animints, this limit should not be a problem. If your data viz contains a TSV file over 100MB, consider using the chunk_vars option to break that TSV file into several smaller files.

5.6 Organizing animints in a gallery

A gallery is a collection of meta-data about animints that have been published to GitHub Pages. For example, the main animint gallery is https://animint.github.io/gallery/ which is a web page that has links to various animints, organized into a table.

There is one row for each animint.
The first column viz.link shows a screenshot of the animint, which links to the animint web page.
The second column title shows the name of the data viz (taken from the title option of the animint).
The third column shows links to
- the GitHub repo which hosts the data viz.
- the R source code used to create that animint (taken from the source option of the animint).
- optionally, a video that explains typical interactions with the animint.

A gallery is defined as a github repo that should have two source files in the gh-pages branch:

repos.txt (list of github repositories which contain animints, one owner/repo per line), and
index.Rmd (source for web page with links to animints).

To add a new animint to the gallery which is published in the gh-pages branch of your_github_username/gallery_repo, you can use the following method:

Create a new animint in R code, and make sure to define the source and title options.
use animint2pages(viz, "viz_repo") to publish that animint to the gh-pages branch of your_github_username/viz_repo (this should be a different repo than the one used to host the source code).
take a screenshot of that animint, and commit/push that screenshot as a file named Capture.PNG (case-sensitive), in the gh-pages branch of your_github_username/viz_repo.
add your_github_username/viz_repo to the repos.txt file in the gh-pages branch of your_github_username/gallery_repo.
run the R code animint2::update_gallery("path/to/gallery_repo") (note that a clone of the gallery repo must be present on the system where you run this function, and the GitHub remote must be named origin). It will read gallery_repo/repos.txt, read meta-data (title, source, Capture.PNG) from each repo which is not already present in gallery_repo/meta.csv, write updated meta-data files to the gallery, render gallery_repo/index.Rmd to gallery_repo/index.html, commit, and push to origin.
the updated gallery should be viewable on the web, at https://your_github_username.github.io/gallery_repo after a few minutes (usually no more than five).

5.7 The `animint2` GitHub deployment steps

There is a recommended sequence of actions for creating and publishing animints, which we call the animint2 GitHub deployment steps, because GitHub is used for publishing and reproducibility.

Begin by writing some visualization code in figure-name.R in a GitHub repository, where name is an informative name for your data visualization. For example, the tdhock/cs499-spring2020 GitHub repository contains visualization code in figure-quadratic-interactive.R.
Commit and push the R code file to GitHub, so you can get a public URL that you can add in your R code as the source option, for example source="https://github.com/tdhock/cs499-spring2020/blob/master/2020-02-03-capacity/figure-quadratic-interactive.R".
Add a title option in your R code, for example title="Overfitting using linear model polynomial degree".
Use HTML table layout to make sure that the ggplots in your visualisation always have the same arrangement (in any size web browser window).
Optionally, create a 2-5 minute screencast video with voice narration that explains how to interpret and interact with the visualization. Upload the video to a site like vimeo (up to 1GB free hosting without advertisement), then add a video option in your R code, for example video="https://vimeo.com/1127992420".
At this point, using animint() or animint2dir() to output your visualization to a local directory of files should result in working “source” and “video” links at the bottom.
Before publishing your visualization on GitHub, make sure that you can create an automatic screenshot, which requires chromote and magick packages, install.packages(c("chromote","magick")).
Add animint2pages(viz, "new_repo", chromote_sleep_seconds=3) inside an if(FALSE) block at the end of your R code (the if is useful so you can run the whole script without automatically publishing). Make sure new_repo is different from the repo used to host the source code.
Execute the animint2pages() line to publish the visualisation to a GitHub repository. Continuing the example above, my GitHub username is tdhock and the new_repo name I chose was 2020-02-03-capacity-polynomial-degree, so the new owner/repo is tdhock/2020-02-03-capacity-polynomial-degree, and the GitHub Pages link is https://tdhock.github.io/2020-02-03-capacity-polynomial-degree.
Add the owner/repo to the repos.txt file of a gallery, then run animint2::update_gallery() to push the gallery update to GitHub.
Now this data visualization is complete! If you want to make small modifications, you can re-run animint2pages() using the same repo, to replace/update the existing visualization.
If you want to make larger modifications, it is recommended to copy the R code to a new file, for example figure-several-interactive.R for a new visualization with an additional selector for pattern.
Then repeat the steps in this list for the new file!

The GitHub deployment steps are useful because they result in a data visualization that is reproducible due to various links.

The data visualization has links to the corresponding source code and explanatory video.
The gallery entry has links to the data visualization, along with its source code and explanatory video.
The R code file has a link to the repo that deployed the data visualization, for example:
- the R code in figure-quadratic-interactive.R
- has 2020-02-03-capacity-polynomial-degree at the bottom on the animint2pages() line,
- and has tdhock as the owner of the repo,
- so it can be inferred that the visualization was deployed to https://github.com/tdhock/2020-02-03-capacity-polynomial-degree.
The data visualization deployment repo has a README.md which has a link to the data visualization, https://tdhock.github.io/2020-02-03-capacity-polynomial-degree/.

5.8 Chapter summary and exercises

This chapter explained how to share animints on the web.

Exercises:

Create an animint using the options mentioned in this chapter: out.dir (name of directory to save animint on your computer), source (link to R source code used to create animint), title (description of animint).
Use Netlify Drop to publish that animint on the web.
Use animint2pages to publish that animint to a new GitHub repository. Create a screenshot and save it as Capture.PNG in the gh-pages branch of that repository. Add that repository to the main animint gallery repos.txt by submitting a Pull Request on GitHub.
Create your own animint gallery repository, and add two or more of your own animints to that gallery.

Next, Chapter 6 explains the different options that can be used to customize an animint.

# Sharing ```{r setup, echo=FALSE} knitr::opts_chunk$set(fig.path="ch05-figures/") ``` This chapter explains several methods for sharing your interactive data visualizations on the web. After reading this chapter, you will be able to view animints * from a local directory on your personal computer. * in [R Markdown](http://rmarkdown.rstudio.com/) documents. * using any web server, including [Netlify Drop](https://app.netlify.com/drop). * published using [GitHub pages](https://pages.github.com/), and organized into a group called a gallery. ## Compile to a local directory {#animint2dir} When experimenting with different interactive data visualization designs, it is useful to preview them on your personal computer before publishing on the web. This section discusses two methods for compiling animints to a local directory. So far in previous chapters we have only discussed one method for creating interactive data visualizations. If `viz` is an animint (list of ggplots and options with class animint), then printing it on the R command line compiles that animint to a temporary directory, using code like this, ```{r} set.seed(1) ten.points <- data.frame(x=0:9, y=rnorm(10)) library(animint2) animint( point=ggplot()+ geom_point(aes( x, y), data=ten.points) ) ``` The code above saves the animint to a new temporary directory. Rather than saving each animint to a separate temporary directory, you can specify an output directory via the `out.dir` argument to `animint`. If you want to save the animint in the `"ch05-sharing-ten-points"` directory, use: ```{r} animint( point=ggplot()+ geom_point(aes( x, y), data=ten.points), out.dir="ch05-sharing-ten-points" ) ``` If the parent of `out.dir` does not exist, that is an error (you can use `dir.create` to create the parent if necessary). If `out.dir` does not exist, then it will be created. If `out.dir` does exist (and contains a file named `animint.js`), then any files in that directory will be overwritten. To view the data viz, navigate to `ch05-sharing-ten-points/index.html` in a web browser (which should be done automatically / by default). If the web page is blank, you may need to configure your browser to allow execution of local JavaScript code, [as explained on our FAQ](https://github.com/tdhock/animint2/wiki/FAQ#web-browser-on-local-indexhtml-file-is-blank). Internally, R calls the `print.animint` S3 method, which calls `animint2dir` to compile it to a new temporary directory on your personal computer. Generally we advise to avoid calling `animint2dir` directly, but it is useful if you want to avoid opening lots of similar browser windows when repeatedly revising and rendering an animint. You can prevent the default behavior of opening a browser window via: ```{r eval=F} viz <- animint( point=ggplot()+ geom_point(aes( x, y), data=ten.points)) animint2dir( viz, out.dir="ch05-sharing-ten-points-again", open.browser=FALSE) ``` ## Publish in R Markdown {#Rmd} To include an animint in an R Markdown document, use `animint(...)` inside of an R code chunk. R will run the `knit_print.animint` S3 method, which compiles the animint to a local directory, named based on the name of the R code chunk. For example a code chunk named `viz-facets` will be saved in the directory `vizfacets`. Make sure to put each animint in its own code chunk (do not put two animints in the same code chunk). ## Publish on a web server {#web-server} Since animints are just directories with HTML, TSV, and JavaScript files, you can publish them on any web server by simply copying the directory to that server. For example I executed the World Bank data viz example code to create the `WorldBank-facets` directory on my personal computer.^[<https://github.com/animint/animint2/blob/master/inst/examples/WorldBank-facets.R>] I copied that directory to my lab web server using `rsync -r WorldBank-facets/ monsoon.hpc.nau.edu:genomic-ml/WorldBank-facets/` and so I can view it on my university web server.^[<https://rcdata.nau.edu/genomic-ml/WorldBank-facets/>] If you don't have access to a personal/lab web server, try using one of the methods described below, which are free for anyone. ## Publish on Netlify Drop {#netlifydrop} [Netlify Drop](https://app.netlify.com/drop) is for hosting static web sites. To publish your data viz there, simply drag a directory to that web page (it can be a directory resulting from `animint2dir`, or from `rmarkdown::render` if your animint is inside Rmd, as described above). After the upload completes, you will be provided a link which can be used to view the files in that directory. No registration/login is required, but if you do not register an account, your data viz will be deleted after one hour. You can register for a free account if you want your data viz to be available longer. Another limitation is 54,000 files per directory, as mentioned in [the Deploy Overview docs](https://docs.netlify.com/deploy/deploy-overview/). ## Publish on GitHub Pages {#pages} [GitHub Pages](https://pages.github.com/) is a service that provides static web site hosting, and can be used to publish animints. To publish an animint on GitHub Pages, you need a GitHub account, and the packages `gert` (for running git from R), `gh` (for using the GitHub API from R), and `gitcreds` (for interacting with the git credential store, easy authentication when pushing to GitHub). First, install those packages. If you don't have a GitHub account, you can [sign up for free](https://github.com/join). Then make sure to tell R what name/email to use for git commits: ```r gert::git_config_global_set("user.name", "<your_full_name>") gert::git_config_global_set("user.email", "<your_email>") ``` Before publishing, make sure that your `viz` object has the [`title`](/ch06#title-option) and [`source`](/ch06#source-option) options, which are required by default, in order to encourage interpretability and reproducibility. You can then use `animint2pages(viz, "new_repo")` function to publish your data `viz` to the `gh-pages` branch of `your_github_username/new_repo` (note that `your_github_username` is not specified in code, because `gitcreds` will get that information from the git credential store). It should print a message which tells you the URL/link where your data viz will be accessible. It takes a few minutes (usually not more than five) from the time you run animint2pages, to the time the data viz is published for viewing on GitHub Pages. If you want to update an animint that has already been published on GitHub Pages, you can simply run `animint2pages(updated_viz, "existing_repo")`, which will update the `gh-pages` branch of the specified repository. Beware that GitHub Pages imposes a limit of 100MB per file. For most animints, this limit should not be a problem. If your data viz contains a TSV file over 100MB, consider using the [`chunk_vars`](/ch06#chunk-vars) option to break that TSV file into several smaller files. ## Organizing animints in a gallery {#gallery} A gallery is a collection of meta-data about animints that have been published to GitHub Pages. For example, the main animint gallery is <https://animint.github.io/gallery/> which is a web page that has links to various animints, organized into a table. * There is one row for each animint. * The first column `viz.link` shows a screenshot of the animint, which links to the animint web page. * The second column `title` shows the name of the data viz (taken from the `title` option of the animint). * The third column shows `links` to * the GitHub `repo` which hosts the data viz. * the R `source` code used to create that animint (taken from the `source` option of the animint). * optionally, a `video` that explains typical interactions with the animint. A gallery is defined as a github repo that should have two source files in the `gh-pages` branch: * `repos.txt` (list of github repositories which contain animints, one owner/repo per line), and * `index.Rmd` (source for web page with links to animints). To add a new animint to the gallery which is published in the `gh-pages` branch of `your_github_username/gallery_repo`, you can use the following method: * Create a new animint in R code, and make sure to define the `source` and `title` options. * use `animint2pages(viz, "viz_repo")` to publish that animint to the `gh-pages` branch of `your_github_username/viz_repo` (this should be a different repo than the one used to host the `source` code). * take a screenshot of that animint, and commit/push that screenshot as a file named `Capture.PNG` (case-sensitive), in the `gh-pages` branch of `your_github_username/viz_repo`. * add `your_github_username/viz_repo` to the `repos.txt` file in the `gh-pages` branch of `your_github_username/gallery_repo`. * run the R code `animint2::update_gallery("path/to/gallery_repo")` (note that a clone of the gallery repo must be present on the system where you run this function, and the GitHub remote must be named `origin`). It will read `gallery_repo/repos.txt`, read meta-data (`title`, `source`, `Capture.PNG`) from each repo which is not already present in `gallery_repo/meta.csv`, write updated meta-data files to the gallery, render `gallery_repo/index.Rmd` to `gallery_repo/index.html`, commit, and push to `origin`. * the updated gallery should be viewable on the web, at <https://your_github_username.github.io/gallery_repo> after a few minutes (usually no more than five). ## The `animint2` GitHub deployment steps There is a recommended sequence of actions for creating and publishing animints, which we call the `animint2` GitHub deployment steps, because GitHub is used for publishing and reproducibility. * Begin by writing some visualization code in `figure-name.R` in a GitHub repository, where `name` is an informative name for your data visualization. For example, the [tdhock/cs499-spring2020](https://github.com/tdhock/cs499-spring2020) GitHub repository contains visualization code in [figure-quadratic-interactive.R](https://github.com/tdhock/cs499-spring2020/blob/master/2020-02-03-capacity/figure-quadratic-interactive.R). * Commit and push the R code file to GitHub, so you can get a public URL that you can add in your R code as the [`source` option](/ch06#source-option), for example `source="https://github.com/tdhock/cs499-spring2020/blob/master/2020-02-03-capacity/figure-quadratic-interactive.R"`. * Add a [`title` option](/ch06#title-option) in your R code, for example `title="Overfitting using linear model polynomial degree"`. * Use [HTML table layout](/ch06#html-table-layout) to make sure that the ggplots in your visualisation always have the same arrangement (in any size web browser window). * Optionally, create a 2-5 minute screencast video with voice narration that explains how to interpret and interact with the visualization. Upload the video to a site like [vimeo](https://vimeo.com) (up to 1GB free hosting without advertisement), then add a [`video` option](/ch06#video-option) in your R code, for example `video="https://vimeo.com/1127992420"`. * At this point, using `animint()` or `animint2dir()` to output your visualization to a local directory of files should result in working "source" and "video" links at the bottom. * Before publishing your visualization on GitHub, make sure that you can create an automatic screenshot, which requires `chromote` and `magick` packages, `install.packages(c("chromote","magick"))`. * Add `animint2pages(viz, "new_repo", chromote_sleep_seconds=3)` inside an `if(FALSE)` block at the end of your R code (the `if` is useful so you can run the whole script without automatically publishing). Make sure `new_repo` is different from the repo used to host the `source` code. * Execute the `animint2pages()` line to publish the visualisation to a GitHub repository. Continuing the example above, my GitHub username is `tdhock` and the `new_repo` name I chose was `2020-02-03-capacity-polynomial-degree`, so the new owner/repo is `tdhock/2020-02-03-capacity-polynomial-degree`, and the GitHub Pages link is <https://tdhock.github.io/2020-02-03-capacity-polynomial-degree>. * Add the owner/repo to the `repos.txt` file of a gallery, then run `animint2::update_gallery()` to push the gallery update to GitHub. * Now this data visualization is complete! If you want to make small modifications, you can re-run `animint2pages()` using the same repo, to replace/update the existing visualization. * If you want to make larger modifications, it is recommended to copy the R code to a new file, for example [figure-several-interactive.R](https://github.com/tdhock/cs499-spring2020/blob/master/2020-02-03-capacity/figure-several-interactive.R) for a new visualization with an additional selector for `pattern`. * Then repeat the steps in this list for the new file! The GitHub deployment steps are useful because they result in a data visualization that is reproducible due to various links. * The data visualization has links to the corresponding `source` code and explanatory `video`. * The gallery entry has links to the data visualization, along with its `source` code and explanatory `video`. * The R code file has a link to the repo that deployed the data visualization, for example: * the R code in [figure-quadratic-interactive.R](https://github.com/tdhock/cs499-spring2020/blob/master/2020-02-03-capacity/figure-quadratic-interactive.R) * has `2020-02-03-capacity-polynomial-degree` at the bottom on the `animint2pages()` line, * and has `tdhock` as the owner of the repo, * so it can be inferred that the visualization was deployed to <https://github.com/tdhock/2020-02-03-capacity-polynomial-degree>. * The data visualization deployment repo has a [README.md](https://github.com/tdhock/2020-02-03-capacity-polynomial-degree/blob/gh-pages/README.md) which has a link to the data visualization, <https://tdhock.github.io/2020-02-03-capacity-polynomial-degree/>. ## Chapter summary and exercises {#ch05-exercises} This chapter explained how to share animints on the web. Exercises: * Create an animint using the options mentioned in this chapter: `out.dir` (name of directory to save animint on your computer), `source` (link to R source code used to create animint), `title` (description of animint). * Use Netlify Drop to publish that animint on the web. * Use `animint2pages` to publish that animint to a new GitHub repository. Create a screenshot and save it as `Capture.PNG` in the `gh-pages` branch of that repository. Add that repository to the main animint gallery [repos.txt](https://github.com/animint/gallery/blob/gh-pages/repos.txt) by submitting a Pull Request on GitHub. * Create your own animint gallery repository, and add two or more of your own animints to that gallery. Next, [Chapter 6](/ch06) explains the different options that can be used to customize an animint.