Exercises: R Project workflow

Exercises: R Project workflow

Create a project

We are going to create an R project from scratch and then practise the “lather, rinse, repeat” workflow.

First things first, we need to name our package. There are three formal requirements:

  • The name can only consist of letters, numbers, and periods, i.e., ..
  • It must start with a letter.
  • It cannot end with a period.

Choose a name by first checking with the available package.

# install if required
library(available)

# choose your own name e.g.
available("HTAmodel")

Explore what names can and can’t be used for packages

Package creation

There’s more than one way of creating a package in R. To start we will use the usethis package.

usethis::create_package(path = "HTAmodel")

An extension to create_package() exists called create_tidy_package().

Have a look and see what the difference is between these two using the help document.

An alternative to making a full blown R package is to make an R project. You can do this as follows

usethis::create_project(path = "HTAproject")

Create an R project and see what the difference between a project and package is by looking at the folder structure. When do you think using one over the other is a good idea?

An alternative may to create an R package is via the RStudio menus and the new project Wizard

File > New Project > Existing or New Directory> R Package

Try this out

You can now launch your new R project by double-clicking on the .Rproj file or selecting it in the File > Open Project drop down menu in RStudio.

(N.B. You can set up a launcher app to find .Rproj files too to make things even more efficient (e.g Alfred in macOS).)

When you open a .Rproj this will open the package with the working directly of you package folder. You can set the package options to automatically load data or open scripts for you. It can also save your history and other things when you exit. I prefer to turn all of this off so that the session starts from scratch each time and it is more reproducable.

Got to Tools > Project Options > to see the different options available.

These can be set individually for each package or as default for all packages.

Package development

The key package for creating packages is usethis and for package development it is devtools. In particular

devtools::load_all()

load_all() roughly simulates what happens when a package is installed and loaded with library() except it is your own package during the development stage. This is really useful for seeing the effect of incremental changes on your code e.g. you can pick up errors early.

You can mimics what it would be like if someone else were to load your package.

There are 3 ways to use load_all. Try out each one:

  • Keyboard shortcut: Cmd+Shift+L (macOS), Ctrl+Shift+L (Windows, Linux)
  • Build pane’s More … menu
  • Drop down menu Build > Load All

To test this out we will make some changes to your skeleton package.

Copy the ce_markov.R file from the exercises package-workflow folder into the R/ folder of your package and run load_all()

The R/ folder is where all of your package functions should live. Now open the ce_markov.R file to and we will automatically create some documentation using the roxygen syntax. We can do this by using the drop down menu

Code > Insert Roxygen Skeleton

The keyboard short cut for this is Ctrl_Alt+Shift+R

This will create a basic function documentation (more on this later!). Now we want to create the help file documentation using the roxygen code we’ve just created. This is done with the

devtools::document()

Alternatively, you can use the drop down menu

Build > Document

or the short cut keys

Ctrl + Shift + D

If you now look in the Files pane in RStudio you will see a new folder called man. This contains the automatically generated help file documents in .Rd format. If you open up ce_markov.Rd you will see what this type of file looks like. Notice that it says do not edit by hand. If you did then this would only get written over when you run load_all() again.

Every time you run load_all() R will check the function for you. Every time you run document() R will update the function documentation for you.

You can see the help documenation in the Help panel by typing

?ce_markov

Practise changing the roxygen in the function script and running through the workflow.

You could also create a new function and do the same steps.