Vignettes
Last updated on 2024-04-23 | Edit this page
Overview
Questions
- I have written the functions in my package, but can I also use them?
- How can I write a tutorial or paper as part of my package?
Objectives
- Learn how to write reports in the form of a vignette, using R Markdown.
Your package now contains functions, and perhaps data. Others can easily install your package, and use the functionality you created. But, how do they know where to start?
Vignettes are a great way to create a guidebook or tutorial to your package. You have probably already seen vignettes, as you were exploring a new package you were interested in using.
Accessing vignettes
You can take a look at the vignettes that are available for a package
with the function browseVignettes. For example, this shows
you the available vignettes for the dplyr package:
R
browseVignettes("dplyr")
You can also directly open a vignette, if you know its name:
R
vignette("dplyr", package="dplyr")
There are many things that can stand out about vignettes. Some things that may be mentioned:
- Vignettes combine text with code, to give a comprehensive overview of the possibilities of a package.
- Not all packages have vignettes.
- Some packages have more than one vignette
- Vignettes can perform many different functions: they can be tutorials, clarify a specific purpose of a package, or even be a scientific report.
- Code inside a vignette may be executed: the vignette can also contain the results of this code run.
A vignette will take code from your package, execute it, and allow you to provide context and instructions around the functionality you created. The resulting document would be a human readable website or a pdf file. The possible applications for this are endless. It can be a tutorial, a report, or even a scientific paper.
Vignettes as research reports
There are several reasons that make vignettes an excellent way to write up research.
For instance:
- It keeps all the work tidy in a single project folder.
- The document describes and performs the calculations, instead of only describing them.
- The document can be read as a text, but interested readers can also execute it, test it. In short: they can reproduce the work.
Rmarkdown files
In R, vignettes are typically written using
.Rmd (the extension of Rmarkdown) files. The
name is self-descriptive: it is a file that combines
code (in R) and text (in
markdown).
Markdown is a way of creating formatted text using a plain-text
editor. Actually, it looks a lot like plain text, but with some special
symbols every now and then indicating aesthetic details such as bold
typeface, links, tables, … Markdown files can be rendered to
reading-friendly formats, such as html or
pdf.
This website is written in markdown. Below you can see the source for the last paragraph of the previous section.
MARKDOWN
In `R`, vignettes are typically written using `.Rmd` (the extension of `Rmarkdown`) files.
The name is self-descriptive: it is a file that combines **code** (in `R`) and **text** (in `markdown`).Learning Markdown is not complex, and there are lots of good cheat sheets available online.
Creating a vignette
Running the following code will generate an Rmarkdown document with your first vignette:
R
usethis::use_vignette("example")
This will do the following:
- Create a directory
vignettes - Create the file
example.Rmdinside this directory - If necessary, add dependencies to the
DESCRIPTIONfile
Editing the vignette
The file example.Rmd can now be edited.
Let’s start with the header. We can replace the title with a little more information:
YAML
---
title: "Examples of usage"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{test}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---Scrolling down, we see that there is some R code in our vignette
already. This is fenced by so-called back-ticks: (```), as
well as information about the programming language used: R.
This is called a ‘code chunk’. The word setup here is
the name of the code chunk. It can be useful to name code chunks, but it
is optional.
Whenever we want to include code, we will need to do so inside a chunk like this. Later, when we generate the final document, the code inside will be executed, and the results will be included in the vignette.
However, before we start writing code, we should start with an introduction. How about:
Making the vignette complete
The template vignette we just created works fine, but it doesn’t give any useful information about our package. In this section we will fix that. We will create a report including some examples to show how great our package is!
A vignette aboutmysterycoffee
For this exercise, add code chunks and markdown text to make the
vignette complete. Think about what a user may want to know when first
encountering the mysterycoffee package.
You can think about the following elements:
- Describe the purpose of the package (markdown)
- Show how to attach the package (a code chunk)
- Show how to load some names (a code chunk)
- Use the
make_groupsfunction on the names, to make the groups (a code chunk) - Display the groups formed after running
make_groups(a code chunk) - Explanatory text in between the chunks, to narrate the process (markdown)
This is what I wrote. Of course, your text, and even your code, will most likely be different.
MARKDOWN
---
title: "Examples of usage"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{test}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
## Introduction
Working from home can be lonely. Do you miss the random chats at the coffee machine? Certainly we do!
Luckily, our R package `mysterycoffee` is here to help.
## How to use it
Well, first you will have to attach the package.
```{r install}
# library(mysterycoffee) # uncomment this line in the vignette
```
The package will need the names of your colleagues. These are mine:
```{r names}
names <- c("Pablo Rodríguez",
"Lieke de Boer",
"Barbara Vreede",
"President Obama",
"General Sun Tzu",
"Pharaoh Hatshepsut")
```
Now we just have to use the function `make_groups` to assign the random coffee partners:
```{r assign}
groups <- make_groups(names)
```
And here you have the result!
```{r print, echo=FALSE}
print(groups)
```Hiding chunks
Sometimes you don’t want the content of the code chunk to be printed in the knitted document, but only its results. This can be done by adding options to the code chunk. The menu in the upper right corner of each chunk allows you to access the options. You can choose to execute or not execute the chunk, to display the code, the output, or nothing.
As you change the options, you see the text change in the header of
the code chunk. When you choose, for instance, show output
only, the parameter echo=FALSE will be added to the
chunk header.
Take a look at this page
on knitr to learn more about chunk options.
Viewing our vignette
We can always render the vignette simply by knitting the document. However, should you want to view the vignette in the same way as you access another package’s vignette, you need to take an extra step. We need to explicitly build the vignette on installing the package:
R
devtools::install(build_vignettes = TRUE)
Note that clicking the “Install” button does not build the vignette
in a way that allows access through the vignette() and
browseVignettes() functions.
Viewing vignettes from a GitHub installation
If you have made a vignette, but your package is only accessible on
GitHub, it is important to give explicit installation instructions for
the vignette. You use the same argument (build_vignettes)
as with the local install:
R
devtools::install_github(build_vignettes = TRUE)
Without this argument, the vignettes will not be included in the package installation.
Now we can take a look at our own vignette!
R
vignette("example", package="mysterycoffee")