Documentations

Usually, we would write comments to describe what our function does, what are its inputs and outputs. roxygen2 is a package that turns these comments into documentation. For example:

#' Function to compute the square root of a number
#'
#' @description This function is a wrapper around the sqrt function that
#' computes the square root of a number using a loop
#'
#' @param num the number whose square root is computed
#' 
#' @return square root of the input number
#'
#' @details The function only takes in positive values
#'
#' @references None
#'
#' @examples
#' library(myFirstPackage)
#' num <- 4
#' compute_square_root(num)
#' @export
compute_square_root <- function(number) {
    return( sqrt(number) )
}

The first difference with standard comments is that roxygen2 type comments start with the #' symbol instead of simply the # symbol. The fist line is a short description of what the function does. Then, we can supply different keywords to it. Common ones include:

• @description for a longer description of what the function does
• @param that explains what each and every parameter represents
• @return explains the value that the function returns
• @details for more elaboration on the functionality of the function
• @references if we have any
• @examples for a concrete example of how to use the function
• @export for making the function accessible to the user. Sometimes it makes sense to not use @export if we want to have helper functions that are used by our other functions inside the package, and we don’t want to make these functions accessible to the users.

After writing out all of these text before our function, we can then use the roxygenise() function from the roxygen2 package to create the documentation files for our package.

roxygen2::roxygenise()

We can now test building our package by either by clicking on the button named Build and Reload button which we can find inside the Build pane or by using the following keyboard shortcut: CTRL-SHIFT-B in Rstudio. After doing so, we can now load the library use the function inside and search for the help page of the function.

library(myFirstPackage)
compute_square_root(4)

## [1] 2

# search for the documentation
?compute_square_root

Testing Packages

Now that we know the basics of creating a package, let’s apply what we know about unit testing and start testing out package. We’ll simply call devtools::use_testthat() which will create the necessary folders to hold our tests as well as creating a testthat.R file with the code that gets called to run our tests. To elaborate on the necessary folders that the function created, what it’s doing is creating a folder called tests in the root of our package and inside this tests folder create another folder, called testthat. The testthat folder will hold our unit tests. For example, inside the folder, we create a script called test_square_root.R and put the following code in it:

library(testthat)
library(myFirstPackage)

test_that('Test sqrt: positive numeric', {
    expected <- 2
    actual <- compute_square_root(4)
    expect_equal(expected, actual)
})

test_that('Test sqrt: negative numeric', {
    expect_warning(compute_square_root(-4))
})

Now we can run our test by either going under the Build pane in Rstudio and click on Test Package or by simply clicking the keyboard shortcut CTRL-SHIFT-T. After doing so, we should see the following output:

output

Notice the two . above DONE. This means that two unit tests passed. If a unit test does not pass, then the . will be replaced by a number 1 and it will also output the test cases that failed and its corresponding message.

Checking Coverage of Unit Tests

To check if our tests has covered all the functions in our package, we can run the following code:

library(covr)
cov <- package_coverage()
shine(cov)

The line shine(cov) launches an interactive app inside our viewer pane:

coverage

In our case, the coverage shows 100 percent since we did fully tested our function compute_square_root function inside the hello.R script. If we did not fully tested all our functions, then we can click in each of the files to see which line/part of the code did we not test.

Github

Now that we created the skeleton of the package, we can share it by uploading it to Github. After doing so any R user can install your package with just executing the following command in R:

devtools::install_github("username/packagename")

# e.g.
devtools::install_github("ethen8181/myFirstPackage")

For a more detailed introduction please refer to R packages, especially the section about package’s metadata if the goal is to share the package with other users.