Vignettes are documents used to share some documentations about packages. R Notebooks are similar as scripts. In addition they offer the tools to add more textual information and execute some R code.

What is R Markdown

Markdown is a markup languages; it allows to format text using a set of well established symbol. Unlike HTML and other languages, Markdown relies on sequences of characters. Markdown relies on some plain-text syntax to format part of your text. R Markdown is a version of this markup language to allow within R Studio the creation of documents, such web pages, books and scientific articles.

Example of R Markdown

This is a basic example of R Markdown. It shows a title and the output as an html notebook. Some titles, paragraphs and R snippet code have been included within the plain-text document.

The output of the html notebook is shown below. It appears the # characters formats the Heading 1.

Additional reading list Writing a vignette RMarkdown in R Studio RMarkdown reference guide Markdown RFC IETF standardisation

Additional reading list Writing a vignette RMarkdown in R Studio RMarkdown reference guide Markdown RFC IETF standardisation

Packages

You will need to install several packages and create the file structure required to write a vignette.

# install the package R Markdown and knitr
install.packages("rmarkdown")
install.packages("knitr")

Additional reading list R Markdown package Knitr package

Additional reading list R Markdown package Knitr package

Using R Notebooks

R notebooks can create some report in various format. Some textual content can be added alongside some R code. You can create a R Notebook using the icon shown below. Sections of the reports are formatted using the R markdown markup language.

Let’s practice

Use the code you have written in the R script you have created in the previous page (i.e., Becoming familiar with R studio). Produce a R Notebook with the same code.

Additional reading list R Notebook tutorial

Additional reading list R Notebook tutorial

Using Vignettes

Vignettes are created within a R package.

Create an R package

Create a new project (File menu, New project option)
Create a new project in a new directory
Select R package.
Follow the instructions of the following steps.

Create vignettes folder

If you type this instruction (i.e., line 2) within a R package . You should see the following messages.

#create the folder structure
usethis::use_vignette("my-vignette")

This is an example of a R package that shows the vignettes folder has been created.

In the vignette folder you should find a file named my-vignetted.Rmd. You can then add some content to the file.

R Notebooks and Vignettes: How do I execute the code?

You could either click on the green arrows next to each code chunks; i.e., the gray areas.

You can use the menu Run. You can see all the code can the executed in one go (Run All option). You can also run each code chunk on its own.

Save a R Notebook to HTML

Once you have run all the code chunks, you can save the R Notebook. An html file will be created.

Save a Vignette

To save a vignette in the desired format, you need to click on the knit button. The knit to html_vignette will create a html file. It is save in the location stated under the Knit Directory.

This is the vignette created by Knit.

DataSHIELD

Vignettes and R notebooks