1  Setting up

Recording

Create a package project and edit the default files. We’ll start using the most helpful package, usethis.

Today we’ll be using the following packages, so install them if necessary:

Packages required for this chapter

library(usethis)
library(devtools)

You may need to download some other files to allow you to compile packages if you’ve never installed a package “from source” before. If you’re a Windows user, you’ll need RTools; download and install the recommended version. If you’re a Mac user, you’ll need XCode Tools, which you can install by opening the Terminal tab in RStudio (or opening the Terminal application) and typing the following at the command line: xcode-select --install.

Additionally, you may need to install LaTeX to make PDF versions of the code documentation. The tinytex package is usually the easiest way to do this.

run in the console

install.packages("tinytex")
tinytex::install_tinytex()

1.1 Create your R package

Use the following command to create the framework for a new package called demopkg. Set the path argument to the path where you want to save your package. The last section of the path should be the name of the package: demopkg.

run in the console

usethis::create_package(path = "~/rproj/demopkg")

Warning

Package names can only be letters, numbers, and full stops.

You’ll see the following output, and a new RStudio project will open up. You can close the old window now and just work in this project.

✔ Creating '/Users/lisad/rproj/demopkg/'
✔ Setting active project to '/Users/lisad/rproj/demopkg'
✔ Creating 'R/'
✔ Writing 'DESCRIPTION'
Package: demopkg
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R (parsed):
    * First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID)
Description: What the package does (one paragraph).
License: `use_mit_license()`, `use_gpl3_license()` or friends to
    pick a license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.0
✔ Writing 'NAMESPACE'
✔ Writing 'demopkg.Rproj'
✔ Adding '^demopkg\\.Rproj$' to '.Rbuildignore'
✔ Adding '.Rproj.user' to '.gitignore'
✔ Adding '^\\.Rproj\\.user$' to '.Rbuildignore'
✔ Opening '/Users/lisad/rproj/demopkg/' in new RStudio session
✔ Setting active project to '<no active project>'

1.1.1 Edit the DESCRIPTION file

Open the DESCRIPTION file. It should look like this:

DESCRIPTION

Package: demopkg
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person("First", "Last", , "first.last@example.com", role = c("aut", "cre"),
           comment = c(ORCID = "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.0

Change the title, authors, and description to your own information. If your package has multiple authors, add them as a vector like this. You can also add your ORCiD.

DESCRIPTION

Authors@R: c(
    person(given = "Lisa",
           family = "DeBruine",
           role = c("aut", "cre"),
           email = "debruine@gmail.com",
           comment = c(ORCID = "0000-0002-7523-5539")),
    person(given = "Firstname",
           family = "Lastname",
           role = c("aut"),
           email = "person@gmail.com",
           comment = c(ORCID = "0000-0000-0000-000X")))

Also add the date like this. The date is used to create an automatic citation for your package.

DESCRIPTION

Package: demopkg
Date: 2022-10-05

1.1.2 Create a LICENSE

Make sure you’ve saved any changes to the DESCRIPTION file first, as adding a license will modify that file. Add a license using one of the following options:

run one in the console

# more common for study or data packages
usethis::use_ccby_license() # reusable with citation
usethis::use_cc0_license()  # public domain

# more common for function packages
usethis::use_mit_license()  # permissive sharing
usethis::use_gpl3_license() # derivatives must be open

See https://choosealicense.com for more details and other options.

1.1.3 Create a README

Use the following code to set up a README document that will explain how to install and use your package.

run in the console

usethis::use_readme_rmd() 

We’ll eventually put this on github, so change the installation instructions to the following (change yourusername to your github username).

You can install demopkg from [GitHub](https://github.com) with:

```{r}
devtools::install_github("yourusername/demopkg")
```

Delete the example for now.

Warning

Make sure you knit your README.Rmd file when you update it and never edit the README.md file (that’s just for github).

We’ll make a full-featured pkgdown website in Chapter 7, so we don’t need too many details here.

1.2 Install the package

This package doesn’t do much yet, but you can install it. Go to the Build tab of the upper right pane and click the install button (or type devtools::install() in the console). You should get some output that looks like this:

* installing to library ‘/Library/Frameworks/R.framework/Versions/4.2/Resources/library’
* installing *source* package ‘demopkg’ ...
** using staged installation
No man pages found in package  ‘demopkg’ 
** help
*** installing help indices
** building package indices
** testing if installed package can be loaded from temporary location
** testing if installed package can be loaded from final location
** testing if installed package keeps a record of temporary installation path
* DONE (demopkg)

Now you should be able to see demopkg in your Packages tab, load it with the library() function, and get a citation.

run in the console

citation("demopkg")

To cite package 'demopkg' in publications use:

  DeBruine L (2022). _demopkg: Data and analysis from DeBruine (2004)_.
  R package version 0.0.0.9000, <https://github.com/debruine/demopkg>.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {demopkg: Data and analysis from DeBruine (2004)},
    author = {Lisa DeBruine},
    year = {2022},
    note = {R package version 0.0.0.9000},
    url = {https://github.com/debruine/demopkg},
  }

1.3 Glossary

term	definition
argument	A variable that provides input to a function.
github	A cloud-based service for storing and sharing your version controlled files.
package	A group of R functions.
project	A way to organise related files in RStudio
readme	A text file in the base directory of a project that describes the project.

1.4 Further Practice

1. Set up another package for your own data and analysis.

Bryan, J., STAT 545 TAs, & Hester, J. (n.d.). Happy Git and GitHub for the useR. https://happygitwithr.com/

DeBruine, L. M. (2004). Facial resemblance increases the attractiveness of same-sex faces more than other-sex faces. Proceedings of the Royal Society of London B, 271, 2085–2090. https://doi.org/10.1098/rspb.2004.2824

Knuth, D. E. (1984). Literate programming. Comput. J., 27(2), 97–111. https://doi.org/10.1093/comjnl/27.2.97

Wickham, H. (2015). R packages: Organize, test, document, and share your code. "O’Reilly Media, Inc.". https://r-pkgs.org/

Wickham, H. (2019). Advanced R. Chapman; Hall. https://adv-r.hadley.nz