Before We Get Started…

Please go to the following site to vote:

http://etc.ch/qJqU

Objectives

By the end of this workshop you should:

  1. Be convinced reproducible research is important
  2. Become familiar with
  1. Have a website

Part 1: knitr and R Markdown


Standing on the shoulder of giants

None of this would be possible without these trailblazers and the open source community



Reproducible Research

What is needed for Reproducible Research (RR) ?




Why RR?




Division of Labor

Focus on the stats, code, interpretation. Leave everything else (filling in tables, inserting plots, formatting) to the typesetter.


Pictured above is Adam Smith, author of The Wealth of Nations (1776), in which he conceptualizes the notion of the division of labour.

R Markdown

Markdown

Markdown is to HTML what LaTeX is to TeX

Markdown was initially created by John Gruber as a simple way for non-programming types to write in an easy-to-read format that could be converted directly into HTML.


See the Markdown cheatsheet for syntax details.

Note: All HTML is valid Markdown. If you’re stuck not able to format your content how you would like you can always use plain HTML instead of Markdown (e.g. use <br> for line breaks).



R Markdown = R + Markdown

R Markdown combines the computing power of R with the simplicity of Mardown syntax to generate high quality reproducible reports in various formats.

See the R Markdown cheatsheet for syntax details.

Quick Start

We first start with a minimal, complete, and verifiable example (MCVE) to ensure you have all the correct dependencies and updated versions of software installed. In Rstudio, create a new R Markdown document:



Select Document and ensure that the default output format is HTML. Enter a title if you wish, but you can change this later. Click on OK:



A default skeleton of R Markdown code is included everytime you create a new R Markdown document within RStudio. The important pieces of the document are highlited in the figure below. The YAML header is very similar to the header in LaTeX; it contains all the options for the document. The two mandatory pieces in the YAML are a title and the output format. See here for further customizations.



Leave the content as is and click on the knit button:



This will prompt you to save the file:



An RStudio window of the compiled HTML file should appear



The following figure shows exactly what happens when you press the Knit button. The .Rmd file is first converted into a markdown (.md) file, which is subsequently converted by a tool called pandoc into the format specified by output: in the YAML:



Remarks

1. How to choose between LaTeX and Markdown ?



2. Rule of thumb



3. Replicability





Part 2: Creating a Website


Introduction

Even until a couple of years ago, creating a website along with a blog that embeded both code and text, required specific knowledge of HTML. Tools such as markdown and R Markdown, have abstracted the difficult part of writing HTML code for us, so that we can focus on content and creating reproducible analyses. Building on these very tools, the blogdown package by Yihue Xie has made it that much easier to create websites that allow you to showcase your scripts, code and reports, while also maintaining a public portfolio, i.e., having an online presence.

In this part, we will create a minimal working example of a blogdown website. I have provided detailed screenshots with annotations of each step. In general a red encircled annotation means you should click on it, and a red rectangular annotation means that you should verify or be aware of this. Note: the screenshots provided here are from a Linux operating system, however it will be similar on a Windows or Mac.


Step 1: Create 2 git repos

We first need to create two GitHub repositories (abbreviated as repo). One will hold the source code for your website, and the other will host the compiled HTML files which make up your website (these are often referred to as static files). Head over to your GitHub account online and create a new repository:



Give it a name. It can be anything you want such as website, website_source, source (just pick a name that will remind you that this repository contains the source files of your website). In the screenshots below I used website throughout. Check the box to initialize the repository with a README and then click on Create repository:



You should now see the homepage of your repository. Note the URL for the repository is given by https://github.com/<user-name>/<repo-name>. This online version of this repo is called the remote.



Click on the Clone or download green button and copy the URL to your clipboard:



We now want a local copy of the website repo so that we can start creating content to put on our website. Head over to RStudio and go to File --> New Project..:



Select Version Control:



Then select Git:



Paste the repository URL that you copied from your remote GitHub repo. Enter a project directory name (I call it the same as the repo name), and if you want, copy the files of the remote repo to a specific subdirectory:



You will notice that a .Rproj file was created and a .gitignore file was created. Let’s first test to see if our connection from the local repo to the remote repo is working. We first check the boxes next to each file and click on commit:



Enter a commit message and click on Commit:



If everything went ok, you should see a window like this:



Next we want to Push these local changes to the remote. Click on the Push button:



This will prompt you to enter your GitHub username:



… and password:



If everything worked smoothly, you should see a window like this:



Head over to the webpage for your GitHub repo (refresh the page if necessary) and you should see you commit message, as well as a .gitignore file and a .Rproj file.



We now need to repeat the exact same steps as before to create the second repo which will host the static files for your website. Create a local copy, though it is not yet necessary to push your changes to the remote as this will be done in a later step.

Note: the name of this repo must be <user-name>.github.io.













Step 2: Install Hugo


Note for Mac Users: the first time you install Hugo, you might need to install homebrew.



Choose a theme

Choose a theme from https://themes.gohugo.io/ and find the link to the theme’s GitHub repository. In this example we choose the Academic theme.