I will demonstrate the use of the usethis and devtools packages to create an R package. I’ll be doing this in RStudio desktop.

Start with some functions

I think it’s best to start with some functions that we want to put in the R package. We will use a pair of functions: one for simulating Brownian motion, and the second for plotting the results.

# simulate Brownian motion
# n = number of steps
# sigma = SD of step size
# output is an nx2 matrix of positions
simBrM <-
function(n, sigma=1)
{
    stopifnot(n>=2, sigma>0)

    x <- matrix(rnorm(n*2, 0, sigma), ncol=2)
    colnames(x) <- c("x", "y")

    apply(x, 2, cumsum)
}

# plot Brownian motion
# x = matrix with two columns
# pointcolor = color of start and end points
# ... = passed to plot()
plotBrM <-
function(x, pointcolor=c("springgreen", "violetred"), ...)
{
    stopifnot(is.matrix(x), ncol(x)>=2, nrow(x)>=2)

    if(is.null(colnames(x))) colnames(x) <- c("x", "y")

    plot(x[,1], x[,2], xlab=colnames(x)[1], ylab=colnames(x)[2],
         type="l", las=1, ...)

    if(!is.null(pointcolor)) {
        points(x[c(1,nrow(x)), 1], x[c(1,nrow(x)), 2],
               pch=21, bg=pointcolor)
    }
}

Our goal is to make a package containing these functions.

Create package skeleton

We first use usethis::create_package() to create a directory for the package plus the skeleton of the files that are needed. I’m going to place it on my Desktop (because I’m just going to delete it later). But generally I keep my R packages in ~/Code/.

library(usethis)
create_package("~/Desktop/simBrM")

This will create a directory to contain the package, create some of the basic files and subdirectories that are needed, including to make the package directory an RStudio Project, and then open up another copy of RStudio with that project open.

Make it a git repository

Next I’ll make it a git repository.

use_git()

It will ask me a couple of questions about making an initial commit and will restart RStudio.

Edit DESCRIPTION

I’ll next edit the DESCRIPTION file. I’ll click on it in the Files pane and will edit the Title, Authors@R, and Description fields.

The title is supposed to be in “title case” (all words capitalized), and the description is supposed to be one or more complete sentences (start with capital letter and end with period).

I’ll then click the Git pane in RStudio and stage and commit the change.

Put it on GitHub

I’ll next connect to GitHub and will push my repository there.

use_github()

If you’ve not connected to GitHub before, this will give an error, and you need to set up a “personal token” in order to do things like create github repositories from R. So you’ll first do:

browse_github_token()

This will open up a browser, ask you to log in to your github account, and will open a form to create a github personal token:

github personal token

Agree to the form and it will create a token like the following, which you’ll want to copy but not share with anyone. (The one shown here is not my actual token; I deleted this one.)

github personal token

Finally, go back to RStudio and edit (or create) your ~.Renviron file.

edit_r_environ()

You’ll want to add a line with GITHUB_PAT=[your token], as in the following.

github personal token

You might need to restart R (in RStudio, click Session → Restart R).

Then you can try again to make the connection to GitHub:

use_github()

This will create the repository at GitHub, push your materials there, and also change the DESCRIPTION file to include the GitHub URL.

Stage, commit, and push the change to the DESCRIPTION file.

Try it out

Let’s try installing the package.

install()

We can also check that the package conforms to R’s requirements.

check()

Add a license

We got a warning about a non-standard license, so let’s go ahead and add a license. I generally choose between the MIT and GPL-3. (MIT if I can, GPL-3 if I need to.) We’ll talk more about this at the end of the course.

use_mit_license("Karl Broman")

This will add a couple of LICENSE files and edit the DESCRIPTION file. Commit the changes and push them to GitHub.

Now if we run check(), it is clean.

Add the functions

But wait, our package doesn’t actually contain any code! Let’s add our R functions by pasting them into an R file, in the R/ subdirectory.

use_r("simBrM")

Paste in the code from the top of this page.

Now if you run check() again, it’ll give a warning about undocumented code and a note about not importing the functions plot(), points(), and rnorm().

But if we run install() it will still install our package, which we can load with library(simBrM). This will make simBrM() and plotBrM() available to us. Note that we could also use load_all() to do a quicker, temporary install-and-load, for development purposes.

Add documentation

So let’s add some documentation.

First, let’s set things up to use Roxygen2 with markdown.

use_roxygen_md()

Now we’ll open up the R/simBrM.R file and start writing the documentation. Put the cursor inside the first function, simBrM(). We can get a skeleton of Roxygen2 documentation through the menu bar: Code → Insert Roxygen Skeleton.

The key things are: a title; maybe also a description. Then descriptions of each parameter and of the returned object. Finally, add some examples.

For each function, we’ll also want to add some @importFrom directives, of functions that we use. This will lead to changes in the

#' @importFrom stats rnorm

We then process the documentation:

document()

We should also add Imports: stats, graphics to the DESCRIPTION file.

use_package("stats")
use_package("graphics")

It says we should refer to the functions with stats:: and graphics::, so maybe we should go back and edit those things.

But then finally, let’s check the package with check() and install it with install().

Then stage, commit, and push.

Add a ReadMe

It’s always a good idea to include a ReadMe file, particularly for packages on GitHub, as it’s the ReadMe file that serves as sort of the home page for the software.

The key things to include in the ReadMe are the purpose, how to install, and a bit about usage.

To create a Markdown-based ReadMe file, do the following:

use_readme_md()

This creates a README.md file and then opens it for editing.

Many people are making R Markdown based ReadMe files for their R packages, with working R code and graphs and such. If you want to do that, look at use_readme_rmd().

Add a vignette

The three main things people look at are the ReadMe file, the examples in the help file, and tutorials. And in my experience, tutorials are the most popular.

In the context of R packages, tutorials are called “vignettes”. You can create one in R Markdown using the following:

use_vignette("simBrM", "Simulate Brownian motion")

Run check() and install() to make sure that there are no errors.

To install the vignette with the package, you need to do:

install(build_vignettes=TRUE)

You should then be able to see the vignette listed when you do the following:

vignette(package="simBrM")

And you can open the vignette with the following:

vignette("simBrM")

I recommend creating an introductory vignette that has the same name as the package. But you can include as many vignettes as you would like. Users really appreciate having many focused tutorials.