Introduction

Before we start, we will however, sue the Rstudio interface to set up the project and tyhe connection with github.

1. Create a github repository

Go to www.github.com and log in to your account. Create a new repository, with a suitable repository name (ideally the name of your package, only lowercase letters).

2. Link an Rstudio project with github

OPen Rstudio and create a new project. Select “Version control” > Git and copy the url of your github repository. Let Rstuido restart. You will now see the git tab newly added to the project panes.

3. Set up package build tools.

Go to “Tools” > “Project options” > “Build tools” select “package”. Done.

4. Set up package structure

FRom now on we will exclusively use the R console to build the package. In this course we try to have each step be based on an R function that carries out the step. For many steps there are alternative ways, including to click on some button. This is typical for R, but also makes it at times cumbersome to find the right way to do something, there is often no “right way”.

However, there is a “more reproducable way”, for example when using an R function instead of clicking on buttons. The buttons may be at different locations in the specific IDE (Integrated development environment, here RStudio) but the function works in any instance of R that has the respective package installed. To provide fully transparent and reproducilbe documentation, you can write down all those steps you took to make the package via R functions, in a document just like this.

THE R package that assistes in package development is devtools (in combination with usethis that got installed automatically with devtools). To start building a package, we thus first load this package.

library(devtools)

## Loading required package: usethis

Create description

use_description()

## √ Setting active project to 'C:/Users/az64mycy/Dropbox (iDiv)/teaching/2020_yDiv_Rpackaging/demofolder'

## √ Writing 'DESCRIPTION'

## Package: demofolder
## 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
## LazyData: true
## Roxygen: list(markdown = TRUE)
## RoxygenNote: 7.1.1

Create namespace file

use_namespace()

## √ Writing 'NAMESPACE'

Set a license

Chose the license you want to use for this package and supply it with one of the use_*_license() functions.

use_gpl3_license(name = "me")
#> ✔ Setting License field in DESCRIPTION to 'GPL-3'
#> ✔ Writing 'LICENSE.md'
#> ✔ Adding '^LICENSE\\.md$' to '.Rbuildignore'

Edit `DESCRIPTION`

The DESCRIPTION gather all information that crucially important as metadata to your package. It contains, amongst others, title and description, dependencies, the package version and author information. The version created by create_package() is relatively self-explanatory.

Package: myPackage
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person(given = "First",
           family = "Last",
           role = c("aut", "cre"),
           email = "first.last@example.com",
           comment = c(ORCID = "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
License: GPL-3
Encoding: UTF-8
LazyData: true
RoxygenNote: 6.1.1

You have to add some fields yourself, for example the url of the package and where bugs can be reported

URL: https://github.com/"YOUR USERNAME/myPackage"
BugReports: https://github.com/"YOUR USERNAME/myPackage"/issues

Dependencies

Some fields are gonna be added automatically with other usethis functions. For example, most packages will require functions from other packages that are not part of base R. Let’s say you want to do some data wrangling with dplyr, want to use tibble instead of data.frame and intend to describe the idea of your package in a vignette names overview. You would include those via.

use_package("dplyr")
#> ✔ Setting active project to '/path/to/myPackage'
#> ✔ Adding 'dplyr' to Imports field in DESCRIPTION
#> ● Refer to functions with `dplyr::fun()`
use_package("tibble")
#> ✔ Adding 'tibble' to Imports field in DESCRIPTION
#> ● Refer to functions with `tibble::fun()`
usethis::use_vignette(name = "overview")
#> ✔ 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/overview.Rmd'
#> ● Modify 'vignettes/overview.Rmd'

This would add the following to DESCRIPTION, right after RoxygenNote: 6.1.1.

Imports: 
    dplyr,
    tibble
Suggests: 
    knitr,
    rmarkdown
VignetteBuilder: knitr

The packages listed in Imports: have to be installed on the users system and the packages listed in Suggests: are not required, but optionally used at some point in your package. knitr and rmarkdonw will, for example, be used when you build the vignette, but the user does not have to do that on their machine.

Versioning

use_description() has already assigned a version to your package. Whenever you include additions, you should increase that version number. For now it is sufficient that each new feature increases the number in your DESCRIPTION by one, for example from 0.0.0.9000 to 0.0.0.9001. For more detailed information on how to handle versioning, check out this.

Include your ORCiD

create_package() has already included a field in DESCRIPTION for your ORCiD identifier. This is recently a comment to your name. Make use of it for all authors!

Exercise 1 - Package skeleton