Coding Club: Creating an R Package

6.1 Create a new vignette

New vignettes need a name (the file name and the string you can use to access it later) and optionally a title. If you omit the title, it will be the same as the file name, but you can edit it in the next step.

run in the console

usethis::use_vignette(name = "demopkg")

Note

If the name of your vignette is the same as your package, it will be treated specially in a pkgdown site, which we’ll create next week. his is typically for the package overview for getting started.

The first time you add a vignette, you will see output like below. You will only see the last two lines after that.

✔ Adding 'knitr' to Suggests field in DESCRIPTION
✔ Setting VignetteBuilder field in DESCRIPTION to 'knitr'
✔ Adding 'inst/doc' to '.gitignore'
✔ Creating 'vignettes/'
✔ Adding '*.html', '*.R' to 'vignettes/.gitignore'
✔ Adding 'rmarkdown' to Suggests field in DESCRIPTION
✔ Writing 'vignettes/demopkg.Rmd'
• Modify 'vignettes/demopkg.Rmd'

6.2 Setup

The new .Rmd file will open in the source pane.

6.2.1 YAML Header

You can update the title of your vignette. See ?rmarkdown::html_vignette for potential options you can set for this document type.

Warning

The VignetteIndexEntry value should be the same as the title. Other than that, don’t edit the vignette lines.

---
title: "Demopkg Overview"
output: 
  rmarkdown::html_vignette:
    df_print: kable
vignette: >
  %\VignetteIndexEntry{Demopkg Overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

6.2.2 Knitr Options

The default knitr options set collapse = TRUE, which means that code and output chunks are merged together, and comment = "#>", which means that output lines are prefixed by #> instead of the normal default of ##.

vignettes/demopkg.Rmd

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

You can change these or any other options (see the knitr manual for more details), but these give you the typical look of R package documentation.

# example code to show the options above
set.seed(8675309)
rnorm(20) |> t.test()
#> 
#>  One Sample t-test
#> 
#> data:  rnorm(20)
#> t = 0.65455, df = 19, p-value = 0.5206
#> alternative hypothesis: true mean is not equal to 0
#> 95 percent confidence interval:
#>  -0.3281379  0.6267663
#> sample estimates:
#> mean of x 
#> 0.1493142

6.3 Contents

Now you can add contents in the same way you would write any R Markdown script. For example, we could create a section to describe the built-in data sets.

## Data

### self_res_att

Attractiveness judgements of same-sex and other-sex self-resembling faces from DeBruine (2004). Data are from 108 participants. Original data are from <https://osf.io/3c5s4/>.

```{r, echo = FALSE}
self_res_att |>
  group_by(sex, ethgroup) |>
  summarise(n = n(),
            mean_age = mean(age) |> round(1),
            sd_age = sd(age) |> round(2),
            .groups = "drop")
```

Warning

You’ll need to add library(dplyr) to your vignette to use group_by() and summarise().

6.4 Build

You can knit the vignette as you’re writing it to quickly check what the output looks like. Once you’re done with a vignette, you can “build” it to add it to the package.

run in the console

devtools::build_vignettes()

You will see the normal output for knitting a document, and then these messages:

Output created: demopkg.html
--- finished re-building ‘demopkg.Rmd’

ℹ Copying vignettes
ℹ Moving demopkg.html and demopkg.R to doc/
ℹ Copying demopkg.Rmd to doc/
ℹ Building vignette index

You can view the HTML file in doc/demopkg.html.

run in the console

browseURL("doc/demopkg.html")

6.5 Check

Run the check (from the Build pane or by running devtools::check()) to make sure everything is set up right. This will re-build your vignettes, as well as run all the unit tests and other checks. You will get the following note (unless you’d already added dplyr to your dependencies).

❯ checking for unstated dependencies in vignettes ... NOTE
  'library' or 'require' call not declared from: ‘dplyr’

You can fix this by adding dplyr as a dependency. If you are only using it in vignettes and not in any actual package code, add it as a suggestion.

run in the console

usethis::use_package("dplyr", "Suggests")

Now when you rerun the check, you should get

0 errors ✔ | 0 warnings ✔ | 0 notes ✔

6.6 Install

Building the vignettes can take up some time, so they are not built by default when you install your package. If you want to install the package so your vignettes are available outside the development project, use the following code.

run in the console

devtools::install(build_vignettes = TRUE)

6.7 Access vignettes

Find out the vignettes a package has with the vignette() function. Make sure you’ve loaded your updated package.

run in the console

vignette(package = "demopkg")

Access a specific vignette topic in the Viewer pane. You don’t need to specify the package if the vignette name is unique.

run in the console

vignette(topic = "demopkg", package = "demopkg")

Next week, we’ll learn how to create a website for your package that displays this vignette.

6.8 Glossary

term	definition
chunk	A section of code in an R Markdown file
r-markdown	The R-specific version of markdown: a way to specify formatting, such as headers, paragraphs, lists, bolding, and links, as well as code blocks and inline code.

6.9 Further Reading

Vignettes from Wickham (2015)

6.10 Further Practice

Add more text to your vignette, such as a plot of the data.
Create another vignette in this package for analyses. Compare m_self vs m_non and f_self vs f_non separately for male and female participants using the apa_t_pair() function.