Advanced R Markdown Workshop on Advanced R Markdown Workshop

AM Session

Wed, 16 Jan 2019 00:00:00 +0000

Welcome! If you chose the ☁️ setup, please enjoy breakfast and walk through these steps before the workshop begins. Our instructors and TAs are available to help!

Log into our virtual classroom

Go here: http://rstd.io/class

Enter our classroom identifier/password (in your email): advanced-rmarkdown
Enter your name and email address.
Leave the toggle button set to “Create new server credentials.”

(Accept the cookies. 🍪) Your credentials will be different, but your screen should look like this. In fact, every person’s credentials will be different- don’t copy and paste your neighbor’s!

Keep this tab open! You will need these additional credentials later.

Open the URL provided in a new tab. You should see a page with options to connect to RStudio Server Pro and RStudio Connect.

Keep this tab open too! We’ll set up both Server and Connect from here.

Access RStudio Server Pro

Click RStudio Server Pro; you should see a page where you can sign in. You’ll use the credentials from that open tab we just came from.

Once you’re signed in, you should be in a fresh RStudio Server Pro instance. Look in Files; you should see a folder for the course materials already there.

RStudio Connect

Setup

From the RMarkdown Training Server tab, click the RStudio Connect button, then Log In in the top right corner. Use the same credentials as you did for RStudio Server.

Once you’re in, you should see something like this (rstudio-user will be replaced with your username):

Connecting Your Account

In order to publish your documents on RStudio Connect, you’ll need to connect RStudio Server and RStudio Connect. One way to do this:

Create a template document (flexdashboard is a good one for this). From that document, click the Publish button in RStudio Server.

Choose which document(s) you want to publish. RStudio will then ask for the URL of your RStudio Connect instance. Use the URL on that first open tab, with one change: Replace :[number] at the end of the URL with /rsconnect.

Once you’ve set up the initial connection, you’ll be asked to verify your account. Click “Connect Account” and you should be set!

Throughout the workshop, we may want to share our work on Gitter (make sure to sign in or create an account if you haven’t - an invitation should have been emailed to you in early January). Default permissions on RStudio Connect are set so that only you can view your files. To change this, you can change the settings on individual projects once you publish them, using the dropdown menu under “Who can view this document.”

Exporting Your Work

Feel free to take notes within the files set up for you on RStudio Server! You can export those updated files once the workshop is over. Make sure the files you want to export are checked, and then click More -> Export:

A dialog box will pop up allowing you to name the zip file.

These detailed instructions were kindly curated by our TA Jennifer Thompson.

Choose a setup

Wed, 16 Jan 2019 00:00:00 +0000

There are two options for participating in this workshop:

Cloud setup: work in the cloud ☁️
- Build your R Markdown documents via a pre-configured, web-based RStudio IDE instance provided by RStudio Server Pro
- Publish your work via RStudio Connect
Local setup: work on your own laptop 💻
- Build your R Markdown documents locally on your laptop using the RStudio IDE
- Publish your work via RStudio Connect, or a combination of GitHub and Netlify

Click on the links above (which take you to menu items in the left sidebar) to find out more about each of these setup options.

Cloud setup

Wed, 16 Jan 2019 00:00:00 +0000

Work in the ☁️

For this option, you will:

Build your R Markdown documents via a pre-configured, web-based RStudio IDE instance provided by RStudio Server Pro
Publish your work via RStudio Connect

This option uses RStudio’s Professional software. These are paid products designed for use within the Enterprise. Access to both RStudio Server Pro (RSP) and RStudio Connect (RSC) are included in your workshop registration. Your access will be for the day prior to and the two full days of the workshop.

Why would I need this option?

You may not have time to do all the local setup, or you may not wish to modify your local install to upgrade right now.

What do I need to do before the workshop?

Not much! We will provide servers with all the software (R, RStudio IDE) and R packages you will need pre-installed and configured. You will need to:

bring a laptop with the ability to access the internet,
bring your laptop charger, and
check your email ahead of the workshop, which will provide login information for our RSP workshop account.

Will I be able to publish my work?

Yes! You will be able to publish to RStudio Connect (RSC) from your RSP instance. This means you will have a shareable link to your work online. However, the link that you publish to will no longer be active after the workshop has ended.

Will I be able to save my work?

Absolutely- there is a “two-click” method for exporting your work within an RSP R project to your desktop in a single zip file. We’ll show you how. Don’t worry- if you choose this option, you’ll be able to grab a local copy before your RSP/RSC ☁️ access disappears.

Install Git & GitHub

Wed, 16 Jan 2019 00:00:00 +0000

To get the most out of this workshop, we will typically work within RStudio Projects (.Rproj) and encourage you to use Git (via GitHub using RStudio) for version control. You can use RStudio as the Git GUI, so there is no need to install a separate GUI unless you have your own favorite. If you would like to use GitHub during the workshop, please follow the steps below from the online book Happy Git with R:

Installation

Connect Git, GitHub, RStudio

Connect to GitHub
Do one of the following:
- Cache credentials for HTTPS
- Set up keys for SSH
Connect RStudio to Git and GitHub

Test-drive

We encourage you to follow a “New project, GitHub first” workflow. This means that if you want to work locally, you’ll want to be comfortable doing the following steps:

Install R packages

Wed, 16 Jan 2019 00:00:00 +0000

For this workshop, you’ll need to install several R packages. This page will guide you through installing the packages we will use. If you are comfortable installing packages in R, then you could run this code from your R console to install all of the necessary packages:

arm_from_cran <- c("flexdashboard", "learnr", "bookdown",
                   "officer", "rticles", "webshot",
                   "tidyverse", "remotes", "babynames", "magick")

install.packages(arm_from_cran, dependencies = TRUE)

arm_from_gh <- c('yihui/xaringan', 'rstudio/blogdown',
                 'rstudio-education/armcompanion', 
                 'haozhu233/kableExtra', 'apreshill/bakeoff',
                 'hebrewseniorlife/memor')

remotes::install_github(arm_from_gh, dependencies = TRUE)

webshot::install_phantomjs()

Also please review section 0.5.2 to make sure you have Hugo version 0.52, which you’ll need for blogdown.
Please review section 0.9.1 to install phantom_js

Download script

Click here to download an R script for installing all the necessary packages.

xaringan

Install the xaringan package from GitHub as follows:

remotes::install_github('yihui/xaringan', dependencies = TRUE)

Can you load the package?

# should just work if installed
library(xaringan)

You can also check to make sure an individual package is installed by running this function (see Section 0.14 for how to check for all packages):

is_installed <- function(pkg_name){
  setNames(is.element(pkg_name, installed.packages()[, "Package"]), pkg_name)
} 
is_installed("xaringan")

# xaringan 
#     TRUE

Does this code return TRUE?

flexdashboard

Install the flexdashboard package from CRAN as follows:

install.packages("flexdashboard", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(flexdashboard)

Does this code return TRUE?

is_installed("flexdashboard")

# flexdashboard 
#          TRUE

learnr

Install the learnr package from CRAN as follows:

install.packages("learnr", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(learnr)

Does this code return TRUE?

is_installed("learnr")

# learnr 
#   TRUE

blogdown

Install the blogdown package from GitHub as follows:

remotes::install_github('rstudio/blogdown', dependencies = TRUE)

Can you load the package?

# should just work if installed
library(blogdown)

Does this code return TRUE?

is_installed("blogdown")

# blogdown 
#     TRUE

Install Hugo

Hugo (https://gohugo.io) is the static site generator on which blogdown is based. You must install Hugo in order to build a site using the blogdown package. You may install Hugo using the blogdown package helper function in your R Console:

blogdown::install_hugo()

Update Hugo (if necessary)

In your R Console, please do the following to make sure that you are working with the latest version of Hugo (>= 0.52):

blogdown::hugo_version() # to check your version
blogdown::update_hugo() # to force an update

bookdown

Install the bookdown package from CRAN as follows:

install.packages("bookdown", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(bookdown)

Does this code return TRUE?

is_installed("bookdown")

# bookdown 
#     TRUE

officer

Install the officer package from CRAN as follows:

install.packages("officer", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(officer)

Does this code return TRUE?

is_installed("officer")

# officer 
#    TRUE

rticles

Install the rticles package from CRAN as follows:

install.packages("rticles", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(rticles)

Does this code return TRUE?

is_installed("rticles")

# rticles 
#    TRUE

kableExtra

Install the kableExtra package from GitHub as follows:

remotes::install_packages("haozhu233/kableExtra", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(kableExtra)

Does this code return TRUE?

is_installed("kableExtra")

# kableExtra 
#       TRUE

webshot

To be able to save HTML table as images (kableExtra::save_kable()):

install.packages("webshot", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(webshot)

Does this code return TRUE?

is_installed("webshot")

# webshot 
#    TRUE

Please also do the following:

webshot::install_phantomjs()

magick

To be able to save PDF table as images (kableExtra::save_kable()):

install.packages("magick", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(magick)

Does this code return TRUE?

is_installed("magick")

# magick 
#   TRUE

memor

Install the memor package from GitHub as follows:

remotes::install_packages("hebrewseniorlife/memor", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(memor)

Does this code return TRUE?

is_installed("memor")

# memor 
#  TRUE

tidyverse & data packages

For many code examples provided in the workshop activities, you’ll need to install the tidyverse meta-package and some data packages from CRAN as follows:

install.packages(c("tidyverse", "babynames"), dependencies = TRUE)

Can you load the packages?

# should just work if installed
library(tidyverse)
library(babynames)

Does this code return TRUE?

is_installed(c("tidyverse", "babynames"))

# tidyverse babynames 
#      TRUE      TRUE

armcompanion

You can download our workshop companion package from the RStudio Education GitHub:

remotes::install_github("rstudio-education/armcompanion", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(armcompanion)

Does this code return TRUE?

is_installed("armcompanion")

# armcompanion 
#         TRUE

bakeoff

You can download our workshop companion package from GitHub:

remotes::install_github("apreshill/bakeoff", dependencies = TRUE)

Can you load the package?

# should just work if installed
library(bakeoff)

Does this code return TRUE?

is_installed("bakeoff")

# bakeoff 
#    TRUE

Check all package installs

is_installed(c(arm_from_cran, 'xaringan', 'blogdown', 'armcompanion', 'kableExtra', 'bakeoff'))

# flexdashboard        learnr      bookdown       officer       rticles 
#          TRUE          TRUE          TRUE          TRUE          TRUE 
#       webshot     tidyverse       remotes     babynames        magick 
#          TRUE          TRUE          TRUE          TRUE          TRUE 
#      xaringan      blogdown  armcompanion    kableExtra       bakeoff 
#          TRUE          TRUE          TRUE          TRUE          TRUE

Install/upgrade software

Wed, 16 Jan 2019 00:00:00 +0000

In this workshop, we will use R and RStudio. RStudio is not required but recommended, because it makes it easier for an average user to work with R Markdown. If you do not have RStudio IDE installed, you will have to install Pandoc (http://pandoc.org), otherwise there is no need to install Pandoc separately because RStudio has bundled it.

Install R

A recent version of R (>= 3.5.1 “Feather Spray”) is recommended. You can check your version from the R Console:

R.version.string

## [1] "R version 3.5.1 (2018-07-02)"

Install RStudio

RStudio (>= 1.1.463) is recommended.

Upgrading your system

For more help installing or upgrading R and RStudio, please read through these links:

Local setup

Wed, 16 Jan 2019 00:00:00 +0000

Work on your own 💻

For this option, you will:

Build your R Markdown documents locally on your laptop using the RStudio IDE
Publish your work via RStudio Connect, or a combination of GitHub and Netlify

This option will require more setup time before the workshop, but will allow you to be able to work from your own workspace using R and the RStudio IDE.

Why would I need this option?

You may not want to use a server, and would strongly prefer to use your own machine. Note that while we will have TAs for this workshop, there is a limit to how much we can help with issues arising from running outdated versions of R, the RStudio IDE, or packages. So, if you choose this option, please carefully follow all the setup instructions listed below. If you run into problems with your local setup, we may ask you to switch to a cloud setup during the workshop so that you can enjoy the workshop and get the most out of it.

What do I need to do before the workshop?

You’ll need to follow these setup instructions:

Will I be able to publish my work?

Yes! You will also need to look at our publishing options and either:

Use an RStudio Connect account we provide (included in your workshop registration) to publish to RSC from your local IDE
Sign up for a Netlify account (we recommend to sign up through your existing GitHub account).

PM Session Overview

Wed, 16 Jan 2019 00:00:00 +0000

The PM session will cover:

bookdown
blogdown
officer

Publishing

Wed, 16 Jan 2019 00:00:00 +0000

In this workshop, we’ll develop static sites, so publishing is a matter of connecting or copying the output directory to a web server or web hosting service. We’ll give you two convenient options for publishing (there are lots more!):

RStudio Connect: for cloud ☁️ and local setups 💻
Netlify: for local setups 💻

RStudio Connect (RSC)

RSC is a publishing platform from RStudio for secure sharing of websites, applications, reports, and plots. It is a paid product designed for use within the Enterprise. RSC is a server that you run inside an organization, so is suitable for publishing content that you only want visible within your organization’s network as opposed to visible to the entire internet. Access to RSC is included in your workshop registration for the days of the workshop.

To use RSC from an RStudio Server Pro instance (i.e., you chose cloud setup ☁️), you don’t need to do anything ahead of time.

To use RSC locally (i.e., you chose local setup 💻), even if you only want to use it for this workshop, you’ll need to install the rsconnect R package from CRAN:

install.packages("rsconnect")

You’ll receive an email from us before the workshop with your login information.

Netlify

If want to work on a local setup 💻 and you are comfortable using GitHub, we recommend using Netlify. Netlify is a popular website hosting service that allows for both direct upload of website files or integrated publishing from Git repositories via commit-hooks. To use Netlify, you can login using your GitHub, GitLab, or Bitbucket account.

blogdown

Wed, 16 Jan 2019 00:00:00 +0000

Slides

Download slide .Rmd

Key Slides
Full slide deck 🖼
Outline 🗒
Get started ☁️ or 💻
Publishing 🚀

Activities

Activity	Time
📩 Your turn #1: Gaze into your directory structure, and site	🕥 05:00 minutes
📩 Your turn #2: Edit the config.toml to customize your site	🕥 05:00 minutes
📩 Your turn #3: Edit some exampleSite content, save, and let 'LiveReload' preview your changes	🕥 05:00 minutes
📩 Your turn #4: Add new content	🕥 05:00 minutes
📩 Your turn #5: Deploy	🕥 05:00 minutes

Enable Continuous Deployment with Netlify

bookdown

Wed, 16 Jan 2019 00:00:00 +0000

Slides

Download slide .Rmd

Key Slides
Full slide deck 🖼
Outline 🗓
Get started ☁️ or 💻
Publishing 🚀

Activities

Activity	Time
📤 Your turn #1: Edit your index.Rmd YAML	🕝 03:00 minutes
📤 Your turn #2: Add new YAML metadata tags to your index.Rmd	🕝 03:00 minutes
📤 Your turn #3: Add/edit chapters in your book	🕝 10:00 minutes
📤 Your turn #4: Change how your sidebar TOC looks & works	🕝 05:00 minutes
📤 Your turn #5: Tune the book output & publish	🕝 15:00 minutes

Enable Continuous Integration with Travis-CI

In Travis:
- Enable continuous integration for your book’s GitHub repo on Travis
Modify .gitignore to include these files as “ignored” by Git:
- _book (unless you had changed the bookdown default output_dir to something else in your _bookdown.yml file)
- _bookdown_files

Add a file named DESCRIPTION (no file extension needed)

Package: placeholder
Type: Book
Title: Does not matter.
Version: 0.0.1
Imports: bookdown, ggplot2
Remotes: rstudio/bookdown

Add a .travis.yml file

  # R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
  
  language: R
  sudo: false
  cache:
  packages: true
  
  script:
  - Rscript -e 'bookdown::render_book("index.Rmd", "bookdown::gitbook")'
  
  deploy:
  provider: pages
  local_dir: _book
  skip_cleanup: true
  keep-history: true
  github_token: $stat545_GITHUB_PAT
  target_branch: gh-pages

You could now deploy this book either using GitHub Pages or Netlify.

Travis-CI to GitHub Pages

In your repo on GitHub, go to Settings > GitHub Pages.
For Source, choose gh-pages branch.

Travis-CI to Netlify

Log in to Netlify
New Site from Git, select your repository
From “Branch to deploy”, select gh-pages branch.
Leave the basic build settings blank (build command and publish directory)
- This is because in our .travis.yml, we set local_dir: _book. This means that we had Travis only push the rendered _book directory to the gh-pages branch. Check it out in that branch in your GitHub repo! You’ll see all the files there that are present locally in your _book folder.

Enable Continuous Integration with Travis-CI and Continuous Deployment with Netlify

flexdashboard

Wed, 16 Jan 2019 00:00:00 +0000

Slides

Download slide .Rmd

Key Slides
🖼 Full slide deck
✔️ Outline
📍 Start Here

Activities

Activity	Time
➕ Your turn #1: Add layouts	🕧 05:00 minutes
➕ Your turn #2: Add components	🕧 05:00 minutes
➕ Your turn #3: On your own: play with interactivity	🕧 infinite minutes

learnr

Wed, 16 Jan 2019 00:00:00 +0000

https://arm.rbind.io/slides/learnr.pdf

Activity: https://appforiarteam.shinyapps.io/PlayR Stretch: jiena/demo.Rmd

officer

Wed, 16 Jan 2019 00:00:00 +0000

Slides

Visit rpodcast.github.io/officer-advrmarkdown

Resources

GitHub repository: github.com/rpodcast/officer-advrmarkdown
Officer package documentation: davidgohel.github.io/officer/
Example Shiny app: rpodcast.shinyapps.io/megaman

xaringan

Wed, 16 Jan 2019 00:00:00 +0000

Slides

Download slide .Rmd

Key Slides
🖼 Full slide deck
✔️ Outline
📍 Start Here

Activities

Activity	Time
➕ Your turn #1: Season some slides with remark.js salt	🕝 10:00 minutes
➕ Your turn #2: Fatten up your slides with some R code chunks (+ knitr butter)	🕝 05:00 minutes
➕ Your turn #3: Add some acid to your slides with images	🕝 08:00 minutes
➕ Your turn #4: Raise the heat on your slides by changing themes	🕝 03:00 minutes
➕ Your turn #5: Serve your slides by publishing them online	🕝 05:00 minutes

Advanced R Markdown Workshop on Advanced R Markdown Workshop

AM Session

Log into our virtual classroom

Access RStudio Server Pro

RStudio Connect

Setup

Connecting Your Account

Sharing Your Work

Exporting Your Work

Choose a setup

Cloud setup

Work in the ☁️

Why would I need this option?

What do I need to do before the workshop?

Will I be able to publish my work?

Will I be able to save my work?

Install Git & GitHub

Installation

Connect Git, GitHub, RStudio

Test-drive

Install R packages

Download script

xaringan

flexdashboard

learnr

blogdown

Install Hugo

Update Hugo (if necessary)

bookdown

officer

rticles

kableExtra

webshot

magick

memor

tidyverse & data packages

armcompanion

bakeoff

Check all package installs

Install/upgrade software

Install R

Install RStudio

Upgrading your system

Local setup

Work on your own 💻

Why would I need this option?

What do I need to do before the workshop?

Will I be able to publish my work?

PM Session Overview

Publishing

RStudio Connect (RSC)

Netlify

blogdown

Slides

Activities

Enable Continuous Deployment with Netlify

bookdown

Slides

Activities

Enable Continuous Integration with Travis-CI

Travis-CI to GitHub Pages

Travis-CI to Netlify

Enable Continuous Integration with Travis-CI and Continuous Deployment with Netlify

flexdashboard

Slides

Activities

learnr

officer

Slides

Resources

xaringan

Slides

Activities